@tinfoilsh/passkey-kit 0.1.0

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/webauthn.d.ts

@@ -0,0 +1,38 @@
+/**
+ * WebAuthn PRF ceremonies: credential creation and assertion with the PRF
+ * extension. Pure ceremony logic — persistence of the results is handled
+ * by the kit through the hooks on {@link CeremonyContext}.
+ */
+import type { PasskeyKitErrorMessages, PasskeyKitLogger, PasskeyUser, PrfPasskeyResult } from "./types.js";
+export interface CeremonyContext {
+    rpId: string;
+    rpName: string;
+    /** Salt passed to PRF eval.first — the client internally computes
+     *  SHA-256("WebAuthn PRF" || 0x00 || salt). */
+    prfSalt: Uint8Array;
+    webauthnTimeoutMs: number;
+    stuckTimeoutMs: number;
+    errorMessages?: PasskeyKitErrorMessages;
+    logger: PasskeyKitLogger;
+    /** Invoked after every successful PRF ceremony so the kit can cache state. */
+    onPrfResult(result: PrfPasskeyResult, credential: PublicKeyCredential): void;
+}
+/**
+ * Create a new PRF-capable passkey for the given user.
+ *
+ * Returns the credential ID and PRF output, or null if the user cancels.
+ * Throws {@link PrfNotSupportedError} when the authenticator cannot supply
+ * PRF output and {@link PasskeyTimeoutError} when the provider hangs.
+ */
+export declare function createPrfPasskey(ctx: CeremonyContext, user: PasskeyUser): Promise<PrfPasskeyResult | null>;
+/**
+ * Authenticate with an existing PRF passkey to derive the PRF output.
+ *
+ * @param credentialIds - base64url-encoded credential IDs to allow. Pass all
+ *   known PRF credential IDs so the browser can select the right one.
+ * @returns The matched credential ID and PRF output, or null on failure/cancel.
+ */
+export declare function authenticatePrfPasskey(ctx: CeremonyContext, credentialIds: string[], options?: {
+    throwOnCancel?: boolean;
+}): Promise<PrfPasskeyResult | null>;
+//# sourceMappingURL=webauthn.d.ts.map

package/dist/webauthn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webauthn.d.ts","sourceRoot":"","sources":["../src/webauthn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EACV,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf;mDAC+C;IAC/C,OAAO,EAAE,UAAU,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC,MAAM,EAAE,gBAAgB,CAAC;IACzB,8EAA8E;IAC9E,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC9E;AAwBD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAqGlC;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,eAAe,EACpB,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA0ElC"}

package/dist/webauthn.js

@@ -0,0 +1,189 @@
+/**
+ * WebAuthn PRF ceremonies: credential creation and assertion with the PRF
+ * extension. Pure ceremony logic — persistence of the results is handled
+ * by the kit through the hooks on {@link CeremonyContext}.
+ */
+import { base64UrlToBytes, bufferSourceToArrayBuffer, bytesToBase64Url, } from "./codec.js";
+import { PasskeyKitError, PasskeyTimeoutError, PrfNotSupportedError, } from "./errors.js";
+const MAX_USER_HANDLE_BYTE_COUNT = 64;
+async function withStuckTimeout(promise, ctx) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new PasskeyTimeoutError(ctx.errorMessages?.timeout)), ctx.stuckTimeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Create a new PRF-capable passkey for the given user.
+ *
+ * Returns the credential ID and PRF output, or null if the user cancels.
+ * Throws {@link PrfNotSupportedError} when the authenticator cannot supply
+ * PRF output and {@link PasskeyTimeoutError} when the provider hangs.
+ */
+export async function createPrfPasskey(ctx, user) {
+    const userIdBytes = new TextEncoder().encode(user.id);
+    if (userIdBytes.byteLength > MAX_USER_HANDLE_BYTE_COUNT) {
+        throw new PasskeyKitError(`passkey-kit: user id must be at most ${MAX_USER_HANDLE_BYTE_COUNT} UTF-8 bytes`);
+    }
+    try {
+        const credential = (await withStuckTimeout(navigator.credentials.create({
+            publicKey: {
+                challenge: crypto.getRandomValues(new Uint8Array(32)),
+                rp: { id: ctx.rpId, name: ctx.rpName },
+                user: {
+                    id: userIdBytes,
+                    name: user.name,
+                    displayName: user.displayName || user.name,
+                },
+                pubKeyCredParams: [
+                    { type: "public-key", alg: -7 }, // ES256
+                    { type: "public-key", alg: -257 }, // RS256 (broader compat)
+                ],
+                authenticatorSelection: {
+                    residentKey: "preferred",
+                    userVerification: "required",
+                },
+                timeout: ctx.webauthnTimeoutMs,
+                extensions: {
+                    prf: { eval: { first: ctx.prfSalt } },
+                },
+            },
+        }), ctx));
+        if (!credential) {
+            return null;
+        }
+        const extensionResults = credential.getClientExtensionResults();
+        const prfResults = extensionResults.prf;
+        if (!prfResults?.enabled) {
+            ctx.logger.info?.("Authenticator does not support PRF", {
+                action: "createPrfPasskey",
+            });
+            throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
+        }
+        const credentialId = bytesToBase64Url(new Uint8Array(credential.rawId));
+        // Some authenticators return PRF results during creation, others don't.
+        // "Not all authenticators support evaluating the PRFs during credential
+        // creation so outputs may, or may not, be provided."
+        // — https://w3c.github.io/webauthn/#prf-extension (eval description)
+        if (prfResults.results?.first) {
+            const result = {
+                credentialId,
+                prfOutput: bufferSourceToArrayBuffer(prfResults.results.first),
+            };
+            ctx.onPrfResult(result, credential);
+            return result;
+        }
+        // PRF enabled but no results during create — do an immediate get()
+        ctx.logger.info?.("PRF enabled but no results during creation, doing immediate auth", { action: "createPrfPasskey" });
+        // Pass throwOnCancel so a user-cancelled assertion surfaces as a
+        // DOMException we can handle below — otherwise a `null` return would
+        // be indistinguishable from "provider returned no PRF output" and we'd
+        // show the misleading "PRF not supported" error for a plain cancel.
+        const postCreateAuth = await authenticatePrfPasskey(ctx, [credentialId], {
+            throwOnCancel: true,
+        });
+        if (!postCreateAuth) {
+            // The provider claimed PRF support during creation but didn't deliver
+            // a PRF output on the immediately-following assertion. Treat this as
+            // a lack of real PRF support rather than a silent failure.
+            throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
+        }
+        return postCreateAuth;
+    }
+    catch (error) {
+        if (error instanceof PrfNotSupportedError)
+            throw error;
+        if (error instanceof PasskeyTimeoutError)
+            throw error;
+        // DOMException with name "NotAllowedError" means the user cancelled
+        if (error instanceof DOMException && error.name === "NotAllowedError") {
+            ctx.logger.info?.("User cancelled passkey creation", {
+                action: "createPrfPasskey",
+            });
+            return null;
+        }
+        ctx.logger.error?.("Failed to create PRF passkey", error, {
+            action: "createPrfPasskey",
+        });
+        throw error;
+    }
+}
+/**
+ * Authenticate with an existing PRF passkey to derive the PRF output.
+ *
+ * @param credentialIds - base64url-encoded credential IDs to allow. Pass all
+ *   known PRF credential IDs so the browser can select the right one.
+ * @returns The matched credential ID and PRF output, or null on failure/cancel.
+ */
+export async function authenticatePrfPasskey(ctx, credentialIds, options = {}) {
+    const { throwOnCancel = false } = options;
+    const allowCredentials = credentialIds.map((id) => ({
+        id: base64UrlToBytes(id),
+        type: "public-key",
+    }));
+    try {
+        const assertion = (await withStuckTimeout(navigator.credentials.get({
+            publicKey: {
+                challenge: crypto.getRandomValues(new Uint8Array(32)),
+                rpId: ctx.rpId,
+                allowCredentials,
+                userVerification: "required",
+                timeout: ctx.webauthnTimeoutMs,
+                extensions: {
+                    prf: { eval: { first: ctx.prfSalt } },
+                },
+            },
+        }), ctx));
+        if (!assertion) {
+            ctx.logger.info?.("passkey assertion returned no credential", {
+                action: "authenticatePrfPasskey",
+                allowedCredentials: credentialIds.length,
+            });
+            return null;
+        }
+        const extensionResults = assertion.getClientExtensionResults();
+        const prfOutput = extensionResults.prf?.results?.first;
+        if (!prfOutput) {
+            ctx.logger.error?.("PRF output missing from assertion", undefined, {
+                action: "authenticatePrfPasskey",
+            });
+            throw new PrfNotSupportedError(ctx.errorMessages?.prfNotSupported);
+        }
+        const result = {
+            credentialId: bytesToBase64Url(new Uint8Array(assertion.rawId)),
+            prfOutput: bufferSourceToArrayBuffer(prfOutput),
+        };
+        ctx.onPrfResult(result, assertion);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof PasskeyTimeoutError)
+            throw error;
+        if (error instanceof DOMException && error.name === "NotAllowedError") {
+            // NotAllowedError covers both a user cancel and the case where the
+            // provider has no usable credential for any of the allowed ids
+            // (e.g. the passkey was created in a different browser/profile and
+            // never persisted on this device).
+            ctx.logger.info?.("passkey authentication not allowed (cancelled or no usable credential)", {
+                action: "authenticatePrfPasskey",
+                allowedCredentials: credentialIds.length,
+            });
+            if (throwOnCancel)
+                throw error;
+            return null;
+        }
+        ctx.logger.error?.("Failed to authenticate with PRF passkey", error, {
+            action: "authenticatePrfPasskey",
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=webauthn.js.map

package/dist/webauthn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webauthn.js","sourceRoot":"","sources":["../src/webauthn.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@tinfoilsh/passkey-kit",
+  "version": "0.1.0",
+  "description": "WebAuthn PRF passkey SDK for protecting encryption keys with passkey-derived keys.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run test && npm run typecheck"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinfoilsh/tinfoil-passkey-kit.git"
+  },
+  "homepage": "https://github.com/tinfoilsh/tinfoil-passkey-kit#readme",
+  "bugs": {
+    "url": "https://github.com/tinfoilsh/tinfoil-passkey-kit/issues"
+  },
+  "keywords": [
+    "passkey",
+    "webauthn",
+    "prf",
+    "webcrypto",
+    "encryption"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.0.11",
+    "typescript": "^5",
+    "vitest": "^4.0.16"
+  }
+}

package/src/codec.ts

@@ -0,0 +1,71 @@
+/** Dependency-free binary codecs shared across the SDK. */
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = ''
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, '0')
+  }
+  return out
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error('passkey-kit: odd-length hex input')
+  }
+  if (!/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error('passkey-kit: invalid hex character')
+  }
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16)
+  }
+  return out
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  const CHUNK_SIZE = 0x8000
+  const chunks: string[] = []
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + CHUNK_SIZE)
+    chunks.push(String.fromCharCode.apply(null, Array.from(chunk)))
+  }
+  return btoa(chunks.join(''))
+}
+
+export function base64ToBytes(base64: string): Uint8Array {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}
+
+export function bytesToBase64Url(bytes: Uint8Array): string {
+  return bytesToBase64(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+export function base64UrlToBytes(base64url: string): Uint8Array {
+  const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4)
+  return base64ToBytes(padded)
+}
+
+/** Convert a BufferSource (ArrayBuffer or view) to a standalone ArrayBuffer copy. */
+export function bufferSourceToArrayBuffer(source: BufferSource): ArrayBuffer {
+  if (source instanceof ArrayBuffer) {
+    return source.slice(0)
+  }
+  return source.buffer.slice(
+    source.byteOffset,
+    source.byteOffset + source.byteLength,
+  ) as ArrayBuffer
+}
+
+/** Normalize a string (UTF-8 encoded) or byte input to bytes. */
+export function toBytes(input: string | Uint8Array): Uint8Array {
+  return typeof input === 'string' ? new TextEncoder().encode(input) : input
+}

package/src/crypto.ts

@@ -0,0 +1,161 @@
+/**
+ * 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";
+import type { WrappedCek } from "./types.js";
+
+export const CEK_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(): Uint8Array {
+  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: unknown): cek is Uint8Array {
+  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: ArrayBuffer | Uint8Array,
+  hkdfInfo: string | Uint8Array = TINFOIL_HKDF_INFO_V1,
+): Promise<CryptoKey> {
+  const masterKey = await crypto.subtle.importKey(
+    "raw",
+    prfOutput as BufferSource,
+    "HKDF",
+    false, // non-extractable
+    ["deriveKey"],
+  );
+
+  return crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(),
+      info: toBytes(hkdfInfo) as BufferSource,
+    },
+    masterKey,
+    { name: "AES-GCM", length: 256 },
+    false, // non-extractable
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * 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: {
+  credentialId: string;
+  kek: CryptoKey;
+  cek: Uint8Array;
+}): Promise<WrappedCek> {
+  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 as BufferSource },
+    opts.kek,
+    opts.cek as BufferSource,
+  );
+  return {
+    credentialId: opts.credentialId,
+    kekIvHex: bytesToHex(iv),
+    wrappedKeyHex: bytesToHex(new Uint8Array(ciphertext)),
+  };
+}
+
+/**
+ * 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: CryptoKey,
+  wrapped: Pick<WrappedCek, "kekIvHex" | "wrappedKeyHex">,
+): Promise<Uint8Array> {
+  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 as BufferSource },
+    kek,
+    ciphertext as BufferSource,
+  );
+  const cek = new Uint8Array(plaintext);
+  if (cek.length !== CEK_BYTES) {
+    throw new PasskeyKitError(
+      `passkey-kit: unwrapped CEK has wrong length ${cek.length}`,
+    );
+  }
+  return cek;
+}
+
+/**
+ * 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: Uint8Array,
+  opts: { info?: string | Uint8Array; lengthBytes?: number } = {},
+): Promise<Uint8Array> {
+  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 as BufferSource,
+    "HKDF",
+    false,
+    ["deriveBits"],
+  );
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(0) as BufferSource,
+      info: toBytes(opts.info ?? TINFOIL_KEY_ID_INFO_V1) as BufferSource,
+    },
+    ikm,
+    lengthBytes * 8,
+  );
+  return new Uint8Array(bits);
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+/**
+ * Typed errors thrown by the SDK. Callers should branch on `instanceof`
+ * (never on message strings) to drive recovery flows.
+ */
+
+/** Base class for every error the SDK throws on its own behalf. */
+export class PasskeyKitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PasskeyKitError'
+  }
+}
+
+const PROVIDER_SUGGESTION =
+  "Try using iCloud Keychain, Chrome's built-in passkey manager, or the Passwords app in your device settings."
+
+/**
+ * The authenticator created a credential but does not support the WebAuthn
+ * PRF extension, so no key material can be derived from it.
+ */
+export class PrfNotSupportedError extends PasskeyKitError {
+  constructor(
+    message = `Your passkey provider doesn't support the security features required by this app. ${PROVIDER_SUGGESTION}`,
+  ) {
+    super(message)
+    this.name = 'PrfNotSupportedError'
+  }
+}
+
+/**
+ * The passkey provider never resolved the WebAuthn promise within the
+ * SDK's hard timeout (some password-manager browser extensions hang).
+ */
+export class PasskeyTimeoutError extends PasskeyKitError {
+  constructor(
+    message = `Your passkey provider took too long to respond. This can happen with some browser extension password managers. ${PROVIDER_SUGGESTION}`,
+  ) {
+    super(message)
+    this.name = 'PasskeyTimeoutError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+export {
+  base64ToBytes,
+  base64UrlToBytes,
+  bufferSourceToArrayBuffer,
+  bytesToBase64,
+  bytesToBase64Url,
+  bytesToHex,
+  hexToBytes,
+} from "./codec.js";
+export {
+  CEK_BYTES,
+  deriveKeyEncryptionKey,
+  deriveKeyId,
+  generateCek,
+  isValidCek,
+  unwrapCek,
+  wrapCek,
+} from "./crypto.js";
+export {
+  PasskeyKitError,
+  PasskeyTimeoutError,
+  PrfNotSupportedError,
+} from "./errors.js";
+export { createPasskeyKit } from "./kit.js";
+export type { PasskeyKit } from "./kit.js";
+export {
+  TINFOIL_HKDF_INFO_V1,
+  TINFOIL_KEY_ID_INFO_V1,
+  TINFOIL_PRF_SALT_INPUT_V1,
+} from "./protocol.js";
+export {
+  browserLocalStorageAdapter,
+  createMemoryStorageAdapter,
+} from "./storage.js";
+export type { StorageAdapter } from "./storage.js";
+export { detectPrfSupport } from "./support.js";
+export type {
+  EnrollResult,
+  PasskeyKitConfig,
+  PasskeyKitErrorMessages,
+  PasskeyKitLogger,
+  PasskeyKitStorageKeys,
+  PasskeyUser,
+  PrfPasskeyResult,
+  UnlockResult,
+  WrappedCek,
+} from "./types.js";