@sd-jwt/core 0.1.0 → 0.1.1-next.0

package/src/test/types/type.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'vitest';
+import {
+  type DisclosureFrame,
+  KB_JWT_TYP,
+  type PresentationFrame,
+  SD_DECOY,
+  SD_DIGEST,
+  SD_LIST_KEY,
+  SD_SEPARATOR,
+} from '../../types';
+
+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',
+  },
+};
+
+describe('Variable tests', () => {
+  test('SD_SEPARATOR', () => {
+    expect(SD_SEPARATOR).toBe('~');
+  });
+
+  test('SD_LIST_KEY', () => {
+    expect(SD_LIST_KEY).toBe('...');
+  });
+
+  test('SD_DIGEST', () => {
+    expect(SD_DIGEST).toBe('_sd');
+  });
+
+  test('SD_DECOY', () => {
+    expect(SD_DECOY).toBe('_sd_decoy');
+  });
+
+  test('KB_JWT_TYP', () => {
+    expect(KB_JWT_TYP).toBe('kb+jwt');
+  });
+
+  test('DisclosureFrameType test', () => {
+    const disclosureFrame: DisclosureFrame<typeof claims> = {
+      _sd: ['data', 'firstname', 'data2'],
+      data: {
+        _sd: ['list', 'ssn'],
+        _sd_decoy: 2,
+        list: {
+          _sd: [0, 2],
+          0: {
+            _sd: ['r'],
+          },
+        },
+      },
+    };
+    expect(disclosureFrame).toBeDefined();
+  });
+
+  test('PresentationFrameType test', () => {
+    const presentationFrame: PresentationFrame<typeof claims> = {
+      firstname: true,
+      data: {
+        firstname: true,
+        list: {
+          1: true,
+          0: {
+            r: true,
+          },
+        },
+        list2: {
+          1: true,
+        },
+        list3: true,
+      },
+      data2: true,
+    };
+    expect(presentationFrame).toBeDefined();
+  });
+});

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

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'vitest';
+import {
+  base64UrlToUint8Array,
+  base64urlDecode,
+  base64urlEncode,
+  uint8ArrayToBase64Url,
+} from '../../utils/base64url';
+
+describe('Base64url', () => {
+  const raw = 'abcdefghijklmnopqrstuvwxyz';
+  const encoded = 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo';
+  test('Encode', () => {
+    expect(base64urlEncode(raw)).toStrictEqual(encoded);
+  });
+  test('Decode', () => {
+    expect(base64urlDecode(encoded)).toStrictEqual(raw);
+  });
+  test('Encode and decode', () => {
+    const str = 'hello world';
+    expect(base64urlDecode(base64urlEncode(str))).toStrictEqual(str);
+  });
+  test('Uint8Array', () => {
+    const str = 'hello world';
+    const uint8 = new TextEncoder().encode(str);
+    expect(uint8ArrayToBase64Url(uint8)).toStrictEqual(base64urlEncode(str));
+  });
+
+  test('Base64Url to Uint8Array', () => {
+    const str = 'hello world';
+    const uint8 = new TextEncoder().encode(str);
+    expect(base64UrlToUint8Array(base64urlEncode(str))).toStrictEqual(uint8);
+  });
+});

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