@tgoliveira/vault-core 0.1.1 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,77 @@
+# Agent and Contributor Guide
+
+This file is the operational entry point for AI agents and human contributors working on
+`@tgoliveira/vault-core`.
+
+## Language
+
+- Source code, identifiers, error messages, tests, comments, and documentation must be written in
+  English.
+- Consumer-facing API examples must be complete TypeScript that reflects the current signatures.
+
+## Read first
+
+1. `README.md` for package scope and the shortest working example.
+2. `docs/IMPLEMENTATION_GUIDE.md` for the complete consumer workflow.
+3. `SECURITY.md` before changing crypto, persistence, validation, or session behavior.
+4. `API_REFERENCE.md` for public entry points and security preconditions.
+5. `CHANGELOG.md` before modifying a public contract.
+6. `docs/RELEASING.md` before changing the package version or publishing.
+
+## Public package boundaries
+
+| Import | Responsibility |
+| --- | --- |
+| `@tgoliveira/vault-core` | Crypto, envelopes, recovery, schemas, AAD, and validation |
+| `@tgoliveira/vault-core/browser` | Browser session lifecycle, storage inspection, PRF salt, recovery kit DOM helpers |
+| `@tgoliveira/vault-core/react` | React session provider, hooks, and client status derivation |
+| `@tgoliveira/vault-core/testing` | Plaintext sentinels and leak-detection helpers |
+
+Do not add framework, persistence, database, route, authentication, or product payload concerns to
+the core entry.
+
+## Non-negotiable security invariants
+
+- Vault passwords, recovery phrases, UVKs, PRF output, and decrypted payloads never go to the server.
+- Decrypted vault state is never persisted to localStorage or IndexedDB.
+- High-level decrypt and unlock calls always receive and validate the expected scope and profile.
+- Persisted KDF metadata is untrusted and bounded before work begins.
+- Session key changes use lifecycle-aware lock and unlock APIs; public direct setters are forbidden.
+- Account authentication and vault unlock remain separate security domains.
+
+## Change protocol
+
+For every user-visible change:
+
+1. Update implementation and tests together.
+2. Add an entry under the appropriate `CHANGELOG.md` `Unreleased` heading.
+3. Update every affected example and signature in consumer documentation.
+4. Preserve deprecated aliases only when the migration path remains safe and explicit.
+5. Run `npm run validate`.
+6. Run `npm pack --dry-run` when exports, package files, or documentation change.
+
+The test suite enforces that the current `package.json` version has a released changelog entry. A
+version bump without a changelog release section must fail validation.
+
+Do not bump versions, create release tags, or publish manually. Start the `Publish package to npmjs`
+workflow on `main`; it owns version selection, release metadata, npm publication, and tag creation.
+
+## Required validation
+
+```bash
+npm ci
+npm run validate
+npm pack --dry-run
+```
+
+Coverage thresholds are enforced per production file at 90% for statements, branches, functions,
+and lines. Do not lower or bypass thresholds to merge a change.
+
+## Definition of done
+
+- Public types and runtime schemas agree.
+- Security failures have regression tests.
+- All code and documentation are in English.
+- `CHANGELOG.md` describes the consumer-visible effect.
+- Documentation examples typecheck conceptually against current APIs.
+- `npm run validate` and package dry-run pass.

package/API_REFERENCE.md

@@ -1,36 +1,206 @@
 # API Reference
 
-See TypeScript exports from:
+The package exposes four supported entry points. Internal `dist/*` paths are not public APIs.
 
-- `@tgoliveira/vault-core`
-- `@tgoliveira/vault-core/browser`
-- `@tgoliveira/vault-core/testing`
-- `@tgoliveira/vault-core/react`
+For complete workflows, use [`docs/IMPLEMENTATION_GUIDE.md`](docs/IMPLEMENTATION_GUIDE.md).
 
-## Core types
+## Core: `@tgoliveira/vault-core`
 
-- `VaultCryptoProfile`, `VaultCryptoVersion`
-- `EncryptedVaultPayload`, `VaultEnvelope`, `PasswordEnvelope`, `RecoveryPhraseEnvelope`, `PasskeyPrfEnvelope`
-- `RecoveryPhraseWordCount` (`12 | 24`)
-- `VaultUnlockResult<TPayload>`, `VaultCoreError`
+### Protocol constants and profile
 
-## Core functions
+| Export | Purpose |
+| --- | --- |
+| `ENCRYPTION_VERSION` | Stored payload version, currently `enc-v1` |
+| `ENCRYPTION_ALG` | Stored algorithm identifier, currently `AES-GCM` |
+| `VAULT_CRYPTO_VERSION` | Vault protocol version, currently `vault-v1` |
+| `DEFAULT_VAULT_AUTO_LOCK_MINUTES` | Default browser inactivity timeout |
+| `VaultCryptoProfile` | Stable application AAD contexts |
+| `VaultAadScope`, `VaultAadField` | Authenticated user/resource/field scope |
+| `RecoveryPhraseWordCount` | `12 | 24` |
+| `resolveAadContext(scope, profile)` | Resolves explicit or profile-derived AAD context |
 
-- `createUserVaultKey()`
-- `encryptVaultPayload<T>(payload, key, scope, profile)`
-- `decryptVaultPayload<T>(encrypted, key)`
-- `createPasswordEnvelope` / `unlockWithPasswordEnvelope`
-- `createRecoveryPhrase` / `createRecoveryEnvelope` / `unlockWithRecoveryEnvelope`
-- `createPasskeyPrfEnvelope` / `unlockWithPasskeyPrfEnvelope`
-- `createRecoveryKitText(...)`
-- `assertVaultKeyAad` / `assertVaultPayloadAad`
-- `assertNoVaultPlaintextFields` / `validateNoPlaintextLeak`
+### User Vault Key and AES-GCM
 
-Deprecated aliases (`wrapVaultKeyForPassword`, etc.) remain for migration.
+| Export | Purpose |
+| --- | --- |
+| `createUserVaultKey()` | Generates an extractable 256-bit AES-GCM UVK |
+| `importUserVaultKey(bytes)` | Imports raw UVK bytes |
+| `exportUserVaultKey(key)` | Exports raw UVK bytes; keep client-only |
+| `generateAesKey()`, `importAesKey()`, `exportAesKey()` | Low-level AES key primitives |
+| `encryptVaultPayload(payload, key, scope, profile)` | Serializes and encrypts generic JSON |
+| `decryptVaultPayload(encrypted, key, expectedScope, profile)` | Validates expected AAD, decrypts, and parses JSON |
+| `encryptField(plaintext, key, aad, profile)` | Low-level string encryption |
+| `decryptField(encrypted, key)` | Low-level compatibility decrypt without expected-scope validation |
+| `canonicalAadString(aad)` | Produces canonical AAD JSON |
+| `aadByteCandidates(aad)` | Produces canonical and legacy AAD byte candidates |
 
-## React entry (`@tgoliveira/vault-core/react`)
+Use the high-level payload APIs for application data. `decryptField()` is appropriate only when the
+caller separately validates expected AAD, such as a bounded legacy migration.
 
-- `useVaultUnlocked()`, `useVaultLockState()`
-- `useVaultSession()`, `VaultSessionProvider`
-- `resolveVaultClientStatus()`, `useVaultClientStatus()`
-- `VaultClientStatus`, `VaultServerStatusSnapshot`
+### Encoding, random, and serialization utilities
+
+- `bytesToBase64Url(bytes)` / `base64UrlToBytes(value)`
+- `stringToBytes(value)` / `bytesToString(bytes)`
+- `toBufferSource(bytes)`
+- `randomBytes(length)`
+- `serializeVaultPayload(payload)` / `parseVaultPayload<T>(json)`
+
+### Argon2id
+
+| Export | Purpose |
+| --- | --- |
+| `DEFAULT_ARGON2ID_PARAMS` | Creation defaults |
+| `ARGON2ID_LIMITS` | Accepted persisted resource bounds |
+| `assertSafeArgon2idParams(params)` | Validates memory, iteration, and parallelism bounds |
+| `assertSafeArgon2idSalt(salt)` | Validates salt size |
+| `serializeArgon2idMetadata(salt, params?)` | Builds persisted metadata |
+| `parseArgon2idMetadata(metadata)` | Decodes and validates persisted metadata |
+| `deriveArgon2idAesKey(...)` | Low-level byte-based derivation |
+| `deriveArgon2idAesKeyFromMetadata(...)` | Low-level derivation from stored metadata |
+| `deriveVaultPasswordKey(password, salt?)` | NFKC-normalized password derivation |
+| `deriveVaultPasswordKeyFromMetadata(password, metadata)` | Password derivation from stored metadata |
+
+Applications normally use envelope APIs instead of direct derivation functions.
+
+### Password envelopes
+
+- `createPasswordEnvelope(vaultKey, password, scope, profile, salt?)`
+- `unlockWithPasswordEnvelope(password, envelope, expectedScope, profile)`
+
+### Recovery phrases and envelopes
+
+- `createRecoveryPhrase({ wordCount })`
+- `normalizeRecoveryPhrase(phrase)`
+- `validateRecoveryPhraseFormat(phrase)`
+- `getRecoveryPhraseWordCount(phrase)`
+- `parseRecoveryPhraseWordCount(publicMetadata)`
+- `assertRecoveryPhraseUnlockInput(phrase, expectedWordCount?)`
+- `getRecoveryConfirmationPromptCount(wordCount)`
+- `pickRecoveryConfirmationIndices(wordCount, count?)`
+- `assertRecoveryPhraseConfirmation(original, confirmation)`
+- `assertRecoveryPhraseWordConfirmation(phrase, answers, requiredIndices?)`
+- `deriveRecoveryPhraseKey(...)` / `deriveRecoveryPhraseKeyFromMetadata(...)`
+- `createRecoveryEnvelope(vaultKey, phrase, scope, profile, publicMetadata?, salt?)`
+- `unlockWithRecoveryEnvelope(phrase, envelope, expectedScope, profile, options?)`
+- `createRecoveryKitText(input)`
+- `RECOVERY_PHRASE_WORDLIST_SOURCE`, `DEFAULT_RECOVERY_PHRASE_WORD_COUNT`
+
+Word confirmation requires all deterministic default indices unless explicit required indices are
+provided.
+
+### Passkey PRF envelopes
+
+- `createPasskeyPrfEnvelope(vaultKey, prfOutput, scope, profile, publicMetadata?)`
+- `unlockWithPasskeyPrfEnvelope(envelope, prfOutput, expectedScope, profile, options?)`
+- `unwrapVaultKeyFromPasskey(encryptedVaultKey, prfOutput, expectedScope, profile)`
+- `extractPasskeyPrfOutput(extensionResults)`
+- `isPasskeySupported()` / `isPrfExtensionSupported()`
+
+The application owns WebAuthn ceremonies. Capability probes are preliminary; the actual ceremony may
+still return no PRF output. PRF output must remain client-only.
+
+### Runtime schemas and types
+
+| Export | Runtime contract |
+| --- | --- |
+| `encryptedPayloadSchema` | `enc-v1` AES-GCM payload with UUID AAD identifiers |
+| `argon2idKdfMetadataSchema` / `kdfMetadataSchema` | Bounded `kdf-v1` Argon2id metadata |
+| `passwordEnvelopeSchema` | Password method plus required Argon2id metadata |
+| `recoveryPhraseEnvelopeSchema` | Recovery method plus required Argon2id metadata |
+| `passkeyPrfEnvelopeSchema` | Passkey PRF method plus null KDF metadata |
+| `storedEnvelopeSchema` | Method-discriminated union of all envelopes |
+| `vaultSetupEnvelopeFieldsSchema` | Complete encrypted setup record |
+
+Associated inferred types include `EncryptedVaultPayload`, `Argon2idKdfMetadata`, `VaultEnvelope`,
+`PasswordEnvelope`, `RecoveryPhraseEnvelope`, `PasskeyPrfEnvelope`, and `VaultEnvelopeMethod`.
+
+### AAD and plaintext validation
+
+- `assertVaultKeyAad(expectedScope, payload, profile)`
+- `assertVaultPayloadAad(expectedScope, payload, profile)`
+- `rejectVaultPlaintextFields(body)`
+- `assertNoVaultPlaintextFields(body)`
+- `validateNoPlaintextLeak(data)`
+- `scanForSentinels(data, sentinels?)`
+- `containsSentinel(value, sentinels?)`
+- `PLAINTEXT_FORBIDDEN_VAULT_FIELDS`, `ALL_SENTINELS`, and named `SENTINEL_*` constants
+
+The plaintext field guard is recursive and cycle-safe. It is defense in depth; closed API schemas are
+still required.
+
+### Errors
+
+- `VaultPlaintextRejectionError`
+- `VaultConflictError`
+- `VaultNotFoundError`
+- `PasskeyPrfRequiredError`
+- `PasskeyUnlockError`
+- `RecoveryPhraseConfirmationError`
+- `VaultCoreError`
+
+### Deprecated migration aliases
+
+- `generateUserVaultKey`
+- `generateRecoveryPhrase`
+- `wrapVaultKeyForPassword` / `unwrapVaultKeyFromPassword`
+- `wrapVaultKeyForRecoveryPhrase` / `unwrapVaultKeyFromRecoveryPhrase`
+- `wrapVaultKeyForPasskey` / `unlockVaultFromPasskeyEnvelope`
+- `buildRecoveryKitContent`
+- `EncryptedPayload`, `StoredEnvelope`
+
+New code should use the canonical APIs. Deprecated unlock aliases use the current secure signatures.
+
+## Browser: `@tgoliveira/vault-core/browser`
+
+### Session lifecycle
+
+- `configureVaultSession(config)`
+- `unlockVaultSession(vaultKey)` / `lockVaultSession()`
+- `lockVaultSessionManually()` / `isVaultManuallyLocked()`
+- `touchVaultSession()` / `scheduleVaultAutoLock()` / `clearVaultAutoLockTimer()`
+- `getVaultAutoLockRemainingMs()`
+- `getSessionVaultKey()` / `isVaultUnlocked()`
+- `subscribeVaultSession(listener)`
+- `registerVaultActivityGuard(events?)`
+- `registerVaultUnloadGuard()`
+- `resetVaultSessionLockState()`
+- `VaultSessionConfig`
+
+Direct session-key setters are intentionally not exported.
+
+### Storage inspection
+
+- `VaultStorageInspectionResult`: `"clear" | "found" | "unavailable"`
+- `inspectLocalStoragePrefix(prefix)`
+- `inspectIndexedDBPrefix(prefix)`
+- `persistVaultRecordLocally()` always throws to prevent accidental plaintext persistence
+
+Namespace inspection does not inspect record contents. Treat `"unavailable"` as a failed security
+check. `assertNoDecryptedVaultInLocalStorage` and `assertNoDecryptedVaultInIndexedDB` are deprecated
+boolean aliases that fail closed.
+
+### Browser UX and passkey helpers
+
+- `buildPrfSaltBytes(prefix, userId)`
+- `createRecoveryKitDownload(content, filename)`
+- `printRecoveryKitContent(content)`
+- `extractPasskeyPrfOutput`, `isPasskeySupported`, `isPrfExtensionSupported`
+- `createRecoveryKitText`, `buildRecoveryKitContent`
+
+## React: `@tgoliveira/vault-core/react`
+
+- `VaultSessionProvider` / `VaultSessionProviderProps`
+- `useVaultSession(options)` / `UseVaultSessionOptions`
+- `useVaultUnlocked()` / `useVaultLockState()`
+- `resolveVaultClientStatus(status, unlocked, prfSupported)`
+- `useVaultClientStatus(serverStatus, prfSupported)`
+- `VaultClientStatus` / `VaultServerStatusSnapshot`
+
+Provider and session hook guard options are `registerActivityGuard` and `registerUnloadGuard`, both
+defaulting to `true`.
+
+## Testing: `@tgoliveira/vault-core/testing`
+
+This entry exports the plaintext validation functions, forbidden field list, `ALL_SENTINELS`, and all
+named `SENTINEL_*` values. Use it in network, persistence, logging, and fixture tests. It does not
+export internal LiqSense compatibility fixtures.

package/ARCHITECTURE.md

@@ -13,6 +13,8 @@
 | Passkey PRF | PRF output → AES key | UVK |
 
 Envelope AAD field: `vault_key` with app `aadContextEnvelope`.
+Persisted envelopes are validated as a method-discriminated union, so password and recovery
+envelopes require Argon2id metadata while passkey PRF envelopes require `null` KDF metadata.
 
 ## Encrypted payload
 
@@ -30,3 +32,6 @@ Format: `enc-v1` / `AES-GCM` / `kdf-v1`.
 ```
 
 Apps own: persistence, routes, product UI, product payload schema, WebAuthn ceremony.
+
+Browser and React session layers keep the UVK in memory, renew auto-lock on activity, and clear it on
+lock or `pagehide`. Direct key mutation is not part of the public browser entry.

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Because the package is pre-1.0, breaking
+API changes increment the minor version.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-19
+
+### Added
+
+- Per-file coverage enforcement at 90% for statements, branches, functions, and lines.
+- Method-specific Zod schemas for password, recovery phrase, and passkey PRF envelopes.
+- Explicit `clear`, `found`, and `unavailable` storage namespace inspection results.
+- Automatic browser activity tracking for React session hooks and providers.
+- Complete implementation, adoption, security, and release documentation for humans and agents.
+- Continuous validation for pull requests and pushes, including the per-file coverage gate.
+- Manually dispatched npm publication with changelog-based automatic versioning, provenance, release
+  commits, generated Git tags, and GitHub release notes.
+
+### Changed
+
+- **Breaking:** high-level payload decrypt and envelope unlock APIs now require the expected AAD
+  scope and crypto profile.
+- **Breaking:** direct session-key mutation helpers are no longer exported from the browser entry.
+- **Breaking:** recovery word confirmation now requires every expected answer.
+- Deprecated boolean storage checks now fail closed when inspection is unavailable.
+- The published package now includes the complete `docs` directory and this changelog.
+
+### Security
+
+- Plaintext request guards now inspect nested objects and arrays with cycle protection.
+- Persisted Argon2id parameters, salt sizes, and hash length are bounded before derivation.
+- High-level decrypt and unlock operations reject AAD belonging to another user, resource, field,
+  or application context.
+- Envelope schemas reject invalid method and KDF metadata combinations.
+
+## [0.1.1] - 2026-06-18
+
+### Added
+
+- Initial public release of `@tgoliveira/vault-core`.
+- AES-GCM payload encryption with canonical AAD.
+- Password and BIP39 recovery phrase envelopes using Argon2id.
+- Passkey PRF envelope primitives.
+- Browser in-memory session and React integration helpers.
+- Plaintext rejection and sentinel-based testing utilities.
+- LiqSense compatibility fixtures and migration aliases.

package/MIGRATION_FROM_LIQSENSE.md

@@ -17,11 +17,13 @@ export const LIQSENSE_PRF_SALT_PREFIX = "liqsense-passkey-prf-v1:";
 | --- | --- |
 | `generateUserVaultKey` | `createUserVaultKey` |
 | `wrapVaultKeyForPassword` | `createPasswordEnvelope` + profile |
-| `unwrapVaultKeyFromPassword` | `unlockWithPasswordEnvelope` |
+| `unwrapVaultKeyFromPassword` | `unlockWithPasswordEnvelope(password, envelope, expectedScope, profile)` |
 | `wrapVaultKeyForRecoveryPhrase` | `createRecoveryEnvelope` + profile |
 | `generateRecoveryPhrase` | `createRecoveryPhrase` |
 
 LiqSense keeps thin wrappers in `src/modules/vault/core/` binding `LIQSENSE_VAULT_PROFILE`.
+High-level decrypt and unlock calls must also bind the expected scope so authenticated AAD cannot be
+replayed under another user or resource.
 
 ## Local dev
 

package/PASSKEY_PRF_ENVELOPES.md

@@ -3,7 +3,8 @@
 - Separate from account passkey login
 - App provides PRF output bytes (≥ 32 bytes) from WebAuthn ceremony
 - Package wraps UVK with PRF-derived AES key
-- API: `createPasskeyPrfEnvelope` / `unlockWithPasskeyPrfEnvelope`
+- API: `createPasskeyPrfEnvelope(vaultKey, prfOutput, scope, profile)` / `unlockWithPasskeyPrfEnvelope(envelope, prfOutput, expectedScope, profile)`
+- Unlock rejects envelopes whose authenticated AAD does not match the expected scope and profile
 - Browser helpers: `buildPrfSaltBytes(prefix, userId)`, capability probes
 
 PRF output never sent to server. WebAuthn ceremony stays in the app.

package/PASSWORD_ENVELOPES.md

@@ -2,6 +2,8 @@
 
 - Vault password normalized with NFKC before Argon2id
 - Default params: memory 65536 KiB, iterations 3, parallelism 1, 32-byte hash, 16-byte salt
-- API: `createPasswordEnvelope` / `unlockWithPasswordEnvelope`
+- Persisted Argon2id parameters are bounded before derivation to prevent client-side resource exhaustion
+- API: `createPasswordEnvelope(vaultKey, password, scope, profile)` / `unlockWithPasswordEnvelope(password, envelope, expectedScope, profile)`
+- Unlock rejects envelopes whose authenticated AAD does not match the expected scope and profile
 
 Vault password never sent to server.

package/README.md

@@ -29,6 +29,26 @@ Build vault-core before consuming:
 cd ../vault-core && npm run validate
 ```
 
+## Testing
+
+```bash
+npm test
+npm run test:coverage
+```
+
+Coverage is enforced per production file at 90% for statements, branches, functions, and lines.
+`npm run validate` includes the coverage gate.
+
+## Documentation
+
+- [Complete implementation guide](docs/IMPLEMENTATION_GUIDE.md)
+- [Documentation index](docs/README.md)
+- [API reference](API_REFERENCE.md)
+- [Security model](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+- [Release process](docs/RELEASING.md)
+- [Agent and contributor guide](AGENTS.md)
+
 ## Quick start
 
 ```ts
@@ -57,14 +77,33 @@ const { envelope } = await createPasswordEnvelope(
   scope,
   profile
 );
+
+const encryptedPayload = await encryptVaultPayload(
+  { version: 1, entries: [] },
+  vaultKey,
+  scope,
+  profile
+);
+
+const unlockedKey = await unlockWithPasswordEnvelope(
+  userVaultPassword,
+  envelope,
+  scope,
+  profile
+);
+
+const payload = await decryptVaultPayload(encryptedPayload, unlockedKey, scope, profile);
 ```
 
+High-level decrypt and unlock APIs require the expected scope and profile. This binds authenticated
+AAD to the user, resource, field, and application context expected by the caller.
+
 ## Exports
 
 | Entry | Purpose |
 | --- | --- |
 | `@tgoliveira/vault-core` | Core crypto, envelopes, payload, validation |
-| `@tgoliveira/vault-core/browser` | In-memory session, auto-lock, PRF salt, recovery kit DOM helpers |
+| `@tgoliveira/vault-core/browser` | In-memory session, activity-aware auto-lock, storage inspection, PRF salt, recovery kit DOM helpers |
 | `@tgoliveira/vault-core/testing` | Sentinels and plaintext scan helpers |
 | `@tgoliveira/vault-core/react` | Headless React session/status hooks (optional peer: `react`) |
 
@@ -74,5 +113,6 @@ const { envelope } = await createPasswordEnvelope(
 - Does **not** require React, Next.js, or product payload schemas on the default entry
 - `./react` is optional and requires `react >= 18`
 - Vault password, recovery phrase, UVK, PRF output, and decrypted payload must stay client-side
+- Persisted envelope schemas enforce method-specific KDF metadata at runtime
 
-See `SECURITY.md`, `ARCHITECTURE.md`, and `MIGRATION_FROM_LIQSENSE.md`.
+See `SECURITY.md`, `ARCHITECTURE.md`, `MIGRATION_FROM_LIQSENSE.md`, and [`docs/ADOPTING_VAULT_CORE_IN_EXISTING_APPS.md`](docs/ADOPTING_VAULT_CORE_IN_EXISTING_APPS.md) for migrating other apps (including [letter-to-god](https://github.com/tgoliveira11/letter-to-god)).

package/RECOVERY_PHRASE.md

@@ -3,7 +3,8 @@
 - BIP39 English wordlist via `@scure/bip39`
 - Supported lengths: **12 words** (128-bit) and **24 words** (256-bit, default)
 - Normalization: trim, lowercase, single-space separated
-- Confirmation helpers: deterministic word indices (3 for 12 words, 4 for 24)
+- Confirmation helpers: deterministic word indices (3 for 12 words, 4 for 24); every requested answer is required
 - Recovery kit text via `createRecoveryKitText({ productName, ... })`
+- Envelope unlock requires the expected scope and profile and validates authenticated AAD before KDF work
 
 Recovery phrase never sent to server.

package/SECURITY.md

@@ -14,18 +14,38 @@ Vault unlock requires a separate vault password, recovery phrase, or passkey PRF
 - PRF output
 - Decrypted vault payload
 
-Use `assertNoVaultPlaintextFields()` on API request bodies.
+Use `assertNoVaultPlaintextFields()` on API request bodies. The guard recursively checks nested
+objects and arrays and safely handles cyclic in-memory objects.
 
 ## Client must never persist
 
 - Decrypted vault payload in localStorage or IndexedDB
 
-Browser session helpers clear UVK on lock and `pagehide`.
+Browser session helpers clear UVK on lock and `pagehide`. React session helpers also renew the
+inactivity timer on pointer, keyboard, touch, and focus activity by default. Public browser exports
+do not expose direct session-key setters; use `unlockVaultSession()` and `lockVaultSession()` so
+timers and subscribers remain consistent.
+
+`inspectLocalStoragePrefix()` and `inspectIndexedDBPrefix()` are namespace inspections, not content
+scanners. They return `"unavailable"` when inspection is blocked or unsupported. Treat that result
+as a failed security check. IndexedDB inspection checks database names and cannot prove that records
+inside an unrelated database contain no plaintext.
 
 ## Crypto constants (per app profile)
 
 Apps define `VaultCryptoProfile` with stable AAD contexts. Existing ciphertext breaks if contexts change.
 
+High-level decrypt and envelope-unlock APIs require the expected scope and profile. They reject a
+valid ciphertext when its authenticated AAD belongs to a different user, resource, field, or app
+context. Treat `decryptField()` as a low-level compatibility primitive: callers that use it directly
+must validate the expected AAD separately.
+
+## Untrusted persisted data
+
+Treat encrypted payloads, envelopes, AAD, and KDF metadata loaded from a server or local storage as
+untrusted. Argon2id metadata is bounded before derivation to prevent excessive client memory or CPU
+consumption. Do not bypass the high-level APIs or their runtime validation for persisted data.
+
 ## Logging
 
 Never log vault secrets, request bodies containing envelopes, or decrypted payloads.

package/dist/browser.d.ts

@@ -2,10 +2,21 @@ import { extractPasskeyPrfOutput, isPasskeySupported, isPrfExtensionSupported }
 export declare function buildPrfSaltBytes(prefix: string, userId: string): Promise<ArrayBuffer>;
 export declare function createRecoveryKitDownload(content: string, filename: string): void;
 export declare function printRecoveryKitContent(content: string): void;
+export type VaultStorageInspectionResult = "clear" | "found" | "unavailable";
+export declare function inspectLocalStoragePrefix(storagePrefix: string): VaultStorageInspectionResult;
+export declare function inspectIndexedDBPrefix(storagePrefix: string): Promise<VaultStorageInspectionResult>;
+/**
+ * @deprecated This is a namespace-level, fail-closed check. Use inspectLocalStoragePrefix
+ * and handle all three result states explicitly.
+ */
 export declare function assertNoDecryptedVaultInLocalStorage(storagePrefix: string): boolean;
+/**
+ * @deprecated This checks database names, not record contents. Use inspectIndexedDBPrefix
+ * and handle all three result states explicitly.
+ */
 export declare function assertNoDecryptedVaultInIndexedDB(storagePrefix: string): Promise<boolean>;
 export declare function persistVaultRecordLocally(): never;
 export { extractPasskeyPrfOutput, isPasskeySupported, isPrfExtensionSupported, };
-export { configureVaultSession, subscribeVaultSession, isVaultManuallyLocked, clearVaultAutoLockTimer, scheduleVaultAutoLock, touchVaultSession, unlockVaultSession, lockVaultSession, lockVaultSessionManually, resetVaultSessionLockState, registerVaultUnloadGuard, getVaultAutoLockRemainingMs, getSessionVaultKey, setSessionVaultKey, lockVault, isVaultUnlocked, clearVaultClientState, type VaultSessionConfig, } from "./session/auto-lock.js";
+export { configureVaultSession, subscribeVaultSession, isVaultManuallyLocked, clearVaultAutoLockTimer, scheduleVaultAutoLock, touchVaultSession, unlockVaultSession, lockVaultSession, lockVaultSessionManually, resetVaultSessionLockState, registerVaultUnloadGuard, registerVaultActivityGuard, getVaultAutoLockRemainingMs, getSessionVaultKey, isVaultUnlocked, type VaultSessionConfig, } from "./session/auto-lock.js";
 export { createRecoveryKitText, buildRecoveryKitContent } from "./recovery/kit.js";
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAG5F;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,IAAI,CASN;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAU7D;AASD,wBAAgB,oCAAoC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAWnF;AAED,wBAAsB,iCAAiC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB/F;AAED,wBAAgB,yBAAyB,IAAI,KAAK,CAEjD;AAED,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,GACxB,CAAC;AAEF,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,2BAA2B,EAC3B,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAG5F;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,IAAI,CASN;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAU7D;AASD,MAAM,MAAM,4BAA4B,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAE7E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,4BAA4B,CAiB9B;AAED,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,4BAA4B,CAAC,CAwBvC;AAED;;;GAGG;AACH,wBAAgB,oCAAoC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;;GAGG;AACH,wBAAsB,iCAAiC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/F;AAED,wBAAgB,yBAAyB,IAAI,KAAK,CAEjD;AAED,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,GACxB,CAAC;AAEF,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/browser.js

@@ -32,40 +32,68 @@ function escapeHtml(value) {
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
 }
-export function assertNoDecryptedVaultInLocalStorage(storagePrefix) {
-    if (typeof window === "undefined")
-        return true;
-    for (let i = 0; i < localStorage.length; i++) {
-        const key = localStorage.key(i);
-        if (!key)
-            continue;
-        if (key.startsWith(storagePrefix)) {
-            return false;
+export function inspectLocalStoragePrefix(storagePrefix) {
+    if (typeof window === "undefined" || typeof localStorage === "undefined") {
+        return "unavailable";
+    }
+    try {
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (!key)
+                continue;
+            if (key.startsWith(storagePrefix)) {
+                return "found";
+            }
         }
+        return "clear";
+    }
+    catch {
+        return "unavailable";
     }
-    return true;
 }
-export async function assertNoDecryptedVaultInIndexedDB(storagePrefix) {
-    if (typeof window === "undefined" || typeof indexedDB === "undefined")
-        return true;
+export async function inspectIndexedDBPrefix(storagePrefix) {
+    if (typeof window === "undefined" || typeof indexedDB === "undefined") {
+        return "unavailable";
+    }
     return new Promise((resolve) => {
-        const request = indexedDB.databases?.();
+        let request;
+        try {
+            request = indexedDB.databases?.();
+        }
+        catch {
+            resolve("unavailable");
+            return;
+        }
         if (!request) {
-            resolve(true);
+            resolve("unavailable");
             return;
         }
         void request
             .then((databases) => {
             const hasVaultDb = databases.some((db) => db.name?.startsWith(storagePrefix));
-            resolve(!hasVaultDb);
+            resolve(hasVaultDb ? "found" : "clear");
         })
-            .catch(() => resolve(true));
+            .catch(() => resolve("unavailable"));
     });
 }
+/**
+ * @deprecated This is a namespace-level, fail-closed check. Use inspectLocalStoragePrefix
+ * and handle all three result states explicitly.
+ */
+export function assertNoDecryptedVaultInLocalStorage(storagePrefix) {
+    return inspectLocalStoragePrefix(storagePrefix) === "clear";
+}
+/**
+ * @deprecated This checks database names, not record contents. Use inspectIndexedDBPrefix
+ * and handle all three result states explicitly.
+ */
+export async function assertNoDecryptedVaultInIndexedDB(storagePrefix) {
+    return (await inspectIndexedDBPrefix(storagePrefix)) === "clear";
+}
 export function persistVaultRecordLocally() {
     throw new Error("Decrypted vault state must not be persisted to localStorage or IndexedDB");
 }
 export { extractPasskeyPrfOutput, isPasskeySupported, isPrfExtensionSupported, };
-export { configureVaultSession, subscribeVaultSession, isVaultManuallyLocked, clearVaultAutoLockTimer, scheduleVaultAutoLock, touchVaultSession, unlockVaultSession, lockVaultSession, lockVaultSessionManually, resetVaultSessionLockState, registerVaultUnloadGuard, getVaultAutoLockRemainingMs, getSessionVaultKey, setSessionVaultKey, lockVault, isVaultUnlocked, clearVaultClientState, } from "./session/auto-lock.js";
+export { configureVaultSession, subscribeVaultSession, isVaultManuallyLocked, clearVaultAutoLockTimer, scheduleVaultAutoLock, touchVaultSession, unlockVaultSession, lockVaultSession, lockVaultSessionManually, resetVaultSessionLockState, registerVaultUnloadGuard, registerVaultActivityGuard, getVaultAutoLockRemainingMs, getSessionVaultKey, isVaultUnlocked, } from "./session/auto-lock.js";
 export { createRecoveryKitText, buildRecoveryKitContent } from "./recovery/kit.js";
 //# sourceMappingURL=browser.js.map