@sd-jwt/core 0.19.1-next.1 → 0.19.1-next.11

package/README.md

@@ -9,7 +9,9 @@
 
 ### About
 
-Core library for selective disclosure JWTs
+Core library for [Selective Disclosure for JWTs (SD-JWT) — RFC 9901](https://www.rfc-editor.org/rfc/rfc9901.html).
+
+This package provides types, utilities, encoding/decoding, presentation, and the main `SDJwtInstance` class — everything needed to issue, present, and verify SD-JWTs.
 
 Check the detail description in our github [repo](https://github.com/openwallet-foundation/sd-jwt-js).
 
@@ -37,7 +39,68 @@ If you want to use the pure sd-jwt class or implement your own sd-jwt credential
 
 ### Dependencies
 
-- @sd-jwt/decode
-- @sd-jwt/present
-- @sd-jwt/types
-- @sd-jwt/utils
+- [@owf/identity-common](https://www.npmjs.com/package/@owf/identity-common)
+
+### Verification
+
+The library provides two verification approaches:
+
+#### Standard Verification (Fail-Fast)
+
+The `verify()` method throws an error immediately when the first validation failure is encountered:
+
+```typescript
+try {
+  const result = await sdjwt.verify(credential);
+  console.log('Verified payload:', result.payload);
+} catch (error) {
+  console.error('Verification failed:', error.message);
+}
+```
+
+#### Safe Verification (Collect All Errors)
+
+The `safeVerify()` method collects all validation errors instead of failing on the first one. This is useful when you want to show users all issues with a credential at once:
+
+```typescript
+import type { SafeVerifyResult, VerificationError } from '@sd-jwt/core';
+
+const result = await sdjwt.safeVerify(credential);
+
+if (result.success) {
+  // Verification succeeded
+  console.log('Verified payload:', result.data.payload);
+  console.log('Header:', result.data.header);
+  if (result.data.kb) {
+    console.log('Key binding:', result.data.kb);
+  }
+} else {
+  // Verification failed - inspect all errors
+  for (const error of result.errors) {
+    console.error(`[${error.code}] ${error.message}`);
+    if (error.details) {
+      console.error('Details:', error.details);
+    }
+  }
+}
+```
+
+##### Error Codes
+
+The `safeVerify()` method returns errors with the following codes:
+
+| Code | Description |
+|------|-------------|
+| `HASHER_NOT_FOUND` | Hasher function not configured |
+| `VERIFIER_NOT_FOUND` | Verifier function not configured |
+| `INVALID_SD_JWT` | SD-JWT structure is invalid or cannot be decoded |
+| `INVALID_JWT_FORMAT` | JWT format is malformed |
+| `JWT_NOT_YET_VALID` | JWT `iat` or `nbf` claim is in the future |
+| `JWT_EXPIRED` | JWT `exp` claim is in the past |
+| `INVALID_JWT_SIGNATURE` | Signature verification failed |
+| `MISSING_REQUIRED_CLAIMS` | Required claim keys are not present |
+| `KEY_BINDING_JWT_MISSING` | Key binding JWT required but not present |
+| `KEY_BINDING_VERIFIER_NOT_FOUND` | Key binding verifier not configured |
+| `KEY_BINDING_SIGNATURE_INVALID` | Key binding signature verification failed |
+| `KEY_BINDING_SD_HASH_INVALID` | Key binding `sd_hash` does not match |
+| `UNKNOWN_ERROR` | An unexpected error occurred |

package/dist/index.d.mts

@@ -1,6 +1,224 @@
-import * as _sd_jwt_types from '@sd-jwt/types';
-import { Signer, Base64urlString, Verifier, kbHeader, kbPayload, KbVerifier, JwtPayload, SDJWTCompact, Hasher, PresentationFrame, DisclosureFrame, HasherAndAlg, SaltGenerator, SDJWTConfig, KBOptions } from '@sd-jwt/types';
-import { Disclosure } from '@sd-jwt/utils';
+export { base64UrlToUint8Array, base64urlDecode, base64urlEncode, uint8ArrayToBase64Url } from '@owf/identity-common';
+
+declare const SD_SEPARATOR = "~";
+declare const SD_LIST_KEY = "...";
+declare const SD_DIGEST = "_sd";
+declare const SD_DECOY = "_sd_decoy";
+declare const KB_JWT_TYP = "kb+jwt";
+type SDJWTCompact = string;
+type Base64urlString = string;
+type DisclosureData<T> = [string, string, T] | [string, T];
+declare const IANA_HASH_ALGORITHMS: readonly ["sha-256", "sha-256-128", "sha-256-120", "sha-256-96", "sha-256-64", "sha-256-32", "sha-384", "sha-512", "sha3-224", "sha3-256", "sha3-384", "sha3-512", "blake2s-256", "blake2b-256", "blake2b-512", "k12-256", "k12-512"];
+type HashAlgorithm = (typeof IANA_HASH_ALGORITHMS)[number];
+type SDJWTConfig<T = unknown> = {
+    omitTyp?: boolean;
+    hasher?: Hasher;
+    hashAlg?: HashAlgorithm;
+    saltGenerator?: SaltGenerator;
+    signer?: Signer;
+    signAlg?: string;
+    verifier?: Verifier<T>;
+    kbSigner?: Signer;
+    kbSignAlg?: string;
+    kbVerifier?: KbVerifier;
+};
+type kbHeader = {
+    typ: 'kb+jwt';
+    alg: string;
+};
+type kbPayload = {
+    iat: number;
+    aud: string;
+    nonce: string;
+    sd_hash: string;
+};
+type KBOptions = {
+    payload: Omit<kbPayload, 'sd_hash'>;
+};
+interface RsaOtherPrimesInfo {
+    d?: string;
+    r?: string;
+    t?: string;
+}
+interface JsonWebKey {
+    alg?: string;
+    crv?: string;
+    d?: string;
+    dp?: string;
+    dq?: string;
+    e?: string;
+    ext?: boolean;
+    k?: string;
+    key_ops?: string[];
+    kty?: string;
+    n?: string;
+    oth?: RsaOtherPrimesInfo[];
+    p?: string;
+    q?: string;
+    qi?: string;
+    use?: string;
+    x?: string;
+    y?: string;
+}
+interface JwtPayload {
+    cnf?: {
+        jwk: JsonWebKey;
+    };
+    exp?: number;
+    [key: string]: unknown;
+}
+type OrPromise<T> = T | Promise<T>;
+type Signer = (data: string) => OrPromise<string>;
+type Verifier<T = unknown> = (data: string, sig: string, options?: T) => OrPromise<boolean>;
+type KbVerifier = (data: string, sig: string, payload: JwtPayload) => OrPromise<boolean>;
+type Hasher = (data: string | ArrayBuffer, alg: string) => OrPromise<Uint8Array>;
+type SaltGenerator = (length: number) => OrPromise<string>;
+type HasherAndAlg = {
+    hasher: Hasher;
+    alg: string;
+};
+type SignerSync = (data: string) => string;
+type VerifierSync = (data: string, sig: string) => boolean;
+type HasherSync = (data: string, alg: string) => Uint8Array;
+type SaltGeneratorSync = (length: number) => string;
+type HasherAndAlgSync = {
+    hasher: HasherSync;
+    alg: string;
+};
+type NonNever<T> = {
+    [P in keyof T as T[P] extends never ? never : P]: T[P];
+};
+type SD<Payload> = {
+    [SD_DIGEST]?: Array<keyof Payload>;
+};
+type DECOY = {
+    [SD_DECOY]?: number;
+};
+/**
+ * This is a disclosureFrame type that is used to represent the structure of what is being disclosed.
+ * DisclosureFrame is made from the payload type.
+ *
+ * For example, if the payload is
+ * {
+ *  foo: 'bar',
+ *  test: {
+ *   zzz: 'yyy',
+ *  }
+ *  arr: ['1', '2', {a: 'b'}]
+ * }
+ *
+ * The disclosureFrame can be subset of:
+ * {
+ *  _sd: ["foo", "test", "arr"],
+ *  test: {
+ *    _sd: ["zzz"],
+ *  },
+ *  arr: {
+ *    _sd: ["0", "1", "2"],
+ *    "2": {
+ *      _sd: ["a"],
+ *    }
+ *  }
+ * }
+ *
+ * The disclosureFrame can be used with decoy.
+ * Decoy can be used like this:
+ * {
+ *  ...
+ *  _sd: ...
+ *  _sd_decoy: 1 // number of decoy in this layer
+ * }
+ *
+ */
+type Frame<Payload> = Payload extends Array<infer U> ? U extends object ? Record<number, Frame<U>> & SD<Payload> & DECOY : SD<Payload> & DECOY : Payload extends Record<string, unknown> ? NonNever<{
+    [K in keyof Payload]?: NonNullable<Payload[K]> extends object ? Frame<Payload[K]> : never;
+} & SD<Payload> & DECOY> : SD<Payload> & DECOY;
+/**
+ * This is a disclosureFrame type that is used to represent the structure of what is being disclosed.
+ */
+type Extensible = Record<string, unknown | boolean>;
+type DisclosureFrame<T extends Extensible> = Frame<T>;
+/**
+ * This is a presentationFrame type that is used to represent the structure of what is being presented.
+ * PresentationFrame is made from the payload type.
+ * const claims = {
+      firstname: 'John',
+      lastname: 'Doe',
+      ssn: '123-45-6789',
+      id: '1234',
+      data: {
+        firstname: 'John',
+        lastname: 'Doe',
+        ssn: '123-45-6789',
+        list: [{ r: 'd' }, 'b', 'c'],
+        list2: ['1', '2', '3'],
+        list3: ['1', null, 2],
+      },
+      data2: {
+        hi: 'bye',
+      },
+    };
+
+  Example of a presentationFrame:
+  const presentationFrame: PresentationFrame<typeof claims> = {
+    firstname: true,
+    lastname: true,
+    ssn: true,
+    id: 'true',
+    data: {
+      firstname: true,
+      list: {
+        1: true,
+        0: {
+          r: true,
+        },
+      },
+      list2: {
+        1: true,
+      },
+      list3: true,
+    },
+    data2: true,
+  };
+*/
+type PFrame<Payload> = Payload extends Array<infer U> ? U extends object ? Record<number, PFrame<U> | boolean> | boolean : Record<number, boolean> | boolean : {
+    [K in keyof Payload]?: NonNullable<Payload[K]> extends object ? PFrame<Payload[K]> | boolean : boolean;
+};
+type PresentationFrame<T extends Extensible> = PFrame<T>;
+
+/**
+ * Error codes for SD-JWT verification errors.
+ */
+type VerificationErrorCode = 'HASHER_NOT_FOUND' | 'VERIFIER_NOT_FOUND' | 'INVALID_SD_JWT' | 'INVALID_JWT_FORMAT' | 'JWT_NOT_YET_VALID' | 'JWT_EXPIRED' | 'INVALID_JWT_SIGNATURE' | 'MISSING_REQUIRED_CLAIMS' | 'KEY_BINDING_JWT_MISSING' | 'KEY_BINDING_VERIFIER_NOT_FOUND' | 'KEY_BINDING_SIGNATURE_INVALID' | 'KEY_BINDING_SD_HASH_INVALID' | 'STATUS_VERIFICATION_FAILED' | 'STATUS_INVALID' | 'VCT_VERIFICATION_FAILED' | 'UNKNOWN_ERROR';
+/**
+ * Represents a single verification error.
+ */
+type VerificationError = {
+    /**
+     * The error code identifying the type of error.
+     */
+    code: VerificationErrorCode;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * Optional additional details about the error.
+     */
+    details?: unknown;
+};
+/**
+ * Result type for safe verification that collects all errors.
+ */
+type SafeVerifyResult<T> = {
+    success: true;
+    data: T;
+    errors?: never;
+} | {
+    success: false;
+    data?: never;
+    errors: VerificationError[];
+};
 
 type FlattenJSONData = {
     jwtData: {
@@ -156,8 +374,13 @@ declare class Jwt<Header extends Record<string, unknown> = Record<string, unknow
 declare class KBJwt<Header extends kbHeader = kbHeader, Payload extends kbPayload = kbPayload> extends Jwt<Header, Payload> {
     verifyKB(values: {
         verifier: KbVerifier;
-        payload: JwtPayload;
+        payload: Record<string, unknown>;
         nonce: string;
+        /**
+         * Options forwarded to the common JWT verification, e.g. currentDate and
+         * skewSeconds used to validate the iat, nbf and exp claims.
+         */
+        options?: VerifierOptions;
     }): Promise<{
         payload: Payload;
         header: Header;
@@ -165,6 +388,38 @@ declare class KBJwt<Header extends kbHeader = kbHeader, Payload extends kbPayloa
     static fromKBEncode<Header extends kbHeader = kbHeader, Payload extends kbPayload = kbPayload>(encodedJwt: string): KBJwt<Header, Payload>;
 }
 
+declare class Disclosure<T = unknown> {
+    salt: string;
+    key?: string;
+    value: T;
+    _digest: string | undefined;
+    private _encoded;
+    constructor(data: DisclosureData<T>, _meta?: {
+        digest: string;
+        encoded: string;
+    });
+    static fromEncode<T>(s: string, hash: HasherAndAlg): Promise<Disclosure<T>>;
+    static fromEncodeSync<T>(s: string, hash: HasherAndAlgSync): Disclosure<T>;
+    static fromArray<T>(item: DisclosureData<T>, _meta?: {
+        digest: string;
+        encoded: string;
+    }): Disclosure<T>;
+    encode(): string;
+    decode(): DisclosureData<T>;
+    digest(hash: HasherAndAlg): Promise<string>;
+    digestSync(hash: HasherAndAlgSync): string;
+}
+
+declare class SDJWTException extends Error {
+    details?: unknown;
+    constructor(message: string, details?: unknown);
+    getFullMessage(): string;
+}
+/**
+ * Narrows an unknown caught value to an Error instance.
+ */
+declare function ensureError(value: unknown): Error;
+
 type SDJwtData<Header extends Record<string, unknown>, Payload extends Record<string, unknown>, KBHeader extends kbHeader = kbHeader, KBPayload extends kbPayload = kbPayload> = {
     jwt?: Jwt<Header, Payload>;
     disclosures?: Array<Disclosure>;
@@ -195,8 +450,85 @@ declare const pack: <T extends Record<string, unknown>>(claims: T, disclosureFra
     disclosures: Array<Disclosure>;
 }>;
 
+declare const decodeJwt: <H extends Record<string, unknown>, T extends Record<string, unknown>>(jwt: string) => {
+    header: H;
+    payload: T;
+    signature: string;
+};
+declare const splitSdJwt: (sdjwt: string) => {
+    jwt: string;
+    disclosures: string[];
+    kbJwt?: string;
+};
+declare const decodeSdJwt: (sdjwt: string, hasher: Hasher) => Promise<DecodedSDJwt>;
+declare const decodeSdJwtSync: (sdjwt: string, hasher: HasherSync) => DecodedSDJwt;
+declare const getClaims: <T = Record<string, unknown>>(rawPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: Hasher) => Promise<T>;
+declare const getClaimsSync: <T = Record<string, unknown>>(rawPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: HasherSync) => T;
+declare const unpackObj: (obj: unknown, map: Record<string, Disclosure>) => {
+    unpackedObj: unknown;
+    disclosureKeymap: Record<string, string>;
+};
+declare const createHashMapping: (disclosures: Array<Disclosure>, hash: HasherAndAlg) => Promise<Record<string, Disclosure<unknown>>>;
+declare const createHashMappingSync: (disclosures: Array<Disclosure>, hash: HasherAndAlgSync) => Record<string, Disclosure<unknown>>;
+declare const getSDAlgAndPayload: (SdJwtPayload: Record<string, unknown>) => {
+    _sd_alg: string;
+    payload: {
+        [x: string]: unknown;
+    };
+};
+declare const unpack: (SdJwtPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: Hasher) => Promise<{
+    unpackedObj: unknown;
+    disclosureKeymap: Record<string, string>;
+}>;
+declare const unpackSync: (SdJwtPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: HasherSync) => {
+    unpackedObj: unknown;
+    disclosureKeymap: Record<string, string>;
+};
+type DecodedSDJwt = {
+    jwt: {
+        header: Record<string, unknown>;
+        payload: Record<string, unknown>;
+        signature: string;
+    };
+    disclosures: Array<Disclosure>;
+    kbJwt?: {
+        header: Record<string, unknown>;
+        payload: Record<string, unknown>;
+        signature: string;
+    };
+};
+
 declare const createDecoy: (hash: HasherAndAlg, saltGenerator: SaltGenerator) => Promise<string>;
 
+declare const presentableKeys: (rawPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: Hasher) => Promise<string[]>;
+declare const presentableKeysSync: (rawPayload: Record<string, unknown>, disclosures: Array<Disclosure>, hasher: HasherSync) => string[];
+declare const present: <T extends Record<string, unknown>>(sdJwt: string, presentFrame: PresentationFrame<T>, hasher: Hasher) => Promise<string>;
+declare const presentSync: <T extends Record<string, unknown>>(sdJwt: string, presentFrame: PresentationFrame<T>, hasher: HasherSync) => string;
+/**
+ * Transform the object keys into an array of strings. We are not sorting the array in any way.
+ * @param obj The object to transform
+ * @param prefix The prefix to add to the keys
+ * @returns
+ */
+declare const transformPresentationFrame: (obj: PresentationFrame<Extensible>, prefix?: string) => string[];
+type SerializedDisclosure = {
+    digest: string;
+    encoded: string;
+    salt: string;
+    key: string | undefined;
+    value: unknown;
+};
+declare const createHashMappingForSerializedDisclosure: (disclosures: SerializedDisclosure[]) => Record<string, Disclosure<unknown>>;
+/**
+ * This function selects the serialized disclosures from the payload
+ * and array of serialized disclosure based on the presentation frame.
+ * If you want to know what is serialized disclosures, check type SerializedDisclosure.
+ * @param payload: Record<string, unknown>
+ * @param disclosures: SerializedDisclosure[]
+ * @param presentationFrame: PresentationFrame<T>
+ */
+declare const selectDisclosures: <T extends Record<string, unknown>>(payload: Record<string, unknown>, disclosures: SerializedDisclosure[], presentationFrame: PresentationFrame<T>) => SerializedDisclosure[];
+
 type SdJwtPayload = Record<string, unknown>;
 declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload, T = unknown> {
     protected type?: string;
@@ -219,17 +551,33 @@ declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload, T = unknown> {
         kb?: KBOptions;
     }): Promise<SDJWTCompact>;
     verify(encodedSDJwt: string, options?: T & VerifierOptions): Promise<{
-        payload: unknown;
+        payload: ExtendedPayload;
         header: Record<string, unknown> | undefined;
         kb?: undefined;
     } | {
-        payload: unknown;
+        payload: ExtendedPayload;
         header: Record<string, unknown> | undefined;
         kb: {
-            payload: _sd_jwt_types.kbPayload;
-            header: _sd_jwt_types.kbHeader;
+            payload: kbPayload;
+            header: kbHeader;
         };
     }>;
+    /**
+     * Safe verification that collects all errors instead of failing fast.
+     * Returns a result object with either the verified data or an array of all errors.
+     *
+     * @param encodedSDJwt - The encoded SD-JWT to verify
+     * @param options - Verification options
+     * @returns A SafeVerifyResult containing either success data or collected errors
+     */
+    safeVerify(encodedSDJwt: string, options?: T & VerifierOptions): Promise<SafeVerifyResult<{
+        payload: ExtendedPayload;
+        header: Record<string, unknown> | undefined;
+        kb?: {
+            payload: Record<string, unknown>;
+            header: Record<string, unknown>;
+        };
+    }>>;
     private calculateSDHash;
     /**
      * This function is for validating the SD JWT
@@ -239,12 +587,12 @@ declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload, T = unknown> {
      * @returns
      */
     validate(encodedSDJwt: string, options?: T & VerifierOptions): Promise<{
-        payload: unknown;
+        payload: ExtendedPayload;
         header: Record<string, unknown> | undefined;
     }>;
     config(newConfig: SDJWTConfig): void;
     encode(sdJwt: SDJwt): SDJWTCompact;
-    decode(endcodedSDJwt: SDJWTCompact): Promise<SDJwt<Record<string, unknown>, Record<string, unknown>, _sd_jwt_types.kbHeader, _sd_jwt_types.kbPayload>>;
+    decode(endcodedSDJwt: SDJWTCompact): Promise<SDJwt<Record<string, unknown>, Record<string, unknown>, kbHeader, kbPayload>>;
     keys(endcodedSDJwt: SDJWTCompact): Promise<string[]>;
     presentableKeys(endcodedSDJwt: SDJWTCompact): Promise<string[]>;
     getClaims(endcodedSDJwt: SDJWTCompact): Promise<unknown>;
@@ -276,20 +624,20 @@ declare class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
         kb?: KBOptions;
     }): Promise<GeneralJSON>;
     verify(generalJSON: GeneralJSON, options?: VerifierOptions): Promise<{
-        payload: unknown;
+        payload: ExtendedPayload;
         headers: any[];
         kb?: undefined;
     } | {
-        payload: unknown;
+        payload: ExtendedPayload;
         headers: any[];
         kb: {
-            payload: _sd_jwt_types.kbPayload;
-            header: _sd_jwt_types.kbHeader;
+            payload: kbPayload;
+            header: kbHeader;
         };
     }>;
     private calculateSDHash;
     validate(generalJSON: GeneralJSON): Promise<{
-        payload: unknown;
+        payload: ExtendedPayload;
         headers: any[];
     }>;
     config(newConfig: SDJWTConfig): void;
@@ -300,4 +648,4 @@ declare class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
     getClaims(generalSdjwt: GeneralJSON): Promise<unknown>;
 }
 
-export { FlattenJSON, type FlattenJSONData, type FlattenJSONSerialized, GeneralJSON, type GeneralJSONData, type GeneralJSONSerialized, Jwt, type JwtData, KBJwt, SDJwt, type SDJwtData, SDJwtGeneralJSONInstance, SDJwtInstance, type SdJwtPayload, type VerifierOptions, createDecoy, listKeys, pack };
+export { type Base64urlString, type DECOY, type DecodedSDJwt, Disclosure, type DisclosureData, type DisclosureFrame, type Extensible, FlattenJSON, type FlattenJSONData, type FlattenJSONSerialized, GeneralJSON, type GeneralJSONData, type GeneralJSONSerialized, type HashAlgorithm, type Hasher, type HasherAndAlg, type HasherAndAlgSync, type HasherSync, IANA_HASH_ALGORITHMS, Jwt, type JwtData, type JwtPayload, KBJwt, type KBOptions, KB_JWT_TYP, type KbVerifier, type OrPromise, type PresentationFrame, type SD, type SDJWTCompact, type SDJWTConfig, SDJWTException, SDJwt, type SDJwtData, SDJwtGeneralJSONInstance, SDJwtInstance, SD_DECOY, SD_DIGEST, SD_LIST_KEY, SD_SEPARATOR, type SafeVerifyResult, type SaltGenerator, type SaltGeneratorSync, type SdJwtPayload, type SerializedDisclosure, type Signer, type SignerSync, type VerificationError, type VerificationErrorCode, type Verifier, type VerifierOptions, type VerifierSync, createDecoy, createHashMapping, createHashMappingForSerializedDisclosure, createHashMappingSync, decodeJwt, decodeSdJwt, decodeSdJwtSync, ensureError, getClaims, getClaimsSync, getSDAlgAndPayload, type kbHeader, type kbPayload, listKeys, pack, present, presentSync, presentableKeys, presentableKeysSync, selectDisclosures, splitSdJwt, transformPresentationFrame, unpack, unpackObj, unpackSync };