@learncard/helpers 1.5.1 → 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.5.1",
+    "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.20.0",
+        "@learncard/types": "5.22.0",
         "@trpc/server": "11.8.0",
         "immer": "^10.0.3",
         "use-immer": "^0.9.0",

package/src/credential-refresh.ts

@@ -1,5 +1,7 @@
 import {
+    ManagedCredentialRefreshServiceValidator,
     SupportedCredentialRefreshServiceValidator,
+    type ManagedCredentialRefreshService,
     type SupportedCredentialRefreshService,
 } from '@learncard/types';
 
@@ -105,6 +107,262 @@ export const canonicalizeCredentialContent = <T>(value: T): T => {
 export const canonicalizeCredentialJson = (value: unknown): string =>
     JSON.stringify(canonicalizeCredentialContent(value));
 
+// --- Managed refresh JSON-LD context preparation (LC-2198) --------------------
+
+/** Term used by the LearnCard-managed refresh service type. */
+const MANAGED_REFRESH_TYPE_TERM = 'LearnCardCredentialRefresh2026';
+
+/** Term for the LearnCard DID-auth extension inside a managed refresh service. */
+const MANAGED_REFRESH_DID_AUTH_TERM = 'LearnCardDIDAuth';
+
+/** IRI the managed refresh service type term must resolve to. */
+export const MANAGED_REFRESH_TYPE_IRI =
+    'https://learncard.com/refresh#LearnCardCredentialRefresh2026';
+
+/** OBv3-namespaced IRI for the authorization term of a managed refresh service. */
+export const MANAGED_REFRESH_AUTHORIZATION_IRI =
+    'https://purl.imsglobal.org/spec/ob/v3p0#authorization';
+
+/** IRI for the LearnCard DID-auth scheme of a managed refresh service. */
+export const MANAGED_REFRESH_DID_AUTH_IRI =
+    'https://docs.learncard.com/definitions#LearnCardDIDAuth';
+
+/**
+ * Inline JSON-LD context fragment required to sign credentials carrying a
+ * LearnCard-managed `LearnCardCredentialRefresh2026` refresh service.
+ *
+ * Neither VCDM 1.1 (which defines only `ManualRefreshService2018`), VCDM 2.0, nor the
+ * live OBv3/CLR contexts define the term `LearnCardCredentialRefresh2026` (nor the
+ * LearnCard `authorization` / `LearnCardDIDAuth` extension terms), so DIDKit's
+ * data-loss detection refuses to sign unless issuers define these terms inline.
+ */
+export const MANAGED_REFRESH_SERVICE_CONTEXT = {
+    [MANAGED_REFRESH_TYPE_TERM]: MANAGED_REFRESH_TYPE_IRI,
+    authorization: {
+        '@id': MANAGED_REFRESH_AUTHORIZATION_IRI,
+        '@context': { [MANAGED_REFRESH_DID_AUTH_TERM]: MANAGED_REFRESH_DID_AUTH_IRI },
+    },
+} as const;
+
+type ContextObject = Record<string, unknown>;
+
+type CredentialWithOptionalRefreshService = {
+    refreshService?: unknown;
+};
+
+const isPlainObject = (value: unknown): value is ContextObject =>
+    !!value && typeof value === 'object' && !Array.isArray(value);
+
+/** `"iri"` and `{ "@id": "iri" }` are the same JSON-LD term definition. */
+const toIdForm = (definition: unknown): unknown =>
+    typeof definition === 'string' ? { '@id': definition } : definition;
+
+/** Extracts the `@id` of a term definition, accounting for the string shorthand. */
+const definitionId = (definition: unknown): unknown => {
+    const idForm = toIdForm(definition);
+
+    return isPlainObject(idForm) ? idForm['@id'] : undefined;
+};
+
+/**
+ * Effective (last-wins) definition of a term across the credential's inline context
+ * objects. Only top-level context objects participate: nested `@context` blocks scope
+ * to their term's value and cannot redefine unrelated terms.
+ */
+const findTopLevelDefinition = (contextObjects: ContextObject[], term: string): unknown => {
+    let found: unknown;
+
+    for (const contextObject of contextObjects) {
+        if (term in contextObject) found = contextObject[term];
+    }
+
+    return found;
+};
+
+/** Ensures an existing term definition resolves to the expected IRI, or throws. */
+const assertDefinitionMatchesIri = (term: string, definition: unknown, expectedIri: string) => {
+    const actualIri = definitionId(definition);
+
+    if (actualIri !== expectedIri) {
+        throw new Error(
+            `Conflicting JSON-LD definition for term "${term}": expected "${expectedIri}" but the credential already defines it as ${JSON.stringify(
+                definition
+            )}. Remove or correct the existing definition before signing.`
+        );
+    }
+};
+
+/**
+ * Returns the LearnCard-managed refresh services carried by a credential.
+ *
+ * Accepts a single service object or an array; standard 1EdTech services and unknown
+ * entries are ignored.
+ */
+export const getManagedRefreshServices = (
+    vc: CredentialWithOptionalRefreshService
+): ManagedCredentialRefreshService[] => {
+    const refreshService = vc?.refreshService;
+
+    if (!refreshService) return [];
+
+    const services = Array.isArray(refreshService) ? refreshService : [refreshService];
+
+    return services.flatMap(service => {
+        const parsed = ManagedCredentialRefreshServiceValidator.safeParse(service);
+
+        return parsed.success ? [parsed.data] : [];
+    });
+};
+
+/**
+ * Ensures a credential carrying a LearnCard-managed refresh service also carries the
+ * inline JSON-LD context needed to sign it.
+ *
+ * - Credentials without a managed service are returned **by reference**, untouched.
+ * - The input is never mutated; a shallow-extended copy is returned when a fragment
+ *   must be appended.
+ * - Equivalent existing definitions are idempotent (no duplicate fragment).
+ * - Incomplete mappings are completed with only the missing terms.
+ * - Conflicting definitions (same term, different IRI) throw a clear error instead of
+ *   silently signing an unexpected expansion.
+ */
+export const prepareManagedRefreshContext = <T>(credential: T): T => {
+    const source = credential as unknown as CredentialWithOptionalRefreshService;
+
+    if (getManagedRefreshServices(source).length === 0) return credential;
+
+    const existingContext = (credential as unknown as ContextObject)['@context'];
+    const contextList: unknown[] =
+        existingContext === undefined || existingContext === null
+            ? []
+            : Array.isArray(existingContext)
+              ? [...existingContext]
+              : [existingContext];
+    const inlineObjects = contextList.filter(isPlainObject);
+
+    const fragment: Record<string, unknown> = {};
+
+    // Managed refresh service type term
+    const typeDefinition = findTopLevelDefinition(inlineObjects, MANAGED_REFRESH_TYPE_TERM);
+
+    if (typeDefinition === undefined) {
+        fragment[MANAGED_REFRESH_TYPE_TERM] = MANAGED_REFRESH_TYPE_IRI;
+    } else {
+        assertDefinitionMatchesIri(
+            MANAGED_REFRESH_TYPE_TERM,
+            typeDefinition,
+            MANAGED_REFRESH_TYPE_IRI
+        );
+    }
+
+    // Authorization term (scopes the DID-auth term inside managed refresh services)
+    const authorizationDefinition = findTopLevelDefinition(inlineObjects, 'authorization');
+    let didAuthCovered = false;
+
+    if (authorizationDefinition === undefined) {
+        // Full definition, including the nested LearnCardDIDAuth scope.
+        fragment['authorization'] = MANAGED_REFRESH_SERVICE_CONTEXT.authorization;
+        didAuthCovered = true;
+    } else {
+        assertDefinitionMatchesIri(
+            'authorization',
+            authorizationDefinition,
+            MANAGED_REFRESH_AUTHORIZATION_IRI
+        );
+
+        if (
+            isPlainObject(authorizationDefinition) &&
+            isPlainObject(authorizationDefinition['@context'])
+        ) {
+            const scopedContext = authorizationDefinition['@context'];
+
+            if (MANAGED_REFRESH_DID_AUTH_TERM in scopedContext) {
+                assertDefinitionMatchesIri(
+                    MANAGED_REFRESH_DID_AUTH_TERM,
+                    scopedContext[MANAGED_REFRESH_DID_AUTH_TERM],
+                    MANAGED_REFRESH_DID_AUTH_IRI
+                );
+                didAuthCovered = true;
+            }
+        }
+    }
+
+    // LearnCardDIDAuth term (top-level fallback when not covered by authorization's scope)
+    if (!didAuthCovered) {
+        const didAuthDefinition = findTopLevelDefinition(
+            inlineObjects,
+            MANAGED_REFRESH_DID_AUTH_TERM
+        );
+
+        if (didAuthDefinition === undefined) {
+            fragment[MANAGED_REFRESH_DID_AUTH_TERM] = MANAGED_REFRESH_DID_AUTH_IRI;
+        } else {
+            assertDefinitionMatchesIri(
+                MANAGED_REFRESH_DID_AUTH_TERM,
+                didAuthDefinition,
+                MANAGED_REFRESH_DID_AUTH_IRI
+            );
+        }
+    }
+
+    if (Object.keys(fragment).length === 0) return credential;
+
+    return {
+        ...credential,
+        '@context': [...contextList, fragment],
+    } as T;
+};
+
+/**
+ * Injects an allocated managed refresh service into an unsigned credential so the
+ * service becomes part of the signed payload.
+ *
+ * The managed service is made primary: any existing refresh services (for example a
+ * standard `1EdTechCredentialRefresh` service) are kept unchanged after it. Injecting
+ * a second, different managed service is rejected. The required inline context is
+ * prepared via {@link prepareManagedRefreshContext}.
+ */
+export const injectManagedRefreshService = <T>(
+    credential: T,
+    refreshService: ManagedCredentialRefreshService
+): T => {
+    const service = ManagedCredentialRefreshServiceValidator.parse(refreshService);
+    const source = credential as unknown as ContextObject;
+
+    const existing = source['refreshService'];
+    const existingServices: unknown[] =
+        existing === undefined || existing === null
+            ? []
+            : Array.isArray(existing)
+              ? [...existing]
+              : [existing];
+
+    const existingManaged = getManagedRefreshServices({ refreshService: existingServices });
+
+    if (existingManaged.some(entry => entry.id !== service.id)) {
+        throw new Error(
+            'Credential already carries a different managed refresh service; a credential can only reference one managed refresh service.'
+        );
+    }
+
+    const nonManagedEntries = existingServices.filter(
+        entry => !ManagedCredentialRefreshServiceValidator.safeParse(entry).success
+    );
+
+    const mergedRefreshService: unknown =
+        existingServices.length === 0
+            ? service
+            : !Array.isArray(existing) && existingManaged.length > 0
+              ? // Re-injecting the same managed service: keep object form (idempotent)
+                service
+              : [service, ...nonManagedEntries];
+
+    return prepareManagedRefreshContext({
+        ...credential,
+        refreshService: mergedRefreshService,
+    } as T);
+};
+
 /**
  * Proof-insensitive content comparison for refresh changed-content detection.
  *

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;
+};