@sd-jwt/core 0.20.1 → 0.21.0-alpha-20260916100413

package/src/jwt.ts

@@ -1,286 +0,0 @@
-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[];
-
-  /**
-   * Expected audience for the processed SD-JWT payload.
-   */
-  expectedAudience?: string | string[];
-
-  /**
-   * Allowed JOSE algorithms for issuer-signed JWTs. `none` is always rejected.
-   */
-  allowedIssuerAlgorithms?: string[];
-
-  /**
-   * nonce used to verify the key binding jwt to prevent replay attacks.
-   */
-  keyBindingNonce?: string;
-
-  /**
-   * Expected audience for the Key Binding JWT.
-   */
-  expectedKeyBindingAudience?: string | string[];
-
-  /**
-   * Maximum acceptable age of the Key Binding JWT, in seconds.
-   */
-  keyBindingMaxAgeSeconds?: number;
-
-  /**
-   * Internal option used by SD-JWT validation to defer claim checks until after
-   * disclosures are processed.
-   */
-  skipJwtClaimValidation?: boolean;
-
-  /**
-   * disable the verification of the status claim in the payload.
-   *
-   * @default false
-   */
-  disableStatusVerification?: boolean;
-
-  /**
-   * any other custom options
-   */
-  [key: string]: unknown;
-};
-
-const isStringArray = (value: unknown): value is string[] =>
-  Array.isArray(value) && value.every((item) => typeof item === 'string');
-
-const validateNumericDate = (
-  payload: Record<string, unknown>,
-  claim: 'iat' | 'nbf' | 'exp',
-) => {
-  const value = payload[claim];
-  if (value === undefined) return undefined;
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw new SDJWTException(`Verify Error: JWT ${claim} must be a number`);
-  }
-  return value;
-};
-
-const getAudiences = (audience: unknown): string[] | undefined => {
-  if (typeof audience === 'string') return [audience];
-  if (isStringArray(audience)) return audience;
-  return undefined;
-};
-
-const validateAudience = (
-  payload: Record<string, unknown>,
-  expectedAudience: string | string[] | undefined,
-) => {
-  if (expectedAudience === undefined) return;
-
-  const expectedAudiences = Array.isArray(expectedAudience)
-    ? expectedAudience
-    : [expectedAudience];
-  const audiences = getAudiences(payload.aud);
-
-  if (
-    !audiences ||
-    !expectedAudiences.some((expected) => audiences.includes(expected))
-  ) {
-    throw new SDJWTException('Verify Error: Invalid audience');
-  }
-};
-
-export const validateJwtPayload = (
-  payload: Record<string, unknown> | undefined,
-  options?: VerifierOptions,
-) => {
-  if (!payload) {
-    throw new SDJWTException('Verify Error: JWT payload is missing');
-  }
-
-  const skew = options?.skewSeconds ? options.skewSeconds : 0;
-  const currentDate = options?.currentDate ?? Math.floor(Date.now() / 1000);
-  const iat = validateNumericDate(payload, 'iat');
-  const nbf = validateNumericDate(payload, 'nbf');
-  const exp = validateNumericDate(payload, 'exp');
-
-  if (iat !== undefined && iat - skew > currentDate) {
-    throw new SDJWTException('Verify Error: JWT is not yet valid');
-  }
-
-  if (nbf !== undefined && nbf - skew > currentDate) {
-    throw new SDJWTException('Verify Error: JWT is not yet valid');
-  }
-
-  if (exp !== undefined && exp + skew <= currentDate) {
-    throw new SDJWTException('Verify Error: JWT is expired');
-  }
-
-  validateAudience(payload, options?.expectedAudience);
-};
-
-// 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) {
-    if (!this.header || this.header.alg === 'none') {
-      throw new SDJWTException('Sign Error: alg "none" is not allowed');
-    }
-    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 alg = this.header?.alg;
-    if (typeof alg !== 'string' || alg === 'none') {
-      throw new SDJWTException('Verify Error: alg "none" is not allowed');
-    }
-    if (
-      options?.allowedIssuerAlgorithms &&
-      !options.allowedIssuerAlgorithms.includes(alg)
-    ) {
-      throw new SDJWTException(`Verify Error: Disallowed alg ${alg}`);
-    }
-
-    if (!options?.skipJwtClaimValidation) {
-      validateJwtPayload(this.payload, options);
-    }
-
-    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

@@ -1,101 +0,0 @@
-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 (
-      typeof this.header.alg !== 'string' ||
-      this.header.alg === 'none' ||
-      typeof this.header.typ !== 'string' ||
-      this.header.typ !== KB_JWT_TYP ||
-      typeof this.payload.iat !== 'number' ||
-      typeof this.payload.aud !== 'string' ||
-      typeof this.payload.nonce !== 'string' ||
-      typeof this.payload.sd_hash !== 'string' ||
-      this.payload.sd_hash.length === 0
-    ) {
-      throw new SDJWTException('Invalid Key Binding Jwt');
-    }
-
-    if (this.payload.nonce !== values.nonce) {
-      throw new SDJWTException('Verify Error: Invalid Nonce');
-    }
-
-    if (values.options?.expectedKeyBindingAudience !== undefined) {
-      const expectedAudiences = Array.isArray(
-        values.options.expectedKeyBindingAudience,
-      )
-        ? values.options.expectedKeyBindingAudience
-        : [values.options.expectedKeyBindingAudience];
-      if (!expectedAudiences.includes(this.payload.aud)) {
-        throw new SDJWTException('Verify Error: Invalid Key Binding audience');
-      }
-    }
-
-    if (values.options?.keyBindingMaxAgeSeconds !== undefined) {
-      const currentDate =
-        values.options.currentDate ?? Math.floor(Date.now() / 1000);
-      const skew = values.options.skewSeconds ?? 0;
-      if (
-        this.payload.iat + values.options.keyBindingMaxAgeSeconds + skew <
-        currentDate
-      ) {
-        throw new SDJWTException('Verify Error: Key Binding JWT is too old');
-      }
-    }
-
-    // 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

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

package/src/present/present.ts

@@ -1,216 +0,0 @@
-import {
-  createHashMapping,
-  createHashMappingSync,
-  decodeSdJwt,
-  decodeSdJwtSync,
-  getSDAlgAndPayload,
-  splitSdJwt,
-  unpack,
-  unpackObj,
-  unpackSync,
-} from '../decode';
-import type { Extensible, HasherSync } from '../types';
-import {
-  encodePath,
-  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[] = [],
-): string[] => {
-  return Object.entries(obj).reduce<string[]>((acc, [key, value]) => {
-    const newPrefix = [...prefix, key];
-    const encodedPrefix = encodePath(newPrefix);
-    if (typeof value === 'boolean') {
-      // only add it, when it's true
-      if (value) {
-        acc.push(encodedPrefix);
-      }
-    } else if (typeof value === 'object' && value !== null) {
-      acc.push(
-        encodedPrefix,
-        ...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;
-};