@tgoliveira/vault-core 0.1.1 → 0.2.0

package/docs/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,577 @@
+# Complete Implementation Guide
+
+This guide is the end-to-end consumer contract for `@tgoliveira/vault-core`. It is written so a
+developer or coding agent can implement the package without reading its source code.
+
+## 1. What the package owns
+
+The package owns:
+
+- Generation and import/export of the 256-bit User Vault Key (UVK).
+- AES-GCM encryption of generic JSON payloads with authenticated context.
+- Password and recovery phrase envelopes using bounded Argon2id.
+- Passkey PRF envelopes when the application provides WebAuthn PRF output bytes.
+- BIP39 English recovery phrase generation, validation, confirmation, and recovery kit text.
+- Runtime schemas for encrypted payloads and stored envelopes.
+- Browser-only in-memory session, inactivity lock, storage namespace inspection, and recovery kit UI
+  helpers.
+- Optional React session and status helpers.
+- Plaintext leak guards and testing sentinels.
+
+The consuming application owns:
+
+- Account authentication and authorization.
+- API routes, database schemas, persistence, rate limiting, and audit logging.
+- The product-specific plaintext payload schema and migrations.
+- WebAuthn registration and authentication ceremonies.
+- UI, password policy, recovery education, and destructive recovery decisions.
+
+Account login must never unlock the vault. Account password reset must never replace vault recovery.
+
+## 2. Requirements and installation
+
+- Node.js 20 or newer for build, SSR, and tests.
+- Web Crypto (`globalThis.crypto.subtle`) in the runtime performing encryption.
+- React 18 or newer only when using `@tgoliveira/vault-core/react`.
+
+```bash
+npm install @tgoliveira/vault-core
+```
+
+Use only documented package entry points:
+
+```ts
+import { createUserVaultKey } from "@tgoliveira/vault-core";
+import { unlockVaultSession } from "@tgoliveira/vault-core/browser";
+import { VaultSessionProvider } from "@tgoliveira/vault-core/react";
+import { SENTINEL_VAULT_PASSWORD } from "@tgoliveira/vault-core/testing";
+```
+
+Do not import internal `dist/*` files. They are not stable public APIs.
+
+## 3. Freeze the application crypto profile
+
+Choose profile strings once, before production data exists:
+
+```ts
+import type { VaultCryptoProfile } from "@tgoliveira/vault-core";
+
+export const VAULT_PROFILE: VaultCryptoProfile = {
+  cryptoVersion: "vault-v1",
+  aadContextVault: "acme:vault:v1",
+  aadContextEnvelope: "acme:vault-envelope:v1",
+};
+
+export function vaultScope(userId: string) {
+  return { userId, resourceId: userId };
+}
+```
+
+Both identifiers must be UUID strings when data is validated by `encryptedPayloadSchema`. A profile
+change makes existing high-level decrypt and unlock operations fail by design. Treat profile strings
+as persisted protocol constants, not environment labels.
+
+For multi-resource vaults, use the authenticated resource identifier as `resourceId`. Always pass the
+same expected scope back during decrypt or unlock.
+
+## 4. Persisted data model
+
+A minimal server record contains only encrypted structures and non-secret status metadata:
+
+```ts
+import type {
+  EncryptedVaultPayload,
+  PasskeyPrfEnvelope,
+  PasswordEnvelope,
+  RecoveryPhraseEnvelope,
+} from "@tgoliveira/vault-core";
+
+export type StoredVaultRecord = {
+  cryptoVersion: "vault-v1";
+  encryptedBlob: EncryptedVaultPayload;
+  passwordEnvelope: PasswordEnvelope;
+  recoveryEnvelope: RecoveryPhraseEnvelope;
+  passkeyPrfEnvelope?: PasskeyPrfEnvelope | null;
+};
+```
+
+The server may store these structures because ciphertext, IV, salt, bounded KDF metadata, and AAD are
+not plaintext secrets. The server must never receive the vault password, recovery phrase, UVK, PRF
+output, or decrypted payload.
+
+Validate records at every untrusted boundary:
+
+```ts
+import { vaultSetupEnvelopeFieldsSchema } from "@tgoliveira/vault-core";
+
+const record = vaultSetupEnvelopeFieldsSchema.parse(untrustedDatabaseValue);
+```
+
+The envelope schemas are discriminated by `method`. Password and recovery envelopes require
+Argon2id metadata; passkey PRF envelopes require `kdfMetadata: null`.
+
+## 5. Initial vault setup
+
+Run the complete setup flow in a trusted client runtime:
+
+```ts
+import {
+  createPasskeyPrfEnvelope,
+  createPasswordEnvelope,
+  createRecoveryEnvelope,
+  createRecoveryPhrase,
+  createUserVaultKey,
+  encryptVaultPayload,
+  vaultSetupEnvelopeFieldsSchema,
+} from "@tgoliveira/vault-core";
+import { VAULT_PROFILE, vaultScope } from "./vault-profile.js";
+
+export async function createInitialVault<T>(input: {
+  userId: string;
+  vaultPassword: string;
+  initialPayload: T;
+  passkeyPrfOutput?: Uint8Array;
+}) {
+  const scope = vaultScope(input.userId);
+  const vaultKey = await createUserVaultKey();
+  const recoveryPhrase = createRecoveryPhrase({ wordCount: 24 });
+
+  const { envelope: passwordEnvelope } = await createPasswordEnvelope(
+    vaultKey,
+    input.vaultPassword,
+    scope,
+    VAULT_PROFILE
+  );
+
+  const { envelope: recoveryEnvelope } = await createRecoveryEnvelope(
+    vaultKey,
+    recoveryPhrase,
+    scope,
+    VAULT_PROFILE,
+    { phraseLength: 24 }
+  );
+
+  const passkeyPrfEnvelope = input.passkeyPrfOutput
+    ? await createPasskeyPrfEnvelope(
+        vaultKey,
+        input.passkeyPrfOutput,
+        scope,
+        VAULT_PROFILE
+      )
+    : null;
+
+  const encryptedBlob = await encryptVaultPayload(
+    input.initialPayload,
+    vaultKey,
+    scope,
+    VAULT_PROFILE
+  );
+
+  const serverRecord = vaultSetupEnvelopeFieldsSchema.parse({
+    cryptoVersion: "vault-v1",
+    encryptedBlob,
+    passwordEnvelope,
+    recoveryEnvelope,
+    passkeyPrfEnvelope,
+  });
+
+  return {
+    serverRecord,
+    recoveryPhrase,
+    clientOnlyVaultKey: vaultKey,
+  };
+}
+```
+
+Send only `serverRecord` to the server. Keep `recoveryPhrase` in the recovery confirmation UI and
+`clientOnlyVaultKey` in the in-memory session. Never serialize either value into analytics, logs,
+URLs, cookies, localStorage, IndexedDB, server actions, or API requests.
+
+Argon2id work is deliberately sequential in this example to avoid doubling peak browser memory.
+
+## 6. Recovery phrase confirmation and kit
+
+Generate the required confirmation prompts and reject partial answers:
+
+```ts
+import {
+  assertRecoveryPhraseWordConfirmation,
+  createRecoveryKitText,
+  getRecoveryConfirmationPromptCount,
+  pickRecoveryConfirmationIndices,
+} from "@tgoliveira/vault-core";
+
+const words = recoveryPhrase.split(" ");
+const count = getRecoveryConfirmationPromptCount(24);
+const requiredIndices = pickRecoveryConfirmationIndices(words.length, count);
+
+assertRecoveryPhraseWordConfirmation(
+  recoveryPhrase,
+  answersByOneBasedIndex,
+  requiredIndices
+);
+
+const recoveryKit = createRecoveryKitText({
+  recoveryPhrase,
+  wordCount: 24,
+  productName: "Acme",
+});
+```
+
+In a browser, `createRecoveryKitDownload()` and `printRecoveryKitContent()` are available from the
+browser entry. Explain that anyone holding the phrase can unlock the vault. Do not automatically save
+the kit to cloud storage.
+
+## 7. Password unlock
+
+```ts
+import {
+  decryptVaultPayload,
+  encryptedPayloadSchema,
+  passwordEnvelopeSchema,
+  unlockWithPasswordEnvelope,
+} from "@tgoliveira/vault-core";
+import { VAULT_PROFILE, vaultScope } from "./vault-profile.js";
+
+export async function unlockWithPassword<T>(input: {
+  userId: string;
+  vaultPassword: string;
+  passwordEnvelope: unknown;
+  encryptedBlob: unknown;
+}) {
+  const scope = vaultScope(input.userId);
+  const envelope = passwordEnvelopeSchema.parse(input.passwordEnvelope);
+  const encryptedBlob = encryptedPayloadSchema.parse(input.encryptedBlob);
+  const vaultKey = await unlockWithPasswordEnvelope(
+    input.vaultPassword,
+    envelope,
+    scope,
+    VAULT_PROFILE
+  );
+  const payload = await decryptVaultPayload<T>(
+    encryptedBlob,
+    vaultKey,
+    scope,
+    VAULT_PROFILE
+  );
+  return { vaultKey, payload };
+}
+```
+
+Do not expose whether a password failed during KDF derivation versus AES-GCM authentication. Present
+a generic unlock failure to the user. UI throttling can improve local UX but cannot prevent offline
+attacks against copied envelopes, so require a strong vault password and protect ciphertext access.
+
+## 8. Recovery phrase unlock
+
+```ts
+import {
+  decryptVaultPayload,
+  encryptedPayloadSchema,
+  parseRecoveryPhraseWordCount,
+  recoveryPhraseEnvelopeSchema,
+  unlockWithRecoveryEnvelope,
+} from "@tgoliveira/vault-core";
+
+const envelope = recoveryPhraseEnvelopeSchema.parse(serverRecord.recoveryEnvelope);
+const expectedWordCount = parseRecoveryPhraseWordCount(envelope.publicMetadata);
+const vaultKey = await unlockWithRecoveryEnvelope(
+  enteredRecoveryPhrase,
+  envelope,
+  vaultScope(userId),
+  VAULT_PROFILE,
+  { expectedWordCount }
+);
+const payload = await decryptVaultPayload(
+  encryptedPayloadSchema.parse(serverRecord.encryptedBlob),
+  vaultKey,
+  vaultScope(userId),
+  VAULT_PROFILE
+);
+```
+
+After successful recovery, let the user create a new password envelope around the same UVK and
+replace the old password envelope atomically on the server.
+
+## 9. Passkey PRF integration
+
+The package does not run WebAuthn ceremonies. The application must request the PRF extension and pass
+the first PRF result to vault-core.
+
+Use a stable, application-specific PRF salt:
+
+```ts
+import {
+  buildPrfSaltBytes,
+  extractPasskeyPrfOutput,
+  isPasskeySupported,
+  isPrfExtensionSupported,
+} from "@tgoliveira/vault-core/browser";
+
+const salt = await buildPrfSaltBytes("acme-passkey-prf-v1:", userId);
+
+if (!isPasskeySupported() || !isPrfExtensionSupported()) {
+  // Offer password or recovery phrase unlock instead.
+}
+
+const credential = await navigator.credentials.get({
+  publicKey: {
+    ...applicationOwnedRequestOptions,
+    extensions: { prf: { eval: { first: salt } } },
+  },
+});
+
+if (!(credential instanceof PublicKeyCredential)) {
+  throw new Error("Passkey ceremony did not return a public-key credential");
+}
+
+const prfOutput = extractPasskeyPrfOutput(
+  credential.getClientExtensionResults()
+);
+```
+
+Exact WebAuthn option typing and credential verification belong to the application. Never send
+`prfOutput` to the server.
+
+Unlock after obtaining the PRF output:
+
+```ts
+import {
+  passkeyPrfEnvelopeSchema,
+  unlockWithPasskeyPrfEnvelope,
+} from "@tgoliveira/vault-core";
+
+const envelope = passkeyPrfEnvelopeSchema.parse(serverRecord.passkeyPrfEnvelope);
+const vaultKey = await unlockWithPasskeyPrfEnvelope(
+  envelope,
+  prfOutput,
+  vaultScope(userId),
+  VAULT_PROFILE
+);
+```
+
+Treat PRF support as an optional unlock method. Always preserve password or recovery fallback.
+
+## 10. Save and update encrypted payloads
+
+Keep the typed product schema in the application:
+
+```ts
+import { z } from "zod";
+import { encryptVaultPayload } from "@tgoliveira/vault-core";
+
+const appVaultPayloadSchema = z.object({
+  version: z.literal(1),
+  entries: z.array(z.object({ id: z.string(), secret: z.string() })),
+});
+
+const validatedPayload = appVaultPayloadSchema.parse(nextPayload);
+const encryptedBlob = await encryptVaultPayload(
+  validatedPayload,
+  inMemoryVaultKey,
+  vaultScope(userId),
+  VAULT_PROFILE
+);
+```
+
+Persist only `encryptedBlob`. Use application-owned optimistic concurrency or record versions to
+prevent lost updates and ciphertext rollback. Vault-core authenticates content and AAD but does not
+provide server freshness or synchronization.
+
+## 11. Browser session without React
+
+```ts
+import {
+  configureVaultSession,
+  getSessionVaultKey,
+  lockVaultSession,
+  registerVaultActivityGuard,
+  registerVaultUnloadGuard,
+  unlockVaultSession,
+} from "@tgoliveira/vault-core/browser";
+
+configureVaultSession({ autoLockMinutes: 15 });
+
+const removeActivityGuard = registerVaultActivityGuard();
+const removeUnloadGuard = registerVaultUnloadGuard();
+
+unlockVaultSession(vaultKey);
+const currentKey = getSessionVaultKey();
+
+// On explicit lock or logout:
+lockVaultSession();
+
+// On application teardown:
+removeActivityGuard();
+removeUnloadGuard();
+```
+
+There is no public direct key setter. This ensures unlock, lock, timers, and subscribers remain in
+sync. Call `touchVaultSession()` manually only for meaningful activity not represented by the default
+pointer, keyboard, touch, or focus events.
+
+## 12. React session integration
+
+Mount one provider near the client application root:
+
+```tsx
+import type { ReactNode } from "react";
+import { VaultSessionProvider } from "@tgoliveira/vault-core/react";
+
+export function AppProviders({ children }: { children: ReactNode }) {
+  return (
+    <VaultSessionProvider
+      sessionConfig={{ autoLockMinutes: 15 }}
+      registerActivityGuard
+      registerUnloadGuard
+    >
+      {children}
+    </VaultSessionProvider>
+  );
+}
+```
+
+Read and control state:
+
+```tsx
+import {
+  useVaultClientStatus,
+  useVaultSession,
+  useVaultUnlocked,
+} from "@tgoliveira/vault-core/react";
+
+const unlocked = useVaultUnlocked();
+const { lock, touch } = useVaultSession({
+  registerActivityGuard: false,
+  registerUnloadGuard: false,
+});
+const status = useVaultClientStatus(serverStatus, browserSupportsPrf);
+```
+
+Avoid mounting both `VaultSessionProvider` and a default `useVaultSession()` solely to register the
+same guards. When the provider owns guards, use the hook with guard registration disabled or call the
+browser lifecycle functions directly.
+
+## 13. Storage policy and inspection
+
+Do not persist decrypted payloads or the UVK. Storage helpers inspect namespace presence; they cannot
+classify arbitrary record contents:
+
+```ts
+import {
+  inspectIndexedDBPrefix,
+  inspectLocalStoragePrefix,
+} from "@tgoliveira/vault-core/browser";
+
+const localResult = inspectLocalStoragePrefix("acme:vault:");
+const idbResult = await inspectIndexedDBPrefix("acme-vault-");
+
+if (localResult !== "clear" || idbResult !== "clear") {
+  // Investigate "found" and treat "unavailable" as a failed security check.
+}
+```
+
+`inspectIndexedDBPrefix()` checks database names, not object-store contents. Enforce the real no-
+plaintext rule through architecture, code review, CSP/XSS controls, and sentinel-based integration
+tests.
+
+## 14. Server request validation
+
+Reject known plaintext fields recursively before accepting an encrypted vault request:
+
+```ts
+import {
+  assertNoVaultPlaintextFields,
+  vaultSetupEnvelopeFieldsSchema,
+} from "@tgoliveira/vault-core";
+
+export function parseVaultSetupRequest(body: unknown) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error("Vault request body must be an object");
+  }
+  assertNoVaultPlaintextFields(body as Record<string, unknown>);
+  return vaultSetupEnvelopeFieldsSchema.parse(body);
+}
+```
+
+This guard is defense in depth, not a complete data-loss-prevention system. Use closed route schemas,
+never log request bodies, and verify the authenticated account owns the AAD `userId` and resource.
+
+## 15. Password and recovery rotation
+
+To change a vault password:
+
+1. Unlock the existing envelope and obtain the UVK in memory.
+2. Call `createPasswordEnvelope()` with the new password, same expected scope, and same profile.
+3. Atomically replace only the password envelope on the server.
+4. Keep the encrypted payload and other envelopes unchanged.
+
+To rotate a recovery phrase, generate a new phrase and recovery envelope around the same UVK. Require
+confirmation and replace the old recovery envelope atomically. Deleting an envelope is an application
+authorization decision.
+
+## 16. Error handling
+
+Expected domain errors include:
+
+- `VaultPlaintextRejectionError`
+- `PasskeyPrfRequiredError`
+- `PasskeyUnlockError`
+- `RecoveryPhraseConfirmationError`
+- `VaultConflictError`
+- `VaultNotFoundError`
+
+Web Crypto, JSON parsing, Zod, and Argon2id validation may also throw standard errors. Convert detailed
+internal failures into generic user-facing unlock messages. Never include entered secrets, decrypted
+data, PRF bytes, or full encrypted request bodies in logs.
+
+## 17. Testing a consuming application
+
+Use the testing entry to prove plaintext never crosses persistence or network boundaries:
+
+```ts
+import {
+  SENTINEL_PRIVATE_NOTE,
+  SENTINEL_VAULT_PASSWORD,
+  validateNoPlaintextLeak,
+} from "@tgoliveira/vault-core/testing";
+
+const result = validateNoPlaintextLeak(capturedRequestBody);
+expect(result.ok).toBe(true);
+```
+
+Required integration tests:
+
+- Password, recovery, and passkey round trips.
+- Wrong password, wrong phrase, missing PRF, tampered ciphertext, and wrong expected AAD.
+- API bodies contain no password, phrase, UVK, PRF output, or product plaintext sentinels.
+- localStorage and IndexedDB contain no decrypted vault state.
+- Auto-lock clears the in-memory key and updates subscribed UI.
+- Stored legacy fixtures still decrypt through the documented migration path.
+
+## 18. Legacy ciphertext
+
+High-level APIs require the configured AAD context. For a legacy record with missing context:
+
+1. Use `decryptField()` only inside an explicit migration path.
+2. Validate every available AAD field against the authenticated user and resource.
+3. Parse and validate the decrypted product payload.
+4. Re-encrypt immediately with `encryptVaultPayload()` and the frozen profile.
+5. Remove the compatibility path after migration completes.
+
+Never make missing AAD context a permanent high-level fallback.
+
+## 19. Production readiness checklist
+
+- [ ] Profile strings are unique, stable, documented, and frozen.
+- [ ] User and resource IDs passed to AAD match authenticated ownership.
+- [ ] Product payloads are validated before encryption and after decryption.
+- [ ] Server routes accept only runtime-validated encrypted structures.
+- [ ] Password, phrase, UVK, PRF output, and decrypted payload never reach the server or logs.
+- [ ] Decrypted data is absent from localStorage, IndexedDB, cookies, URLs, and analytics.
+- [ ] Password and recovery unlock remain available if passkey PRF is unsupported.
+- [ ] Recovery confirmation and offline storage education are implemented.
+- [ ] In-memory sessions auto-lock and clear on `pagehide`.
+- [ ] Rotation and recovery updates are atomic and authorization-protected.
+- [ ] Wrong-AAD, tamper, leak, storage, and auto-lock tests pass.
+- [ ] The application pins a compatible package version and reviews `CHANGELOG.md` before upgrades.

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation Index
+
+Use this page as the documentation router for `@tgoliveira/vault-core`.
+
+## Consumers
+
+- [`IMPLEMENTATION_GUIDE.md`](IMPLEMENTATION_GUIDE.md): complete greenfield implementation from
+  setup through password, recovery phrase, passkey PRF, persistence boundaries, and sessions.
+- [`ADOPTING_VAULT_CORE_IN_EXISTING_APPS.md`](ADOPTING_VAULT_CORE_IN_EXISTING_APPS.md): phased
+  migration for an application that already has vault code or stored ciphertext.
+- [`../API_REFERENCE.md`](../API_REFERENCE.md): public entry points and their security preconditions.
+- [`../SECURITY.md`](../SECURITY.md): threat model, secret boundaries, and storage rules.
+
+## Maintainers and agents
+
+- [`../AGENTS.md`](../AGENTS.md): repository operating rules and definition of done.
+- [`RELEASING.md`](RELEASING.md): versioning, changelog, tag, validation, and publication procedure.
+- [`../CHANGELOG.md`](../CHANGELOG.md): released and unreleased consumer-visible changes.
+- [`../ARCHITECTURE.md`](../ARCHITECTURE.md): package layers and cryptographic data flow.
+
+## Topic references
+
+- [`../PASSWORD_ENVELOPES.md`](../PASSWORD_ENVELOPES.md)
+- [`../RECOVERY_PHRASE.md`](../RECOVERY_PHRASE.md)
+- [`../PASSKEY_PRF_ENVELOPES.md`](../PASSKEY_PRF_ENVELOPES.md)
+- [`../MIGRATION_FROM_LIQSENSE.md`](../MIGRATION_FROM_LIQSENSE.md)
+
+If documentation and implementation disagree, treat the TypeScript declarations and runtime tests as
+the immediate source of truth, then fix the documentation in the same change.
+

package/docs/RELEASING.md

@@ -0,0 +1,102 @@
+# Release Process
+
+Releases are initiated manually, but version calculation, validation, npm publication, Git commit,
+Git tag, and GitHub release creation are automated. Do not create release tags manually.
+
+## Version policy
+
+This package follows Semantic Versioning. While the major version is `0`:
+
+- Patch releases contain backward-compatible fixes or documentation-only changes.
+- Minor releases contain new features or any breaking public API change.
+- After `1.0.0`, breaking changes increment the major version.
+
+Every consumer-visible change belongs under `CHANGELOG.md` → `Unreleased` in one of these sections:
+
+- `Added`
+- `Changed`
+- `Deprecated`
+- `Removed`
+- `Fixed`
+- `Security`
+
+Mark breaking changes with `**Breaking:**` and include a migration path.
+
+## One-time repository and npm setup
+
+1. Create a protected GitHub environment named `npmjs`.
+2. Add required reviewers to that environment if publication needs human approval.
+3. Allow the GitHub Actions bot to push the release commit and `vault-core-v*` tags to `main`, or
+   provide an equivalently scoped GitHub App token if branch protection forbids `GITHUB_TOKEN` pushes.
+4. In the npm package settings, configure a GitHub Actions trusted publisher with:
+   - Repository owner: the GitHub owner of this repository.
+   - Repository: `vault-core`.
+   - Workflow filename: `publish-vault-core.yml`.
+   - Environment: `npmjs`.
+   - Allowed action: `npm publish`.
+5. After one successful OIDC publication, remove the legacy `NPM_TOKEN` secret and disallow token
+   publishing in npm package settings. The workflow retains token fallback only for migration.
+
+Trusted publishing requires a GitHub-hosted runner, Node 22.14 or newer, npm 11.5.1 or newer, and
+`id-token: write`. The workflow uses Node 24 and verifies the npm version before continuing.
+
+## Start a release
+
+Use the GitHub Actions UI:
+
+1. Open **Actions** → **Publish package to npmjs**.
+2. Select **Run workflow** on `main`.
+3. Leave `version` blank for automatic versioning, or enter one of:
+   - An exact stable version such as `0.3.0`.
+   - `patch`, `minor`, or `major`.
+
+Equivalent GitHub CLI commands:
+
+```bash
+# Automatic version
+gh workflow run publish-vault-core.yml --ref main
+
+# Exact or explicit bump
+gh workflow run publish-vault-core.yml --ref main -f version=0.3.0
+gh workflow run publish-vault-core.yml --ref main -f version=patch
+```
+
+## Automatic version calculation
+
+When `version` is blank or `auto`, `scripts/prepare-release.mjs` reads the `Unreleased` changelog:
+
+1. Any `**Breaking:**` entry selects major, or minor while the current major version is `0`.
+2. Otherwise, at least one `Added` entry selects minor.
+3. Otherwise, the release selects patch.
+
+When `Unreleased` is empty, the workflow enters recovery mode for the current released version. It
+completes missing npm, tag, or GitHub release state without publishing a duplicate.
+
+## Publication gates and ordering
+
+The workflow serializes releases so two versions cannot publish concurrently. It then:
+
+1. Checks out `main` with full tag history.
+2. Installs the exact lockfile with `npm ci`.
+3. Runs `npm audit` at the `high` threshold, which also blocks critical vulnerabilities.
+4. Calculates the version and moves `Unreleased` entries to a dated release section.
+5. Runs typecheck, all tests, per-file coverage gates, and the production build.
+6. Builds one tarball that becomes the exact validated publication artifact.
+7. Rejects version collisions or inconsistent pre-existing tags.
+8. Commits `package.json`, `package-lock.json`, and `CHANGELOG.md` as `Release x.y.z`.
+9. Publishes to npm with OIDC/provenance when trusted publishing is configured.
+10. Creates and pushes `vault-core-vx.y.z` only after npm publication succeeds.
+11. Creates GitHub release notes and a workflow summary.
+
+The npm registry is immutable: a published version cannot be overwritten. If publication succeeds
+but tag or GitHub release creation fails, rerun the workflow with a blank version. Recovery mode
+detects the released changelog version, skips duplicate npm publication, and completes missing Git
+metadata.
+
+## Post-release verification
+
+- Confirm npmjs shows the expected version and provenance badge.
+- Confirm all four package entry points resolve.
+- Confirm README, changelog, and implementation guide render on npmjs.
+- Confirm `vault-core-vx.y.z` and the GitHub release point to the release commit.
+- Confirm `CHANGELOG.md` has a new empty `Unreleased` section.