@opentdf/sdk 0.9.0-beta.92 → 0.9.0-beta.94

package/tdf3/src/crypto/jose/jwt-claims-set.ts

@@ -0,0 +1,10 @@
+import type { JWTHeaderParameters, JWTPayload, JWTVerifyOptions } from 'jose';
+import jwtClaimsSet from './vendor/lib/jwt_claims_set.js';
+
+export default function joseJwtClaimsSet(
+  protectedHeader: JWTHeaderParameters,
+  encodedPayload: Uint8Array,
+  options?: JWTVerifyOptions
+): JWTPayload {
+  return jwtClaimsSet(protectedHeader, encodedPayload, options) as JWTPayload;
+}

package/tdf3/src/crypto/jose/validate-crit.ts

@@ -0,0 +1,9 @@
+import validateCrit from './vendor/lib/validate_crit.js';
+
+export default validateCrit as (
+  Err: new (message?: string, options?: { cause?: unknown }) => Error,
+  recognizedDefault: Map<string, boolean>,
+  recognizedOption: Record<string, boolean> | undefined,
+  protectedHeader: Record<string, unknown> | undefined,
+  joseHeader: Record<string, unknown>
+) => Set<string>;

package/tdf3/src/crypto/jose/vendor/lib/buffer_utils.ts

@@ -0,0 +1,34 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+export const encoder = new TextEncoder();
+export const decoder = new TextDecoder();
+const MAX_INT32 = 2 ** 32;
+export function concat(...buffers) {
+    const size = buffers.reduce((acc, { length }) => acc + length, 0);
+    const buf = new Uint8Array(size);
+    let i = 0;
+    for (const buffer of buffers) {
+        buf.set(buffer, i);
+        i += buffer.length;
+    }
+    return buf;
+}
+function writeUInt32BE(buf, value, offset) {
+    if (value < 0 || value >= MAX_INT32) {
+        throw new RangeError(`value must be >= 0 and <= ${MAX_INT32 - 1}. Received ${value}`);
+    }
+    buf.set([value >>> 24, value >>> 16, value >>> 8, value & 0xff], offset);
+}
+export function uint64be(value) {
+    const high = Math.floor(value / MAX_INT32);
+    const low = value % MAX_INT32;
+    const buf = new Uint8Array(8);
+    writeUInt32BE(buf, high, 0);
+    writeUInt32BE(buf, low, 4);
+    return buf;
+}
+export function uint32be(value) {
+    const buf = new Uint8Array(4);
+    writeUInt32BE(buf, value);
+    return buf;
+}

package/tdf3/src/crypto/jose/vendor/lib/epoch.ts

@@ -0,0 +1,3 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+export default (date) => Math.floor(date.getTime() / 1000);

package/tdf3/src/crypto/jose/vendor/lib/is_object.ts

@@ -0,0 +1,18 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+export default (input) => {
+    if (!isObjectLike(input) || Object.prototype.toString.call(input) !== '[object Object]') {
+        return false;
+    }
+    if (Object.getPrototypeOf(input) === null) {
+        return true;
+    }
+    let proto = input;
+    while (Object.getPrototypeOf(proto) !== null) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(input) === proto;
+};

package/tdf3/src/crypto/jose/vendor/lib/jwt_claims_set.ts

@@ -0,0 +1,106 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+import { JWTClaimValidationFailed, JWTExpired, JWTInvalid } from '../util/errors.js';
+import { decoder } from './buffer_utils.js';
+import epoch from './epoch.js';
+import secs from './secs.js';
+import isObject from './is_object.js';
+const normalizeTyp = (value) => value.toLowerCase().replace(/^application\//, '');
+const checkAudiencePresence = (audPayload, audOption) => {
+    if (typeof audPayload === 'string') {
+        return audOption.includes(audPayload);
+    }
+    if (Array.isArray(audPayload)) {
+        return audOption.some(Set.prototype.has.bind(new Set(audPayload)));
+    }
+    return false;
+};
+export default (protectedHeader, encodedPayload, options = {}) => {
+    let payload;
+    try {
+        payload = JSON.parse(decoder.decode(encodedPayload));
+    }
+    catch {
+    }
+    if (!isObject(payload)) {
+        throw new JWTInvalid('JWT Claims Set must be a top-level JSON object');
+    }
+    const { typ } = options;
+    if (typ &&
+        (typeof protectedHeader.typ !== 'string' ||
+            normalizeTyp(protectedHeader.typ) !== normalizeTyp(typ))) {
+        throw new JWTClaimValidationFailed('unexpected "typ" JWT header value', payload, 'typ', 'check_failed');
+    }
+    const { requiredClaims = [], issuer, subject, audience, maxTokenAge } = options;
+    const presenceCheck = [...requiredClaims];
+    if (maxTokenAge !== undefined)
+        presenceCheck.push('iat');
+    if (audience !== undefined)
+        presenceCheck.push('aud');
+    if (subject !== undefined)
+        presenceCheck.push('sub');
+    if (issuer !== undefined)
+        presenceCheck.push('iss');
+    for (const claim of new Set(presenceCheck.reverse())) {
+        if (!(claim in payload)) {
+            throw new JWTClaimValidationFailed(`missing required "${claim}" claim`, payload, claim, 'missing');
+        }
+    }
+    if (issuer &&
+        !(Array.isArray(issuer) ? issuer : [issuer]).includes(payload.iss)) {
+        throw new JWTClaimValidationFailed('unexpected "iss" claim value', payload, 'iss', 'check_failed');
+    }
+    if (subject && payload.sub !== subject) {
+        throw new JWTClaimValidationFailed('unexpected "sub" claim value', payload, 'sub', 'check_failed');
+    }
+    if (audience &&
+        !checkAudiencePresence(payload.aud, typeof audience === 'string' ? [audience] : audience)) {
+        throw new JWTClaimValidationFailed('unexpected "aud" claim value', payload, 'aud', 'check_failed');
+    }
+    let tolerance;
+    switch (typeof options.clockTolerance) {
+        case 'string':
+            tolerance = secs(options.clockTolerance);
+            break;
+        case 'number':
+            tolerance = options.clockTolerance;
+            break;
+        case 'undefined':
+            tolerance = 0;
+            break;
+        default:
+            throw new TypeError('Invalid clockTolerance option type');
+    }
+    const { currentDate } = options;
+    const now = epoch(currentDate || new Date());
+    if ((payload.iat !== undefined || maxTokenAge) && typeof payload.iat !== 'number') {
+        throw new JWTClaimValidationFailed('"iat" claim must be a number', payload, 'iat', 'invalid');
+    }
+    if (payload.nbf !== undefined) {
+        if (typeof payload.nbf !== 'number') {
+            throw new JWTClaimValidationFailed('"nbf" claim must be a number', payload, 'nbf', 'invalid');
+        }
+        if (payload.nbf > now + tolerance) {
+            throw new JWTClaimValidationFailed('"nbf" claim timestamp check failed', payload, 'nbf', 'check_failed');
+        }
+    }
+    if (payload.exp !== undefined) {
+        if (typeof payload.exp !== 'number') {
+            throw new JWTClaimValidationFailed('"exp" claim must be a number', payload, 'exp', 'invalid');
+        }
+        if (payload.exp <= now - tolerance) {
+            throw new JWTExpired('"exp" claim timestamp check failed', payload, 'exp', 'check_failed');
+        }
+    }
+    if (maxTokenAge) {
+        const age = now - payload.iat;
+        const max = typeof maxTokenAge === 'number' ? maxTokenAge : secs(maxTokenAge);
+        if (age - tolerance > max) {
+            throw new JWTExpired('"iat" claim timestamp check failed (too far in the past)', payload, 'iat', 'check_failed');
+        }
+        if (age < 0 - tolerance) {
+            throw new JWTClaimValidationFailed('"iat" claim timestamp check failed (it should be in the past)', payload, 'iat', 'check_failed');
+        }
+    }
+    return payload;
+};

package/tdf3/src/crypto/jose/vendor/lib/secs.ts

@@ -0,0 +1,57 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+const minute = 60;
+const hour = minute * 60;
+const day = hour * 24;
+const week = day * 7;
+const year = day * 365.25;
+const REGEX = /^(\+|\-)? ?(\d+|\d+\.\d+) ?(seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)(?: (ago|from now))?$/i;
+export default (str) => {
+    const matched = REGEX.exec(str);
+    if (!matched || (matched[4] && matched[1])) {
+        throw new TypeError('Invalid time period format');
+    }
+    const value = parseFloat(matched[2]);
+    const unit = matched[3].toLowerCase();
+    let numericDate;
+    switch (unit) {
+        case 'sec':
+        case 'secs':
+        case 'second':
+        case 'seconds':
+        case 's':
+            numericDate = Math.round(value);
+            break;
+        case 'minute':
+        case 'minutes':
+        case 'min':
+        case 'mins':
+        case 'm':
+            numericDate = Math.round(value * minute);
+            break;
+        case 'hour':
+        case 'hours':
+        case 'hr':
+        case 'hrs':
+        case 'h':
+            numericDate = Math.round(value * hour);
+            break;
+        case 'day':
+        case 'days':
+        case 'd':
+            numericDate = Math.round(value * day);
+            break;
+        case 'week':
+        case 'weeks':
+        case 'w':
+            numericDate = Math.round(value * week);
+            break;
+        default:
+            numericDate = Math.round(value * year);
+            break;
+    }
+    if (matched[1] === '-' || matched[4] === 'ago') {
+        return -numericDate;
+    }
+    return numericDate;
+};

package/tdf3/src/crypto/jose/vendor/lib/validate_crit.ts

@@ -0,0 +1,35 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+import { JOSENotSupported, JWEInvalid, JWSInvalid } from '../util/errors.js';
+export default (Err, recognizedDefault, recognizedOption, protectedHeader, joseHeader) => {
+    if (joseHeader.crit !== undefined && protectedHeader?.crit === undefined) {
+        throw new Err('"crit" (Critical) Header Parameter MUST be integrity protected');
+    }
+    if (!protectedHeader || protectedHeader.crit === undefined) {
+        return new Set();
+    }
+    if (!Array.isArray(protectedHeader.crit) ||
+        protectedHeader.crit.length === 0 ||
+        protectedHeader.crit.some((input) => typeof input !== 'string' || input.length === 0)) {
+        throw new Err('"crit" (Critical) Header Parameter MUST be an array of non-empty strings when present');
+    }
+    let recognized;
+    if (recognizedOption !== undefined) {
+        recognized = new Map([...Object.entries(recognizedOption), ...recognizedDefault.entries()]);
+    }
+    else {
+        recognized = recognizedDefault;
+    }
+    for (const parameter of protectedHeader.crit) {
+        if (!recognized.has(parameter)) {
+            throw new JOSENotSupported(`Extension Header Parameter "${parameter}" is not recognized`);
+        }
+        if (joseHeader[parameter] === undefined) {
+            throw new Err(`Extension Header Parameter "${parameter}" is missing`);
+        }
+        if (recognized.get(parameter) && protectedHeader[parameter] === undefined) {
+            throw new Err(`Extension Header Parameter "${parameter}" MUST be integrity protected`);
+        }
+    }
+    return new Set(protectedHeader.crit);
+};

package/tdf3/src/crypto/jose/vendor/util/errors.ts

@@ -0,0 +1,101 @@
+// @ts-nocheck
+// Generated from jose@6.0.8. Do not edit directly.
+export class JOSEError extends Error {
+    static code = 'ERR_JOSE_GENERIC';
+    code = 'ERR_JOSE_GENERIC';
+    constructor(message, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+export class JWTClaimValidationFailed extends JOSEError {
+    static code = 'ERR_JWT_CLAIM_VALIDATION_FAILED';
+    code = 'ERR_JWT_CLAIM_VALIDATION_FAILED';
+    claim;
+    reason;
+    payload;
+    constructor(message, payload, claim = 'unspecified', reason = 'unspecified') {
+        super(message, { cause: { claim, reason, payload } });
+        this.claim = claim;
+        this.reason = reason;
+        this.payload = payload;
+    }
+}
+export class JWTExpired extends JOSEError {
+    static code = 'ERR_JWT_EXPIRED';
+    code = 'ERR_JWT_EXPIRED';
+    claim;
+    reason;
+    payload;
+    constructor(message, payload, claim = 'unspecified', reason = 'unspecified') {
+        super(message, { cause: { claim, reason, payload } });
+        this.claim = claim;
+        this.reason = reason;
+        this.payload = payload;
+    }
+}
+export class JOSEAlgNotAllowed extends JOSEError {
+    static code = 'ERR_JOSE_ALG_NOT_ALLOWED';
+    code = 'ERR_JOSE_ALG_NOT_ALLOWED';
+}
+export class JOSENotSupported extends JOSEError {
+    static code = 'ERR_JOSE_NOT_SUPPORTED';
+    code = 'ERR_JOSE_NOT_SUPPORTED';
+}
+export class JWEDecryptionFailed extends JOSEError {
+    static code = 'ERR_JWE_DECRYPTION_FAILED';
+    code = 'ERR_JWE_DECRYPTION_FAILED';
+    constructor(message = 'decryption operation failed', options) {
+        super(message, options);
+    }
+}
+export class JWEInvalid extends JOSEError {
+    static code = 'ERR_JWE_INVALID';
+    code = 'ERR_JWE_INVALID';
+}
+export class JWSInvalid extends JOSEError {
+    static code = 'ERR_JWS_INVALID';
+    code = 'ERR_JWS_INVALID';
+}
+export class JWTInvalid extends JOSEError {
+    static code = 'ERR_JWT_INVALID';
+    code = 'ERR_JWT_INVALID';
+}
+export class JWKInvalid extends JOSEError {
+    static code = 'ERR_JWK_INVALID';
+    code = 'ERR_JWK_INVALID';
+}
+export class JWKSInvalid extends JOSEError {
+    static code = 'ERR_JWKS_INVALID';
+    code = 'ERR_JWKS_INVALID';
+}
+export class JWKSNoMatchingKey extends JOSEError {
+    static code = 'ERR_JWKS_NO_MATCHING_KEY';
+    code = 'ERR_JWKS_NO_MATCHING_KEY';
+    constructor(message = 'no applicable key found in the JSON Web Key Set', options) {
+        super(message, options);
+    }
+}
+export class JWKSMultipleMatchingKeys extends JOSEError {
+    [Symbol.asyncIterator];
+    static code = 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
+    code = 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
+    constructor(message = 'multiple matching keys found in the JSON Web Key Set', options) {
+        super(message, options);
+    }
+}
+export class JWKSTimeout extends JOSEError {
+    static code = 'ERR_JWKS_TIMEOUT';
+    code = 'ERR_JWKS_TIMEOUT';
+    constructor(message = 'request timed out', options) {
+        super(message, options);
+    }
+}
+export class JWSSignatureVerificationFailed extends JOSEError {
+    static code = 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED';
+    code = 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED';
+    constructor(message = 'signature verification failed', options) {
+        super(message, options);
+    }
+}

package/tdf3/src/crypto/jwt.ts

@@ -0,0 +1,256 @@
+import {
+  type AsymmetricSigningAlgorithm,
+  type CryptoService,
+  type PrivateKey,
+  type PublicKey,
+  type SigningAlgorithm,
+  type SymmetricKey,
+} from './declarations.js';
+import { base64 } from '../../../src/encodings/index.js';
+import {
+  decodeProtectedHeader as joseDecodeProtectedHeader,
+  errors as joseErrors,
+  type JWTHeaderParameters,
+  type JWTPayload,
+  type JWTVerifyOptions,
+  type SignOptions,
+} from 'jose';
+import jwtClaimsSet from './jose/jwt-claims-set.js';
+import validateCrit from './jose/validate-crit.js';
+
+export type JwtHeader = JWTHeaderParameters & { alg: SigningAlgorithm };
+export type JwtPayload = JWTPayload;
+
+/**
+ * Options for JWT signing. Matches jose SignOptions interface.
+ */
+export type SignJwtOptions = SignOptions;
+
+/**
+ * Options for JWT verification. Matches jose JWTVerifyOptions interface.
+ * Combines signature verification options and JWT claim verification options.
+ */
+export type VerifyJwtOptions = Omit<JWTVerifyOptions, 'algorithms'> & {
+  /**
+   * A list of accepted JWS "alg" (Algorithm) Header Parameter values.
+   * By default all algorithms supported by the CryptoService are allowed.
+   * Unsecured JWTs ({ "alg": "none" }) are never accepted.
+   */
+  algorithms?: SigningAlgorithm[];
+};
+
+/**
+ * Base64url encode data per RFC 4648 Section 5.
+ * Uses URL-safe alphabet (- and _ instead of + and /) with no padding.
+ * Exported for testing purposes.
+ */
+export function base64urlEncode(data: string | Uint8Array): string {
+  if (typeof data === 'string') {
+    // Encode string to base64url
+    const bytes = new TextEncoder().encode(data);
+    return base64.encodeArrayBuffer(bytes.buffer, true); // urlSafe = true
+  } else {
+    // Encode Uint8Array to base64url
+    const buffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    return base64.encodeArrayBuffer(buffer, true); // urlSafe = true
+  }
+}
+
+/**
+ * Helper to convert base64url to standard base64 with padding.
+ */
+function base64urlToBase64(str: string): string {
+  // Convert base64url to base64: replace - with +, _ with /
+  let b64 = str.replace(/-/g, '+').replace(/_/g, '/');
+
+  // Add padding if needed
+  const padding = (4 - (b64.length % 4)) % 4;
+  b64 += '='.repeat(padding);
+
+  return b64;
+}
+
+/**
+ * Base64url decode to Uint8Array per RFC 4648 Section 5.
+ */
+function base64urlDecodeBytes(str: string): Uint8Array {
+  const b64 = base64urlToBase64(str);
+  return new Uint8Array(base64.decodeArrayBuffer(b64));
+}
+
+/**
+ * Decode the protected header from a JWT without verifying the signature.
+ * Useful for inspecting the header to determine key type before verification.
+ *
+ * @param token - The JWT string
+ * @returns The decoded header
+ * @throws Error if the token is malformed or uses alg "none"
+ */
+export function decodeProtectedHeader(token: string): JwtHeader {
+  return joseDecodeProtectedHeader(token) as JwtHeader;
+}
+
+/**
+ * Sign a JWT using CryptoService. Replaces jose SignJWT.
+ *
+ * Implementation:
+ * 1. Base64url encode header and payload as JSON
+ * 2. Create signing input: `${headerB64}.${payloadB64}`
+ * 3. Sign via cryptoService.sign() (asymmetric) or hmac() (HS256)
+ * 4. Return compact JWT: `${headerB64}.${payloadB64}.${signatureB64}`
+ *
+ * @param cryptoService - Crypto implementation to use
+ * @param payload - JWT payload (claims)
+ * @param key - PEM-encoded private key for asymmetric algorithms, or raw key bytes for HS256
+ * @param header - JWT header (must include alg)
+ * @param options - Optional signing options (e.g., crit header handling)
+ * @returns Compact JWT string
+ */
+export async function signJwt(
+  cryptoService: CryptoService,
+  payload: JwtPayload,
+  key: PrivateKey | SymmetricKey,
+  header: JwtHeader,
+  options?: SignJwtOptions
+): Promise<string> {
+  validateCrit(joseErrors.JWSInvalid, new Map([['b64', true]]), options?.crit, header, header);
+
+  // Encode header and payload per RFC 7515
+  const headerB64 = base64urlEncode(JSON.stringify(header));
+  const payloadB64 = base64urlEncode(JSON.stringify(payload));
+
+  // Create signing input
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signingInputBytes = new TextEncoder().encode(signingInput);
+
+  // Sign via CryptoService - route based on algorithm
+  let signature: Uint8Array;
+  if (header.alg === 'HS256') {
+    if (key._brand !== 'SymmetricKey') {
+      throw new Error('HS256 requires a SymmetricKey');
+    }
+    signature = await cryptoService.hmac(signingInputBytes, key);
+  } else {
+    if (key._brand !== 'PrivateKey') {
+      throw new Error(`${header.alg} requires a PrivateKey`);
+    }
+    signature = await cryptoService.sign(
+      signingInputBytes,
+      key,
+      header.alg as AsymmetricSigningAlgorithm
+    );
+  }
+
+  // Return compact JWT
+  return `${signingInput}.${base64urlEncode(signature)}`;
+}
+
+/**
+ * Verify a JWT and return its contents. Replaces jose jwtVerify.
+ *
+ * Implementation:
+ * 1. Split token into header.payload.signature
+ * 2. Decode header, validate algorithm against allowlist
+ * 3. Verify signature via cryptoService.verify() (asymmetric) or verifyHmac() (HS256)
+ * 4. Validate JWT claims (aud, iss, exp, nbf, etc.)
+ * 5. Return decoded header and payload
+ *
+ * @param cryptoService - Crypto implementation to use
+ * @param token - The JWT string to verify
+ * @param key - For asymmetric: PEM string or PublicKey (opaque). For HS256: Uint8Array or SymmetricKey (opaque).
+ * @param options - Verification options including algorithm allowlist and claim validations
+ * @throws Error if signature invalid, algorithm not in allowlist, claims invalid, or token malformed
+ * @returns Decoded header and payload
+ */
+export async function verifyJwt(
+  cryptoService: CryptoService,
+  token: string,
+  key: string | Uint8Array | PublicKey | SymmetricKey,
+  options?: VerifyJwtOptions
+): Promise<{ header: JwtHeader; payload: JwtPayload }> {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    throw new joseErrors.JWTInvalid('Invalid Token or Protected Header formatting');
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // Decode and validate header
+  const headerRaw = decodeProtectedHeader(token);
+  if (typeof headerRaw.alg !== 'string' || !headerRaw.alg) {
+    throw new joseErrors.JWTInvalid('JWS "alg" (Algorithm) Header Parameter missing or invalid');
+  }
+  if ((headerRaw.alg as string) === 'none') {
+    throw new joseErrors.JWTInvalid('Invalid JWT: alg "none" not allowed');
+  }
+
+  // Validate algorithm is in allowlist if provided
+  if (options?.algorithms && !options.algorithms.includes(headerRaw.alg as SigningAlgorithm)) {
+    throw new joseErrors.JWTInvalid(`Invalid JWT: algorithm "${headerRaw.alg}" not in allowlist`);
+  }
+
+  const extensions = validateCrit(
+    joseErrors.JWSInvalid,
+    new Map([['b64', true]]),
+    options?.crit,
+    headerRaw,
+    headerRaw
+  );
+
+  // Now we know it's a valid algorithm
+  const header = headerRaw as JwtHeader;
+
+  // Verify signature via CryptoService - route based on algorithm
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const signingInputBytes = new TextEncoder().encode(signingInput);
+  const signature = base64urlDecodeBytes(signatureB64);
+
+  let valid: boolean;
+  if (header.alg === 'HS256') {
+    // Symmetric verification - accept Uint8Array or SymmetricKey
+    if (typeof key === 'string') {
+      throw new Error('HS256 requires a Uint8Array or SymmetricKey, not a PEM string');
+    }
+    if ('_brand' in key && key._brand === 'PublicKey') {
+      throw new Error('HS256 requires a SymmetricKey, not a PublicKey');
+    }
+    // Convert Uint8Array to SymmetricKey if needed, otherwise assume it's already SymmetricKey
+    const symmetricKey =
+      key instanceof Uint8Array
+        ? await cryptoService.importSymmetricKey(key)
+        : (key as SymmetricKey);
+    valid = await cryptoService.verifyHmac(signingInputBytes, signature, symmetricKey);
+  } else {
+    // Asymmetric verification - accept string (PEM) or PublicKey
+    if (key instanceof Uint8Array) {
+      throw new Error(`${header.alg} requires a PEM string or PublicKey, not Uint8Array`);
+    }
+    if (typeof key === 'object' && '_brand' in key && key._brand === 'SymmetricKey') {
+      throw new Error(`${header.alg} requires a PublicKey, not a SymmetricKey`);
+    }
+    // Convert PEM string to PublicKey if needed, otherwise assume it's already PublicKey
+    const publicKey =
+      typeof key === 'string'
+        ? await cryptoService.importPublicKey(key, { usage: 'sign' })
+        : (key as PublicKey);
+    valid = await cryptoService.verify(
+      signingInputBytes,
+      signature,
+      publicKey,
+      header.alg as AsymmetricSigningAlgorithm
+    );
+  }
+
+  if (!valid) {
+    throw new joseErrors.JWTInvalid('Invalid JWT: signature verification failed');
+  }
+
+  if (extensions.has('b64') && (header as { b64?: boolean }).b64 === false) {
+    throw new joseErrors.JWTInvalid('JWTs MUST NOT use unencoded payload');
+  }
+
+  // Decode payload and validate JWT claims
+  const payloadBytes = base64urlDecodeBytes(payloadB64);
+  const payload = jwtClaimsSet(header, payloadBytes, options) as JwtPayload;
+
+  return { header, payload };
+}

package/tdf3/src/crypto/salt.ts

@@ -1,11 +1,19 @@
-const generateSalt = async () => {
-  const encoder = new TextEncoder();
-  const data = encoder.encode('TDF');
+import type { CryptoService } from './declarations.js';
+
+let cachedSalt: Uint8Array | null = null;
 
-  // Generate hash
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+/**
+ * Get the ZTDF salt (SHA-256 of "TDF").
+ * Lazily computed on first call and cached thereafter.
+ */
+export async function getZtdfSalt(cryptoService: CryptoService): Promise<Uint8Array> {
+  if (cachedSalt) {
+    return cachedSalt;
+  }
 
-  return new Uint8Array(hashBuffer);
-};
+  const encoder = new TextEncoder();
+  const data = encoder.encode('TDF');
 
-export const ztdfSalt = generateSalt();
+  cachedSalt = await cryptoService.digest('SHA-256', data);
+  return cachedSalt;
+}