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

package/src/utils/disclosure.ts

@@ -0,0 +1,101 @@
+import type { DisclosureData, HasherAndAlg, HasherAndAlgSync } from '../types';
+import { base64urlEncode, uint8ArrayToBase64Url } from './base64url';
+import { SDJWTException } from './error';
+import { decodeBase64urlJsonStrict } from './strict-json';
+
+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 = decodeBase64urlJsonStrict<DisclosureData<T>>(
+      s,
+      'Invalid disclosure data',
+    );
+    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 = decodeBase64urlJsonStrict<DisclosureData<T>>(
+      s,
+      'Invalid disclosure data',
+    );
+    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/src/utils/strict-json.ts

@@ -0,0 +1,17 @@
+import { base64UrlToUint8Array } from './base64url';
+import { SDJWTException } from './error';
+
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+
+export const decodeBase64urlJsonStrict = <T>(
+  encoded: string,
+  errorMessage: string,
+): T => {
+  try {
+    const bytes = base64UrlToUint8Array(encoded);
+    const decoded = utf8Decoder.decode(bytes);
+    return JSON.parse(decoded) as T;
+  } catch {
+    throw new SDJWTException(errorMessage);
+  }
+};

package/test/app-e2e.spec.ts

@@ -0,0 +1,292 @@
+import Crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasher as digest, generateSalt, type Signer } from '@owf/crypto';
+import { describe, expect, test } from 'vitest';
+import {
+  type DisclosureFrame,
+  type PresentationFrame,
+  SDJwtInstance,
+  type SdJwtPayload,
+  type Verifier,
+} from '../src';
+
+const createSignerVerifier = () => {
+  const { privateKey, publicKey } = Crypto.generateKeyPairSync('ed25519');
+  const signer: Signer = async (data: string) => {
+    const sig = Crypto.sign(null, Buffer.from(data), privateKey);
+    return Buffer.from(sig).toString('base64url');
+  };
+  const verifier: Verifier = async (data: string, sig: string) => {
+    return Crypto.verify(
+      null,
+      Buffer.from(data),
+      publicKey,
+      Buffer.from(sig, 'base64url'),
+    );
+  };
+  return { signer, verifier };
+};
+
+describe('App', () => {
+  test('Example', async () => {
+    const { signer, verifier } = createSignerVerifier();
+    const sdjwt = new SDJwtInstance<SdJwtPayload>({
+      signer,
+      signAlg: 'EdDSA',
+      verifier,
+      hasher: digest,
+      hashAlg: 'sha-256',
+      saltGenerator: generateSalt,
+    });
+
+    const claims = {
+      firstname: 'John',
+      lastname: 'Doe',
+      ssn: '123-45-6789',
+      id: '1234',
+      data: {
+        firstname: 'John',
+        lastname: 'Doe',
+        ssn: '123-45-6789',
+        list: [{ r: '1' }, 'b', 'c'],
+      },
+      data2: {
+        hi: 'bye',
+      },
+    };
+    const disclosureFrame: DisclosureFrame<typeof claims> = {
+      _sd: ['firstname', 'id', 'data2'],
+      data: {
+        _sd: ['list'],
+        _sd_decoy: 2,
+        list: {
+          _sd: [0, 2],
+          _sd_decoy: 1,
+          0: {
+            _sd: ['r'],
+          },
+        },
+      },
+      data2: {
+        _sd: ['hi'],
+      },
+    };
+    const encodedSdjwt = await sdjwt.issue(claims, disclosureFrame);
+    expect(encodedSdjwt).toBeDefined();
+    const validated = await sdjwt.validate(encodedSdjwt);
+    expect(validated).toBeDefined();
+
+    const decoded = await sdjwt.decode(encodedSdjwt);
+    const keys = await decoded.keys(digest);
+    expect(keys).toEqual([
+      'data',
+      'data.firstname',
+      'data.lastname',
+      'data.list',
+      'data.list.0',
+      'data.list.0.r',
+      'data.list.1',
+      'data.list.2',
+      'data.ssn',
+      'data2',
+      'data2.hi',
+      'firstname',
+      'id',
+      'lastname',
+      'ssn',
+    ]);
+    const payloads = await decoded.getClaims(digest);
+    expect(payloads).toEqual(claims);
+    const presentableKeys = await decoded.presentableKeys(digest);
+    expect(presentableKeys).toEqual([
+      'data.list',
+      'data.list.0',
+      'data.list.0.r',
+      'data.list.2',
+      'data2',
+      'data2.hi',
+      'firstname',
+      'id',
+    ]);
+
+    const presentationFrame = {
+      firstname: true,
+      id: true,
+    };
+    const presentedSDJwt = await sdjwt.present<typeof claims>(
+      encodedSdjwt,
+      presentationFrame,
+    );
+    expect(presentedSDJwt).toBeDefined();
+
+    const presentationClaims = await sdjwt.getClaims(presentedSDJwt);
+    expect(presentationClaims).toBeDefined();
+    expect(presentationClaims).toEqual({
+      lastname: 'Doe',
+      ssn: '123-45-6789',
+      data: { firstname: 'John', lastname: 'Doe', ssn: '123-45-6789' },
+      id: '1234',
+      firstname: 'John',
+    });
+
+    const requiredClaimKeys = ['firstname', 'id', 'data.ssn'];
+    const verified = await sdjwt.verify(encodedSdjwt, { requiredClaimKeys });
+    expect(verified).toBeDefined();
+  });
+
+  test('rejects tampered disclosure bytes', async () => {
+    const { signer, verifier } = createSignerVerifier();
+    const sdjwt = new SDJwtInstance<SdJwtPayload>({
+      signer,
+      signAlg: 'EdDSA',
+      verifier,
+      hasher: digest,
+      hashAlg: 'sha-256',
+      saltGenerator: generateSalt,
+    });
+
+    const claims = {
+      firstname: 'John',
+      lastname: 'Doe',
+    };
+    const disclosureFrame: DisclosureFrame<typeof claims> = {
+      _sd: ['firstname', 'lastname'],
+    };
+
+    const encodedSdjwt = await sdjwt.issue(claims, disclosureFrame);
+    const parts = encodedSdjwt.split('~');
+    const disclosureBytes = Buffer.from(parts[1], 'base64url');
+    disclosureBytes[2] = 0xf2;
+    parts[1] = Buffer.from(disclosureBytes).toString('base64url');
+    const tamperedSdjwt = parts.join('~');
+
+    await expect(sdjwt.verify(tamperedSdjwt)).rejects.toThrow(
+      'Invalid disclosure data',
+    );
+  });
+
+  test('From JSON (complex)', async () => {
+    await JSONtest('./complex.json');
+  });
+
+  test('From JSON (array_data_types)', async () => {
+    await JSONtest('./array_data_types.json');
+  });
+
+  test('From JSON (array_full_sd)', async () => {
+    await JSONtest('./array_full_sd.json');
+  });
+
+  test('From JSON (array_in_sd)', async () => {
+    await JSONtest('./array_in_sd.json');
+  });
+
+  test('From JSON (array_recursive_sd_some_disclosed)', async () => {
+    await JSONtest('./array_recursive_sd_some_disclosed.json');
+  });
+
+  test('From JSON (header_mod)', async () => {
+    await JSONtest('./header_mod.json');
+  });
+
+  test('From JSON (json_serialization)', async () => {
+    await JSONtest('./json_serialization.json');
+  });
+
+  test('From JSON (key_binding)', async () => {
+    await JSONtest('./key_binding.json');
+  });
+
+  test('From JSON (no_sd)', async () => {
+    await JSONtest('./no_sd.json');
+  });
+
+  test('From JSON (object_data_types)', async () => {
+    await JSONtest('./object_data_types.json');
+  });
+
+  test('From JSON (recursions)', async () => {
+    await JSONtest('./recursions.json');
+  });
+
+  test('From JSON (array_recursive_sd)', async () => {
+    await JSONtest('./array_recursive_sd.json');
+  });
+
+  test('From JSON (array_of_scalars)', async () => {
+    await JSONtest('./array_of_scalars.json');
+  });
+
+  test('From JSON (array_of_objects)', async () => {
+    await JSONtest('./array_of_objects.json');
+  });
+
+  test('From JSON (array_of_nulls)', async () => {
+    await JSONtest('./array_of_nulls.json');
+  });
+
+  test('From JSON (array_nested_in_plain)', async () => {
+    await JSONtest('./array_nested_in_plain.json');
+  });
+});
+
+async function JSONtest(filename: string) {
+  const test = loadTestJsonFile(filename);
+  const { signer, verifier } = createSignerVerifier();
+  const sdjwt = new SDJwtInstance<SdJwtPayload>({
+    signer,
+    signAlg: 'EdDSA',
+    verifier,
+    hasher: digest,
+    hashAlg: 'sha-256',
+    saltGenerator: generateSalt,
+  });
+
+  const encodedSdjwt = await sdjwt.issue(test.claims, test.disclosureFrame);
+
+  expect(encodedSdjwt).toBeDefined();
+
+  const validated = await sdjwt.validate(encodedSdjwt);
+
+  expect(validated).toBeDefined();
+  expect(validated).toStrictEqual({
+    header: { alg: 'EdDSA' },
+    payload: test.claims,
+  });
+
+  const presentedSDJwt = await sdjwt.present<typeof test.claims>(
+    encodedSdjwt,
+    test.presentationFrames,
+  );
+
+  expect(presentedSDJwt).toBeDefined();
+
+  const presentationClaims = await sdjwt.getClaims(presentedSDJwt);
+
+  expect(presentationClaims).toEqual(test.presentedClaims);
+
+  const verified = await sdjwt.verify(encodedSdjwt, {
+    requiredClaimKeys: test.requiredClaimKeys,
+  });
+
+  expect(verified).toBeDefined();
+  expect(verified).toStrictEqual({
+    header: { alg: 'EdDSA' },
+    payload: test.claims,
+  });
+}
+
+type TestJson = {
+  claims: SdJwtPayload;
+  disclosureFrame: DisclosureFrame<SdJwtPayload>;
+  presentationFrames: PresentationFrame<SdJwtPayload>;
+  presentedClaims: object;
+  requiredClaimKeys: string[];
+};
+
+function loadTestJsonFile(filename: string) {
+  const filepath = path.join(__dirname, filename);
+  const fileContents = fs.readFileSync(filepath, 'utf8');
+  return JSON.parse(fileContents) as TestJson;
+}

package/test/array_data_types.json

@@ -0,0 +1,31 @@
+{
+  "claims": {
+    "data_types": [null, 42, 3.14, "foo", ["Test"], { "foo": "bar" }]
+  },
+  "disclosureFrame": {
+    "data_types": {
+      "_sd": [0, 1, 2, 3, 4, 5]
+    }
+  },
+  "presentationFrames": {
+    "data_types": {
+      "0": true,
+      "1": true,
+      "2": true,
+      "3": true,
+      "4": true,
+      "5": true
+    }
+  },
+  "presentedClaims": {
+    "data_types": [null, 42, 3.14, "foo", ["Test"], { "foo": "bar" }]
+  },
+  "requiredClaimKeys": [
+    "data_types.0",
+    "data_types.1",
+    "data_types.2",
+    "data_types.3",
+    "data_types.4",
+    "data_types.5"
+  ]
+}

package/test/array_full_sd.json

@@ -0,0 +1,21 @@
+{
+  "claims": {
+    "is_over": {
+      "13": true,
+      "18": false,
+      "21": false
+    }
+  },
+  "disclosureFrame": {
+    "is_over": {
+      "_sd": ["13", "18", "21"]
+    }
+  },
+  "presentationFrames": { "is_over": { "18": true } },
+  "presentedClaims": {
+    "is_over": {
+      "18": false
+    }
+  },
+  "requiredClaimKeys": ["is_over.18"]
+}

package/test/array_in_sd.json

@@ -0,0 +1,13 @@
+{
+  "claims": {
+    "sd_array": ["32", "23"]
+  },
+  "disclosureFrame": {
+    "_sd": ["sd_array"]
+  },
+  "presentationFrames": { "sd_array": true },
+  "presentedClaims": {
+    "sd_array": ["32", "23"]
+  },
+  "requiredClaimKeys": ["sd_array"]
+}

package/test/array_nested_in_plain.json

@@ -0,0 +1,29 @@
+{
+  "claims": {
+    "nested_array": [["foo", "bar"], ["baz", "qux"]]
+  },
+  "disclosureFrame": {
+    "nested_array": {
+      "0": {
+        "_sd": [0, 1]
+      },
+      "1": {
+        "_sd": [0, 1]
+      }
+    }
+  },
+  "presentationFrames": {
+    "nested_array": {
+      "0": {
+        "0": true
+      },
+      "1": {
+        "1": true
+      }
+    }
+  },
+  "presentedClaims": {
+    "nested_array": [["foo"], ["qux"]]
+  },
+  "requiredClaimKeys": ["nested_array.0.0", "nested_array.1.0"]
+}

package/test/array_none_disclosed.json

@@ -0,0 +1,17 @@
+{
+  "claims": {
+    "is_over": {
+      "13": false,
+      "18": true,
+      "21": false
+    }
+  },
+  "disclosureFrame": {
+    "is_over": {
+      "_sd": ["13", "18", "21"]
+    }
+  },
+  "presentationFrames": {},
+  "presentedClaims": {},
+  "requiredClaimKeys": []
+}

package/test/array_of_nulls.json

@@ -0,0 +1,15 @@
+{
+  "claims": {
+    "null_values": [null, null, null, null]
+  },
+  "disclosureFrame": {
+    "null_values": {
+      "_sd": [1, 2]
+    }
+  },
+  "presentationFrames": {},
+  "presentedClaims": {
+    "null_values": [null, null]
+  },
+  "requiredClaimKeys": ["null_values.0", "null_values.1"]
+}

package/test/array_of_objects.json

@@ -0,0 +1,65 @@
+{
+  "claims": {
+    "addresses": [
+      {
+        "street": "123 Main St",
+        "city": "Anytown",
+        "state": "NY",
+        "zip": "12345",
+        "type": "main_address"
+      },
+      {
+        "street": "456 Main St",
+        "city": "Anytown",
+        "state": "NY",
+        "zip": "12345",
+        "type": "secondary_address"
+      }
+    ],
+    "array_with_one_sd_object": {
+      "foo": "bar"
+    }
+  },
+  "disclosureFrame": {
+    "addresses": {
+      "_sd": [1]
+    },
+    "array_with_one_sd_object": {
+      "_sd": ["foo"]
+    }
+  },
+  "presentationFrames": {
+    "addresses": {
+      "1": true
+    },
+    "array_with_one_sd_object": {
+      "foo": true
+    }
+  },
+  "presentedClaims": {
+    "addresses": [
+      {
+        "street": "123 Main St",
+        "city": "Anytown",
+        "state": "NY",
+        "zip": "12345",
+        "type": "main_address"
+      },
+      {
+        "street": "456 Main St",
+        "city": "Anytown",
+        "state": "NY",
+        "zip": "12345",
+        "type": "secondary_address"
+      }
+    ],
+    "array_with_one_sd_object": {
+      "foo": "bar"
+    }
+  },
+  "requiredClaimKeys": [
+    "addresses.0.type",
+    "addresses.1.city",
+    "array_with_one_sd_object.foo"
+  ]
+}

package/test/array_of_scalars.json

@@ -0,0 +1,19 @@
+{
+  "claims": {
+    "nationalities": ["US", "CA", "DE"]
+  },
+  "disclosureFrame": {
+    "nationalities": {
+      "_sd": [0, 1]
+    }
+  },
+  "presentationFrames": {
+    "nationalities": {
+      "1": true
+    }
+  },
+  "presentedClaims": {
+    "nationalities": ["CA", "DE"]
+  },
+  "requiredClaimKeys": ["nationalities.0", "nationalities.1"]
+}

package/test/array_recursive_sd.json

@@ -0,0 +1,35 @@
+{
+  "claims": {
+    "array_with_recursive_sd": [
+      "boring",
+      {
+        "foo": "bar",
+        "baz": {
+          "qux": "quxx"
+        }
+      },
+      ["foo", "bar"]
+    ],
+    "test2": ["foo", "bar"]
+  },
+  "disclosureFrame": {
+    "array_with_recursive_sd": {
+      "_sd": [1],
+      "1": {
+        "_sd": ["baz"]
+      },
+      "2": {
+        "_sd": [0, 1]
+      }
+    },
+    "test2": {
+      "_sd": [0, 1]
+    }
+  },
+  "presentationFrames": {},
+  "presentedClaims": {
+    "array_with_recursive_sd": ["boring", []],
+    "test2": []
+  },
+  "requiredClaimKeys": ["array_with_recursive_sd.0", "test2"]
+}