@learncard/helpers 1.6.0 → 1.6.1

package/dist/index.d.cts

@@ -41,4 +41,5 @@ export * from './credential-format';
  * @returns true if the DID is an app did:web, false otherwise
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
+export * from './share-content-canonical';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -41,4 +41,5 @@ export * from './credential-format';
  * @returns true if the DID is an app did:web, false otherwise
  */
 export declare const isAppDidWeb: (did?: string) => boolean;
+export * from './share-content-canonical';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAgB,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,YAA6B,CAAC;AAE/D,8DAA8D;AAC9D,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,GAEnD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,OAAO,KAAG,OAQjD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,GAAI,KAAK,EAAE,GAAG,UAAU,QAMzD,CAAC;AAGF,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,eAAe,CAAC;AAG9B,cAAc,qBAAqB,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAK1C,CAAC;AAEF,cAAc,2BAA2B,CAAC"}

package/dist/share-content-canonical.d.ts

@@ -0,0 +1,13 @@
+/** C1 request serialization shared by the signing client and verifying service. */
+export declare const DEFAULT_MAX_CANONICAL_BYTES: number;
+export declare const DEFAULT_MAX_CANONICAL_DEPTH = 32;
+export declare class ShareContentCanonicalizationError extends Error {
+    readonly code = "UNSUPPORTED_REQUEST_VALUE";
+    constructor(message: string);
+}
+/** Deterministic UTF-8 canonical serialization of a request body. */
+export declare const canonicalizeShareContentRequestBody: (body: unknown, options?: {
+    maxBytes?: number;
+    maxDepth?: number;
+}) => string;
+//# sourceMappingURL=share-content-canonical.d.ts.map

package/dist/share-content-canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-content-canonical.d.ts","sourceRoot":"","sources":["../src/share-content-canonical.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,eAAO,MAAM,2BAA2B,QAAkB,CAAC;AAC3D,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAI9C,qBAAa,iCAAkC,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,OAAO,EAAE,MAAM;CAI9B;AAoGD,qEAAqE;AACrE,eAAO,MAAM,mCAAmC,GAC5C,MAAM,OAAO,EACb,UAAS;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,KACvD,MAUF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/helpers",
-    "version": "1.6.0",
+    "version": "1.6.1",
     "description": "Shared helpers for LearnCard packages",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -54,7 +54,7 @@
     "dependencies": {
         "@noble/hashes": "^1.8.0",
         "@sd-jwt/decode": "^0.19.0",
-        "@learncard/types": "5.21.0",
+        "@learncard/types": "5.22.0",
         "@trpc/server": "11.8.0",
         "immer": "^10.0.3",
         "use-immer": "^0.9.0",

package/src/index.ts

@@ -106,3 +106,5 @@ export const isAppDidWeb = (did?: string): boolean => {
     const LCN_APP_DID_WEB_REGEX = /^did:web:.*:app:([^:]+)$/;
     return LCN_APP_DID_WEB_REGEX.test(did);
 };
+
+export * from './share-content-canonical';

package/src/share-content-canonical.ts

@@ -0,0 +1,128 @@
+/** C1 request serialization shared by the signing client and verifying service. */
+export const DEFAULT_MAX_CANONICAL_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_MAX_CANONICAL_DEPTH = 32;
+
+const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+export class ShareContentCanonicalizationError extends Error {
+    readonly code = 'UNSUPPORTED_REQUEST_VALUE';
+
+    constructor(message: string) {
+        super(message);
+        this.name = 'ShareContentCanonicalizationError';
+    }
+}
+
+const serializeCanonical = (
+    value: unknown,
+    seen: Set<object>,
+    depth: number,
+    maxDepth: number
+): string => {
+    if (value === null) return 'null';
+
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+
+        case 'string': {
+            if (LONE_SURROGATE_RE.test(value)) {
+                throw new ShareContentCanonicalizationError(
+                    'string contains an unpaired surrogate'
+                );
+            }
+
+            return JSON.stringify(value);
+        }
+
+        case 'number': {
+            if (!Number.isSafeInteger(value) || Object.is(value, -0)) {
+                throw new ShareContentCanonicalizationError(
+                    'numbers must be safe integers without a negative-zero sign'
+                );
+            }
+
+            return String(value);
+        }
+
+        case 'object': {
+            if (depth >= maxDepth) {
+                throw new ShareContentCanonicalizationError(
+                    'value exceeds the maximum nesting depth'
+                );
+            }
+
+            if (seen.has(value)) {
+                throw new ShareContentCanonicalizationError('cyclic value is not supported');
+            }
+
+            seen.add(value);
+
+            try {
+                if (Array.isArray(value)) {
+                    const items: string[] = [];
+
+                    for (let index = 0; index < value.length; index += 1) {
+                        if (!(index in value)) {
+                            throw new ShareContentCanonicalizationError(
+                                'sparse arrays are not supported'
+                            );
+                        }
+
+                        items.push(serializeCanonical(value[index], seen, depth + 1, maxDepth));
+                    }
+
+                    return `[${items.join(',')}]`;
+                }
+
+                const prototype = Object.getPrototypeOf(value);
+
+                if (prototype !== Object.prototype && prototype !== null) {
+                    throw new ShareContentCanonicalizationError('only plain objects are supported');
+                }
+
+                const record = value as Record<string, unknown>;
+
+                const entries = Object.keys(record)
+                    .sort()
+                    .map(key => {
+                        if (LONE_SURROGATE_RE.test(key)) {
+                            throw new ShareContentCanonicalizationError(
+                                'object key contains an unpaired surrogate'
+                            );
+                        }
+
+                        return `${JSON.stringify(key)}:${serializeCanonical(
+                            record[key],
+                            seen,
+                            depth + 1,
+                            maxDepth
+                        )}`;
+                    });
+
+                return `{${entries.join(',')}}`;
+            } finally {
+                seen.delete(value);
+            }
+        }
+
+        default:
+            throw new ShareContentCanonicalizationError(`unsupported value type: ${typeof value}`);
+    }
+};
+
+/** Deterministic UTF-8 canonical serialization of a request body. */
+export const canonicalizeShareContentRequestBody = (
+    body: unknown,
+    options: { maxBytes?: number; maxDepth?: number } = {}
+): string => {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_CANONICAL_BYTES;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_CANONICAL_DEPTH;
+    const serialized = serializeCanonical(body, new Set(), 0, maxDepth);
+
+    if (new TextEncoder().encode(serialized).byteLength > maxBytes) {
+        throw new ShareContentCanonicalizationError('canonical request exceeds the maximum size');
+    }
+
+    return serialized;
+};