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

package/src/jwt.ts

@@ -0,0 +1,190 @@
+import { decodeJwt } from './decode';
+import type { Base64urlString, Signer, Verifier } from './types';
+import { base64urlEncode, SDJWTException } from './utils';
+
+export type JwtData<
+  Header extends Record<string, unknown>,
+  Payload extends Record<string, unknown>,
+> = {
+  header?: Header;
+  payload?: Payload;
+  signature?: Base64urlString;
+  encoded?: string;
+};
+
+/**
+ * Options for the JWT verifier
+ */
+export type VerifierOptions = {
+  /**
+   * current time in seconds since epoch
+   */
+  currentDate?: number;
+
+  /**
+   * allowed skew for the current time in seconds. Positive value that will lower the iat and nbf checks, and increase the exp check.
+   */
+  skewSeconds?: number;
+
+  /**
+   * required claim keys for the payload.
+   * If the payload does not contain these keys, the verification will fail.
+   */
+  requiredClaimKeys?: string[];
+
+  /**
+   * nonce used to verify the key binding jwt to prevent replay attacks.
+   */
+  keyBindingNonce?: string;
+
+  /**
+   * disable the verification of the status claim in the payload.
+   *
+   * @default false
+   */
+  disableStatusVerification?: boolean;
+
+  /**
+   * any other custom options
+   */
+  [key: string]: unknown;
+};
+
+// This class is used to create and verify JWT
+// Contains header, payload, and signature
+export class Jwt<
+  Header extends Record<string, unknown> = Record<string, unknown>,
+  Payload extends Record<string, unknown> = Record<string, unknown>,
+> {
+  public header?: Header;
+  public payload?: Payload;
+  public signature?: Base64urlString;
+  private encoded?: string;
+
+  constructor(data?: JwtData<Header, Payload>) {
+    this.header = data?.header;
+    this.payload = data?.payload;
+    this.signature = data?.signature;
+    this.encoded = data?.encoded;
+  }
+
+  public static decodeJWT<
+    Header extends Record<string, unknown> = Record<string, unknown>,
+    Payload extends Record<string, unknown> = Record<string, unknown>,
+  >(
+    jwt: string,
+  ): { header: Header; payload: Payload; signature: Base64urlString } {
+    return decodeJwt(jwt);
+  }
+
+  public static fromEncode<
+    Header extends Record<string, unknown> = Record<string, unknown>,
+    Payload extends Record<string, unknown> = Record<string, unknown>,
+  >(encodedJwt: string): Jwt<Header, Payload> {
+    const { header, payload, signature } = Jwt.decodeJWT<Header, Payload>(
+      encodedJwt,
+    );
+
+    const jwt = new Jwt<Header, Payload>({
+      header,
+      payload,
+      signature,
+      encoded: encodedJwt,
+    });
+
+    return jwt;
+  }
+
+  public setHeader(header: Header): Jwt<Header, Payload> {
+    this.header = header;
+    this.encoded = undefined;
+    return this;
+  }
+
+  public setPayload(payload: Payload): Jwt<Header, Payload> {
+    this.payload = payload;
+    this.encoded = undefined;
+    return this;
+  }
+
+  protected getUnsignedToken() {
+    if (!this.header || !this.payload) {
+      throw new SDJWTException('Serialize Error: Invalid JWT');
+    }
+
+    if (this.encoded) {
+      const parts = this.encoded.split('.');
+      if (parts.length !== 3) {
+        throw new SDJWTException(`Invalid JWT format: ${this.encoded}`);
+      }
+      const unsignedToken = parts.slice(0, 2).join('.');
+      return unsignedToken;
+    }
+
+    const header = base64urlEncode(JSON.stringify(this.header));
+    const payload = base64urlEncode(JSON.stringify(this.payload));
+    return `${header}.${payload}`;
+  }
+
+  public async sign(signer: Signer) {
+    const data = this.getUnsignedToken();
+    this.signature = await signer(data);
+
+    return this.encodeJwt();
+  }
+
+  public encodeJwt(): string {
+    if (this.encoded) {
+      return this.encoded;
+    }
+
+    if (!this.header || !this.payload || !this.signature) {
+      throw new SDJWTException('Serialize Error: Invalid JWT');
+    }
+
+    const header = base64urlEncode(JSON.stringify(this.header));
+    const payload = base64urlEncode(JSON.stringify(this.payload));
+    const signature = this.signature;
+    const compact = `${header}.${payload}.${signature}`;
+    this.encoded = compact;
+
+    return compact;
+  }
+
+  /**
+   * Verify the JWT using the provided verifier function.
+   * It checks the signature and validates the iat, nbf, and exp claims if they are present.
+   * @param verifier
+   * @param options - Options for verification, such as current date and skew seconds
+   * @returns
+   */
+  public async verify<T>(verifier: Verifier<T>, options?: T & VerifierOptions) {
+    const skew = options?.skewSeconds ? options.skewSeconds : 0;
+    const currentDate = options?.currentDate ?? Math.floor(Date.now() / 1000);
+    const iat = this.payload?.iat;
+    const nbf = this.payload?.nbf;
+    const exp = this.payload?.exp;
+
+    if (typeof iat === 'number' && iat - skew > currentDate) {
+      throw new SDJWTException('Verify Error: JWT is not yet valid');
+    }
+
+    if (typeof nbf === 'number' && nbf - skew > currentDate) {
+      throw new SDJWTException('Verify Error: JWT is not yet valid');
+    }
+    if (typeof exp === 'number' && exp + skew < currentDate) {
+      throw new SDJWTException('Verify Error: JWT is expired');
+    }
+
+    if (!this.signature) {
+      throw new SDJWTException('Verify Error: no signature in JWT');
+    }
+    const data = this.getUnsignedToken();
+
+    const verified = await verifier(data, this.signature, options);
+    if (!verified) {
+      throw new SDJWTException('Verify Error: Invalid JWT Signature');
+    }
+    return { payload: this.payload, header: this.header };
+  }
+}

package/src/kbjwt.ts

@@ -0,0 +1,81 @@
+import { Jwt, type VerifierOptions } from './jwt';
+import {
+  KB_JWT_TYP,
+  type KbVerifier,
+  type kbHeader,
+  type kbPayload,
+} from './types';
+import { SDJWTException } from './utils';
+
+export class KBJwt<
+  Header extends kbHeader = kbHeader,
+  Payload extends kbPayload = kbPayload,
+> extends Jwt<Header, Payload> {
+  // Checking the validity of the key binding jwt
+  // the type unknown is not good, but we don't know at this point how to get the public key of the signer, this is defined in the kbVerifier
+  public async verifyKB(values: {
+    verifier: KbVerifier;
+    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;
+  }) {
+    if (!this.header || !this.payload || !this.signature) {
+      throw new SDJWTException('Verify Error: Invalid JWT');
+    }
+
+    if (
+      !this.header.alg ||
+      this.header.alg === 'none' ||
+      !this.header.typ ||
+      this.header.typ !== KB_JWT_TYP ||
+      !this.payload.iat ||
+      !this.payload.aud ||
+      !this.payload.nonce ||
+      // this is for backward compatibility with version 06
+      !(
+        this.payload.sd_hash ||
+        ('_sd_hash' in this.payload && this.payload._sd_hash)
+      )
+    ) {
+      throw new SDJWTException('Invalid Key Binding Jwt');
+    }
+
+    if (this.payload.nonce !== values.nonce) {
+      throw new SDJWTException('Verify Error: Invalid Nonce');
+    }
+
+    // Delegate signature verification and common JWT claim validation
+    // (iat, nbf, exp) to the shared Jwt.verify implementation. The kbVerifier
+    // needs the kb+jwt payload (e.g. the holder's cnf key), so we wrap it to
+    // forward values.payload instead of the base verifier's options argument.
+    await this.verify(
+      (data, sig) => values.verifier(data, sig, values.payload),
+      values.options,
+    );
+
+    return { payload: this.payload, header: this.header };
+  }
+
+  // This function is for creating KBJwt object for verify properly
+  public static fromKBEncode<
+    Header extends kbHeader = kbHeader,
+    Payload extends kbPayload = kbPayload,
+  >(encodedJwt: string): KBJwt<Header, Payload> {
+    const { header, payload, signature } = Jwt.decodeJWT<Header, Payload>(
+      encodedJwt,
+    );
+
+    const jwt = new KBJwt<Header, Payload>({
+      header,
+      payload,
+      signature,
+      encoded: encodedJwt,
+    });
+
+    return jwt;
+  }
+}

package/src/present/index.ts

@@ -0,0 +1 @@
+export * from './present';

package/src/present/present.ts

@@ -0,0 +1,210 @@
+import {
+  createHashMapping,
+  createHashMappingSync,
+  decodeSdJwt,
+  decodeSdJwtSync,
+  getSDAlgAndPayload,
+  splitSdJwt,
+  unpack,
+  unpackObj,
+  unpackSync,
+} from '../decode';
+import type { Extensible, HasherSync } from '../types';
+import { type Hasher, type PresentationFrame, SD_SEPARATOR } from '../types';
+import { Disclosure, SDJWTException } from '../utils';
+
+// Presentable keys
+// The presentable keys are the path of JSON object that are presentable in the SD JWT
+// e.g. if the SD JWT has the following payload and set sd like this:
+// {
+//   "foo": "bar",  // sd
+//   "arr": [       // sd
+//     "1",         // sd
+//     "2",
+//     {
+//       "a": "1"   // sd
+//     }
+//   ],
+//   "test": {
+//     "zzz": "xxx" // sd
+//   }
+// }
+// The presentable keys are: ["arr", "arr.0", "arr.2.a", "foo", "test.zzz"]
+export const presentableKeys = async (
+  rawPayload: Record<string, unknown>,
+  disclosures: Array<Disclosure>,
+  hasher: Hasher,
+): Promise<string[]> => {
+  const { disclosureKeymap } = await unpack(rawPayload, disclosures, hasher);
+  return Object.keys(disclosureKeymap).sort();
+};
+
+export const presentableKeysSync = (
+  rawPayload: Record<string, unknown>,
+  disclosures: Array<Disclosure>,
+  hasher: HasherSync,
+): string[] => {
+  const { disclosureKeymap } = unpackSync(rawPayload, disclosures, hasher);
+  return Object.keys(disclosureKeymap).sort();
+};
+
+export const present = async <T extends Record<string, unknown>>(
+  sdJwt: string,
+  presentFrame: PresentationFrame<T>,
+  hasher: Hasher,
+): Promise<string> => {
+  const { jwt, kbJwt } = splitSdJwt(sdJwt);
+  const {
+    jwt: { payload },
+    disclosures,
+  } = await decodeSdJwt(sdJwt, hasher);
+
+  const { _sd_alg: alg } = getSDAlgAndPayload(payload);
+  const hash = { alg, hasher };
+  const keys = transformPresentationFrame(presentFrame);
+
+  // hashmap: <digest> => <disclosure>
+  // to match the digest with the disclosure
+  const hashmap = await createHashMapping(disclosures, hash);
+  const { disclosureKeymap } = await unpack(payload, disclosures, hasher);
+  const presentedDisclosures = keys
+    .map((k) => hashmap[disclosureKeymap[k]])
+    .filter((d) => d !== undefined);
+
+  return [
+    jwt,
+    ...presentedDisclosures.map((d) => d.encode()),
+    kbJwt ?? '',
+  ].join(SD_SEPARATOR);
+};
+
+export const presentSync = <T extends Record<string, unknown>>(
+  sdJwt: string,
+  presentFrame: PresentationFrame<T>,
+  hasher: HasherSync,
+): string => {
+  const { jwt, kbJwt } = splitSdJwt(sdJwt);
+  const {
+    jwt: { payload },
+    disclosures,
+  } = decodeSdJwtSync(sdJwt, hasher);
+
+  const { _sd_alg: alg } = getSDAlgAndPayload(payload);
+  const hash = { alg, hasher };
+  const keys = transformPresentationFrame(presentFrame);
+
+  // hashmap: <digest> => <disclosure>
+  // to match the digest with the disclosure
+  const hashmap = createHashMappingSync(disclosures, hash);
+  const { disclosureKeymap } = unpackSync(payload, disclosures, hasher);
+
+  const presentedDisclosures = keys
+    .map((k) => hashmap[disclosureKeymap[k]])
+    .filter((d) => d !== undefined);
+
+  return [
+    jwt,
+    ...presentedDisclosures.map((d) => d.encode()),
+    kbJwt ?? '',
+  ].join(SD_SEPARATOR);
+};
+
+/**
+ * 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
+ */
+export const transformPresentationFrame = (
+  obj: PresentationFrame<Extensible>,
+  prefix = '',
+): string[] => {
+  return Object.entries(obj).reduce<string[]>((acc, [key, value]) => {
+    const newPrefix = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === 'boolean') {
+      // only add it, when it's true
+      if (value) {
+        acc.push(newPrefix);
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      acc.push(
+        newPrefix,
+        ...transformPresentationFrame(
+          value as PresentationFrame<Extensible>,
+          newPrefix,
+        ),
+      );
+    }
+    return acc;
+  }, []);
+};
+
+export type SerializedDisclosure = {
+  digest: string;
+  encoded: string;
+  salt: string;
+  key: string | undefined;
+  value: unknown;
+};
+
+export const createHashMappingForSerializedDisclosure = (
+  disclosures: SerializedDisclosure[],
+) => {
+  const map: Record<string, Disclosure> = {};
+  for (let i = 0; i < disclosures.length; i++) {
+    const disclosure = disclosures[i];
+    const { digest, encoded, key, salt, value } = disclosure;
+    // we made Disclosure to fit the interface of unpack
+    map[digest] = Disclosure.fromArray(
+      key ? [salt, key, value] : [salt, value],
+      { digest, encoded },
+    );
+  }
+  return map;
+};
+
+/**
+ * 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>
+ */
+export const selectDisclosures = <T extends Record<string, unknown>>(
+  payload: Record<string, unknown>,
+  disclosures: SerializedDisclosure[],
+  presentationFrame: PresentationFrame<T>,
+) => {
+  if (disclosures.length === 0) {
+    return [];
+  }
+
+  const hashmap = createHashMappingForSerializedDisclosure(disclosures);
+  const { disclosureKeymap } = unpackObj(payload, hashmap);
+  const keys = transformPresentationFrame(presentationFrame);
+
+  const presentedDisclosures = keys
+    .map((k) => hashmap[disclosureKeymap[k]])
+    .filter((d) => d !== undefined);
+
+  const selectedDisclosures: SerializedDisclosure[] = presentedDisclosures.map(
+    (d) => {
+      const { salt, key, value, _digest } = d;
+      if (!_digest) {
+        throw new SDJWTException(
+          'Implementation error: _digest is not defined',
+        );
+      }
+      return {
+        digest: _digest,
+        encoded: d.encode(),
+        salt,
+        key,
+        value,
+      };
+    },
+  );
+
+  return selectedDisclosures;
+};