@sd-jwt/core 0.19.1-next.5 → 0.19.1-next.6

package/src/types/type.ts

@@ -0,0 +1,249 @@
+export const SD_SEPARATOR = '~';
+export const SD_LIST_KEY = '...';
+export const SD_DIGEST = '_sd';
+export const SD_DECOY = '_sd_decoy';
+export const KB_JWT_TYP = 'kb+jwt';
+
+export type SDJWTCompact = string;
+export type Base64urlString = string;
+
+export type DisclosureData<T> = [string, string, T] | [string, T];
+
+// based on https://www.iana.org/assignments/named-information/named-information.xhtml
+export const IANA_HASH_ALGORITHMS = [
+  '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',
+] as const;
+
+export type HashAlgorithm = (typeof IANA_HASH_ALGORITHMS)[number];
+
+export 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;
+};
+
+export type kbHeader = { typ: 'kb+jwt'; alg: string };
+export type kbPayload = {
+  iat: number;
+  aud: string;
+  nonce: string;
+  sd_hash: string;
+};
+
+export type KBOptions = {
+  payload: Omit<kbPayload, 'sd_hash'>;
+};
+
+// This type declaration is from lib.dom.ts
+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;
+}
+
+export interface JwtPayload {
+  cnf?: {
+    jwk: JsonWebKey;
+  };
+  exp?: number;
+  [key: string]: unknown;
+}
+
+export type OrPromise<T> = T | Promise<T>;
+
+export type Signer = (data: string) => OrPromise<string>;
+export type Verifier<T = unknown> = (
+  data: string,
+  sig: string,
+  options?: T,
+) => OrPromise<boolean>;
+export type KbVerifier = (
+  data: string,
+  sig: string,
+  payload: JwtPayload,
+) => OrPromise<boolean>;
+export type Hasher = (
+  data: string | ArrayBuffer,
+  alg: string,
+) => OrPromise<Uint8Array>;
+export type SaltGenerator = (length: number) => OrPromise<string>;
+export type HasherAndAlg = {
+  hasher: Hasher;
+  alg: string;
+};
+
+// This functions are sync versions
+export type SignerSync = (data: string) => string;
+export type VerifierSync = (data: string, sig: string) => boolean;
+export type HasherSync = (data: string, alg: string) => Uint8Array;
+export type SaltGeneratorSync = (length: number) => string;
+export type HasherAndAlgSync = {
+  hasher: HasherSync;
+  alg: string;
+};
+
+type NonNever<T> = {
+  [P in keyof T as T[P] extends never ? never : P]: T[P];
+};
+
+export type SD<Payload> = { [SD_DIGEST]?: Array<keyof Payload> };
+export 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.
+ */
+export type Extensible = Record<string, unknown | boolean>;
+
+export 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;
+      };
+
+export type PresentationFrame<T extends Extensible> = PFrame<T>;

package/src/types/verification-error.ts

@@ -0,0 +1,55 @@
+/**
+ * Error codes for SD-JWT verification errors.
+ */
+export 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.
+ */
+export 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.
+ */
+export type SafeVerifyResult<T> =
+  | {
+      success: true;
+      data: T;
+      errors?: never;
+    }
+  | {
+      success: false;
+      data?: never;
+      errors: VerificationError[];
+    };

package/src/utils/base64url.ts

@@ -0,0 +1,6 @@
+export {
+  base64UrlToUint8Array,
+  base64urlDecode,
+  base64urlEncode,
+  uint8ArrayToBase64Url,
+} from '@owf/identity-common';

package/src/utils/disclosure.ts

@@ -0,0 +1,98 @@
+import type { DisclosureData, HasherAndAlg, HasherAndAlgSync } from '../types';
+import {
+  base64urlDecode,
+  base64urlEncode,
+  uint8ArrayToBase64Url,
+} from './base64url';
+import { SDJWTException } from './error';
+
+export class Disclosure<T = unknown> {
+  public salt: string;
+  public key?: string;
+  public value: T;
+  public _digest: string | undefined;
+  private _encoded: string | undefined;
+
+  public constructor(
+    data: DisclosureData<T>,
+    _meta?: { digest: string; encoded: string },
+  ) {
+    // If the meta is provided, then we assume that the data is already encoded and digested
+    this._digest = _meta?.digest;
+    this._encoded = _meta?.encoded;
+
+    if (data.length === 2) {
+      this.salt = data[0];
+      this.value = data[1];
+      return;
+    }
+    if (data.length === 3) {
+      this.salt = data[0];
+      this.key = data[1];
+      this.value = data[2];
+      return;
+    }
+    throw new SDJWTException('Invalid disclosure data');
+  }
+
+  // We need to digest of the original encoded data.
+  // After decode process, we use JSON.stringify to encode the data.
+  // This can be different from the original encoded data.
+  public static async fromEncode<T>(s: string, hash: HasherAndAlg) {
+    const { hasher, alg } = hash;
+    const digest = await hasher(s, alg);
+    const digestStr = uint8ArrayToBase64Url(digest);
+    const item = JSON.parse(base64urlDecode(s)) as DisclosureData<T>;
+    return Disclosure.fromArray<T>(item, { digest: digestStr, encoded: s });
+  }
+
+  public static fromEncodeSync<T>(s: string, hash: HasherAndAlgSync) {
+    const { hasher, alg } = hash;
+    const digest = hasher(s, alg);
+    const digestStr = uint8ArrayToBase64Url(digest);
+    const item = JSON.parse(base64urlDecode(s)) as DisclosureData<T>;
+    return Disclosure.fromArray<T>(item, { digest: digestStr, encoded: s });
+  }
+
+  public static fromArray<T>(
+    item: DisclosureData<T>,
+    _meta?: { digest: string; encoded: string },
+  ) {
+    return new Disclosure(item, _meta);
+  }
+
+  public encode() {
+    if (!this._encoded) {
+      // we use JSON.stringify to encode the data
+      // It's the most reliable and universal way to encode JSON object
+      this._encoded = base64urlEncode(JSON.stringify(this.decode()));
+    }
+    return this._encoded;
+  }
+
+  public decode(): DisclosureData<T> {
+    return this.key
+      ? [this.salt, this.key, this.value]
+      : [this.salt, this.value];
+  }
+
+  public async digest(hash: HasherAndAlg): Promise<string> {
+    const { hasher, alg } = hash;
+    if (!this._digest) {
+      const hash = await hasher(this.encode(), alg);
+      this._digest = uint8ArrayToBase64Url(hash);
+    }
+
+    return this._digest;
+  }
+
+  public digestSync(hash: HasherAndAlgSync): string {
+    const { hasher, alg } = hash;
+    if (!this._digest) {
+      const hash = hasher(this.encode(), alg);
+      this._digest = uint8ArrayToBase64Url(hash);
+    }
+
+    return this._digest;
+  }
+}

package/src/utils/error.ts

@@ -0,0 +1,25 @@
+export class SDJWTException extends Error {
+  public details?: unknown;
+
+  constructor(message: string, details?: unknown) {
+    super(message);
+    Object.setPrototypeOf(this, SDJWTException.prototype);
+    this.name = 'SDJWTException';
+    this.details = details;
+  }
+
+  getFullMessage(): string {
+    return `${this.name}: ${this.message} ${
+      this.details ? `- ${JSON.stringify(this.details)}` : ''
+    }`;
+  }
+}
+
+/**
+ * Narrows an unknown caught value to an Error instance.
+ */
+export function ensureError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  if (typeof value === 'string') return new Error(value);
+  return new Error(String(value));
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './base64url';
+export * from './disclosure';
+export * from './error';

package/test/app-e2e.spec.ts

@@ -1,15 +1,15 @@
 import Crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { digest, generateSalt } from '@sd-jwt/crypto-nodejs';
-import type {
-  DisclosureFrame,
-  PresentationFrame,
-  Signer,
-  Verifier,
-} from '@sd-jwt/types';
+import { hasher as digest, generateSalt, type Signer } from '@owf/crypto';
 import { describe, expect, test } from 'vitest';
-import { SDJwtInstance, type SdJwtPayload } from '../src';
+import {
+  type DisclosureFrame,
+  type PresentationFrame,
+  SDJwtInstance,
+  type SdJwtPayload,
+  type Verifier,
+} from '../src';
 
 const createSignerVerifier = () => {
   const { privateKey, publicKey } = Crypto.generateKeyPairSync('ed25519');

package/test/rfc9901-validation.spec.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'vitest';
+import { unpackObj } from '../src/decode';
+import { Disclosure } from '../src/utils';
+
+/**
+ * Tests for RFC 9901 validation checks added to unpackObj / unpackObjInternal.
+ *
+ * Section 7.1 step 4: Duplicate digest rejection
+ * Section 7.1 step 5: Unreferenced disclosure rejection
+ * Section 7.1 step 3c.ii.3: Claim name collision rejection
+ */
+
+const makeDisclosure = (
+  digest: string,
+  key: string | undefined,
+  value: unknown,
+) =>
+  Disclosure.fromArray(key ? ['salt', key, value] : ['salt', value], {
+    digest,
+    encoded: `encoded-${digest}`,
+  });
+
+describe('RFC 9901 validation', () => {
+  // ──────────────────────────────────────────
+  // 7.1 step 4 — Duplicate digest in _sd array
+  // ──────────────────────────────────────────
+  test('rejects duplicate digest in _sd array', () => {
+    const digest = 'abc123';
+    const payload = { _sd: [digest, digest] };
+    const map: Record<string, Disclosure> = {
+      [digest]: makeDisclosure(digest, 'foo', 'bar'),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Duplicate digest found in SD-JWT payload',
+    );
+  });
+
+  // ──────────────────────────────────────────
+  // 7.1 step 4 — Duplicate digest across nested _sd
+  // ──────────────────────────────────────────
+  test('rejects duplicate digest across nested _sd arrays', () => {
+    const digest = 'dup1';
+    const payload = {
+      _sd: [digest],
+      nested: {
+        _sd: [digest],
+      },
+    };
+    const map: Record<string, Disclosure> = {
+      [digest]: makeDisclosure(digest, 'x', 'y'),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Duplicate digest found in SD-JWT payload',
+    );
+  });
+
+  // ──────────────────────────────────────────
+  // 7.1 step 4 — Duplicate digest in array items
+  // ──────────────────────────────────────────
+  test('rejects duplicate digest in array element disclosures', () => {
+    const digest = 'arrdup';
+    const payload = {
+      arr: [{ '...': digest }, { '...': digest }],
+    };
+    const map: Record<string, Disclosure> = {
+      [digest]: makeDisclosure(digest, undefined, 'val'),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Duplicate digest found in SD-JWT payload',
+    );
+  });
+
+  // ──────────────────────────────────────────
+  // 7.1 step 5 — Unreferenced disclosure
+  // ──────────────────────────────────────────
+  test('rejects unreferenced disclosure', () => {
+    const usedDigest = 'used1';
+    const unusedDigest = 'unused1';
+    const payload = { _sd: [usedDigest] };
+    const map: Record<string, Disclosure> = {
+      [usedDigest]: makeDisclosure(usedDigest, 'a', 1),
+      [unusedDigest]: makeDisclosure(unusedDigest, 'b', 2),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Unreferenced disclosure(s) detected in SD-JWT',
+    );
+  });
+
+  test('rejects when no digests exist in payload but disclosures provided', () => {
+    const payload = { plain: 'value' };
+    const map: Record<string, Disclosure> = {
+      orphan: makeDisclosure('orphan', 'k', 'v'),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Unreferenced disclosure(s) detected in SD-JWT',
+    );
+  });
+
+  // ──────────────────────────────────────────
+  // 7.1 step 3c.ii.3 — Claim name collision
+  // ──────────────────────────────────────────
+  test('rejects disclosed claim name that conflicts with plaintext key', () => {
+    const digest = 'col1';
+    // The payload has both a plaintext "name" and a disclosure that would add "name"
+    const payload = { name: 'Alice', _sd: [digest] };
+    const map: Record<string, Disclosure> = {
+      [digest]: makeDisclosure(digest, 'name', 'Mallory'),
+    };
+    expect(() => unpackObj(payload, map)).toThrow(
+      'Disclosed claim name "name" conflicts with existing payload key',
+    );
+  });
+
+  // ──────────────────────────────────────────
+  // Positive: valid SD-JWT unpacks without error
+  // ──────────────────────────────────────────
+  test('unpacks valid SD-JWT without errors', () => {
+    const d1 = 'digest1';
+    const d2 = 'digest2';
+    const payload = { _sd: [d1, d2], plain: 'hello' };
+    const map: Record<string, Disclosure> = {
+      [d1]: makeDisclosure(d1, 'foo', 'bar'),
+      [d2]: makeDisclosure(d2, 'baz', 42),
+    };
+    const { unpackedObj, disclosureKeymap } = unpackObj(payload, map);
+    expect(unpackedObj).toEqual({ plain: 'hello', foo: 'bar', baz: 42 });
+    expect(disclosureKeymap).toEqual({ foo: d1, baz: d2 });
+  });
+
+  test('unpacks valid SD-JWT with array disclosures', () => {
+    const d1 = 'arrdig1';
+    const d2 = 'arrdig2';
+    const payload = {
+      arr: [{ '...': d1 }, 'plainItem', { '...': d2 }],
+    };
+    const map: Record<string, Disclosure> = {
+      [d1]: makeDisclosure(d1, undefined, 'secret1'),
+      [d2]: makeDisclosure(d2, undefined, 'secret2'),
+    };
+    const { unpackedObj } = unpackObj(payload, map);
+    expect(unpackedObj).toEqual({ arr: ['secret1', 'plainItem', 'secret2'] });
+  });
+
+  test('allows empty disclosure map with no _sd in payload', () => {
+    const payload = { plain: 'value' };
+    const map: Record<string, Disclosure> = {};
+    const { unpackedObj } = unpackObj(payload, map);
+    expect(unpackedObj).toEqual({ plain: 'value' });
+  });
+});