@mudlet/mudlet-web 0.4.4 → 0.5.0

package/dist-lib/ui/CharLoginModal.d.ts

@@ -3,19 +3,24 @@ interface CharLoginModalProps {
     connectionName?: string;
     /** Error from a previous failed attempt (Char.Login.Result success=false). */
     error?: string;
-    /** Account/username to prefill (saved per-profile credential). */
+    /** Account/username to prefill. Not a secret — it lives on the connection
+     *  record, and prefilling it is also what lets a password manager pick the
+     *  matching password instead of listing every profile's. */
     initialAccount?: string;
-    /** Password to prefill (saved per-profile credential — plaintext). */
+    /** Password to prefill, from the unlocked vault. */
     initialPassword?: string;
-    /** Initial state of the "remember on this device" checkbox. */
-    initialRemember?: boolean;
-    /** Show the "remember on this device" checkbox (default true). Branded
-     *  builds hide it — credentials are never persisted there, so `onSubmit`
-     *  always receives `remember=false`. */
-    allowRemember?: boolean;
+    /** Initial state of the "save this password" checkbox. */
+    initialSave?: boolean;
+    /** Offer to save the password (default true). False where there is nothing
+     *  to save it into: branded builds, which never persist credentials, and
+     *  pages served without a secure context. */
+    allowSave?: boolean;
+    /** Wording under the checkbox — the caller knows whether ticking it will
+     *  store into an existing vault or set one up first. */
+    saveNote?: string;
     /** Send `account` + `password` to the server (Char.Login.Credentials).
-     *  `remember` tells the caller whether to persist them for next time. */
-    onSubmit: (account: string, password: string, remember: boolean) => void;
+     *  `save` asks the caller to put the password in the credential vault. */
+    onSubmit: (account: string, password: string, save: boolean) => void;
     /** Decline GMCP login — sends the empty reply so the server falls back to
      *  its text login prompt. */
     onCancel: () => void;
@@ -27,10 +32,14 @@ interface CharLoginModalProps {
 /**
  * Credentials popup for GMCP `Char.Login` authentication. Rendered as a real
  * `<form>` with `autocomplete="username"` / `autocomplete="current-password"`
- * inputs so browser password managers offer to fill and save. Optionally
- * remembers the account + password per profile (plaintext localStorage — see
- * the inline warning); the password is otherwise handed straight to `onSubmit`
- * and relayed to the server, never stored. Cancelling falls back to text login.
+ * inputs so browser password managers can still fill and save for anyone who
+ * prefers them.
+ *
+ * Saving is the credential vault's job (`vault/CredentialVault`): ticking the
+ * box hands the password to the caller, which encrypts it under a key derived
+ * from a passkey or a passphrase. That replaced an older checkbox that wrote
+ * the password to localStorage in the clear and had to apologise for it in a
+ * red warning right underneath — see issue #25.
  */
-export declare function CharLoginModal({ connectionName, error, initialAccount, initialPassword, initialRemember, allowRemember, onSubmit, onCancel, restoreFocusTo, }: CharLoginModalProps): import("react/jsx-runtime").JSX.Element;
+export declare function CharLoginModal({ connectionName, error, initialAccount, initialPassword, initialSave, allowSave, saveNote, onSubmit, onCancel, restoreFocusTo, }: CharLoginModalProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/ui/ConnectionFormModal.d.ts

@@ -1,4 +1,5 @@
 import { type MudConnection } from '../storage';
+import type { VaultSaver } from './useVaultSaver';
 interface Props {
     /** The connection to edit, or null to add a new one. */
     connection: MudConnection | null;
@@ -8,6 +9,10 @@ interface Props {
     onAdd: (data: Omit<MudConnection, 'id'>) => string;
     onUpdate: (id: string, data: Omit<MudConnection, 'id'>) => void;
     onClose: () => void;
+    /** Where a typed password goes. Owned by the screen above, not by this
+     *  modal: saving may need a vault setup or unlock step, and this form closes
+     *  on submit — a prompt rendered from here would unmount with it. */
+    vaultSaver: VaultSaver;
 }
-export declare function ConnectionFormModal({ connection, firstConnection, busy, onAdd, onUpdate, onClose }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function ConnectionFormModal({ connection, firstConnection, busy, onAdd, onUpdate, onClose, vaultSaver }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/ui/VaultManageButton.d.ts

@@ -0,0 +1,15 @@
+import type { MudConnection } from '../storage';
+interface VaultManageButtonProps {
+    connections: MudConnection[];
+    disabled?: boolean;
+}
+/**
+ * "Saved logins" on the connection screen's tools row — the one place to lock
+ * the vault, change how it opens, drop a stored password or delete the whole
+ * thing.
+ *
+ * Renders nothing when no vault is installed, which is how a branded build gets
+ * neither the button nor anything behind it (see `vault/vaultAccess`).
+ */
+export declare function VaultManageButton({ connections, disabled }: VaultManageButtonProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/ui/VaultModal.d.ts

@@ -0,0 +1,2 @@
+import { type VaultUIProps } from '../vault/vaultAccess';
+export declare function VaultModal({ mode, reason, seed, connectionNames, onDone }: VaultUIProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/ui/VaultUnlockPrompt.d.ts

@@ -0,0 +1,15 @@
+interface VaultUnlockPromptProps {
+    /** Why the app is asking right now — shown above the unlock controls. */
+    reason: string;
+    onDone: (result: 'created' | 'unlocked' | 'closed') => void;
+}
+/**
+ * The unlock step on its own.
+ *
+ * Kept separate from `useVaultSaver` because unlocking is asked for on the read
+ * path — a profile with a saved login is being opened — where there is nothing
+ * to save and no vault to create. Renders nothing in a build that installed no
+ * vault UI, which is how a branded build gets none of this.
+ */
+export declare function VaultUnlockPrompt({ reason, onDone }: VaultUnlockPromptProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist-lib/ui/output/clearSplit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Closing the split view — Mudlet's `TConsole::clearSplit`, which drops the
+ * frozen upper pane and puts the console back on the tail. Mudlet reaches it
+ * two ways: Ctrl+Return in the command line (`TCommandLine::event`) and a
+ * middle click anywhere on the console (`TTextEdit::mousePressEvent`). This
+ * module holds the DOM-level predicate so it's unit-testable without React.
+ */
+/** True when `e` is the Ctrl/Cmd+Return that closes the split view. Shift and
+ *  Alt combinations are left alone — the command bar stages a newline on those
+ *  — as is anything typed into an editor that owns its own Ctrl+Enter: a code
+ *  editor (contentEditable) or any textarea other than the command line, which
+ *  is itself a textarea and so cannot be excluded by tag alone. */
+export declare function matchClearSplitKey(e: KeyboardEvent): boolean;
+/** True when `e` is the middle click that closes the split view. */
+export declare function isClearSplitClick(e: {
+    button: number;
+}): boolean;

package/dist-lib/ui/useVaultSaver.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+/**
+ * "Save this password" for the two places that offer it — the GMCP login popup
+ * and the connection editor.
+ *
+ * Saving can need a detour: the vault may not exist yet (set one up) or may be
+ * locked (unlock it). Rather than making every caller sequence that, `save()`
+ * parks the password and returns, the returned `element` renders whichever step
+ * is needed, and the write happens once it succeeds.
+ *
+ * In a build with no vault installed `canSave` is false and `element` is null —
+ * callers then don't offer the checkbox at all (see `vault/vaultAccess`).
+ */
+export interface VaultSaver {
+    /** True when a vault can be written to, now or after a setup/unlock step. */
+    canSave: boolean;
+    /** Store (or, with `null`, forget) a profile's password, prompting first if
+     *  the vault needs setting up or unlocking. */
+    save: (connectionId: string, password: string | null) => void;
+    /** Explains where a ticked checkbox will put the password. */
+    note: string;
+    /** Render this next to the form — the setup/unlock modal, when one is due.
+     *  Mount it somewhere that outlives the form: saving usually closes it. */
+    element: ReactNode;
+}
+export declare function useVaultSaver(): VaultSaver;

package/dist-lib/utils/storedCredentials.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where auto-login credentials come from, in priority order — one place so the
+ * GMCP `Char.Login` path and the text-login state machine can never disagree
+ * about which password they are about to send.
+ *
+ * 1. **In-memory** (`sessionCredentials`) — a branded build's login form. Those
+ *    builds never persist anything, so this is the only source they have.
+ * 2. **The credential vault**, when one is installed and unlocked.
+ * 3. **`charLoginPassword` on the connection record** — the pre-vault plaintext
+ *    field. Never written any more (see issue #25) and no longer offered in the
+ *    UI, but still read so that an existing saved login keeps working until the
+ *    user sets a vault up, at which point it is migrated and deleted
+ *    (`useVaultSaver`).
+ *
+ * The account name is not a secret and stays on the connection record either
+ * way: prefilling it is also what lets a browser password manager pick the one
+ * matching password instead of offering every profile's.
+ */
+export interface StoredLogin {
+    account: string;
+    password: string;
+}
+export declare function readStoredLogin(connectionId: string): StoredLogin;
+/**
+ * Drop vault entries for profiles that no longer exist.
+ *
+ * Deleting a profile can't rewrite the vault when it is locked — there is no
+ * key to re-encrypt the remaining secrets with — so `forgetConnection` leaves
+ * the entry behind and the sweep happens here instead, on the next unlock.
+ */
+export declare function pruneVaultEntries(): void;

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

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ *
+ * State changes notify `subscribe` listeners so React can render off
+ * `getSnapshot` through `useSyncExternalStore`.
+ */
+import { type VaultRecord, type VaultUnlocker } 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[];
+    /** Unlock methods, without their key material. */
+    unlockers: readonly {
+        id: string;
+        kind: VaultUnlocker['kind'];
+        label: string;
+        createdAt: string;
+    }[];
+}
+/** 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 record;
+    /** Recovered at unlock, dropped at lock. Never persisted. */
+    private masterKey;
+    /** Decrypted secrets while unlocked, keyed by connection id. */
+    private secrets;
+    private listeners;
+    private snapshot;
+    constructor(io?: VaultIO);
+    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;
+    /**
+     * 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. */
+    lock(): 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>;
+    /** 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;
+export {};

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,58 @@
+/**
+ * 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, 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. */
+export declare function vaultNeedsUnlock(connectionId: string): 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/vaultRecord.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 = "mudix_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;
+}
+/** 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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudlet/mudlet-web",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "description": "Mudlet Web — Mudlet in the browser, usable standalone or as a library for branded builds",
   "license": "GPL-2.0-or-later",