nfc related support #93

bparth24 · 2025-11-12T01:48:50Z

Implements the W3C VC Rendering Methods spec for NFC rendering with both static
and dynamic modes. Includes comprehensive tests and maintains backward
compatibility with the legacy NfcRenderingTemplate2024 format.

Disclaimer: I will remove the commented code in helper.js once approved and before merging.

Implements NFC rendering support for verifiable credentials following the W3C VC Rendering Methods specification. Provides both static and dynamic rendering modes: - Static mode: Decodes pre-encoded payloads from template/payload fields - Dynamic mode: Extracts credential data using JSON pointer paths - Supports multibase (base58/base64url) and data URI encoding - Compatible with W3C spec renderSuite types (nfc, nfc-static, nfc-dynamic) - Maintains backward compatibility with legacy NfcRenderingTemplate2024 Public API includes supportsNFC() to check NFC capability and renderToNfc() to generate NFC payload bytes from credentials.

Implements test suite covering NFC rendering functionality: - Tests supportsNFC() with various renderSuite configurations - Tests renderToNfc() static rendering with multibase, base64url, and data URIs - Tests renderToNfc() dynamic rendering with renderProperty extraction - Tests EAD credential handling with single/multiple field extraction - Tests legacy NfcRenderingTemplate2024 type compatibility - Tests error handling for invalid credentials and missing parameters - Includes real-world credential tests fetched from external sources Ensures compliance with W3C VC Rendering Methods specification.

Replaces legacy NFC rendering implementation in helper.js with calls to the new standardized nfcRenderer library functions: - Replace toNFCPayload() implementation with renderToNfc() call - Replace hasNFCPayload() implementation with supportsNFC() call - Remove unused base58 and base64url imports - Comment out legacy helper functions: _getNFCRenderingTemplate2024() and _decodeMultibase() - Comment out multibaseDecoders constant (now handled in nfcRenderer.js) This change consolidates NFC rendering logic into a single reusable library while maintaining backward compatibility with existing API. The new implementation supports both W3C spec formats and legacy NfcRenderingTemplate2024 type.

Implements field validation: - TemplateRenderMethod: requires 'template' field only (W3C spec) - NfcRenderingTemplate2024: requires 'payload' field only (legacy) - Rejects credentials with both fields present Updates _renderStatic() and _hasStaticPayload() functions with explicit field checking and clear error messages. Adds comprehensive validation tests and fixes existing tests to use correct fields for their respective render method types.

bparth24 · 2025-11-15T03:14:39Z

@BigBlueHat cc: @dlongley

I have enforced some level of type compliance for template and payload field in this commit - 83386f1.

Replace separate static/dynamic rendering with unified pipeline where template is always required and renderProperty validates credential fields. Update implementation and tests to reflect single rendering flow: filter credential -> decode template -> return bytes. Changes: - Consolidate rendering functions into _decodeTemplateToBytes(). - Add _filterCredential() for renderProperty validation. - Remove obsolete static vs dynamic distinction. - Update all tests to match unified architecture. - Fix test encodings and add comprehensive error coverage.

dlongley · 2025-11-21T19:24:57Z

lib/helpers.js

+// import * as base58 from 'base58-universal';
+// import * as base64url from 'base64url-universal';


Can you remove all the commented stuff here and below so it's easier to understand what would be approved and get merged?

Sorry, just saw the "disclaimer" above.

EDIT: Though, I still think it would be better to remove before approval so it's easier to review and to understand what will get merged.

dlongley · 2025-11-21T19:26:21Z

lib/nfcRenderer.js

+    if(renderMethod !== null) {
+      return true;
+    }
+    // no NFC render method found
+    return false;


Suggested change

if(renderMethod !== null) {

return true;

}

// no NFC render method found

return false;

// return whether any NFC render method was found

return renderMethod !== null;

dlongley · 2025-11-21T19:26:48Z

lib/nfcRenderer.js

+export function supportsNFC({credential} = {}) {
+  try {
+    const renderMethod = _findNFCRenderMethod({credential});


Our naming convention is usually camel case (and this will make it consistent with renderToNfc() below):

Suggested change

export function supportsNFC({credential} = {}) {

try {

const renderMethod = _findNFCRenderMethod({credential});

export function supportsNfc({credential} = {}) {

try {

const renderMethod = _findNfcRenderMethod({credential});

dlongley · 2025-11-21T19:27:59Z

lib/nfcRenderer.js

+      'The verifiable credential does not support NFC rendering.'
+    );


Linting should be catching this, so we might be missing a rule:

Suggested change

'The verifiable credential does not support NFC rendering.'

);

'The verifiable credential does not support NFC rendering.');

dlongley · 2025-11-21T19:30:16Z

lib/nfcRenderer.js

+    throw new Error(
+      'NFC rendering requires a template field. ' +
+      'The template should contain the pre-encoded NFC payload.'
+    );


This message will get out-of-date if a template becomes something other than a "pre-encoded NFC payload" (and same linting issue as above with dropped lonely parenthesis):

Suggested change

throw new Error(

'NFC rendering requires a template field. ' +

'The template should contain the pre-encoded NFC payload.'

);

throw new Error('NFC render method is missing the "template" field.');

Though, on second thought, I think the _findNfcRenderMethod should probably only find valid NFC render methods. Maybe we'd want to console.warn() any invalid methods found, but that might be better than turning on UI elements that won't work anyway ... this is debatable / would love to hear more opinions. We can leave it how it is now (where "inoperable"/"invalid" NFC render methods are still "found") until we decide to change this.

dlongley · 2025-11-21T19:41:52Z

lib/nfcRenderer.js

+    // validate: should not have both fields
+    if(renderMethod.template && renderMethod.payload) {
+      throw new Error(
+        'TemplateRenderMethod requires "template". ' +
+        'It should not have both fields.'
+      );
+    }
+


Note that the error text below might be confusing to a reader, i.e, "What two fields?". However, for TemplateRenderMethod, payload isn't specified at all (in the spec) and we don't expect it to be, so it would just be ignored. I had mentioned before this might be an error case, but I think that would have only been for the legacy NFC render (2024) method ... but I don't think it ever used template. In other words, I suspect we don't have to check for the case where both appear at all, it's an "ignore unknown fields" case for both the modern renderer and the legacy one.

Suggested change

// validate: should not have both fields

if(renderMethod.template && renderMethod.payload) {

throw new Error(

'TemplateRenderMethod requires "template". ' +

'It should not have both fields.'

);

}

dlongley · 2025-11-21T19:43:41Z

lib/nfcRenderer.js

+    // validate: should not have both fields
+    if(renderMethod.template && renderMethod.payload) {
+      throw new Error(
+        'NfcRenderingTemplate2024 should not have both template ' +
+        'and payload fields.'
+      );
+    }


As mentioned above, unless there was ever legitimate use of "template" in an NfcRenderingTemplate2024 renderer, we should treat the presence of both properties as an "ignore unknown field" case. Only if we ever defined "template" and used it in the absence of "payload" should we throw here -- so if we don't have that case, we actually shouldn't throw this error.

Suggested change

// validate: should not have both fields

if(renderMethod.template && renderMethod.payload) {

throw new Error(

'NfcRenderingTemplate2024 should not have both template ' +

'and payload fields.'

);

}

dlongley · 2025-11-21T19:44:19Z

lib/nfcRenderer.js

+
+  // validate template is a string
+  if(typeof encoded !== 'string') {
+    throw new Error('Template or payload must be a string.');


Suggested change

throw new Error('Template or payload must be a string.');

throw new TypeError('Template or payload must be a string.');

dlongley · 2025-11-21T19:48:53Z

lib/nfcRenderer.js

+function _base64ToBytes({base64String} = {}) {
+  // use atob in browser, Buffer in Node
+  if(typeof atob !== 'undefined') {
+    const binaryString = atob(base64String);
+    const bytes = new Uint8Array(binaryString.length);
+    for(let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  // Node.js environment
+  return Buffer.from(base64String, 'base64');
+}


This won't work -- static analyzers will see Buffer and inject a polyfill into the browser bundle. There are other patterns that solve this that we should use instead. The utilities have to be split and different aliased files loaded. For example:

https://github.com/digitalbazaar/http-digest-header/blob/v2.3.0/lib/util-browser.js
https://github.com/digitalbazaar/http-digest-header/blob/v2.3.0/lib/util.js

Also note the more modern API Uint8Array.toBase64.

dlongley · 2025-11-21T19:50:13Z

lib/nfcRenderer.js

+// ========================
+// JSON pointer utilities
+// ========================
+
+/**
+ * Resolve a JSON pointer in an object per RFC 6901.
+ *
+ * @private
+ * @param {object} options - Options object.
+ * @param {object} options.obj - The object to traverse.
+ * @param {string} options.pointer - JSON pointer string.
+ * @returns {*} The value at the pointer location or undefined.
+ */
+function _resolveJSONPointer({obj, pointer} = {}) {


This we really need to get into a shared library (or reuse an existing shared library that doesn't bring in any of its own problems).

bparth24 added 3 commits November 11, 2025 17:42

bparth24 requested review from BigBlueHat, dlongley, gannan08, jameseaster, msporny and tminard November 12, 2025 01:48

dlongley requested changes Nov 21, 2025

View reviewed changes

		// import * as base58 from 'base58-universal';
		// import * as base64url from 'base64url-universal';

		'The verifiable credential does not support NFC rendering.'
		);

	throw new Error('Template or payload must be a string.');
	throw new TypeError('Template or payload must be a string.');

nfc related support #93

Are you sure you want to change the base?

nfc related support #93

Uh oh!

Conversation

bparth24 commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bparth24 commented Nov 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dlongley Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bparth24 commented Nov 12, 2025 •

edited

Loading

dlongley Nov 21, 2025 •

edited

Loading