gdc-common-utils-ts 2.0.8 → 2.0.10

package/README.md

@@ -136,6 +136,7 @@ If you need the canonical explanation of how DIDComm envelope, batch body,
 entry types, FHIR-like resources, and `resource.meta.claims` fit together,
 read first:
 
+- [`docs/101-ID_TOKEN.md`](docs/101-ID_TOKEN.md)
 - [`docs/101-COMMUNICATION_LAYERING.md`](docs/101-COMMUNICATION_LAYERING.md)
 - [`docs/101-BUNDLE_EDITOR_READER.md`](docs/101-BUNDLE_EDITOR_READER.md)
 - [`docs/101-CLINICAL-IPS.md`](docs/101-CLINICAL-IPS.md)

package/dist/examples/organization-controller.d.ts

@@ -127,7 +127,26 @@ export declare const EXAMPLE_EMPLOYEE_DEVICE_ACTIVATION_INPUT: {
     readonly activationCode: "ACT-001";
     readonly idToken: "employee-id-token-001";
     readonly dcrPayload: {
-        readonly application_type: "web";
+        readonly application_type: "native";
+        readonly client_name: "Acme Controller App";
+        readonly redirect_uris: readonly ["acme-controller://callback"];
+        readonly jwks: {
+            readonly keys: readonly [{
+                readonly kid: "controller-didcomm-enc-001";
+                readonly kty: "EC";
+                readonly crv: "P-384";
+                readonly x: "<enc-x>";
+                readonly y: "<enc-y>";
+                readonly use: "enc";
+                readonly purposes: readonly ["didcomm-enc"];
+            }];
+        };
+        readonly ext_device_info: {
+            readonly push_token: "ExponentPushToken[example-controller]";
+            readonly push_provider: "expo";
+            readonly device_id: "device-controller-001";
+            readonly device_name: "Controller iPhone";
+        };
     };
 };
 export declare const EXAMPLE_EMPLOYEE_DEVICE_EXCHANGE_RESPONSE: {

package/dist/examples/organization-controller.js

@@ -79,7 +79,16 @@ export const EXAMPLE_EMPLOYEE_DEVICE_ACTIVATION_INPUT = {
     activationCode: EXAMPLE_EMPLOYEE_ACTIVATION_CODE,
     idToken: 'employee-id-token-001',
     dcrPayload: {
-        application_type: 'web',
+        application_type: 'native',
+        client_name: 'Acme Controller App',
+        redirect_uris: ['acme-controller://callback'],
+        jwks: EXAMPLE_CONTROLLER_BINDING.jwks,
+        ext_device_info: {
+            push_token: 'ExponentPushToken[example-controller]',
+            push_provider: 'expo',
+            device_id: 'device-controller-001',
+            device_name: 'Controller iPhone',
+        },
     },
 };
 export const EXAMPLE_EMPLOYEE_DEVICE_EXCHANGE_RESPONSE = {

package/dist/models/interoperable-claims/observation-claims.d.ts

@@ -41,6 +41,11 @@ export declare const ObservationClaim: {
     readonly CodeValue: "Observation.code-value";
     /** Local-language label used by UI/forms. Example: `Heart rate`. */
     readonly CodeText: "Observation.code-text";
+    /**
+     * Naming alias for `Observation.code-text` when the caller wants the
+     * setter/getter name to make the local-text intent explicit.
+     */
+    readonly CodeTextLocal: "Observation.code-text";
     /** Canonical English/international display. Example: `Heart rate`. */
     readonly CodeDisplay: "Observation.code-display";
     /** Observation or component code as `system|code`. Example: `http://loinc.org|8867-4`. */

package/dist/models/interoperable-claims/observation-claims.js

@@ -43,6 +43,11 @@ export const ObservationClaim = {
     CodeValue: 'Observation.code-value',
     /** Local-language label used by UI/forms. Example: `Heart rate`. */
     CodeText: 'Observation.code-text',
+    /**
+     * Naming alias for `Observation.code-text` when the caller wants the
+     * setter/getter name to make the local-text intent explicit.
+     */
+    CodeTextLocal: 'Observation.code-text',
     /** Canonical English/international display. Example: `Heart rate`. */
     CodeDisplay: 'Observation.code-display',
     /** Observation or component code as `system|code`. Example: `http://loinc.org|8867-4`. */

package/dist/utils/bundle-editor.d.ts

@@ -235,8 +235,23 @@ export declare class ObservationComponentEntryEditor extends BundleEntryEditor {
     getCodeValue(): string | undefined;
     setCodeDisplay(display: string): this;
     getCodeDisplay(): string | undefined;
-    /** Local-language label intended for forms and local UI. */
+    /**
+     * Stores the local-language label used by forms and local UI copy.
+     *
+     * Keep this distinct from `setCodeDisplay(...)`, which is the canonical
+     * English/international display carried by the coded concept.
+     */
+    setCodeTextLocal(text: string): this;
+    /**
+     * Returns the local-language label used by forms and local UI copy.
+     *
+     * Keep this distinct from `getCodeDisplay()`, which returns the canonical
+     * English/international display when present.
+     */
+    getCodeTextLocal(): string | undefined;
+    /** Compatibility alias for older examples/tests. Prefer `setCodeTextLocal(...)`. */
     setLocalText(text: string): this;
+    /** Compatibility alias for older examples/tests. Prefer `getCodeTextLocal()`. */
     getLocalText(): string | undefined;
     setValueQuantityNumber(value: number): this;
     getValueQuantityNumber(): number | undefined;

package/dist/utils/bundle-editor.js

@@ -724,13 +724,32 @@ export class ObservationComponentEntryEditor extends BundleEntryEditor {
     getCodeDisplay() {
         return normalizeOptionalIdentifier(this.getClaim(ObservationClaim.CodeDisplay));
     }
-    /** Local-language label intended for forms and local UI. */
-    setLocalText(text) {
+    /**
+     * Stores the local-language label used by forms and local UI copy.
+     *
+     * Keep this distinct from `setCodeDisplay(...)`, which is the canonical
+     * English/international display carried by the coded concept.
+     */
+    setCodeTextLocal(text) {
         return this.setClaim(ObservationClaim.CodeText, String(text).trim());
     }
-    getLocalText() {
+    /**
+     * Returns the local-language label used by forms and local UI copy.
+     *
+     * Keep this distinct from `getCodeDisplay()`, which returns the canonical
+     * English/international display when present.
+     */
+    getCodeTextLocal() {
         return normalizeOptionalIdentifier(this.getClaim(ObservationClaim.CodeText));
     }
+    /** Compatibility alias for older examples/tests. Prefer `setCodeTextLocal(...)`. */
+    setLocalText(text) {
+        return this.setCodeTextLocal(text);
+    }
+    /** Compatibility alias for older examples/tests. Prefer `getCodeTextLocal()`. */
+    getLocalText() {
+        return this.getCodeTextLocal();
+    }
     setValueQuantityNumber(value) {
         return this.setClaim(ObservationClaim.ValueQuantityNumber, String(value));
     }
@@ -841,7 +860,7 @@ export class VitalSignEntryEditor extends ObservationComponentEntryEditor {
         this.setCodeValue(code.code);
         if (code.display) {
             this.setCodeDisplay(code.display);
-            this.setLocalText(code.display);
+            this.setCodeTextLocal(code.display);
         }
         if (unit) {
             this.setValueQuantityUnit(unit);

package/dist/utils/communication-attached-bundle-session.d.ts

@@ -142,20 +142,32 @@ export declare class CommunicationAttachedBundleSession {
     getBundleInMemory(): BundleJsonApi<BundleEntry>;
     /** Returns the active entry index, or null when no entry is selected. */
     getActiveEntryIndex(): number | null;
+    /** Alias of `getActiveEntryIndex()` with entry-selection wording. */
+    getSelectedEntryIndex(): number | null;
     /** Returns a deep copy of the active entry when selected. */
     getActiveEntry(): BundleEntry | null;
+    /** Alias of `getActiveEntry()` with entry-selection wording. */
+    getSelectedEntry(): BundleEntry | null;
     /** Returns one claim from the currently selected active entry. */
     getActiveEntryClaim(key: string): unknown;
+    /** Alias of `getActiveEntryClaim()` with entry-selection wording. */
+    getSelectedEntryClaim(key: string): unknown;
     /** Returns whether the currently selected active entry carries one claim key. */
     hasActiveEntryClaim(key: string): boolean;
+    /** Alias of `hasActiveEntryClaim()` with entry-selection wording. */
+    hasSelectedEntryClaim(key: string): boolean;
     /** Sets one claim on the currently selected active entry and syncs the bundle attachment. */
     setActiveEntryClaim(key: string, value: unknown): this;
+    /** Alias of `setActiveEntryClaim()` with entry-selection wording. */
+    setSelectedEntryClaim(key: string, value: unknown): this;
     /** Appends one claim value on the currently selected active entry and syncs the bundle attachment. */
     addActiveEntryClaim(key: string, value: unknown): this;
     /** Removes one claim from the currently selected active entry and syncs the bundle attachment. */
     removeActiveEntryClaim(key: string): this;
     /** Selects an active entry by index or fullUrl. */
     selectActiveEntry(selection: ActiveEntrySelection): this;
+    /** Alias of `selectActiveEntry()` with entry-selection wording. */
+    selectEntry(selection: ActiveEntrySelection): this;
     /** Clears active entry selection from memory. */
     clearActiveEntry(): this;
     /**

package/dist/utils/communication-attached-bundle-session.js

@@ -64,6 +64,10 @@ export class CommunicationAttachedBundleSession {
     getActiveEntryIndex() {
         return this.activeEntryIndex;
     }
+    /** Alias of `getActiveEntryIndex()` with entry-selection wording. */
+    getSelectedEntryIndex() {
+        return this.getActiveEntryIndex();
+    }
     /** Returns a deep copy of the active entry when selected. */
     getActiveEntry() {
         if (this.activeEntryIndex === null) {
@@ -71,16 +75,28 @@ export class CommunicationAttachedBundleSession {
         }
         return cloneEntry(this.bundleInMemory.data[this.activeEntryIndex]);
     }
+    /** Alias of `getActiveEntry()` with entry-selection wording. */
+    getSelectedEntry() {
+        return this.getActiveEntry();
+    }
     /** Returns one claim from the currently selected active entry. */
     getActiveEntryClaim(key) {
         const claims = this.getRequiredActiveEntryClaims();
         return cloneUnknownValue(claims[key]);
     }
+    /** Alias of `getActiveEntryClaim()` with entry-selection wording. */
+    getSelectedEntryClaim(key) {
+        return this.getActiveEntryClaim(key);
+    }
     /** Returns whether the currently selected active entry carries one claim key. */
     hasActiveEntryClaim(key) {
         const claims = this.getRequiredActiveEntryClaims();
         return Object.prototype.hasOwnProperty.call(claims, key);
     }
+    /** Alias of `hasActiveEntryClaim()` with entry-selection wording. */
+    hasSelectedEntryClaim(key) {
+        return this.hasActiveEntryClaim(key);
+    }
     /** Sets one claim on the currently selected active entry and syncs the bundle attachment. */
     setActiveEntryClaim(key, value) {
         const current = cloneEntry(this.getRequiredActiveEntry());
@@ -95,6 +111,10 @@ export class CommunicationAttachedBundleSession {
         this.syncAttachmentFromBundle();
         return this;
     }
+    /** Alias of `setActiveEntryClaim()` with entry-selection wording. */
+    setSelectedEntryClaim(key, value) {
+        return this.setActiveEntryClaim(key, value);
+    }
     /** Appends one claim value on the currently selected active entry and syncs the bundle attachment. */
     addActiveEntryClaim(key, value) {
         const current = cloneEntry(this.getRequiredActiveEntry());
@@ -152,6 +172,10 @@ export class CommunicationAttachedBundleSession {
         }
         throw new Error('selectActiveEntry requires either index or fullUrl.');
     }
+    /** Alias of `selectActiveEntry()` with entry-selection wording. */
+    selectEntry(selection) {
+        return this.selectActiveEntry(selection);
+    }
     /** Clears active entry selection from memory. */
     clearActiveEntry() {
         this.activeEntryIndex = null;

package/dist/utils/jwt.d.ts

@@ -51,6 +51,53 @@ export declare function encodeSignature(signatureBytes?: Uint8Array): string;
  * @returns A compact JWT string.
  */
 export declare function compactJWT(header: object, payload: object, signatureBytes?: Uint8Array): Promise<string>;
+/**
+ * Prepares the JOSE compact-signing input for an externally signed JWT/JWS.
+ *
+ * This helper is intended for BFF, wallet, Expo/native, or server-side flows
+ * where the signing key lives in an external KMS/HSM and the application must:
+ *
+ * 1. build the protected header and JWT payload locally
+ * 2. obtain the canonical `base64url(header).base64url(payload)` string
+ * 3. sign that exact byte sequence with the external signer
+ * 4. assemble the final compact JWS/JWT by appending the returned signature
+ *
+ * References:
+ * - RFC 7515 (JWS), Compact Serialization
+ * - RFC 7519 (JWT)
+ * - OpenID Connect Core 1.0 (`id_token` profile claims such as `email`)
+ *
+ * Note:
+ * - this helper only prepares the compact signing input
+ * - it does not verify that the payload is a particular profile such as
+ *   `vp_token`, `id_token`, or `private_key_jwt`
+ */
+export declare function prepareJwtForSignature(header: object, payload: object): {
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+};
+/**
+ * Returns the UTF-8 bytes of the canonical compact JWT/JWS signing input.
+ *
+ * This is the exact byte sequence that an external signer must sign before the
+ * caller assembles the final compact JWT string with
+ * `buildJwtCompact(...)`.
+ */
+export declare function prepareJwtBytesForSignature(header: object, payload: object): Uint8Array;
+/**
+ * Assembles the final compact JWT/JWS once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ *
+ * This helper is profile-agnostic. It can be used for:
+ * - OpenID Connect `id_token`
+ * - `vp_token`
+ * - other compact JWS/JWT profiles that follow RFC 7515 / RFC 7519
+ */
+export declare function buildJwtCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string;
 /**
  * Builds an unsigned compact JWT with `alg=none`.
  *

package/dist/utils/jwt.js

@@ -152,6 +152,62 @@ export async function compactJWT(header, payload, signatureBytes) {
     const encodedSignature = encodeSignature(signatureBytes);
     return `${encodedHeader}.${encodedPayload}.${encodedSignature}`;
 }
+/**
+ * Prepares the JOSE compact-signing input for an externally signed JWT/JWS.
+ *
+ * This helper is intended for BFF, wallet, Expo/native, or server-side flows
+ * where the signing key lives in an external KMS/HSM and the application must:
+ *
+ * 1. build the protected header and JWT payload locally
+ * 2. obtain the canonical `base64url(header).base64url(payload)` string
+ * 3. sign that exact byte sequence with the external signer
+ * 4. assemble the final compact JWS/JWT by appending the returned signature
+ *
+ * References:
+ * - RFC 7515 (JWS), Compact Serialization
+ * - RFC 7519 (JWT)
+ * - OpenID Connect Core 1.0 (`id_token` profile claims such as `email`)
+ *
+ * Note:
+ * - this helper only prepares the compact signing input
+ * - it does not verify that the payload is a particular profile such as
+ *   `vp_token`, `id_token`, or `private_key_jwt`
+ */
+export function prepareJwtForSignature(header, payload) {
+    const encodedHeader = encodeHeader(header);
+    const encodedPayload = Content.objectToRawBase64UrlSafe(payload);
+    return {
+        encodedHeader,
+        encodedPayload,
+        signingInput: `${encodedHeader}.${encodedPayload}`,
+    };
+}
+/**
+ * Returns the UTF-8 bytes of the canonical compact JWT/JWS signing input.
+ *
+ * This is the exact byte sequence that an external signer must sign before the
+ * caller assembles the final compact JWT string with
+ * `buildJwtCompact(...)`.
+ */
+export function prepareJwtBytesForSignature(header, payload) {
+    const { signingInput } = prepareJwtForSignature(header, payload);
+    return new TextEncoder().encode(signingInput);
+}
+/**
+ * Assembles the final compact JWT/JWS once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ *
+ * This helper is profile-agnostic. It can be used for:
+ * - OpenID Connect `id_token`
+ * - `vp_token`
+ * - other compact JWS/JWT profiles that follow RFC 7515 / RFC 7519
+ */
+export function buildJwtCompact(encodedHeader, encodedPayload, signatureBase64Url) {
+    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+}
 /**
  * Builds an unsigned compact JWT with `alg=none`.
  *

package/dist/utils/vp-token.js

@@ -1,5 +1,4 @@
-// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
-import { Content } from './content.js';
+import { buildJwtCompact, prepareJwtBytesForSignature, prepareJwtForSignature } from './jwt.js';
 import { ORGANIZATION_ACTIVATION_VC_TYPES, REPRESENTATIVE_ACTIVATION_VC_TYPES, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
 function fallbackId() {
     const rand = Math.random().toString(36).slice(2, 10);
@@ -224,13 +223,7 @@ export function addLegalRepresentativeCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...REPRESENTATIVE_ACTIVATION_VC_TYPES], 'LegalRepresentative');
 }
 export function prepareForSignature(header, payload) {
-    const encodedHeader = Content.objectToRawBase64UrlSafe(header);
-    const encodedPayload = Content.objectToRawBase64UrlSafe(payload);
-    return {
-        encodedHeader,
-        encodedPayload,
-        signingInput: `${encodedHeader}.${encodedPayload}`,
-    };
+    return prepareJwtForSignature(header, payload);
 }
 /**
  * Returns the UTF-8 bytes of the canonical `base64url(header).base64url(payload)`
@@ -241,8 +234,7 @@ export function prepareForSignature(header, payload) {
  * `buildVpTokenCompact(...)`.
  */
 export function prepareBytesForSignature(header, payload) {
-    const { signingInput } = prepareForSignature(header, payload);
-    return new TextEncoder().encode(signingInput);
+    return prepareJwtBytesForSignature(header, payload);
 }
 /**
  * Assembles the final compact VP JWT once the caller already has:
@@ -252,5 +244,5 @@ export function prepareBytesForSignature(header, payload) {
  * - the detached signature returned by the external signer, also base64url-encoded
  */
 export function buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url) {
-    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+    return buildJwtCompact(encodedHeader, encodedPayload, signatureBase64Url);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "publishConfig": {
     "access": "public"
   },