@mudlet/mudlet-web 0.4.5 → 1.0.0

package/dist-lib/vault/CredentialVault.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The credential vault: per-profile login passwords, encrypted at rest under a
+ * key the browser cannot produce on its own.
+ *
+ * Why this exists rather than a "remember my password" checkbox: the app store
+ * is plaintext localStorage, so the old checkbox had to ship a warning telling
+ * the user that the convenience it had just offered was unsafe (issue #25). And
+ * handing the job to the browser's password manager doesn't work either —
+ * managers scope credentials by *origin*, so ten profiles on one host produce
+ * ten indistinguishable entries in one dropdown, every time, for every game.
+ *
+ * The vault inverts that. Secrets live here, encrypted; the single thing the
+ * password manager is asked to remember is the vault's unlock passphrase — one
+ * entry per origin, never ambiguous — or nothing at all when the unlocker is a
+ * passkey. Envelope encryption (see `vaultCrypto`) lets a vault carry several
+ * unlockers at once, so a passkey can be primary with a passphrase as the
+ * recovery path.
+ *
+ * **Scope of the protection.** Ciphertext at rest defends against everything
+ * that reads storage without running in the page: disk images, backups, profile
+ * sync, another user on the machine, an extension trawling localStorage. It does
+ * not defend against script running in the page *while the vault is unlocked* —
+ * no in-page vault can, and neither can a password manager with an open vault.
+ * The unlocked state is per page load and lives only in memory — unless the
+ * player opts into keeping it unlocked on this device (see `deviceUnlock`).
+ *
+ * State changes notify `subscribe` listeners so React can render off
+ * `getSnapshot` through `useSyncExternalStore`.
+ */
+import { type DeviceUnlockStore } from './deviceUnlock';
+import { type VaultRecord, type VaultSignIn, type VaultUnlocker } from './vaultRecord';
+export type { VaultSignIn } from './vaultRecord';
+/** What a listener needs to render. Immutable; identity changes on every
+ *  mutation so `useSyncExternalStore` re-renders exactly when something did. */
+export interface VaultSnapshot {
+    /** A vault has been set up on this device. */
+    exists: boolean;
+    /** Set up but not opened this page load. `false` when `exists` is false. */
+    locked: boolean;
+    /** Profiles with a stored password — readable while locked. */
+    entryIds: readonly string[];
+    /** Profiles with a saved GMCP sign-in token — readable while locked. */
+    signInIds: readonly string[];
+    /** Unlock methods, without their key material. */
+    unlockers: readonly {
+        id: string;
+        kind: VaultUnlocker['kind'];
+        label: string;
+        createdAt: string;
+    }[];
+    /** Epoch ms until which this device opens the vault by itself, when the
+     *  player chose that. Known only once the vault is open. */
+    rememberedUntil: number | null;
+}
+/** Failure modes worth telling apart in the UI. */
+export type VaultErrorCode = 'unavailable' | 'no-vault' | 'locked' | 'no-prf' | 'no-passkey' | 'last-unlocker';
+export declare class VaultError extends Error {
+    code: VaultErrorCode;
+    constructor(code: VaultErrorCode, message: string);
+}
+interface VaultIO {
+    load(): VaultRecord | null;
+    save(record: VaultRecord | null): void;
+}
+export declare class CredentialVault {
+    private io;
+    private device;
+    private record;
+    /** Recovered at unlock, dropped at lock. Never persisted. */
+    private masterKey;
+    /** Decrypted secrets while unlocked, keyed by connection id. */
+    private secrets;
+    /** Decrypted GMCP sign-ins while unlocked, keyed by connection id. */
+    private signIns;
+    private listeners;
+    private snapshot;
+    /** See {@link VaultSnapshot.rememberedUntil}. */
+    private rememberedUntil;
+    constructor(io?: VaultIO, device?: DeviceUnlockStore | null);
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => VaultSnapshot;
+    /** Whether this browser can do vault crypto at all (secure context). */
+    get available(): boolean;
+    /** Whether a passkey unlocker can even be offered here. */
+    get passkeysSupported(): boolean;
+    get exists(): boolean;
+    get locked(): boolean;
+    /** True when this profile has a stored password — answerable while locked,
+     *  which is what lets the app decide whether an unlock is worth asking for. */
+    hasEntry(connectionId: string): boolean;
+    /** The stored password, or `undefined` when there is none *or* the vault is
+     *  locked. Callers treat both the same way: fall back to asking the user. */
+    getPassword(connectionId: string): string | undefined;
+    /** True when this profile has a saved sign-in *token* — answerable while
+     *  locked. A token-less resume hint does not count: it is not worth asking
+     *  the player to unlock for. */
+    hasSignIn(connectionId: string): boolean;
+    /** The saved GMCP sign-in (a copy), or `undefined` when there is none or
+     *  the vault is locked. */
+    getSignIn(connectionId: string): VaultSignIn | undefined;
+    /** Whether this browser can keep the vault unlocked between visits. */
+    get canRemember(): boolean;
+    /** Whether a secret written now would actually be kept: a vault exists and
+     *  is open. What the GMCP `token_storage` field reports. */
+    get canStore(): boolean;
+    /**
+     * Create a vault whose first unlocker is a passphrase.
+     *
+     * `seed` migrates any passwords that were already sitting in plaintext on
+     * the connection records — the caller strips them from the store once this
+     * resolves, so the plaintext copy does not outlive its replacement.
+     */
+    createWithPassphrase(passphrase: string, seed?: Record<string, string>): Promise<void>;
+    /**
+     * Create a vault whose first unlocker is a passkey. Two authenticator
+     * prompts: one to register the credential, one to evaluate PRF for its KEK
+     * (Chrome does not return PRF output at registration).
+     *
+     * Throws `no-prf` when the authenticator cannot do PRF — the caller falls
+     * back to `createWithPassphrase`.
+     */
+    createWithPasskey(appName: string, label: string, seed?: Record<string, string>): Promise<void>;
+    /** Open the vault with a passphrase. `false` = wrong passphrase (the only
+     *  outcome a user can act on); anything else throws. */
+    unlockWithPassphrase(passphrase: string): Promise<boolean>;
+    /** Open the vault with a registered passkey. Throws on cancel (WebAuthn's
+     *  own error) or when no passkey unlocker exists. */
+    unlockWithPasskey(): Promise<boolean>;
+    /** Drop the master key and every decrypted secret. The record stays. A
+     *  vault kept unlocked on this device stops being so: "Lock" means locked
+     *  on the next visit too. */
+    lock(): void;
+    /**
+     * Open the vault from a remembered unlock, if this device has one for it.
+     * Called once at startup, before anything reads a password. A stale entry —
+     * expired, for a vault since replaced, or one that will not decrypt — is
+     * dropped. Never throws: the worst case is the usual unlock prompt.
+     */
+    restoreOnThisDevice(): Promise<boolean>;
+    /** Keep the open vault unlocked on this device until the expiry. Asking
+     *  again renews it. Requires unlocked. */
+    rememberOnThisDevice(): Promise<void>;
+    /** Stop keeping the vault unlocked on this device. It stays open for the
+     *  rest of this visit. */
+    forgetOnThisDevice(): Promise<void>;
+    /** Remove the vault and everything in it, irreversibly. */
+    deleteVault(): void;
+    /** Store (or, with `null`, forget) one profile's password. Requires unlocked. */
+    setPassword(connectionId: string, password: string | null): Promise<void>;
+    /**
+     * Forget every trace of a profile — called when the profile is deleted.
+     *
+     * A locked vault cannot rewrite its ciphertext, so the entry is left in
+     * place and swept on the next unlock by {@link pruneMissing}. Returning
+     * `false` says so; nothing leaks either way, since a deleted profile's
+     * password is unreachable.
+     */
+    forgetConnection(connectionId: string): Promise<boolean>;
+    /**
+     * Store (or, with `null`, forget) one profile's GMCP sign-in. Requires
+     * unlocked: whether a token can be kept at all is decided from
+     * {@link canStore} *before* the game is told (`token_storage`), so a locked
+     * vault here is a race for the caller to report, not a silent drop.
+     */
+    setSignIn(connectionId: string, entry: VaultSignIn | null): Promise<void>;
+    /** Drop stored passwords for profiles that no longer exist. No-op while
+     *  locked; the caller runs it right after an unlock. */
+    pruneMissing(existingConnectionIds: Iterable<string>): Promise<void>;
+    /** Add a passphrase to an already-open vault (recovery path for a
+     *  passkey-first vault, or a new phrase alongside the old one). */
+    addPassphrase(passphrase: string, label?: string): Promise<void>;
+    /** Add a passkey to an already-open vault. */
+    addPasskey(appName: string, label: string): Promise<void>;
+    /** Remove an unlock method. Refuses to remove the last one — that would
+     *  leave a vault nobody can open, which is data loss wearing a button. */
+    removeUnlocker(id: string): void;
+    /** Replace every passphrase unlocker with one derived from `next`. The
+     *  vault must be open, so this is "change", not "reset" — a forgotten
+     *  passphrase is recovered with a passkey or not at all. */
+    changePassphrase(next: string, label?: string): Promise<void>;
+    private requireAvailable;
+    private requireRecord;
+    private requireMaster;
+    private requireUnlocked;
+    private buildPassphraseUnlocker;
+    private buildPasskeyUnlocker;
+    private installNewVault;
+    private adoptMasterKey;
+    private persistSecrets;
+    private writeRecord;
+    private buildSnapshot;
+    private emit;
+}
+/** The app's vault. One per page — the unlocked state is deliberately shared
+ *  across profiles, so opening a second game after unlocking the first asks for
+ *  nothing. */
+export declare const credentialVault: CredentialVault;

package/dist-lib/vault/deviceUnlock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * "Keep unlocked on this device": the vault opens by itself on later visits.
+ *
+ * The master key is wrapped under a *device key* — an AES-GCM key created with
+ * `extractable: false` and kept in IndexedDB, which stores a `CryptoKey` by
+ * structured clone. Script on this origin can ask the browser to use it but can
+ * never read its bytes, so the wrapped copy is useless anywhere but this
+ * browser profile: not in a backup, not on another machine, not to an extension
+ * that copies localStorage (where the vault record lives).
+ *
+ * What it gives up, and what the player is told: anyone who can use this
+ * browser profile can open the vault, as with the browser's own saved
+ * passwords. Script in the page could already use an unlocked vault, so that
+ * exposure is unchanged. Someone copying the profile directory off the disk may
+ * recover the key, since browsers do not all encrypt IndexedDB at rest. Hence
+ * opt-in, and an expiry ({@link REMEMBER_UNLOCK_DAYS}) that re-asking renews.
+ *
+ * Kept in its own database so dropping it never touches anything else, and so
+ * no backup or storage sweep that names the app's other databases picks it up.
+ */
+import { type Ciphertext } from './vaultCrypto';
+/** How long a remembered unlock lasts before the vault asks again. */
+export declare const REMEMBER_UNLOCK_DAYS = 30;
+/** One remembered unlock — at most one per browser profile, like the vault. */
+export interface RememberedUnlock {
+    /** Non-extractable; never leaves IndexedDB as bytes. */
+    deviceKey: CryptoKey;
+    /** The vault master key, encrypted under `deviceKey`. */
+    wrapped: Ciphertext;
+    /** Which vault this opens — its `prfSalt`, random per vault. A vault
+     *  deleted and set up again must not be "opened" by a stale entry. */
+    vaultTag: string;
+    /** Epoch ms after which it is discarded unused. */
+    expiresAt: number;
+}
+export interface DeviceUnlockStore {
+    load(): Promise<RememberedUnlock | null>;
+    save(entry: RememberedUnlock): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Wrap `master` under a fresh device key. */
+export declare function rememberMasterKey(master: CryptoKey, vaultTag: string, now?: number): Promise<RememberedUnlock>;
+/** The master key back, or `null` when the entry is for another vault, has
+ *  expired, or will not decrypt. */
+export declare function recallMasterKey(entry: RememberedUnlock, vaultTag: string, now?: number): Promise<CryptoKey | null>;
+/** The IndexedDB-backed store, or `null` where there is no IndexedDB. */
+export declare function idbDeviceUnlockStore(): DeviceUnlockStore | null;

package/dist-lib/vault/passkeyPrf.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Passkey-backed vault unlocking, via the WebAuthn **PRF extension**.
+ *
+ * PRF turns an authenticator into a keyed pseudo-random function: given a salt,
+ * the credential returns the same 32 secret bytes every time, and those bytes
+ * never leave the authenticator's control without a user-verification gesture
+ * (Touch ID, Windows Hello, a security key's PIN). We use them as the KEK for
+ * one vault unlocker — so "unlock" is a fingerprint rather than a typed secret,
+ * and the browser's password manager holds a single passkey for the app instead
+ * of one saved login per game.
+ *
+ * There is no server here. The challenges are client-side randomness and the
+ * signature is never verified: we are deriving a key, not authenticating. That
+ * is why registration invents a local user handle.
+ *
+ * Support is feature-detected at registration: `create()` reports `prf.enabled`,
+ * and an authenticator that says no cannot back a vault, so the caller falls
+ * back to a passphrase.
+ */
+/** Registered credential, as persisted in the vault record. */
+export interface PasskeyRegistration {
+    /** Raw credential id, base64 — replayed in `allowCredentials` at unlock. */
+    credentialId: string;
+}
+/** True when the browser exposes WebAuthn at all. PRF support is only knowable
+ *  after a registration attempt, so this is a pre-filter, not a guarantee. */
+export declare function passkeysAvailable(): boolean;
+/** True when this device has a built-in authenticator (Touch ID, Hello, Android
+ *  screen lock) — used only to word the offer, never to gate it: security keys
+ *  do PRF too. */
+export declare function platformAuthenticatorAvailable(): Promise<boolean>;
+/**
+ * Register a new passkey for the vault and check that it can do PRF.
+ *
+ * Returns `null` when the credential was created but the authenticator refused
+ * PRF — the caller must then fall back to a passphrase. Throws when the user
+ * cancels or registration fails outright.
+ */
+export declare function registerVaultPasskey(appName: string, label: string): Promise<PasskeyRegistration | null>;
+/**
+ * Evaluate the vault's PRF salt against whichever registered passkey the user
+ * presents, and return the 32 secret bytes it answers with.
+ *
+ * All known credentials go into one `allowCredentials` list so a vault holding
+ * a laptop's Touch ID *and* a phone opens from either in a single prompt. That
+ * works because the salt belongs to the vault, not to a credential: one
+ * assertion cannot evaluate a different salt per credential, and the KEKs stay
+ * distinct regardless, since PRF output is keyed by the credential's own secret.
+ *
+ * Returns `null` when the authenticator answered without a PRF result. A cancel
+ * or timeout throws, as WebAuthn does.
+ */
+export declare function evaluateVaultPrf(registrations: PasskeyRegistration[], prfSalt: Uint8Array): Promise<{
+    credentialId: string;
+    secret: Uint8Array;
+} | null>;

package/dist-lib/vault/useVault.d.ts

@@ -0,0 +1,8 @@
+import type { VaultSnapshot } from './CredentialVault';
+/**
+ * Render off the credential vault's state. Returns the "no vault" snapshot in
+ * builds that never installed one (see `vaultAccess`), so every consumer can
+ * call this unconditionally and simply render nothing when `exists` is false
+ * and the vault cannot be created.
+ */
+export declare function useVault(): VaultSnapshot;

package/dist-lib/vault/vaultAccess.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The seam between the app and the credential vault.
+ *
+ * The vault is a **stock-app feature only**. A branded build ships for one game,
+ * so the problem it solves — ten profiles' logins piling up indistinguishably in
+ * one origin's password-manager dropdown — does not exist there, and branded
+ * builds keep credentials in memory for the page (`utils/sessionCredentials`)
+ * rather than storing them at all.
+ *
+ * So the library entry (`src/index.ts` → `MudletWebApp`) must not reach the
+ * vault, and this module is how: it is the only vault file the shared UI
+ * imports, it names the vault and its modal through `import type` alone, and
+ * `main.tsx` — which the standalone app loads and the library does not — is what
+ * puts the real ones in. Nothing here pulls in crypto, WebAuthn or the modal, so
+ * a consumer build contains none of it; every `getVault()` there is `null` and
+ * the callers render nothing.
+ */
+import type { ComponentType } from 'react';
+import type { CredentialVault, VaultSignIn, VaultSnapshot } from './CredentialVault';
+/** Props of the vault's modal. Declared here, not in the component, so this
+ *  module can describe the UI it hands out without importing it. */
+export interface VaultUIProps {
+    /** Which step to show: create a vault, open one, or manage one. */
+    mode: 'setup' | 'unlock' | 'manage';
+    /** Why an unlock is being asked for — e.g. the profile being opened. */
+    reason?: string;
+    /** Plaintext passwords to fold into a *new* vault, keyed by connection id. */
+    seed?: Record<string, string>;
+    /** Profile id → display name, for the saved-logins list. */
+    connectionNames?: Record<string, string>;
+    onDone: (result: 'created' | 'unlocked' | 'closed') => void;
+}
+export type VaultUI = ComponentType<VaultUIProps>;
+/** What a consumer without a vault sees. Frozen and shared: `useSyncExternalStore`
+ *  needs a stable identity from a snapshot that has not changed. */
+export declare const NO_VAULT: VaultSnapshot;
+/**
+ * Make a vault (and the UI that drives it) available to the app. Called once
+ * from `main.tsx`, before the first render, so credential reads on a cold
+ * auto-connect never race the install.
+ */
+export declare function installVault(vault: CredentialVault, ui: VaultUI): void;
+/** Drop the installed vault. Tests only — the app installs once per page. */
+export declare function uninstallVault(): void;
+/** The app's vault, or `null` in a build that never installed one. */
+export declare function getVault(): CredentialVault | null;
+/** The vault's modal, or `null` — render it only when this is non-null. */
+export declare function getVaultUI(): VaultUI | null;
+export declare function subscribeVault(listener: () => void): () => void;
+export declare function vaultSnapshot(): VaultSnapshot;
+/** A stored password, or `undefined` when there is no vault, no entry, or the
+ *  vault is locked. All three mean the same thing to a caller: ask the user. */
+export declare function vaultPassword(connectionId: string): string | undefined;
+/** Whether this profile has a stored password — true even while locked, which
+ *  is what tells the app an unlock is worth offering. */
+export declare function vaultHasEntry(connectionId: string): boolean;
+/** Whether opening this profile should ask for an unlock first — it has a
+ *  saved password or a saved GMCP sign-in token, and the vault is shut. */
+export declare function vaultNeedsUnlock(connectionId: string): boolean;
+/** The profile's saved GMCP `Char.Login` sign-in, or `undefined` when there is
+ *  no vault, no entry, or the vault is locked. */
+export declare function vaultSignIn(connectionId: string): VaultSignIn | undefined;
+/** Whether a vault could be set up here but none exists yet. False with no
+ *  vault installed (a branded build) or no crypto (an insecure context). */
+export declare function vaultMissing(): boolean;
+/** Whether a vault exists and is locked. */
+export declare function vaultLocked(): boolean;
+/** Whether this profile has a saved sign-in token — true even while locked. */
+export declare function vaultHasSignIn(connectionId: string): boolean;
+/**
+ * Whether a sign-in token handed to us right now would be kept — the honest
+ * answer to GMCP's `token_storage`. With no vault (a branded build, or a player
+ * who never set one up) or a locked one, a token would be thrown away, and the
+ * standard asks the client to say so up front, so the game does not offer the
+ * player a "remember me" that cannot happen.
+ */
+export declare function vaultCanStoreSignIn(): boolean;
+/** Save (or with `null` forget) a profile's sign-in. Resolves `false` when it
+ *  could not — no vault, locked, or the write failed. */
+export declare function saveVaultSignIn(connectionId: string, entry: VaultSignIn | null): Promise<boolean>;

package/dist-lib/vault/vaultCrypto.d.ts

@@ -0,0 +1,56 @@
+/**
+ * WebCrypto primitives for the credential vault.
+ *
+ * Envelope encryption: one random 256-bit AES-GCM **master key** encrypts the
+ * secrets blob, and every *unlocker* (a passphrase, a passkey) wraps a copy of
+ * that master key with a key-encryption key it derives on its own. Adding or
+ * removing an unlock method therefore rewraps one small blob instead of
+ * re-encrypting the secrets, and two methods can coexist without either being
+ * able to read the other's derivation input.
+ *
+ * Everything here is pure WebCrypto over plain values — no storage, no DOM —
+ * so the format can be tested end-to-end without IndexedDB or a browser.
+ */
+/** AES-GCM ciphertext plus its nonce, both base64 for JSON storage. */
+export interface Ciphertext {
+    /** 12-byte GCM nonce, freshly random for every encryption. */
+    iv: string;
+    /** Ciphertext with the 16-byte GCM tag appended (WebCrypto's layout). */
+    ct: string;
+}
+/**
+ * PBKDF2 work factor for passphrase unlockers. OWASP's 2023 floor for
+ * PBKDF2-HMAC-SHA256; ~0.3s on a mid-range laptop, which is the right trade for
+ * something typed once per page rather than once per keystroke. Stored *in* the
+ * record so the number can be raised later without stranding existing vaults.
+ */
+export declare const PBKDF2_ITERATIONS = 600000;
+/** True when this context can do vault crypto at all. */
+export declare function cryptoAvailable(): boolean;
+export declare function randomBytes(length: number): Uint8Array;
+export declare function toBase64(bytes: ArrayBuffer | Uint8Array): string;
+export declare function fromBase64(b64: string): Uint8Array;
+/** A fresh master key. Extractable — it has to be, to be wrapped by unlockers. */
+export declare function generateMasterKey(): Promise<CryptoKey>;
+/**
+ * Stretch a passphrase into a key-encryption key. The KEK never encrypts
+ * secrets directly — it only wraps the master key — so changing the passphrase
+ * costs one rewrap.
+ */
+export declare function deriveKeyFromPassphrase(passphrase: string, salt: Uint8Array, iterations?: number): Promise<CryptoKey>;
+/**
+ * Stretch a WebAuthn PRF result into a key-encryption key. The PRF output is
+ * already 32 uniformly-random bytes bound to the authenticator, so this is a
+ * domain-separating HKDF rather than a cost function — there is nothing to
+ * brute-force without the authenticator.
+ */
+export declare function deriveKeyFromPrf(prfOutput: ArrayBuffer | Uint8Array): Promise<CryptoKey>;
+export declare function encryptBytes(key: CryptoKey, plaintext: Uint8Array): Promise<Ciphertext>;
+/** Decrypt, or throw — GCM authentication failure is how a wrong passphrase is detected. */
+export declare function decryptBytes(key: CryptoKey, box: Ciphertext): Promise<Uint8Array>;
+export declare function encryptJson(key: CryptoKey, value: unknown): Promise<Ciphertext>;
+export declare function decryptJson<T>(key: CryptoKey, box: Ciphertext): Promise<T>;
+/** Wrap the master key for one unlocker. */
+export declare function wrapMasterKey(kek: CryptoKey, master: CryptoKey): Promise<Ciphertext>;
+/** Recover the master key from an unlocker's wrapped copy. Throws on a bad KEK. */
+export declare function unwrapMasterKey(kek: CryptoKey, wrapped: Ciphertext): Promise<CryptoKey>;

package/dist-lib/vault/vaultHelpTopic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The manual page for the credential vault.
+ *
+ * It lives here rather than in `ui/helpTopics.ts` for the same reason the vault
+ * itself does: a branded build ships for one game, has no vault, and must not
+ * carry a help topic explaining a feature its players cannot find. Registered
+ * from `main.tsx` at boot — the standalone app's entry, never the library's.
+ */
+export declare function installVaultHelpTopic(): void;

package/dist-lib/vault/vaultRecord.d.ts

@@ -0,0 +1,92 @@
+/**
+ * On-disk shape of the credential vault, and its (synchronous) persistence.
+ *
+ * The record lives in `localStorage` rather than IndexedDB on purpose: it is
+ * small, and everything sensitive in it is already AES-GCM ciphertext, so the
+ * weakness that made plaintext `charLoginPassword` a bad idea — localStorage is
+ * readable by anything running on the page — costs nothing here. In exchange
+ * the vault's *shape* (does one exist, which profiles have a saved password) is
+ * readable synchronously during the first render, with no async init race and
+ * no loading state in every consumer.
+ *
+ * It is deliberately NOT part of the Zustand store: `mudix_v1` is exported,
+ * imported and reset by profile tooling, and vault material must not travel
+ * with a profile export.
+ */
+import type { Ciphertext } from './vaultCrypto';
+export declare const VAULT_STORAGE_KEY = "mudlet_vault_v1";
+interface UnlockerBase {
+    /** Stable local id, so the manage UI can remove one unambiguously. */
+    id: string;
+    /** User-facing name ("Passphrase", "MacBook Touch ID"). */
+    label: string;
+    createdAt: string;
+    /** The vault's master key, wrapped by the KEK this unlocker derives. */
+    wrapped: Ciphertext;
+}
+export interface PassphraseUnlocker extends UnlockerBase {
+    kind: 'passphrase';
+    /** PBKDF2 salt, base64. */
+    salt: string;
+    /** PBKDF2 iteration count *as used*, so the cost can be raised for new
+     *  vaults without stranding existing ones. */
+    iterations: number;
+}
+export interface PasskeyUnlocker extends UnlockerBase {
+    kind: 'passkey';
+    /** WebAuthn credential id, base64. */
+    credentialId: string;
+}
+export type VaultUnlocker = PassphraseUnlocker | PasskeyUnlocker;
+export interface VaultRecord {
+    version: 1;
+    /** 32-byte PRF salt shared by every passkey unlocker, base64. See
+     *  `evaluateVaultPrf` for why it is per-vault and not per-credential. */
+    prfSalt: string;
+    unlockers: VaultUnlocker[];
+    /** Connection ids that have a stored password. Plaintext by design — it is
+     *  what lets a *locked* vault answer "does this profile have a saved login?"
+     *  so the app knows whether to offer an unlock at all. */
+    entryIds: string[];
+    /** AES-GCM under the master key over `Record<connectionId, password>`.
+     *  `null` before the first secret is stored. */
+    payload: Ciphertext | null;
+    /** Profiles holding a saved GMCP `Char.Login` sign-in token (see
+     *  {@link VaultSignIn}). Plaintext for the same reason as `entryIds`: a
+     *  locked vault has to be able to say a profile has something worth
+     *  unlocking for. Absent in a record written before sign-ins existed. */
+    signInIds?: string[];
+    /** AES-GCM under the master key over `Record<connectionId, VaultSignIn>`.
+     *  A field of its own rather than more keys in `payload`, so a build from
+     *  before sign-ins existed still reads its passwords unchanged, and carries
+     *  this across its own writes untouched (it spreads the record). */
+    signInPayload?: Ciphertext | null;
+}
+/**
+ * A saved GMCP `Char.Login` v2 sign-in: the reconnect token a game issued with
+ * `Char.Login.Token`, the account it names, and what is needed to replay it
+ * safely — or to resume the same provider once it stops working.
+ *
+ * Mudlet keeps the same entry in the OS keychain (`GMCPAuthenticator`'s
+ * metadata + token keys). The token is a bearer secret — it signs the account
+ * in without a password — so it lives encrypted here or not at all.
+ */
+export interface VaultSignIn {
+    /** The account the token was issued for; `Char.Login.Reconnect` names it. */
+    account: string;
+    /** Provider id (`discord`, `google`, …) learned from `Char.Login.URL`, so a
+     *  dead token can turn into a resume of that provider's sign-in. */
+    provider?: string;
+    /** The bearer token. Absent in a resume hint left behind by a dead one. */
+    token?: string;
+    /** The token may only be replayed over an encrypted game connection — the
+     *  issuing server's requirement, stored because the connection that set it
+     *  is long gone by replay time. Missing reads as true, never widening. */
+    secureOnly?: boolean;
+}
+/** Parse defensively — a corrupt record must degrade to "no vault", never to a
+ *  crash on boot that locks the user out of the app as well as the vault. */
+export declare function parseVaultRecord(raw: string | null): VaultRecord | null;
+export declare function loadVaultRecord(): VaultRecord | null;
+export declare function saveVaultRecord(record: VaultRecord | null): void;
+export {};