@opentdf/sdk 0.9.0-beta.91 → 0.9.0-beta.93

package/src/auth/oidc.ts

@@ -1,8 +1,9 @@
-import { default as dpopFn } from 'dpop';
+import { default as dpopFn } from './dpop.js';
 import { HttpRequest, withHeaders } from './auth.js';
 import { base64 } from '../encodings/index.js';
 import { ConfigurationError, TdfError } from '../errors.js';
-import { cryptoPublicToPem, rstrip } from '../utils.js';
+import { rstrip } from '../utils.js';
+import { type CryptoService, type KeyPair } from '../../tdf3/src/crypto/declarations.js';
 
 /**
  * Common fields used by all OIDC credentialing flows.
@@ -18,7 +19,7 @@ export type CommonCredentials = {
   dpopEnabled?: boolean;
 
   /** the client's public key, base64 encoded. Will be bound to the OIDC token. Deprecated. If not set in the constructor, */
-  signingKey?: CryptoKeyPair;
+  signingKey?: KeyPair;
 };
 
 /**
@@ -94,13 +95,15 @@ export class AccessToken {
   tokenEndpoint: string;
   userInfoEndpoint: string;
 
-  signingKey?: CryptoKeyPair;
+  signingKey?: KeyPair;
 
   extraHeaders: Record<string, string> = {};
 
   currentAccessToken?: string;
 
-  constructor(cfg: OIDCCredentials, request?: typeof fetch) {
+  cryptoService: CryptoService;
+
+  constructor(cfg: OIDCCredentials, cryptoService: CryptoService, request?: typeof fetch) {
     if (!cfg.clientId) {
       throw new ConfigurationError(
         'A Keycloak client identifier is currently required for all auth mechanisms'
@@ -121,6 +124,7 @@ export class AccessToken {
       throw new ConfigurationError('Invalid oidc configuration');
     }
     this.config = cfg;
+    this.cryptoService = cryptoService;
     this.request = request;
     this.baseUrl = rstrip(cfg.oidcOrigin, '/');
     this.tokenEndpoint = cfg.oidcTokenEndpoint || `${this.baseUrl}/protocol/openid-connect/token`;
@@ -140,7 +144,12 @@ export class AccessToken {
       Authorization: `Bearer ${accessToken}`,
     } as Record<string, string>;
     if (this.config.dpopEnabled && this.signingKey) {
-      headers.DPoP = await dpopFn(this.signingKey, this.userInfoEndpoint, 'POST');
+      headers.DPoP = await dpopFn(
+        this.signingKey,
+        this.cryptoService,
+        this.userInfoEndpoint,
+        'POST'
+      );
     }
     const response = await (this.request || fetch)(this.userInfoEndpoint, {
       headers,
@@ -165,9 +174,10 @@ export class AccessToken {
       if (!this.signingKey) {
         throw new ConfigurationError('No signature configured');
       }
-      const clientPubKey = await cryptoPublicToPem(this.signingKey.publicKey);
-      headers['X-VirtruPubKey'] = base64.encode(clientPubKey);
-      headers.DPoP = await dpopFn(this.signingKey, url, 'POST');
+      // Export opaque public key to PEM format for header
+      const publicKeyPem = await this.cryptoService.exportPublicKeyPem(this.signingKey.publicKey);
+      headers['X-VirtruPubKey'] = base64.encode(publicKeyPem);
+      headers.DPoP = await dpopFn(this.signingKey, this.cryptoService, url, 'POST');
     }
     return (this.request || fetch)(url, {
       method: 'POST',
@@ -251,7 +261,7 @@ export class AccessToken {
    *
    * Calling this function will trigger a forcible token refresh using the cached refresh token, and contact the auth server.
    */
-  async refreshTokenClaimsWithClientPubkeyIfNeeded(signingKey: CryptoKeyPair): Promise<void> {
+  async refreshTokenClaimsWithClientPubkeyIfNeeded(signingKey: KeyPair): Promise<void> {
     // If we already have a token, and the pubkey changes,
     // we need to force a refresh now - otherwise
     // we can wait until we create the token for the first time
@@ -299,6 +309,7 @@ export class AccessToken {
     if (this.config.dpopEnabled && this.signingKey) {
       const dpopToken = await dpopFn(
         this.signingKey,
+        this.cryptoService,
         httpReq.url,
         httpReq.method,
         /* nonce */ undefined,

package/src/auth/providers.ts

@@ -10,6 +10,8 @@ import { type AuthProvider } from './auth.js';
 import { OIDCRefreshTokenProvider } from './oidc-refreshtoken-provider.js';
 import { isBrowser } from '../utils.js';
 import { ConfigurationError } from '../errors.js';
+import { type CryptoService } from '../../tdf3/src/crypto/declarations.js';
+import * as defaultCryptoService from '../../tdf3/src/crypto/index.js';
 
 /**
  * Creates an OIDC Client Credentials Provider for non-browser contexts.
@@ -30,15 +32,19 @@ import { ConfigurationError } from '../errors.js';
  *
  */
 export const clientSecretAuthProvider = async (
-  clientConfig: ClientSecretCredentials
+  clientConfig: ClientSecretCredentials,
+  cryptoService: CryptoService = defaultCryptoService
 ): Promise<OIDCClientCredentialsProvider> => {
-  return new OIDCClientCredentialsProvider({
-    clientId: clientConfig.clientId,
-    clientSecret: clientConfig.clientSecret,
-    oidcOrigin: clientConfig.oidcOrigin,
-    oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
-    oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
-  });
+  return new OIDCClientCredentialsProvider(
+    {
+      clientId: clientConfig.clientId,
+      clientSecret: clientConfig.clientSecret,
+      oidcOrigin: clientConfig.oidcOrigin,
+      oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
+      oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
+    },
+    cryptoService
+  );
 };
 
 /**
@@ -58,15 +64,19 @@ export const clientSecretAuthProvider = async (
  * {@link updateClientPublicKey}, which will force an explicit token refresh.
  */
 export const externalAuthProvider = async (
-  clientConfig: ExternalJwtCredentials
+  clientConfig: ExternalJwtCredentials,
+  cryptoService: CryptoService = defaultCryptoService
 ): Promise<OIDCExternalJwtProvider> => {
-  return new OIDCExternalJwtProvider({
-    clientId: clientConfig.clientId,
-    externalJwt: clientConfig.externalJwt,
-    oidcOrigin: clientConfig.oidcOrigin,
-    oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
-    oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
-  });
+  return new OIDCExternalJwtProvider(
+    {
+      clientId: clientConfig.clientId,
+      externalJwt: clientConfig.externalJwt,
+      oidcOrigin: clientConfig.oidcOrigin,
+      oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
+      oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
+    },
+    cryptoService
+  );
 };
 
 /**
@@ -84,15 +94,19 @@ export const externalAuthProvider = async (
  * {@link updateClientPublicKey} which will force an explicit token refresh
  */
 export const refreshAuthProvider = async (
-  clientConfig: RefreshTokenCredentials
+  clientConfig: RefreshTokenCredentials,
+  cryptoService: CryptoService = defaultCryptoService
 ): Promise<OIDCRefreshTokenProvider> => {
-  return new OIDCRefreshTokenProvider({
-    clientId: clientConfig.clientId,
-    refreshToken: clientConfig.refreshToken,
-    oidcOrigin: clientConfig.oidcOrigin,
-    oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
-    oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
-  });
+  return new OIDCRefreshTokenProvider(
+    {
+      clientId: clientConfig.clientId,
+      refreshToken: clientConfig.refreshToken,
+      oidcOrigin: clientConfig.oidcOrigin,
+      oidcTokenEndpoint: clientConfig.oidcTokenEndpoint,
+      oidcUserInfoEndpoint: clientConfig.oidcUserInfoEndpoint,
+    },
+    cryptoService
+  );
 };
 
 /**
@@ -100,7 +114,10 @@ export const refreshAuthProvider = async (
  * @param clientConfig OIDC client credentials
  * @returns a promise for a new auth provider with the requested excahnge type
  */
-export const clientAuthProvider = async (clientConfig: OIDCCredentials): Promise<AuthProvider> => {
+export const clientAuthProvider = async (
+  clientConfig: OIDCCredentials,
+  cryptoService: CryptoService = defaultCryptoService
+): Promise<AuthProvider> => {
   if (!clientConfig.clientId) {
     throw new ConfigurationError('Client ID must be provided to constructor');
   }
@@ -116,13 +133,13 @@ export const clientAuthProvider = async (clientConfig: OIDCCredentials): Promise
     //and provide us with a valid refresh token/clientId obtained from that process.
     switch (clientConfig.exchange) {
       case 'refresh': {
-        return refreshAuthProvider(clientConfig);
+        return refreshAuthProvider(clientConfig, cryptoService);
       }
       case 'external': {
-        return externalAuthProvider(clientConfig);
+        return externalAuthProvider(clientConfig, cryptoService);
       }
       case 'client': {
-        return clientSecretAuthProvider(clientConfig);
+        return clientSecretAuthProvider(clientConfig, cryptoService);
       }
       default:
         throw new ConfigurationError(`Unsupported client type`);
@@ -136,7 +153,7 @@ export const clientAuthProvider = async (clientConfig: OIDCCredentials): Promise
       'When using client credentials, must supply both client ID and client secret to constructor'
     );
   }
-  return clientSecretAuthProvider(clientConfig);
+  return clientSecretAuthProvider(clientConfig, cryptoService);
 };
 
 export * from './auth.js';

package/src/crypto/index.ts

@@ -6,5 +6,25 @@ export { generateKeyPair } from './generateKeyPair.js';
 export { keyAgreement } from './keyAgreement.js';
 export { default as exportCryptoKey } from './exportCryptoKey.js';
 export { generateRandomNumber } from './generateRandomNumber.js';
-export { pemPublicToCrypto, pemCertToCrypto } from './pemPublicToCrypto.js';
+export {
+  pemPublicToCrypto,
+  pemCertToCrypto,
+  guessAlgorithmName,
+  guessCurveName,
+  toJwsAlg,
+  RSA_OID,
+  EC_OID,
+  P256_OID,
+  P384_OID,
+  P521_OID,
+  type AlgorithmName,
+} from './pemPublicToCrypto.js';
 export * as enums from './enums.js';
+
+// PEM Formatting Utilities from tdf3
+export {
+  formatAsPem,
+  removePemFormatting,
+  isPemKeyPair,
+  isCryptoKeyPair,
+} from '../../tdf3/src/crypto/crypto-utils.js';

package/src/crypto/pemPublicToCrypto.ts

@@ -33,11 +33,12 @@ import { encodeArrayBuffer as hexEncodeArrayBuffer } from '../encodings/hex.js';
 import { ConfigurationError, TdfError } from '../errors.js';
 import { NamedCurve } from './enums.js';
 
-const RSA_OID = '06092a864886f70d010101';
-const EC_OID = '06072a8648ce3d0201';
-const P256_OID = '06082a8648ce3d030107';
-const P384_OID = '06052b81040022';
-const P521_OID = '06052b81040023';
+// OID constants for algorithm detection (hex-encoded ASN.1 OIDs)
+export const RSA_OID = '06092a864886f70d010101';
+export const EC_OID = '06072a8648ce3d0201';
+export const P256_OID = '06082a8648ce3d030107';
+export const P384_OID = '06052b81040022';
+export const P521_OID = '06052b81040023';
 const SHA_512 = 'SHA-512';
 const SPKI = 'spki';
 const CERT_BEGIN = '-----BEGIN CERTIFICATE-----';
@@ -47,7 +48,7 @@ const ECDH = 'ECDH';
 const ECDSA = 'ECDSA';
 const RSA_OAEP = 'RSA-OAEP';
 const RSA_PSS = 'RSA-PSS';
-type AlgorithmName = typeof ECDH | typeof ECDSA | typeof RSA_OAEP | typeof RSA_PSS;
+export type AlgorithmName = typeof ECDH | typeof ECDSA | typeof RSA_OAEP | typeof RSA_PSS;
 
 interface PemPublicToCryptoOptions {
   name?: string;
@@ -71,7 +72,7 @@ function guessKeyUsages(algorithmName: AlgorithmName, usages?: KeyUsage[]): KeyU
   }
 }
 
-function guessAlgorithmName(hex: string, algorithmName?: string): AlgorithmName {
+export function guessAlgorithmName(hex: string, algorithmName?: string): AlgorithmName {
   if (hex.includes(EC_OID)) {
     if (!algorithmName || algorithmName === ECDH) {
       return ECDH;
@@ -88,7 +89,7 @@ function guessAlgorithmName(hex: string, algorithmName?: string): AlgorithmName
   throw new TypeError(`Invalid public key, ${algorithmName}`);
 }
 
-function guessCurveName(hex: string): NamedCurve {
+export function guessCurveName(hex: string): NamedCurve {
   if (hex.includes(P256_OID)) {
     return NamedCurve.P256;
   } else if (hex.includes(P384_OID)) {
@@ -155,9 +156,10 @@ export async function pemPublicToCrypto(
 }
 
 /**
+ * Detect JWS algorithm from hex-encoded key/certificate data.
  * Look up JWK algorithm at https://github.com/panva/jose/issues/210
  */
-function toJwsAlg(hex: string) {
+export function toJwsAlg(hex: string) {
   const a = guessAlgorithmName(hex);
   if (a === ECDH) {
     return 'ECDH-ES';

package/src/opentdf.ts

@@ -3,6 +3,8 @@ import { ConfigurationError, InvalidFileError } from './errors.js';
 export { Client as TDF3Client } from '../tdf3/src/client/index.js';
 import { Chunker, fromSource, sourceToStream, type Source } from './seekable.js';
 import { Client as TDF3Client } from '../tdf3/src/client/index.js';
+import { type CryptoService, type KeyPair } from '../tdf3/src/crypto/declarations.js';
+import * as DefaultCryptoService from '../tdf3/src/crypto/index.js';
 import {
   type Assertion,
   AssertionConfig,
@@ -33,6 +35,7 @@ import { Policy } from '../tdf3/src/models/policy.js';
 
 export {
   type Assertion,
+  type CryptoService,
   type EncryptionInformation,
   type IntegrityAlgorithm,
   type KasPublicKeyAlgorithm,
@@ -172,7 +175,14 @@ export type OpenTDFOptions = {
    * These often must be registered via a DPoP flow with the IdP
    * which is out of the scope of this library.
    */
-  dpopKeys?: Promise<CryptoKeyPair>;
+  dpopKeys?: Promise<KeyPair>;
+
+  /**
+   * Optional custom CryptoService implementation.
+   * If not provided, defaults to the browser's native Web Crypto API.
+   * This allows injecting HSM-backed or other secure crypto implementations.
+   */
+  cryptoService?: CryptoService;
 };
 
 /** A decorated readable stream. */
@@ -257,7 +267,9 @@ export class OpenTDF {
   /** Default options for reading TDF objects. */
   defaultReadOptions: Omit<ReadOptions, 'source'>;
   /** The DPoP keys for this instance, if any. */
-  readonly dpopKeys: Promise<CryptoKeyPair>;
+  readonly dpopKeys: Promise<KeyPair>;
+  /** The CryptoService implementation for this instance. */
+  readonly cryptoService: CryptoService;
   /** The TDF3 client for encrypting and decrypting ZTDF files. */
   readonly tdf3Client: TDF3Client;
 
@@ -269,6 +281,7 @@ export class OpenTDF {
     disableDPoP,
     policyEndpoint,
     platformUrl,
+    cryptoService,
   }: OpenTDFOptions) {
     this.authProvider = authProvider;
     this.defaultCreateOptions = defaultCreateOptions || {};
@@ -282,25 +295,17 @@ export class OpenTDF {
       );
     }
     this.policyEndpoint = policyEndpoint || '';
+    this.cryptoService = cryptoService ?? DefaultCryptoService;
     this.tdf3Client = new TDF3Client({
       authProvider,
       dpopKeys,
       kasEndpoint: this.platformUrl || 'https://disallow.all.invalid',
       platformUrl,
       policyEndpoint,
+      cryptoService: this.cryptoService,
     });
-    this.dpopKeys =
-      dpopKeys ??
-      crypto.subtle.generateKey(
-        {
-          name: 'RSASSA-PKCS1-v1_5',
-          hash: 'SHA-256',
-          modulusLength: 2048,
-          publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
-        },
-        true,
-        ['sign', 'verify']
-      );
+    // Use CryptoService for key generation (returns opaque KeyPair)
+    this.dpopKeys = dpopKeys ?? this.cryptoService.generateSigningKeyPair();
   }
 
   /** Creates a new ZTDF stream. */

package/tdf3/index.ts

@@ -14,10 +14,23 @@ import {
 } from './src/client/builders.js';
 import { type ClientConfig, createSessionKeys } from './src/client/index.js';
 import {
+  type AsymmetricSigningAlgorithm,
   type CryptoService,
   type DecryptResult,
+  type ECCurve,
   type EncryptResult,
+  type HashAlgorithm,
+  type HkdfParams,
+  type KeyPair,
+  type KeyOptions,
+  type KeyAlgorithm,
   type PemKeyPair,
+  type PrivateKey,
+  type PublicKey,
+  type PublicKeyInfo,
+  type SigningAlgorithm,
+  type SymmetricKey,
+  type SymmetricSigningAlgorithm,
 } from './src/crypto/declarations.js';
 import { Client, Errors, TDF3Client } from './src/index.js';
 import {
@@ -35,18 +48,31 @@ import { type Chunker } from '../src/seekable.js';
 export type {
   AlgorithmName,
   AlgorithmUrn,
+  AsymmetricSigningAlgorithm,
   AuthProvider,
   Chunker,
   CryptoService,
+  DecryptKeyMiddleware,
   DecryptResult,
+  DecryptStreamMiddleware,
+  ECCurve,
+  EncryptKeyMiddleware,
   EncryptResult,
+  EncryptStreamMiddleware,
+  HashAlgorithm,
+  HkdfParams,
   HttpMethod,
+  KeyPair,
+  KeyOptions,
+  KeyAlgorithm,
   PemKeyPair,
-  EncryptKeyMiddleware,
-  EncryptStreamMiddleware,
-  DecryptKeyMiddleware,
-  DecryptStreamMiddleware,
+  PrivateKey,
+  PublicKey,
+  PublicKeyInfo,
+  SigningAlgorithm,
   SplitStep,
+  SymmetricKey,
+  SymmetricSigningAlgorithm,
 };
 
 export {
@@ -74,7 +100,8 @@ export {
   version,
 };
 
-export * as WebCryptoService from './src/crypto/index.js';
+export { DefaultCryptoService as WebCryptoService } from './src/crypto/index.js';
+// export the other methods from crypto/index.js that aren't part of CryptoService but are needed for JWT handling
 export {
   type CreateOptions,
   type CreateZTDFOptions,

package/tdf3/src/assertions.ts

@@ -1,8 +1,14 @@
 import { canonicalizeEx } from 'json-canonicalize';
-import { SignJWT, jwtVerify, importJWK, importX509 } from 'jose';
 import { base64, hex } from '../../src/encodings/index.js';
 import { ConfigurationError, IntegrityError, InvalidFileError } from '../../src/errors.js';
 import { tdfSpecVersion, version as sdkVersion } from '../../src/version.js';
+import {
+  type CryptoService,
+  type PrivateKey,
+  type PublicKey,
+  type SymmetricKey,
+} from './crypto/declarations.js';
+import { decodeProtectedHeader, signJwt, verifyJwt, type JwtHeader } from './crypto/jwt.js';
 
 export type AssertionKeyAlg = 'ES256' | 'RS256' | 'HS256';
 export type AssertionType = 'handling' | 'other';
@@ -41,39 +47,69 @@ export type AssertionPayload = {
 /**
  * Computes the SHA-256 hash of the assertion object, excluding the 'binding' and 'hash' properties.
  *
+ * @param a - The assertion to hash
+ * @param cryptoService - The crypto service to use for hashing
  * @returns the hexadecimal string representation of the hash
  */
-export async function hash(a: Assertion): Promise<string> {
+export async function hash(a: Assertion, cryptoService: CryptoService): Promise<string> {
   const result = canonicalizeEx(a, {
     exclude: ['binding', 'hash', 'sign', 'verify', 'signingKey'],
   });
 
-  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(result));
-  return hex.encodeArrayBuffer(hash);
+  const hashBytes = await cryptoService.digest('SHA-256', new TextEncoder().encode(result));
+  return hex.encodeArrayBuffer(hashBytes.buffer);
 }
 
 /**
  * Signs the given hash and signature using the provided key and sets the binding method and signature.
  *
- * @param hash - The hash to be signed.
+ * @param thiz - The assertion to sign.
+ * @param assertionHash - The hash to be signed.
  * @param sig - The signature to be signed.
- * @param {AssertionKey} key - The key used for signing.
- * @returns {Promise<void>} A promise that resolves when the signing is complete.
+ * @param key - The key used for signing.
+ * @param cryptoService - The crypto service to use for signing.
+ * @returns A promise that resolves to the signed assertion.
  */
 async function sign(
   thiz: Assertion,
   assertionHash: string,
   sig: string,
-  key: AssertionKey
+  key: AssertionKey,
+  cryptoService: CryptoService
 ): Promise<Assertion> {
   const payload: AssertionPayload = {
     assertionHash,
     assertionSig: sig,
   };
 
+  const header: JwtHeader = { alg: key.alg };
+
+  if (typeof key.key === 'object' && '_brand' in key.key && key.key._brand === 'PublicKey') {
+    throw new ConfigurationError(
+      'Cannot sign assertion with PublicKey. Use PrivateKey or SymmetricKey for signing.'
+    );
+  }
+
+  let signingMaterial: PrivateKey | SymmetricKey;
+  if (typeof key.key === 'string') {
+    if (!cryptoService.importPrivateKey) {
+      throw new ConfigurationError(
+        'CryptoService does not support importing private keys. Cannot sign assertion with a PEM string. Use PrivateKey or SymmetricKey for signing.'
+      );
+    }
+    signingMaterial = await cryptoService.importPrivateKey(key.key, {
+      usage: 'sign',
+      extractable: false,
+    });
+  } else if (key.key instanceof Uint8Array) {
+    signingMaterial = await cryptoService.importSymmetricKey(key.key);
+  } else {
+    signingMaterial = key.key as PrivateKey | SymmetricKey;
+  }
+
   let token: string;
   try {
-    token = await new SignJWT(payload).setProtectedHeader({ alg: key.alg }).sign(key.key);
+    token = await signJwt(cryptoService, payload, signingMaterial, header);
   } catch (error) {
     throw new ConfigurationError(`Signing assertion failed: ${error.message}`, error);
   }
@@ -107,36 +143,54 @@ export function isAssertionConfig(obj: unknown): obj is AssertionConfig {
 /**
  * Verifies the signature of the assertion using the provided key.
  *
- * @param {AssertionKey} key - The key used for verification.
- * @returns {Promise<[string, string]>} A promise that resolves to a tuple containing the assertion hash and signature.
- * @throws {Error} If the verification fails.
+ * @param thiz - The assertion to verify.
+ * @param aggregateHash - The aggregate hash for integrity checking.
+ * @param key - The key used for verification.
+ * @param isLegacyTDF - Whether this is a legacy TDF format.
+ * @param cryptoService - The crypto service to use for verification.
+ * @throws {InvalidFileError} If the verification fails.
+ * @throws {IntegrityError} If the integrity check fails.
  */
 export async function verify(
   thiz: Assertion,
   aggregateHash: Uint8Array,
   key: AssertionKey,
-  isLegacyTDF: boolean
+  isLegacyTDF: boolean,
+  cryptoService: CryptoService
 ): Promise<void> {
   let payload: AssertionPayload;
   try {
-    const uj = await jwtVerify(thiz.binding.signature, async (header) => {
-      if (header.jwk) {
-        return await importJWK(header.jwk, header.alg);
-      }
-      if (header.x5c && header.x5c.length > 0) {
-        const cert = `-----BEGIN CERTIFICATE-----\n${header.x5c[0]}\n-----END CERTIFICATE-----`;
-        return await importX509(cert, header.alg);
-      }
-      return key.key;
+    // Parse JWT header to check for embedded keys (jwk or x5c)
+    const header = decodeProtectedHeader(thiz.binding.signature);
+
+    // Runtime check: ensure we have a verification key, not a signing key
+    if (typeof key.key === 'object' && '_brand' in key.key && key.key._brand === 'PrivateKey') {
+      throw new ConfigurationError(
+        'Cannot verify assertion with PrivateKey. Use PublicKey or SymmetricKey for verification.'
+      );
+    }
+    let verificationKey: string | Uint8Array | PublicKey | SymmetricKey = key.key;
+
+    if (header.jwk) {
+      // Convert embedded JWK to PEM
+      verificationKey = await cryptoService.jwkToPublicKeyPem(header.jwk as JsonWebKey);
+    } else if (header.x5c && Array.isArray(header.x5c) && header.x5c.length > 0) {
+      // Extract public key from X.509 certificate
+      const cert = `-----BEGIN CERTIFICATE-----\n${header.x5c[0]}\n-----END CERTIFICATE-----`;
+      verificationKey = await cryptoService.extractPublicKeyPem(cert);
+    }
+
+    const result = await verifyJwt(cryptoService, thiz.binding.signature, verificationKey, {
+      algorithms: [key.alg],
     });
-    payload = uj.payload as AssertionPayload;
+    payload = result.payload as AssertionPayload;
   } catch (error) {
     throw new InvalidFileError(`Verifying assertion failed: ${error.message}`, error);
   }
   const { assertionHash, assertionSig } = payload;
 
   // Get the hash of the assertion
-  const hashOfAssertion = await hash(thiz);
+  const hashOfAssertion = await hash(thiz, cryptoService);
 
   // check if assertionHash is same as hashOfAssertion
   if (hashOfAssertion !== assertionHash) {
@@ -164,13 +218,17 @@ export async function verify(
 
 /**
  * Creates an Assertion object with the specified properties.
- */
-/**
- * Creates an Assertion object with the specified properties.
+ *
+ * @param aggregateHash - The aggregate hash for the assertion.
+ * @param assertionConfig - The configuration for the assertion.
+ * @param cryptoService - The crypto service to use for signing.
+ * @param targetVersion - The target TDF spec version.
+ * @returns The created assertion.
  */
 export async function CreateAssertion(
   aggregateHash: Uint8Array | string,
   assertionConfig: AssertionConfig,
+  cryptoService: CryptoService,
   targetVersion?: string
 ): Promise<Assertion> {
   if (!assertionConfig.signingKey) {
@@ -187,7 +245,7 @@ export async function CreateAssertion(
     binding: { method: '', signature: '' },
   };
 
-  const assertionHash = await hash(a);
+  const assertionHash = await hash(a, cryptoService);
   let encodedHash: string;
   switch (targetVersion || '4.3.0') {
     case '4.2.2':
@@ -212,12 +270,23 @@ export async function CreateAssertion(
       throw new ConfigurationError(`Unsupported TDF spec version: [${targetVersion}]`);
   }
 
-  return await sign(a, assertionHash, encodedHash, assertionConfig.signingKey);
+  return await sign(a, assertionHash, encodedHash, assertionConfig.signingKey, cryptoService);
 }
 
+// TODO: Split AssertionKey into two separate types:
+//   - AssertionSigningKey: key restricted to PrivateKey | SymmetricKey (no strings, no raw bytes)
+//   - AssertionVerificationKey: key restricted to string | PublicKey | SymmetricKey
+// This would make the signing/verification distinction type-safe rather than relying on runtime checks.
+// AssertionConfig.signingKey would use AssertionSigningKey; verify() and AssertionVerificationKeys would use AssertionVerificationKey.
+
+/**
+ * Key used for signing or verifying assertions.
+ * For asymmetric algorithms (RS256, ES256): PEM string, PrivateKey (for signing), or PublicKey (for verification).
+ * For symmetric algorithms (HS256): Uint8Array or SymmetricKey (opaque).
+ */
 export type AssertionKey = {
   alg: AssertionKeyAlg;
-  key: CryptoKey | Uint8Array;
+  key: string | Uint8Array | PrivateKey | PublicKey | SymmetricKey;
 };
 
 // AssertionConfig is a shadow of Assertion with the addition of the signing key.