@noy-db/on-webauthn 0.1.0-pre.10

package/dist/index.d.cts

@@ -0,0 +1,267 @@
+import { UnlockedKeyring, SlotRewrapContext, EnrollAuthenticatorOptions } from '@noy-db/hub';
+export { ValidationError } from '@noy-db/hub';
+
+/**
+ * @noy-db/on-webauthn —
+ *
+ * Hardware-key keyring for noy-db using the WebAuthn API.
+ *
+ * Covers every form factor:
+ *   - Platform authenticators: Touch ID, Face ID, Windows Hello, Android biometric
+ *   - Roaming authenticators: YubiKey (5C NFC, Bio), SoloKey, Titan, any FIDO2 key
+ *   - Passkey-capable platform authenticators: iCloud Keychain, Google Password Manager
+ *
+ * Key derivation model
+ * ────────────────────
+ * This package uses the **PRF (Pseudo-Random Function) extension** when
+ * available to derive a deterministic wrapping key from the WebAuthn
+ * credential. The PRF output is consistent across assertions on the same
+ * device/credential, enabling unlock-without-passphrase while keeping the
+ * derived key bound to the physical authenticator.
+ *
+ * When PRF is not supported by the authenticator (common on older hardware),
+ * the package falls back to HKDF-SHA256 over the credential's `rawId` —
+ * the same approach as the pre-existing `@noy-db/core` biometric module.
+ *
+ * The derived key is NEVER persisted. It exists only in memory during the
+ * unlock operation. What IS persisted (in the noy-db adapter, not in browser
+ * storage) is the wrapped KEK: `encrypt(KEK, derivedKey)`.
+ *
+ * BE-flag guards
+ * ──────────────
+ * The backup-eligibility (BE) flag in a WebAuthn authenticator data signals
+ * that the credential is (or can be) synced across devices — e.g. stored in
+ * iCloud Keychain. For single-device security policies (air-gapped USB sticks,
+ * high-security terminals), this is a threat: the credential is available on
+ * any device where the user's iCloud account is signed in.
+ *
+ * The `requireSingleDevice: true` option rejects credentials with the BE flag
+ * set during enrollment. Existing enrollments are checked at assertion time —
+ * if the authenticator data shows BE=1 but `requireSingleDevice` was set at
+ * enrollment, the assertion throws `WebAuthnMultiDeviceError`.
+ *
+ * Enrollment flow
+ * ───────────────
+ * 1. User is already authenticated (passphrase or existing session).
+ * 2. Call `enrollWebAuthn(keyring, options)`.
+ * 3. WebAuthn credential is created; PRF or rawId-derived key wraps the KEK.
+ * 4. Returns a `WebAuthnEnrollment` — persist this to the noy-db adapter
+ *    via `saveEnrollment()`, or store it yourself in any encrypted collection.
+ *
+ * Unlock flow
+ * ───────────
+ * 1. Load the `WebAuthnEnrollment` via `loadEnrollment()`.
+ * 2. Call `unlockWebAuthn(enrollment, keyring)` — triggers the WebAuthn
+ *    assertion prompt.
+ * 3. On success, returns the unwrapped `CryptoKey` (the KEK) — use it to
+ *    re-hydrate the session via `createSession()`.
+ */
+
+/**
+ * Thrown when the WebAuthn API is not available in the current environment.
+ *
+ * Check `isWebAuthnAvailable()` before calling `enrollWebAuthn()` or
+ * `unlockWebAuthn()` and show a fallback UI (passphrase entry) if this
+ * returns false. Common scenarios: Node.js environments, older browsers,
+ * non-HTTPS origins (WebAuthn requires a Secure Context).
+ */
+declare class WebAuthnNotAvailableError extends Error {
+    readonly code = "WEBAUTHN_NOT_AVAILABLE";
+    constructor();
+}
+/**
+ * Thrown when the user dismisses the WebAuthn prompt without completing it.
+ *
+ * The `op` field distinguishes enrollment cancellation (user chose not to
+ * enroll a hardware key) from assertion cancellation (user dismissed the
+ * unlock prompt). Treat this as a user-initiated action, not an error — show
+ * a "use passphrase instead" option rather than an error message.
+ */
+declare class WebAuthnCancelledError extends Error {
+    readonly code = "WEBAUTHN_CANCELLED";
+    constructor(op: 'enrollment' | 'assertion');
+}
+/**
+ * Thrown when the authenticator has the backup-eligible (BE) flag set but
+ * the vault requires a single-device credential (`requireSingleDevice: true`).
+ *
+ * A BE credential is synced across devices (e.g. iCloud Keychain, Google
+ * Password Manager), which violates the single-device security model. The
+ * user must enroll a hardware security key (YubiKey, Titan, SoloKey) instead.
+ */
+declare class WebAuthnMultiDeviceError extends Error {
+    readonly code = "WEBAUTHN_MULTI_DEVICE";
+    constructor();
+}
+/**
+ * Thrown (as a non-fatal warning, caught internally) when the PRF extension
+ * is not supported by the authenticator.
+ *
+ * NOYDB prefers PRF for key derivation because it produces a
+ * credential-bound output that is deterministic and not extractable from
+ * the authenticator. When PRF is unavailable, enrollment falls back to
+ * HKDF over the credential's `rawId` — weaker binding, but still functional.
+ * This error is caught at enrollment time; callers only see it if they
+ * explicitly opt into strict PRF-only mode.
+ */
+declare class WebAuthnPRFUnavailableError extends Error {
+    readonly code = "WEBAUTHN_PRF_UNAVAILABLE";
+    constructor();
+}
+/**
+ * A persisted WebAuthn enrollment record. Store this in a noy-db
+ * collection (encrypted like any other record) or return it from
+ * `saveEnrollment()` / `loadEnrollment()` helpers.
+ */
+interface WebAuthnEnrollment {
+    /** Enrollment format version. */
+    readonly _noydb_webauthn: 1;
+    /** The vault this enrollment was created for. */
+    readonly vault: string;
+    /** The user ID this enrollment belongs to. */
+    readonly userId: string;
+    /** WebAuthn credential ID (base64). Use for allowCredentials in assertions. */
+    readonly credentialId: string;
+    /** Whether PRF was used for key derivation (vs rawId HKDF fallback). */
+    readonly prfUsed: boolean;
+    /** Whether the BE (backup-eligibility) flag was present at enrollment time. */
+    readonly beFlag: boolean;
+    /** Whether single-device was required at enrollment time. */
+    readonly requireSingleDevice: boolean;
+    /** The wrapped KEK: encrypt(exportedDekMap, derivedKey). Base64. */
+    readonly wrappedPayload: string;
+    /** IV used for the wrapping. Base64. */
+    readonly wrapIv: string;
+    /** ISO timestamp of enrollment. */
+    readonly enrolledAt: string;
+}
+/** Options for `enrollWebAuthn()`. */
+interface WebAuthnEnrollOptions {
+    /**
+     * Relying party ID and name for the WebAuthn credential.
+     * Defaults to `{ id: window.location.hostname, name: 'NOYDB' }`.
+     */
+    rp?: {
+        id?: string;
+        name: string;
+    };
+    /**
+     * If `true`, refuse to enroll credentials with the BE flag set
+     * (multi-device / syncable passkeys). Defaults to `false`.
+     *
+     * Set to `true` for high-security deployments where the credential
+     * must be bound to a single physical device (YubiKey, Titan, etc.).
+     */
+    requireSingleDevice?: boolean;
+    /**
+     * WebAuthn timeout in milliseconds. Default: 60_000.
+     */
+    timeout?: number;
+    /**
+     * If `true`, prefer a cross-platform authenticator (roaming security key).
+     * If `false`, prefer a platform authenticator (Touch ID, Face ID).
+     * If undefined, let the browser choose.
+     */
+    preferCrossPlatform?: boolean;
+}
+/** Options for `unlockWebAuthn()`. */
+interface WebAuthnUnlockOptions {
+    /** WebAuthn timeout in milliseconds. Default: 60_000. */
+    timeout?: number;
+}
+/**
+ * Returns `true` if WebAuthn is available and can be used for enrollment or unlock.
+ *
+ * Checks for `navigator.credentials`, `window.PublicKeyCredential`, and a
+ * Secure Context (`window.isSecureContext`). Call this before rendering the
+ * "Register hardware key" button to avoid showing options that will fail.
+ */
+declare function isWebAuthnAvailable(): boolean;
+/**
+ * Enroll a WebAuthn credential for the given keyring.
+ *
+ * The caller must already have an unlocked keyring (from passphrase auth or
+ * an existing session). The WebAuthn credential creation prompt is triggered
+ * by this call.
+ *
+ * Returns a `WebAuthnEnrollment` that should be persisted — typically via
+ * `saveEnrollment()` into a noy-db collection.
+ *
+ * @throws `WebAuthnNotAvailableError` if the environment doesn't support WebAuthn.
+ * @throws `WebAuthnCancelledError` if the user cancels the credential creation.
+ * @throws `WebAuthnMultiDeviceError` if `requireSingleDevice` is true and the
+ *         authenticator returned a credential with the BE flag set.
+ */
+declare function enrollWebAuthn(keyring: UnlockedKeyring, vault: string, options?: WebAuthnEnrollOptions): Promise<WebAuthnEnrollment>;
+/**
+ * Unlock a vault using a previously enrolled WebAuthn credential.
+ *
+ * Triggers the WebAuthn assertion prompt. On success, decrypts the keyring
+ * payload from the enrollment record and returns an `UnlockedKeyring`.
+ *
+ * The returned keyring has the same DEKs as at enrollment time. If DEKs
+ * have been rotated since enrollment, this will return stale DEKs — the
+ * caller should detect decryption failures and prompt for re-enrollment.
+ *
+ * @throws `WebAuthnNotAvailableError` if the environment doesn't support WebAuthn.
+ * @throws `WebAuthnCancelledError` if the user cancels the assertion.
+ * @throws `WebAuthnMultiDeviceError` if `requireSingleDevice` was set at
+ *         enrollment and the authenticator data now shows BE=1.
+ * @throws `ValidationError` if decryption of the keyring payload fails.
+ */
+declare function unlockWebAuthn(enrollment: WebAuthnEnrollment, options?: WebAuthnUnlockOptions): Promise<UnlockedKeyring>;
+/**
+ * `SlotRewrapCeremony` for WebAuthn slots — used by hub's
+ * `rotatePassphrase({ slotCeremonies: { [slotId]: webAuthnSlotRewrapCeremony } })`
+ * to preserve a tier-2 WebAuthn enrollment across a tier-1 phrase
+ * rotation without requiring re-enrollment of the credential (#56).
+ *
+ * The credential itself is unaffected by phrase rotation — the
+ * wrapping key derived from PRF (or rawId fallback) is bound to the
+ * authenticator, not to the passphrase. What needs to change is the
+ * **wrapped payload**: the encrypted blob the slot's `wrapped_kek`
+ * field holds. After rotation, the old payload still has the old
+ * DEKs (now stale because rotatePassphrase rewrapped them under a
+ * fresh KEK); the new payload must hold the freshly rewrapped
+ * `ctx.newDeks`.
+ *
+ * Single ceremony, two operations:
+ *   1. Trigger one WebAuthn assertion to derive the wrapping key.
+ *   2. Decrypt the OLD `wrapped_kek` to extract identity fields
+ *      (userId, displayName, role, permissions, salt) — these don't
+ *      change on rotation, so they're carried verbatim into the new
+ *      payload.
+ *   3. Encrypt the NEW payload (same identity + `ctx.newDeks`) under
+ *      the same wrapping key, with a fresh IV.
+ *   4. Return `EnrollAuthenticatorOptions` preserving `oldSlot.id`
+ *      and `method: 'webauthn'` (hub validates these to prevent
+ *      slot-type swap mid-rotation).
+ *
+ * Niwat (consumer) shipped a workaround at #44 — detect dropped slots
+ * after rotate and offer "Re-enrol Touch ID" inline. This ceremony
+ * eliminates that step.
+ *
+ * Out of scope: tier-3 PIN. PIN state lives in `QuickUnlockStore`
+ * (RAM-only), not in `KeyringFile.authenticators[]`, so
+ * `slotCeremonies` doesn't apply. Clear PIN state on rotate; let
+ * the user set a fresh PIN via `db.enrollUnlock` immediately after.
+ *
+ * @throws {WebAuthnNotAvailableError} when the environment lacks WebAuthn.
+ * @throws {WebAuthnCancelledError} when the user dismisses the assertion.
+ * @throws {WebAuthnMultiDeviceError} when `meta.requireSingleDevice` was
+ *         set at enrollment and the authenticator now reports BE=1.
+ * @throws {ValidationError} when `oldSlot.method !== 'webauthn'`,
+ *         when required `meta` fields are missing, or when the old
+ *         payload fails to decrypt (credential changed / payload
+ *         tampered).
+ *
+ * @see #56 #29 — the ceremony plumbing this fills in.
+ */
+declare function webAuthnSlotRewrapCeremony(ctx: SlotRewrapContext, options?: WebAuthnUnlockOptions): Promise<EnrollAuthenticatorOptions>;
+/**
+ * Check whether a `WebAuthnEnrollment` record looks well-formed.
+ * Does not perform any cryptographic verification.
+ */
+declare function isValidEnrollment(value: unknown): value is WebAuthnEnrollment;
+
+export { WebAuthnCancelledError, type WebAuthnEnrollOptions, type WebAuthnEnrollment, WebAuthnMultiDeviceError, WebAuthnNotAvailableError, WebAuthnPRFUnavailableError, type WebAuthnUnlockOptions, enrollWebAuthn, isValidEnrollment, isWebAuthnAvailable, unlockWebAuthn, webAuthnSlotRewrapCeremony };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { UnlockedKeyring, SlotRewrapContext, EnrollAuthenticatorOptions } from '@noy-db/hub';
+export { ValidationError } from '@noy-db/hub';
+
+/**
+ * @noy-db/on-webauthn —
+ *
+ * Hardware-key keyring for noy-db using the WebAuthn API.
+ *
+ * Covers every form factor:
+ *   - Platform authenticators: Touch ID, Face ID, Windows Hello, Android biometric
+ *   - Roaming authenticators: YubiKey (5C NFC, Bio), SoloKey, Titan, any FIDO2 key
+ *   - Passkey-capable platform authenticators: iCloud Keychain, Google Password Manager
+ *
+ * Key derivation model
+ * ────────────────────
+ * This package uses the **PRF (Pseudo-Random Function) extension** when
+ * available to derive a deterministic wrapping key from the WebAuthn
+ * credential. The PRF output is consistent across assertions on the same
+ * device/credential, enabling unlock-without-passphrase while keeping the
+ * derived key bound to the physical authenticator.
+ *
+ * When PRF is not supported by the authenticator (common on older hardware),
+ * the package falls back to HKDF-SHA256 over the credential's `rawId` —
+ * the same approach as the pre-existing `@noy-db/core` biometric module.
+ *
+ * The derived key is NEVER persisted. It exists only in memory during the
+ * unlock operation. What IS persisted (in the noy-db adapter, not in browser
+ * storage) is the wrapped KEK: `encrypt(KEK, derivedKey)`.
+ *
+ * BE-flag guards
+ * ──────────────
+ * The backup-eligibility (BE) flag in a WebAuthn authenticator data signals
+ * that the credential is (or can be) synced across devices — e.g. stored in
+ * iCloud Keychain. For single-device security policies (air-gapped USB sticks,
+ * high-security terminals), this is a threat: the credential is available on
+ * any device where the user's iCloud account is signed in.
+ *
+ * The `requireSingleDevice: true` option rejects credentials with the BE flag
+ * set during enrollment. Existing enrollments are checked at assertion time —
+ * if the authenticator data shows BE=1 but `requireSingleDevice` was set at
+ * enrollment, the assertion throws `WebAuthnMultiDeviceError`.
+ *
+ * Enrollment flow
+ * ───────────────
+ * 1. User is already authenticated (passphrase or existing session).
+ * 2. Call `enrollWebAuthn(keyring, options)`.
+ * 3. WebAuthn credential is created; PRF or rawId-derived key wraps the KEK.
+ * 4. Returns a `WebAuthnEnrollment` — persist this to the noy-db adapter
+ *    via `saveEnrollment()`, or store it yourself in any encrypted collection.
+ *
+ * Unlock flow
+ * ───────────
+ * 1. Load the `WebAuthnEnrollment` via `loadEnrollment()`.
+ * 2. Call `unlockWebAuthn(enrollment, keyring)` — triggers the WebAuthn
+ *    assertion prompt.
+ * 3. On success, returns the unwrapped `CryptoKey` (the KEK) — use it to
+ *    re-hydrate the session via `createSession()`.
+ */
+
+/**
+ * Thrown when the WebAuthn API is not available in the current environment.
+ *
+ * Check `isWebAuthnAvailable()` before calling `enrollWebAuthn()` or
+ * `unlockWebAuthn()` and show a fallback UI (passphrase entry) if this
+ * returns false. Common scenarios: Node.js environments, older browsers,
+ * non-HTTPS origins (WebAuthn requires a Secure Context).
+ */
+declare class WebAuthnNotAvailableError extends Error {
+    readonly code = "WEBAUTHN_NOT_AVAILABLE";
+    constructor();
+}
+/**
+ * Thrown when the user dismisses the WebAuthn prompt without completing it.
+ *
+ * The `op` field distinguishes enrollment cancellation (user chose not to
+ * enroll a hardware key) from assertion cancellation (user dismissed the
+ * unlock prompt). Treat this as a user-initiated action, not an error — show
+ * a "use passphrase instead" option rather than an error message.
+ */
+declare class WebAuthnCancelledError extends Error {
+    readonly code = "WEBAUTHN_CANCELLED";
+    constructor(op: 'enrollment' | 'assertion');
+}
+/**
+ * Thrown when the authenticator has the backup-eligible (BE) flag set but
+ * the vault requires a single-device credential (`requireSingleDevice: true`).
+ *
+ * A BE credential is synced across devices (e.g. iCloud Keychain, Google
+ * Password Manager), which violates the single-device security model. The
+ * user must enroll a hardware security key (YubiKey, Titan, SoloKey) instead.
+ */
+declare class WebAuthnMultiDeviceError extends Error {
+    readonly code = "WEBAUTHN_MULTI_DEVICE";
+    constructor();
+}
+/**
+ * Thrown (as a non-fatal warning, caught internally) when the PRF extension
+ * is not supported by the authenticator.
+ *
+ * NOYDB prefers PRF for key derivation because it produces a
+ * credential-bound output that is deterministic and not extractable from
+ * the authenticator. When PRF is unavailable, enrollment falls back to
+ * HKDF over the credential's `rawId` — weaker binding, but still functional.
+ * This error is caught at enrollment time; callers only see it if they
+ * explicitly opt into strict PRF-only mode.
+ */
+declare class WebAuthnPRFUnavailableError extends Error {
+    readonly code = "WEBAUTHN_PRF_UNAVAILABLE";
+    constructor();
+}
+/**
+ * A persisted WebAuthn enrollment record. Store this in a noy-db
+ * collection (encrypted like any other record) or return it from
+ * `saveEnrollment()` / `loadEnrollment()` helpers.
+ */
+interface WebAuthnEnrollment {
+    /** Enrollment format version. */
+    readonly _noydb_webauthn: 1;
+    /** The vault this enrollment was created for. */
+    readonly vault: string;
+    /** The user ID this enrollment belongs to. */
+    readonly userId: string;
+    /** WebAuthn credential ID (base64). Use for allowCredentials in assertions. */
+    readonly credentialId: string;
+    /** Whether PRF was used for key derivation (vs rawId HKDF fallback). */
+    readonly prfUsed: boolean;
+    /** Whether the BE (backup-eligibility) flag was present at enrollment time. */
+    readonly beFlag: boolean;
+    /** Whether single-device was required at enrollment time. */
+    readonly requireSingleDevice: boolean;
+    /** The wrapped KEK: encrypt(exportedDekMap, derivedKey). Base64. */
+    readonly wrappedPayload: string;
+    /** IV used for the wrapping. Base64. */
+    readonly wrapIv: string;
+    /** ISO timestamp of enrollment. */
+    readonly enrolledAt: string;
+}
+/** Options for `enrollWebAuthn()`. */
+interface WebAuthnEnrollOptions {
+    /**
+     * Relying party ID and name for the WebAuthn credential.
+     * Defaults to `{ id: window.location.hostname, name: 'NOYDB' }`.
+     */
+    rp?: {
+        id?: string;
+        name: string;
+    };
+    /**
+     * If `true`, refuse to enroll credentials with the BE flag set
+     * (multi-device / syncable passkeys). Defaults to `false`.
+     *
+     * Set to `true` for high-security deployments where the credential
+     * must be bound to a single physical device (YubiKey, Titan, etc.).
+     */
+    requireSingleDevice?: boolean;
+    /**
+     * WebAuthn timeout in milliseconds. Default: 60_000.
+     */
+    timeout?: number;
+    /**
+     * If `true`, prefer a cross-platform authenticator (roaming security key).
+     * If `false`, prefer a platform authenticator (Touch ID, Face ID).
+     * If undefined, let the browser choose.
+     */
+    preferCrossPlatform?: boolean;
+}
+/** Options for `unlockWebAuthn()`. */
+interface WebAuthnUnlockOptions {
+    /** WebAuthn timeout in milliseconds. Default: 60_000. */
+    timeout?: number;
+}
+/**
+ * Returns `true` if WebAuthn is available and can be used for enrollment or unlock.
+ *
+ * Checks for `navigator.credentials`, `window.PublicKeyCredential`, and a
+ * Secure Context (`window.isSecureContext`). Call this before rendering the
+ * "Register hardware key" button to avoid showing options that will fail.
+ */
+declare function isWebAuthnAvailable(): boolean;
+/**
+ * Enroll a WebAuthn credential for the given keyring.
+ *
+ * The caller must already have an unlocked keyring (from passphrase auth or
+ * an existing session). The WebAuthn credential creation prompt is triggered
+ * by this call.
+ *
+ * Returns a `WebAuthnEnrollment` that should be persisted — typically via
+ * `saveEnrollment()` into a noy-db collection.
+ *
+ * @throws `WebAuthnNotAvailableError` if the environment doesn't support WebAuthn.
+ * @throws `WebAuthnCancelledError` if the user cancels the credential creation.
+ * @throws `WebAuthnMultiDeviceError` if `requireSingleDevice` is true and the
+ *         authenticator returned a credential with the BE flag set.
+ */
+declare function enrollWebAuthn(keyring: UnlockedKeyring, vault: string, options?: WebAuthnEnrollOptions): Promise<WebAuthnEnrollment>;
+/**
+ * Unlock a vault using a previously enrolled WebAuthn credential.
+ *
+ * Triggers the WebAuthn assertion prompt. On success, decrypts the keyring
+ * payload from the enrollment record and returns an `UnlockedKeyring`.
+ *
+ * The returned keyring has the same DEKs as at enrollment time. If DEKs
+ * have been rotated since enrollment, this will return stale DEKs — the
+ * caller should detect decryption failures and prompt for re-enrollment.
+ *
+ * @throws `WebAuthnNotAvailableError` if the environment doesn't support WebAuthn.
+ * @throws `WebAuthnCancelledError` if the user cancels the assertion.
+ * @throws `WebAuthnMultiDeviceError` if `requireSingleDevice` was set at
+ *         enrollment and the authenticator data now shows BE=1.
+ * @throws `ValidationError` if decryption of the keyring payload fails.
+ */
+declare function unlockWebAuthn(enrollment: WebAuthnEnrollment, options?: WebAuthnUnlockOptions): Promise<UnlockedKeyring>;
+/**
+ * `SlotRewrapCeremony` for WebAuthn slots — used by hub's
+ * `rotatePassphrase({ slotCeremonies: { [slotId]: webAuthnSlotRewrapCeremony } })`
+ * to preserve a tier-2 WebAuthn enrollment across a tier-1 phrase
+ * rotation without requiring re-enrollment of the credential (#56).
+ *
+ * The credential itself is unaffected by phrase rotation — the
+ * wrapping key derived from PRF (or rawId fallback) is bound to the
+ * authenticator, not to the passphrase. What needs to change is the
+ * **wrapped payload**: the encrypted blob the slot's `wrapped_kek`
+ * field holds. After rotation, the old payload still has the old
+ * DEKs (now stale because rotatePassphrase rewrapped them under a
+ * fresh KEK); the new payload must hold the freshly rewrapped
+ * `ctx.newDeks`.
+ *
+ * Single ceremony, two operations:
+ *   1. Trigger one WebAuthn assertion to derive the wrapping key.
+ *   2. Decrypt the OLD `wrapped_kek` to extract identity fields
+ *      (userId, displayName, role, permissions, salt) — these don't
+ *      change on rotation, so they're carried verbatim into the new
+ *      payload.
+ *   3. Encrypt the NEW payload (same identity + `ctx.newDeks`) under
+ *      the same wrapping key, with a fresh IV.
+ *   4. Return `EnrollAuthenticatorOptions` preserving `oldSlot.id`
+ *      and `method: 'webauthn'` (hub validates these to prevent
+ *      slot-type swap mid-rotation).
+ *
+ * Niwat (consumer) shipped a workaround at #44 — detect dropped slots
+ * after rotate and offer "Re-enrol Touch ID" inline. This ceremony
+ * eliminates that step.
+ *
+ * Out of scope: tier-3 PIN. PIN state lives in `QuickUnlockStore`
+ * (RAM-only), not in `KeyringFile.authenticators[]`, so
+ * `slotCeremonies` doesn't apply. Clear PIN state on rotate; let
+ * the user set a fresh PIN via `db.enrollUnlock` immediately after.
+ *
+ * @throws {WebAuthnNotAvailableError} when the environment lacks WebAuthn.
+ * @throws {WebAuthnCancelledError} when the user dismisses the assertion.
+ * @throws {WebAuthnMultiDeviceError} when `meta.requireSingleDevice` was
+ *         set at enrollment and the authenticator now reports BE=1.
+ * @throws {ValidationError} when `oldSlot.method !== 'webauthn'`,
+ *         when required `meta` fields are missing, or when the old
+ *         payload fails to decrypt (credential changed / payload
+ *         tampered).
+ *
+ * @see #56 #29 — the ceremony plumbing this fills in.
+ */
+declare function webAuthnSlotRewrapCeremony(ctx: SlotRewrapContext, options?: WebAuthnUnlockOptions): Promise<EnrollAuthenticatorOptions>;
+/**
+ * Check whether a `WebAuthnEnrollment` record looks well-formed.
+ * Does not perform any cryptographic verification.
+ */
+declare function isValidEnrollment(value: unknown): value is WebAuthnEnrollment;
+
+export { WebAuthnCancelledError, type WebAuthnEnrollOptions, type WebAuthnEnrollment, WebAuthnMultiDeviceError, WebAuthnNotAvailableError, WebAuthnPRFUnavailableError, type WebAuthnUnlockOptions, enrollWebAuthn, isValidEnrollment, isWebAuthnAvailable, unlockWebAuthn, webAuthnSlotRewrapCeremony };