@tinfoilsh/passkey-kit 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,13 @@
 # Tinfoil Passkey Kit
 
-Cross-platform SDKs for protecting content-encryption keys with passkeys and
-the WebAuthn PRF extension. The JavaScript and Swift implementations share the
-same protocol constants and wire formats, so either client can recover a CEK
-wrapped by the other.
+JavaScript and Swift libraries for wrapping 32-byte keys with passkeys and the
+WebAuthn PRF extension. Both implementations use the same profile-driven wire
+format and can recover records produced by the other.
 
-- Passkey creation and authentication with PRF
-- HKDF-SHA-256 key-encryption-key derivation
-- AES-256-GCM CEK wrapping and unwrapping
-- Stable CEK key-ID derivation
-- Device-local PRF and credential persistence
+This kit performs local key wrapping. It does not log users in, authenticate a
+session to a server, or provide hosted storage.
 
-## JavaScript
+## JavaScript quickstart
 
 Install the browser package:
 
@@ -19,109 +15,170 @@ Install the browser package:
 npm install @tinfoilsh/passkey-kit
 ```
 
-```ts
-import { createPasskeyKit, generateCek } from "@tinfoilsh/passkey-kit";
+Create one explicit version 1 profile and keep every field stable for existing
+records. The display name belongs to manager configuration, not the profile.
 
-const kit = createPasskeyKit({
-  rpId: "example.com",
-  rpName: "Example App",
+```ts
+import {
+  createPasskeyKeyManager,
+  decodeWrappedKeyRecord,
+  encodeWrappedKeyRecord,
+} from "@tinfoilsh/passkey-kit";
+
+const encoder = new TextEncoder();
+const profile = {
+  version: 1,
+  relyingPartyId: "example.com",
+  prfSalt: encoder.encode("example-key-wrapping"),
+  hkdfInfo: encoder.encode("example-wrapping-key-v1"),
+};
+const manager = createPasskeyKeyManager({
+  profile,
+  relyingPartyName: "Example App",
 });
-
-const cek = generateCek();
-const enrolled = await kit.enroll({
-  user: { id: userId, name: email, displayName },
-  cek,
+const key = crypto.getRandomValues(new Uint8Array(32));
+
+const created = await manager.createAndWrapKey({
+  user: {
+    id: crypto.getRandomValues(new Uint8Array(32)),
+    name: "person@example.com",
+    displayName: "Example Person",
+  },
+  key,
 });
+await wrappedKeyRepository.save(encodeWrappedKeyRecord(created.wrappedKey));
 
-if (enrolled) {
-  await api.saveBundle(enrolled.wrappedCek);
-}
+const records: string[] = await wrappedKeyRepository.list();
+const wrappedKeys = records.map(decodeWrappedKeyRecord);
+const recovered = await manager.recoverKey({ wrappedKeys });
+useKey(recovered.key);
+```
 
-const unlocked = await kit.unlock(bundlesFromServer);
-if (unlocked) {
-  useCek(unlocked.cek);
-}
+`evaluateCredential` is available for advanced migrations that need direct PRF
+evaluation:
+
+```ts
+const evaluated = await manager.evaluateCredential({
+  credentialIds: wrappedKeys.map(({ credentialId }) => credentialId),
+});
+usePRFOutput(evaluated.prfResult.output);
+evaluated.prfResult.output.fill(0);
 ```
 
-High-level ceremony methods return `null` when the user cancels. They throw
-`PrfNotSupportedError` when the authenticator lacks PRF support and
-`PasskeyTimeoutError` when the provider hangs. Classify these errors with
-`instanceof`, not message strings.
+Treat PRF output as secret key material and prefer `recoverKey` for normal
+recovery. `wrappedKeyRepository` is application-owned. See the minimal
+[repository interface](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/docs/wrapped-key-repository.md)
+and runnable [web example](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/Examples/Web/README.md).
 
-The kit also provides cached unlock and rewrap flows. Lower-level exports
-include `detectPrfSupport`, `deriveKeyEncryptionKey`, `generateCek`,
-`isValidCek`, `wrapCek`, `unwrapCek`, and `deriveKeyId`.
+Ceremony failures throw `PasskeyKeyError`. Branch on its stable `category`, not
+its message. Local PRF caching is disabled unless the application supplies a
+`PasskeyKeyStorage`; cached PRF output is secret key material.
 
-The default storage adapter uses `localStorage` on a best-effort basis. Pass
-`storage: null` to disable persistence or provide a custom `StorageAdapter`.
-Cached PRF output is raw secret key material and must be protected accordingly.
+Persistence is disabled by default. Cached recovery and rewrap require an
+explicit synchronous `PasskeyKeyStorage`. Cached PRF output is raw secret key
+material and requires host-appropriate protection.
 
-## Swift
+The memory adapter is suitable for tests. The explicitly named
+`createInsecureBrowserLocalStoragePasskeyKeyStorage(namespace)` adapter stores
+raw PRF output unencrypted, isolates records by its required namespace, and is
+insecure because same-origin scripts can read the cached secret material.
+
+`evaluateCredential` exposes raw PRF output for advanced migrations. Treat
+`prfResult.output` as secret key material and prefer `recoverKey` for normal
+recovery. `wrapKeyWithPRFResult` and `unwrapKeyWithPRFResult` perform explicit
+crypto-only operations without starting a ceremony or accessing storage.
+
+## Swift quickstart
 
 Add this repository as a Swift Package Manager dependency and link the
 `TinfoilPasskeyKit` product. The package requires iOS 18 or macOS 15.
 
 ```swift
+import Foundation
 import TinfoilPasskeyKit
 
 @MainActor
-func configurePasskeyKit() async throws {
-    let store = KeychainPasskeyStateStore(
-        service: "example.com",
-        account: "com.example.passkey-prf",
-        localCredentialIdKey: "com.example.local-passkey-id"
+func protectKey(
+    _ key: Data,
+    presentationAnchorProvider: any PasskeyPresentationAnchorProviding
+) async throws {
+    let profile = try PasskeyKeyProfile(
+        version: 1,
+        relyingPartyId: "example.com",
+        prfSalt: Data("example-key-wrapping".utf8),
+        hkdfInfo: Data("example-wrapping-key-v1".utf8)
     )
-    let kit = PasskeyKit(
-        configuration: PasskeyKitConfiguration(
-            rpId: "example.com",
-            rpName: "Example App",
-            stateStore: store
-        )
+    let manager = try PasskeyKeyManager(
+        profile: profile,
+        relyingPartyName: "Example App",
+        presentationAnchorProvider: presentationAnchorProvider
     )
 
-    let cek = try PasskeyCrypto.generateCEK()
-    let enrollment = try await kit.enroll(
-        user: PasskeyUser(id: userId, name: email, displayName: displayName),
-        cek: cek
+    let created = try await manager.createAndWrapKey(
+        user: PasskeyUser(
+            id: opaqueUserHandle,
+            name: "person@example.com",
+            displayName: "Example Person"
+        ),
+        key: key
     )
-    await saveToServer(enrollment.wrappedCEK)
+    await wrappedKeyRepository.save(try encodeWrappedKeyRecord(created.wrappedKey))
 
-    let unlocked = try await kit.unlock(wrappedCEKsFromServer)
-    useCEK(unlocked.cek)
+    let records: [Data] = await wrappedKeyRepository.list()
+    let wrappedKeys = try records.map(decodeWrappedKeyRecord)
+    let recovered = try await manager.recoverKey(wrappedKeys: wrappedKeys)
+    useKey(recovered.key)
 }
 ```
 
-`KeychainPasskeyStateStore` stores cached PRF output with
-`kSecAttrAccessibleWhenUnlockedThisDeviceOnly`. Pass `stateStore: nil` to
-disable local persistence. The host app must provide the `webcredentials`
-associated-domain entitlement for its relying-party domain.
-
-## Protocol
-
-Both implementations default to the Tinfoil v1 PRF salt and HKDF info. These
-values must remain identical across clients that wrap the same CEK. Override
-both values together to establish a separate protocol domain.
-
-The server-persisted wrapped bundle contains only:
-
-- The unpadded base64url credential ID
-- The 12-byte AES-GCM IV as lowercase hexadecimal
-- The wrapped CEK ciphertext and 16-byte authentication tag as lowercase
-  hexadecimal
-
-User identity, server persistence, associated-domain configuration, and
-recovery UI remain the host application's responsibility.
-
-## License
-
-Apache License 2.0. See [LICENSE](LICENSE).
+Advanced flows can call `evaluateCredential(credentialIds:interaction:)`.
+Its `prfResult.output` is raw secret key material. Do not log, transmit, or
+retain it longer than necessary.
+
+Apple hosts must pass a `PasskeyPresentationAnchorProviding` implementation to
+the manager as `presentationAnchorProvider`. The provider returns the iOS or
+macOS window AuthenticationServices uses for interactive presentation. Making
+it required prevents constructing a manager that cannot present a ceremony.
+AuthenticationServices does not accept the configured `relyingPartyName`; Apple
+derives relying-party presentation from system and associated-domain metadata.
+
+Persistence is disabled by default. `KeychainPasskeyKeyStorage` is an optional
+generic Apple adapter that stores cached PRF output with
+`kSecAttrAccessibleWhenUnlockedThisDeviceOnly`. Its records are device-bound and
+unavailable while the device is locked, but any process context that can read
+the item can recover keys without another passkey prompt. Choose storage based
+on the host app's threat model. The host app must also provide the
+`webcredentials` associated-domain entitlement for its relying-party domain.
+Keychain operations are synchronous and can block the manager's main actor.
+
+On iOS 18 and macOS 15, recovery supports platform and synced passkeys,
+including Apple's cross-device passkey flow. Explicit security-key PRF is not
+currently enabled in the Apple target because the baseline toolchain does not
+provide that API. Browsers may support security-key or hybrid recovery.
+Capability remains `unknown` when Apple cannot preflight PRF support; callers
+should allow an attempt.
+
+See the compilable [Apple example](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/Examples/Apple/README.md).
+
+## Documentation
+
+- [API contract](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/docs/api-contract.md)
+- [Support matrix](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/docs/support-matrix.md)
+- [Security boundary](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/docs/security-boundary.md)
+- [Scope](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/docs/scope.md)
+- [Contributing](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/tinfoilsh/tinfoil-passkey-kit/blob/main/SECURITY.md)
 
 ## Development
 
 ```sh
-npm install
+npm ci
 npm test
 npm run typecheck
 npm run build
 swift test
 ```
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

package/dist/crypto.d.ts

@@ -1,55 +1,12 @@
-/**
- * Pure WebCrypto primitives: PRF output → KEK derivation (HKDF-SHA-256)
- * and CEK wrap/unwrap under that KEK (AES-256-GCM).
- *
- * References:
- * - W3C WebAuthn Level 3, §10.1.4 (PRF extension): https://w3c.github.io/webauthn/#prf-extension
- * - RFC 5869 (HKDF): https://tools.ietf.org/html/rfc5869
- */
-import type { WrappedCek } from "./types.js";
-export declare const CEK_BYTES = 32;
-/** Generate a fresh random 32-byte CEK suitable for {@link wrapCek}. */
-export declare function generateCek(): Uint8Array;
-/**
- * Type guard for a well-formed CEK: a Uint8Array of exactly
- * {@link CEK_BYTES} bytes. Useful for validating deserialized input
- * before wrapping.
- */
-export declare function isValidCek(cek: unknown): cek is Uint8Array;
-/**
- * Derive an AES-256-GCM Key Encryption Key (KEK) from PRF output using HKDF.
- *
- * Raw PRF output is treated as Input Keying Material (IKM), not used
- * directly as a key. HKDF with a purpose-binding info string produces the
- * final non-extractable CryptoKey. An empty HKDF salt is used, which is
- * fine for high-entropy IKM (RFC 5869 §3.1).
- *
- * `hkdfInfo` defaults to the Tinfoil v1 protocol constant so standalone
- * callers derive the same interoperable KEK as a default-configured kit.
- */
-export declare function deriveKeyEncryptionKey(prfOutput: ArrayBuffer | Uint8Array, hkdfInfo?: string | Uint8Array): Promise<CryptoKey>;
-/**
- * Wrap a raw 32-byte CEK under a passkey-derived KEK using AES-256-GCM
- * with a fresh random IV. The returned hex fields are safe to persist
- * server-side; only the matching passkey can recover the CEK.
- */
-export declare function wrapCek(opts: {
-    credentialId: string;
-    kek: CryptoKey;
-    cek: Uint8Array;
-}): Promise<WrappedCek>;
-/**
- * Inverse of {@link wrapCek}: recover the raw CEK bytes given the same KEK.
- * Throws on tamper (GCM auth failure) or any shape mismatch.
- */
-export declare function unwrapCek(kek: CryptoKey, wrapped: Pick<WrappedCek, "kekIvHex" | "wrappedKeyHex">): Promise<Uint8Array>;
-/**
- * Derive a stable public identifier for a CEK via HKDF-SHA-256 with an
- * empty salt and a purpose-binding info string. The result identifies the key
- * without revealing it (one-way derivation).
- */
-export declare function deriveKeyId(cek: Uint8Array, opts?: {
-    info?: string | Uint8Array;
-    lengthBytes?: number;
-}): Promise<Uint8Array>;
+import type { PasskeyKeyProfile, WrappedKey } from "./types.js";
+export declare const PROFILE_KEYS: readonly ["version", "relyingPartyId", "prfSalt", "hkdfInfo"];
+export declare function copyAndValidateProfile(profile: PasskeyKeyProfile): PasskeyKeyProfile;
+export declare function profilesEqual(left: PasskeyKeyProfile, right: PasskeyKeyProfile): boolean;
+export declare function decodeCanonicalBase64Url(value: unknown, field: string): Uint8Array;
+export declare function validateCredentialId(credentialId: string): void;
+export declare function validateKey(key: Uint8Array, operation?: string): void;
+export declare function validateWrappedKey(wrapped: WrappedKey, profile: PasskeyKeyProfile): void;
+export declare function deriveWrappingKey(prfOutput: Uint8Array, profile: PasskeyKeyProfile): Promise<CryptoKey>;
+export declare function wrapKey(profile: PasskeyKeyProfile, credentialId: string, prfOutput: Uint8Array, key: Uint8Array, operation?: string): Promise<WrappedKey>;
+export declare function unwrapKey(profile: PasskeyKeyProfile, prfOutput: Uint8Array, wrapped: WrappedKey, operation?: string): Promise<Uint8Array>;
 //# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAO,MAAM,SAAS,KAAK,CAAC;AAI5B,wEAAwE;AACxE,wBAAgB,WAAW,IAAI,UAAU,CAExC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,WAAW,GAAG,UAAU,EACnC,QAAQ,GAAE,MAAM,GAAG,UAAiC,GACnD,OAAO,CAAC,SAAS,CAAC,CAqBpB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,SAAS,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;CACjB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBtB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,eAAe,CAAC,GACtD,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,UAAU,EACf,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9D,OAAO,CAAC,UAAU,CAAC,CAyBrB"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAMhE,eAAO,MAAM,YAAY,+DAKf,CAAC;AAQX,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAqBpF;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAST;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAmBlF;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAIrE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAmBxF;AAED,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,CAAC,CAwBpB;AAED,wBAAsB,OAAO,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,UAAU,EACf,SAAS,SAAqB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,SAAe,GACvB,OAAO,CAAC,UAAU,CAAC,CAgBrB"}

package/dist/crypto.js

@@ -1,105 +1,154 @@
-/**
- * Pure WebCrypto primitives: PRF output → KEK derivation (HKDF-SHA-256)
- * and CEK wrap/unwrap under that KEK (AES-256-GCM).
- *
- * References:
- * - W3C WebAuthn Level 3, §10.1.4 (PRF extension): https://w3c.github.io/webauthn/#prf-extension
- * - RFC 5869 (HKDF): https://tools.ietf.org/html/rfc5869
- */
-import { bytesToHex, hexToBytes, toBytes } from "./codec.js";
-import { PasskeyKitError } from "./errors.js";
-import { TINFOIL_HKDF_INFO_V1, TINFOIL_KEY_ID_INFO_V1 } from "./protocol.js";
-export const CEK_BYTES = 32;
+import { base64UrlToBytes, bytesToBase64Url, bytesToHex, hexToBytes, } from "./codec.js";
+import { invalidInput, operationFailed, PasskeyKeyError } from "./errors.js";
+const KEY_BYTES = 32;
+const PRF_OUTPUT_BYTES = 32;
 const AES_GCM_IV_BYTES = 12;
-const DEFAULT_KEY_ID_BYTES = 16;
-/** Generate a fresh random 32-byte CEK suitable for {@link wrapCek}. */
-export function generateCek() {
-    return crypto.getRandomValues(new Uint8Array(CEK_BYTES));
-}
-/**
- * Type guard for a well-formed CEK: a Uint8Array of exactly
- * {@link CEK_BYTES} bytes. Useful for validating deserialized input
- * before wrapping.
- */
-export function isValidCek(cek) {
-    return cek instanceof Uint8Array && cek.length === CEK_BYTES;
-}
-/**
- * Derive an AES-256-GCM Key Encryption Key (KEK) from PRF output using HKDF.
- *
- * Raw PRF output is treated as Input Keying Material (IKM), not used
- * directly as a key. HKDF with a purpose-binding info string produces the
- * final non-extractable CryptoKey. An empty HKDF salt is used, which is
- * fine for high-entropy IKM (RFC 5869 §3.1).
- *
- * `hkdfInfo` defaults to the Tinfoil v1 protocol constant so standalone
- * callers derive the same interoperable KEK as a default-configured kit.
- */
-export async function deriveKeyEncryptionKey(prfOutput, hkdfInfo = TINFOIL_HKDF_INFO_V1) {
-    const masterKey = await crypto.subtle.importKey("raw", prfOutput, "HKDF", false, // non-extractable
-    ["deriveKey"]);
-    return crypto.subtle.deriveKey({
-        name: "HKDF",
-        hash: "SHA-256",
-        salt: new Uint8Array(),
-        info: toBytes(hkdfInfo),
-    }, masterKey, { name: "AES-GCM", length: 256 }, false, // non-extractable
-    ["encrypt", "decrypt"]);
+const AES_GCM_TAG_BYTES = 16;
+export const PROFILE_KEYS = [
+    "version",
+    "relyingPartyId",
+    "prfSalt",
+    "hkdfInfo",
+];
+function assertBytes(value, name, allowEmpty = false) {
+    if (!(value instanceof Uint8Array) || (!allowEmpty && value.length === 0)) {
+        throw invalidInput(`${name} must be ${allowEmpty ? "a" : "a non-empty"} Uint8Array`);
+    }
 }
-/**
- * Wrap a raw 32-byte CEK under a passkey-derived KEK using AES-256-GCM
- * with a fresh random IV. The returned hex fields are safe to persist
- * server-side; only the matching passkey can recover the CEK.
- */
-export async function wrapCek(opts) {
-    if (opts.cek.length !== CEK_BYTES) {
-        throw new PasskeyKitError(`passkey-kit: CEK must be ${CEK_BYTES} bytes, got ${opts.cek.length}`);
-    }
-    const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
-    const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, opts.kek, opts.cek);
+export function copyAndValidateProfile(profile) {
+    if (!profile || typeof profile !== "object")
+        throw invalidInput("profile is required");
+    const keys = Object.keys(profile).sort();
+    const expected = [...PROFILE_KEYS].sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+        throw invalidInput(`profile must contain exactly ${PROFILE_KEYS.join(", ")}`);
+    }
+    if (profile.version !== 1) {
+        throw invalidInput("profile.version must be 1");
+    }
+    if (typeof profile.relyingPartyId !== "string" || profile.relyingPartyId.length === 0) {
+        throw invalidInput("profile.relyingPartyId must be a non-empty string");
+    }
+    assertBytes(profile.prfSalt, "profile.prfSalt");
+    assertBytes(profile.hkdfInfo, "profile.hkdfInfo");
     return {
-        credentialId: opts.credentialId,
-        kekIvHex: bytesToHex(iv),
-        wrappedKeyHex: bytesToHex(new Uint8Array(ciphertext)),
+        version: profile.version,
+        relyingPartyId: profile.relyingPartyId,
+        prfSalt: profile.prfSalt.slice(),
+        hkdfInfo: profile.hkdfInfo.slice(),
     };
 }
-/**
- * Inverse of {@link wrapCek}: recover the raw CEK bytes given the same KEK.
- * Throws on tamper (GCM auth failure) or any shape mismatch.
- */
-export async function unwrapCek(kek, wrapped) {
-    if (!wrapped.kekIvHex || !wrapped.wrappedKeyHex) {
-        throw new PasskeyKitError("passkey-kit: missing iv or wrapped key");
-    }
-    const iv = hexToBytes(wrapped.kekIvHex);
-    if (iv.length !== AES_GCM_IV_BYTES) {
-        throw new PasskeyKitError("passkey-kit: iv length mismatch");
-    }
-    const ciphertext = hexToBytes(wrapped.wrappedKeyHex);
-    const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: iv }, kek, ciphertext);
-    const cek = new Uint8Array(plaintext);
-    if (cek.length !== CEK_BYTES) {
-        throw new PasskeyKitError(`passkey-kit: unwrapped CEK has wrong length ${cek.length}`);
-    }
-    return cek;
+export function profilesEqual(left, right) {
+    return (left.version === right.version &&
+        left.relyingPartyId === right.relyingPartyId &&
+        left.prfSalt.length === right.prfSalt.length &&
+        left.prfSalt.every((byte, index) => byte === right.prfSalt[index]) &&
+        left.hkdfInfo.length === right.hkdfInfo.length &&
+        left.hkdfInfo.every((byte, index) => byte === right.hkdfInfo[index]));
+}
+export function decodeCanonicalBase64Url(value, field) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        !/^[A-Za-z0-9_-]+$/.test(value) ||
+        value.length % 4 === 1) {
+        throw invalidInput(`${field} must be unpadded base64url`);
+    }
+    try {
+        const bytes = base64UrlToBytes(value);
+        if (bytes.length === 0 || bytesToBase64Url(bytes) !== value) {
+            throw invalidInput(`${field} must use canonical unpadded base64url`);
+        }
+        return bytes;
+    }
+    catch (cause) {
+        if (cause instanceof PasskeyKeyError)
+            throw cause;
+        throw invalidInput(`${field} must be unpadded base64url`);
+    }
+}
+export function validateCredentialId(credentialId) {
+    decodeCanonicalBase64Url(credentialId, "credentialId");
 }
-/**
- * Derive a stable public identifier for a CEK via HKDF-SHA-256 with an
- * empty salt and a purpose-binding info string. The result identifies the key
- * without revealing it (one-way derivation).
- */
-export async function deriveKeyId(cek, opts = {}) {
-    if (cek.length !== CEK_BYTES) {
-        throw new PasskeyKitError(`passkey-kit: CEK must be ${CEK_BYTES} bytes, got ${cek.length}`);
-    }
-    const lengthBytes = opts.lengthBytes ?? DEFAULT_KEY_ID_BYTES;
-    const ikm = await crypto.subtle.importKey("raw", cek, "HKDF", false, ["deriveBits"]);
-    const bits = await crypto.subtle.deriveBits({
-        name: "HKDF",
-        hash: "SHA-256",
-        salt: new Uint8Array(0),
-        info: toBytes(opts.info ?? TINFOIL_KEY_ID_INFO_V1),
-    }, ikm, lengthBytes * 8);
-    return new Uint8Array(bits);
+export function validateKey(key, operation) {
+    if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) {
+        throw invalidInput(`key must be exactly ${KEY_BYTES} bytes`, operation);
+    }
+}
+export function validateWrappedKey(wrapped, profile) {
+    if (!wrapped || typeof wrapped !== "object")
+        throw invalidInput("wrapped key is required");
+    const keys = Object.keys(wrapped).sort();
+    const expected = ["profile", "credentialId", "kekIvHex", "wrappedKeyHex"].sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+        throw invalidInput("wrapped key has unexpected fields");
+    }
+    const wrappedProfile = copyAndValidateProfile(wrapped.profile);
+    if (!profilesEqual(wrappedProfile, profile)) {
+        throw invalidInput("wrapped key profile mismatch");
+    }
+    validateCredentialId(wrapped.credentialId);
+    if (!/^[0-9a-f]{24}$/.test(wrapped.kekIvHex)) {
+        throw invalidInput("kekIvHex must be a lowercase 12-byte hex value");
+    }
+    const ciphertextHexLength = (KEY_BYTES + AES_GCM_TAG_BYTES) * 2;
+    if (!new RegExp(`^[0-9a-f]{${ciphertextHexLength}}$`).test(wrapped.wrappedKeyHex)) {
+        throw invalidInput("wrappedKeyHex has an invalid format or length");
+    }
+}
+export async function deriveWrappingKey(prfOutput, profile) {
+    if (!(prfOutput instanceof Uint8Array) || prfOutput.length !== PRF_OUTPUT_BYTES) {
+        throw invalidInput(`PRF output must be exactly ${PRF_OUTPUT_BYTES} bytes`);
+    }
+    try {
+        const ikm = await crypto.subtle.importKey("raw", prfOutput.slice(), "HKDF", false, [
+            "deriveKey",
+        ]);
+        return await crypto.subtle.deriveKey({
+            name: "HKDF",
+            hash: "SHA-256",
+            salt: new Uint8Array(),
+            info: profile.hkdfInfo,
+        }, ikm, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    }
+    catch (cause) {
+        if (cause instanceof PasskeyKeyError)
+            throw cause;
+        throw operationFailed("failed to derive wrapping key", cause);
+    }
+}
+export async function wrapKey(profile, credentialId, prfOutput, key, operation = "createAndWrapKey") {
+    validateCredentialId(credentialId);
+    validateKey(key, operation);
+    try {
+        const wrappingKey = await deriveWrappingKey(prfOutput, profile);
+        const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+        const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, wrappingKey, key);
+        return {
+            profile: copyAndValidateProfile(profile),
+            credentialId,
+            kekIvHex: bytesToHex(iv),
+            wrappedKeyHex: bytesToHex(new Uint8Array(ciphertext)),
+        };
+    }
+    catch (cause) {
+        if (cause instanceof PasskeyKeyError)
+            throw cause;
+        throw operationFailed("failed to wrap key", cause, operation);
+    }
+}
+export async function unwrapKey(profile, prfOutput, wrapped, operation = "recoverKey") {
+    validateWrappedKey(wrapped, profile);
+    try {
+        const wrappingKey = await deriveWrappingKey(prfOutput, profile);
+        const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: hexToBytes(wrapped.kekIvHex) }, wrappingKey, hexToBytes(wrapped.wrappedKeyHex));
+        const key = new Uint8Array(plaintext);
+        validateKey(key, operation);
+        return key;
+    }
+    catch (cause) {
+        if (cause instanceof PasskeyKeyError)
+            throw cause;
+        throw operationFailed("failed to recover key", cause, operation);
+    }
 }
 //# sourceMappingURL=crypto.js.map