@sd-jwt/core 0.3.0 → 2.0.4-next.58

package/src/decoy.ts

@@ -0,0 +1,15 @@
+import { HasherAndAlg, SaltGenerator } from '@sd-jwt/types';
+import { Uint8ArrayToBase64Url } from '@sd-jwt/utils';
+
+// This function creates a decoy value that can be used to obscure SD JWT payload.
+// The value is basically a hash of a random salt. So the value is not predictable.
+// return value is a base64url encoded string.
+export const createDecoy = async (
+  hash: HasherAndAlg,
+  saltGenerator: SaltGenerator,
+): Promise<string> => {
+  const { hasher, alg } = hash;
+  const salt = await saltGenerator(16);
+  const decoy = await hasher(salt, alg);
+  return Uint8ArrayToBase64Url(decoy);
+};

package/src/index.ts

@@ -0,0 +1,235 @@
+import { SDJWTException } from '@sd-jwt/utils';
+import { Jwt } from './jwt';
+import { KBJwt } from './kbjwt';
+import { SDJwt, pack } from './sdjwt';
+import {
+  DisclosureFrame,
+  KBOptions,
+  KB_JWT_TYP,
+  SDJWTCompact,
+  SDJWTConfig,
+  SD_JWT_TYP,
+} from '@sd-jwt/types';
+
+export * from './sdjwt';
+export * from './kbjwt';
+export * from './jwt';
+export * from './decoy';
+
+export class SDJwtInstance {
+  public static DEFAULT_hashAlg = 'sha-256';
+
+  private userConfig: SDJWTConfig = {};
+
+  constructor(userConfig?: SDJWTConfig) {
+    if (userConfig) {
+      this.userConfig = userConfig;
+    }
+  }
+
+  private async createKBJwt(options: KBOptions): Promise<KBJwt> {
+    if (!this.userConfig.kbSigner) {
+      throw new SDJWTException('Key Binding Signer not found');
+    }
+    if (!this.userConfig.kbSignAlg) {
+      throw new SDJWTException('Key Binding sign algorithm not specified');
+    }
+    const { payload } = options;
+    const kbJwt = new KBJwt({
+      header: {
+        typ: KB_JWT_TYP,
+        alg: this.userConfig.kbSignAlg,
+      },
+      payload,
+    });
+
+    await kbJwt.sign(this.userConfig.kbSigner);
+    return kbJwt;
+  }
+
+  private async SignJwt(jwt: Jwt) {
+    if (!this.userConfig.signer) {
+      throw new SDJWTException('Signer not found');
+    }
+    await jwt.sign(this.userConfig.signer);
+    return jwt;
+  }
+
+  private async VerifyJwt(jwt: Jwt) {
+    if (!this.userConfig.verifier) {
+      throw new SDJWTException('Verifier not found');
+    }
+    return jwt.verify(this.userConfig.verifier);
+  }
+
+  public async issue<Payload extends Record<string, unknown>>(
+    payload: Payload,
+    disclosureFrame?: DisclosureFrame<Payload>,
+    options?: {
+      header?: object; // This is for customizing the header of the jwt
+    },
+  ): Promise<SDJWTCompact> {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+
+    if (!this.userConfig.saltGenerator) {
+      throw new SDJWTException('SaltGenerator not found');
+    }
+
+    if (!this.userConfig.signAlg) {
+      throw new SDJWTException('sign alogrithm not specified');
+    }
+
+    const hasher = this.userConfig.hasher;
+    const hashAlg = this.userConfig.hashAlg ?? SDJwtInstance.DEFAULT_hashAlg;
+
+    const { packedClaims, disclosures } = await pack(
+      payload,
+      disclosureFrame,
+      { hasher, alg: hashAlg },
+      this.userConfig.saltGenerator,
+    );
+    const alg = this.userConfig.signAlg;
+    const OptionHeader = options?.header ?? {};
+    const CustomHeader = this.userConfig.omitTyp
+      ? OptionHeader
+      : { typ: SD_JWT_TYP, ...OptionHeader };
+    const header = { ...CustomHeader, alg };
+    const jwt = new Jwt({
+      header,
+      payload: {
+        ...packedClaims,
+        _sd_alg: hashAlg,
+      },
+    });
+    await this.SignJwt(jwt);
+
+    const sdJwt = new SDJwt({
+      jwt,
+      disclosures,
+    });
+
+    return sdJwt.encodeSDJwt();
+  }
+
+  public async present(
+    encodedSDJwt: string,
+    presentationKeys?: string[],
+    options?: {
+      kb?: KBOptions;
+    },
+  ): Promise<SDJWTCompact> {
+    if (!presentationKeys) return encodedSDJwt;
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const hasher = this.userConfig.hasher;
+
+    const sdjwt = await SDJwt.fromEncode(encodedSDJwt, hasher);
+    const kbJwt = options?.kb ? await this.createKBJwt(options.kb) : undefined;
+    sdjwt.kbJwt = kbJwt;
+
+    return sdjwt.present(presentationKeys.sort(), hasher);
+  }
+
+  // This function is for verifying the SD JWT
+  // If requiredClaimKeys is provided, it will check if the required claim keys are presentation in the SD JWT
+  // If requireKeyBindings is true, it will check if the key binding JWT is presentation and verify it
+  public async verify(
+    encodedSDJwt: string,
+    requiredClaimKeys?: string[],
+    requireKeyBindings?: boolean,
+  ) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const hasher = this.userConfig.hasher;
+
+    const sdjwt = await SDJwt.fromEncode(encodedSDJwt, hasher);
+    if (!sdjwt.jwt) {
+      throw new SDJWTException('Invalid SD JWT');
+    }
+    const { payload, header } = await this.validate(encodedSDJwt);
+
+    if (requiredClaimKeys) {
+      const keys = await sdjwt.keys(hasher);
+      const missingKeys = requiredClaimKeys.filter((k) => !keys.includes(k));
+      if (missingKeys.length > 0) {
+        throw new SDJWTException(
+          `Missing required claim keys: ${missingKeys.join(', ')}`,
+        );
+      }
+    }
+
+    if (!requireKeyBindings) {
+      return { payload, header };
+    }
+
+    if (!sdjwt.kbJwt) {
+      throw new SDJWTException('Key Binding JWT not exist');
+    }
+    if (!this.userConfig.kbVerifier) {
+      throw new SDJWTException('Key Binding Verifier not found');
+    }
+    const kb = await sdjwt.kbJwt.verify(this.userConfig.kbVerifier);
+    return { payload, header, kb };
+  }
+
+  // This function is for validating the SD JWT
+  // Just checking signature and return its the claims
+  public async validate(encodedSDJwt: string) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const hasher = this.userConfig.hasher;
+
+    const sdjwt = await SDJwt.fromEncode(encodedSDJwt, hasher);
+    if (!sdjwt.jwt) {
+      throw new SDJWTException('Invalid SD JWT');
+    }
+
+    const verifiedPayloads = await this.VerifyJwt(sdjwt.jwt);
+    const claims = await sdjwt.getClaims(hasher);
+    return { payload: claims, header: verifiedPayloads.header };
+  }
+
+  public config(newConfig: SDJWTConfig) {
+    this.userConfig = { ...this.userConfig, ...newConfig };
+  }
+
+  public encode(sdJwt: SDJwt): SDJWTCompact {
+    return sdJwt.encodeSDJwt();
+  }
+
+  public decode(endcodedSDJwt: SDJWTCompact) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    return SDJwt.fromEncode(endcodedSDJwt, this.userConfig.hasher);
+  }
+
+  public async keys(endcodedSDJwt: SDJWTCompact) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const sdjwt = await SDJwt.fromEncode(endcodedSDJwt, this.userConfig.hasher);
+    return sdjwt.keys(this.userConfig.hasher);
+  }
+
+  public async presentableKeys(endcodedSDJwt: SDJWTCompact) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const sdjwt = await SDJwt.fromEncode(endcodedSDJwt, this.userConfig.hasher);
+    return sdjwt.presentableKeys(this.userConfig.hasher);
+  }
+
+  public async getClaims(endcodedSDJwt: SDJWTCompact) {
+    if (!this.userConfig.hasher) {
+      throw new SDJWTException('Hasher not found');
+    }
+    const sdjwt = await SDJwt.fromEncode(endcodedSDJwt, this.userConfig.hasher);
+    return sdjwt.getClaims(this.userConfig.hasher);
+  }
+}

package/src/jwt.ts

@@ -0,0 +1,107 @@
+import { Base64urlEncode, SDJWTException } from '@sd-jwt/utils';
+import { Base64urlString, Signer, Verifier } from '@sd-jwt/types';
+import { decodeJwt } from '@sd-jwt/decode';
+
+export type JwtData<
+  Header extends Record<string, unknown>,
+  Payload extends Record<string, unknown>,
+> = {
+  header?: Header;
+  payload?: Payload;
+  signature?: Base64urlString;
+};
+
+// 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;
+
+  constructor(data?: JwtData<Header, Payload>) {
+    this.header = data?.header;
+    this.payload = data?.payload;
+    this.signature = data?.signature;
+  }
+
+  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,
+    });
+
+    return jwt;
+  }
+
+  public setHeader(header: Header): Jwt<Header, Payload> {
+    this.header = header;
+    return this;
+  }
+
+  public setPayload(payload: Payload): Jwt<Header, Payload> {
+    this.payload = payload;
+    return this;
+  }
+
+  public async sign(signer: Signer) {
+    if (!this.header || !this.payload) {
+      throw new SDJWTException('Sign Error: Invalid JWT');
+    }
+
+    const header = Base64urlEncode(JSON.stringify(this.header));
+    const payload = Base64urlEncode(JSON.stringify(this.payload));
+    const data = `${header}.${payload}`;
+    this.signature = await signer(data);
+
+    return this.encodeJwt();
+  }
+
+  public encodeJwt(): string {
+    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}`;
+
+    return compact;
+  }
+
+  public async verify(verifier: Verifier) {
+    if (!this.header || !this.payload || !this.signature) {
+      throw new SDJWTException('Verify Error: Invalid JWT');
+    }
+
+    const header = Base64urlEncode(JSON.stringify(this.header));
+    const payload = Base64urlEncode(JSON.stringify(this.payload));
+    const data = `${header}.${payload}`;
+
+    const verified = verifier(data, this.signature);
+    if (!verified) {
+      throw new SDJWTException('Verify Error: Invalid JWT Signature');
+    }
+    return { payload: this.payload, header: this.header };
+  }
+}

package/src/kbjwt.ts

@@ -0,0 +1,45 @@
+import { SDJWTException } from '@sd-jwt/utils';
+import { Jwt } from './jwt';
+import { Verifier, kbHeader, kbPayload } from '@sd-jwt/types';
+
+export class KBJwt<
+  Header extends kbHeader = kbHeader,
+  Payload extends kbPayload = kbPayload,
+> extends Jwt<Header, Payload> {
+  // Checking the validity of the key binding jwt
+  public async verify(verifier: Verifier) {
+    if (
+      !this.header?.alg ||
+      !this.header.typ ||
+      !this.payload?.iat ||
+      !this.payload?.aud ||
+      !this.payload?.nonce ||
+      // this is for backward compatibility with version 06
+      !(
+        this.payload?.sd_hash ||
+        (this.payload as Record<string, unknown> | undefined)?._sd_hash
+      )
+    ) {
+      throw new SDJWTException('Invalid Key Binding Jwt');
+    }
+    return await super.verify(verifier);
+  }
+
+  // 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,
+    });
+
+    return jwt;
+  }
+}