gdc-common-utils-ts 2.0.9 → 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/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.9",
+  "version": "2.0.10",
   "publishConfig": {
     "access": "public"
   },