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

package/src/test/utils/disclosure.spec.ts

@@ -0,0 +1,170 @@
+import { generateSalt, hasher } from '@owf/crypto';
+import { describe, expect, test } from 'vitest';
+import { base64urlEncode, type SDJWTException } from '../../utils';
+import { Disclosure } from '../../utils/disclosure';
+
+const hash = { alg: 'SHA256', hasher };
+
+/* 
+  ref draft-ietf-oauth-selective-disclosure-jwt-07
+  Claim given_name:
+  SHA-256 Hash: jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4
+  Disclosure: WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9obiJd
+  Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "John"]
+  For example, the SHA-256 digest of the Disclosure
+  WyI2cU1RdlJMNWhhaiIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0 would be uutlBuYeMDyjLLTpf6Jxi7yNkEF35jdyWMn9U7b_RYY.
+  The SHA-256 digest of the Disclosure
+  WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgIkZSIl0 would be w0I8EKcdCtUPkGCNUrfwVp2xEgNjtoIDlOxc9-PlOhs.
+*/
+const TestDataDraft7 = {
+  claimTests: [
+    {
+      contents: '["2GLC42sKQveCfGfryNRN9w", "given_name", "John"]',
+      digest: 'jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4',
+      disclosure:
+        'WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9obiJd',
+    },
+  ],
+  sha256Tests: [
+    {
+      digest: 'uutlBuYeMDyjLLTpf6Jxi7yNkEF35jdyWMn9U7b_RYY',
+      disclosure: 'WyI2cU1RdlJMNWhhaiIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0',
+    },
+    {
+      digest: 'w0I8EKcdCtUPkGCNUrfwVp2xEgNjtoIDlOxc9-PlOhs',
+      disclosure: 'WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgIkZSIl0',
+    },
+  ],
+};
+
+describe('Disclosure', () => {
+  test('create object disclosure', async () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'name', 'James']);
+    expect(disclosure).toBeDefined();
+    expect(disclosure.key).toBe('name');
+    expect(disclosure.value).toBe('James');
+    expect(disclosure.salt).toBe(salt);
+  });
+
+  test('create array disclosure', async () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'US']);
+    expect(disclosure).toBeDefined();
+    expect(disclosure.key).toBe(undefined);
+    expect(disclosure.value).toBe('US');
+    expect(disclosure.salt).toBe(salt);
+  });
+
+  test('create disclosure error', async () => {
+    const salt = generateSalt(16);
+    const data: [string, string, string] = [salt, 'name', 'James'];
+    data.push('any');
+    expect(() => new Disclosure(data)).toThrow();
+    try {
+      new Disclosure(data);
+    } catch (e: unknown) {
+      const error = e as SDJWTException;
+      expect(typeof error.getFullMessage()).toBe('string');
+    }
+  });
+
+  test('encode disclosure', async () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'name', 'James']);
+    const encodedDisclosure = disclosure.encode();
+    expect(encodedDisclosure).toBeDefined();
+    expect(typeof encodedDisclosure).toBe('string');
+  });
+
+  test('decode disclosure', async () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'name', 'James']);
+    const encodedDisclosure = disclosure.encode();
+    const newDisclosure = await Disclosure.fromEncode(encodedDisclosure, {
+      alg: 'SHA256',
+      hasher,
+    });
+
+    expect(newDisclosure).toBeDefined();
+    expect(newDisclosure.key).toBe('name');
+    expect(newDisclosure.value).toBe('James');
+    expect(newDisclosure.salt).toBe(salt);
+  });
+
+  test('decode disclosure sync', () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'name', 'James']);
+    const encodedDisclosure = disclosure.encode();
+    const newDisclosure = Disclosure.fromEncodeSync(encodedDisclosure, {
+      alg: 'SHA256',
+      hasher,
+    });
+
+    expect(newDisclosure).toBeDefined();
+    expect(newDisclosure.key).toBe('name');
+    expect(newDisclosure.value).toBe('James');
+    expect(newDisclosure.salt).toBe(salt);
+  });
+
+  test('digest disclosure #1', async () => {
+    const salt = generateSalt(16);
+    const disclosure = new Disclosure([salt, 'name', 'James']);
+    const digest = await disclosure.digest({ alg: 'SHA256', hasher });
+    expect(digest).toBeDefined();
+    expect(typeof digest).toBe('string');
+  });
+
+  test('digest disclosure #2', async () => {
+    const disclosure = new Disclosure([
+      '2GLC42sKQveCfGfryNRN9w',
+      'given_name',
+      'John',
+    ]);
+    const encode = disclosure.encode();
+    expect(encode).toBe(
+      'WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwiZ2l2ZW5fbmFtZSIsIkpvaG4iXQ',
+    );
+    const digest = await disclosure.digest(hash);
+    expect(digest).toBe('8VHiz7qTXavxvpiTYDCSr_shkUO6qRcVXjkhEnt1os4');
+  });
+
+  test('digest disclosure #2 sync', () => {
+    const disclosure = new Disclosure([
+      '2GLC42sKQveCfGfryNRN9w',
+      'given_name',
+      'John',
+    ]);
+    const encode = disclosure.encode();
+    expect(encode).toBe(
+      'WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwiZ2l2ZW5fbmFtZSIsIkpvaG4iXQ',
+    );
+    const digest = disclosure.digestSync(hash);
+    expect(digest).toBe('8VHiz7qTXavxvpiTYDCSr_shkUO6qRcVXjkhEnt1os4');
+  });
+
+  test('digest disclosure #3', async () => {
+    const encoded = base64urlEncode(TestDataDraft7.claimTests[0].contents);
+    expect(encoded).toStrictEqual(TestDataDraft7.claimTests[0].disclosure);
+
+    const disclosure = await Disclosure.fromEncode(
+      TestDataDraft7.claimTests[0].disclosure,
+      hash,
+    );
+
+    const digest = await disclosure.digest(hash);
+    expect(digest).toBe(TestDataDraft7.claimTests[0].digest);
+  });
+
+  test('digest disclosure #4', async () => {
+    for (const sha256Test of TestDataDraft7.sha256Tests) {
+      const disclosure = await Disclosure.fromEncode(
+        sha256Test.disclosure,
+        hash,
+      );
+
+      const digest = await disclosure.digest(hash);
+      expect(digest).toBe(sha256Test.digest);
+    }
+  });
+});

package/src/test/utils/error.spec.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vitest';
+import { SDJWTException } from '../../utils/error';
+
+describe('Error tests', () => {
+  test('Detail', () => {
+    try {
+      throw new SDJWTException('msg', { info: 'details' });
+    } catch (e: unknown) {
+      const exception = e as SDJWTException;
+      expect(exception.getFullMessage()).toEqual(
+        'SDJWTException: msg - {"info":"details"}',
+      );
+    }
+  });
+});

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './type';
+export * from './verification-error';

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');