@tinytars/vault 0.1.4 → 0.1.15

package/README.md

@@ -1,5 +1,6 @@
 # `@tinytars/vault`
 
+[![CI](https://github.com/tinytars/vault/actions/workflows/ci.yml/badge.svg)](https://github.com/tinytars/vault/actions/workflows/ci.yml)
 [![Community Health](https://img.shields.io/badge/dynamic/json?url=https://api.github.com/repos/tinytars/vault/community/profile&query=$.health_percentage&suffix=%25&label=community%20health)](https://github.com/tinytars/vault/community)
 
 A storage operator who can read what it stores hasn't encrypted the data — it's obfuscated it,

package/adapters/d1/accounts.ts

@@ -70,7 +70,7 @@ export async function getAccountByEmail(db: D1Database, email: string): Promise<
 /**
  * The instant before which this account's session cookies are no longer accepted, or null.
  *
- * W71 — read on every authenticated request (see `requireSession`). One indexed lookup by primary
+ * Read on every authenticated request, by the adopter's own session-check middleware. One indexed lookup by primary
  * key is what buys revocability: the cookie is self-contained, so without a server-side fact to
  * check against, nothing short of rotating SESSION_SECRET for the entire deployment can invalidate one.
  */
@@ -149,7 +149,7 @@ export async function tombstoneAccount(db: D1Database, accountId: string, at: st
 }
 
 /**
- * W73 — stamps when the account's email address changed.
+ * Stamps when the account's email address changed.
  *
  * Read by the recovery routes, which refuse to issue a grant while the address is still new: a stolen
  * cookie that repoints the mailbox should not be able to convert that into a recovery code minutes

package/adapters/d1/audit.ts

@@ -6,7 +6,7 @@ export type { AccessEvent };
 // bookkeeping are app-specific concerns that stay in the app's identity-audit.ts (see stores.ts's
 // own docstring on AuditStore).
 
-// W44 P4b — FTC-HBNR (§I) PHI-access/disclosure audit log. Records WHO (actor) accessed WHOSE (subject)
+// FTC-HBNR (§I) PHI-access/disclosure audit log. Records WHO (actor) accessed WHOSE (subject)
 // vault and WHY (action + consent_ref), so a breach can be scoped to affected individuals. NO PHI.
 interface AccessEventRow {
   id: string;

package/adapters/d1/credentials.ts

@@ -99,8 +99,8 @@ export async function getCredential(db: D1Database, accountId: string, method: A
   return row ? mapCredential(row) : null;
 }
 
-// W44 P8 — the account's key-bearing methods (password/passkey/recovery), for the Account screen and the
-// "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
+// The account's key-bearing methods (password/passkey/recovery), for the account-settings screen and
+// the "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
 // row independently wraps the same private key); identities lacks a recovery row.
 export async function listCredentials(db: D1Database, accountId: string): Promise<{ method: AuthMethod; createdAt: string }[]> {
   const { results } = await db
@@ -118,7 +118,7 @@ export async function deleteIdentity(db: D1Database, accountId: string, method:
   await db.prepare("DELETE FROM identities WHERE account_id = ? AND method = ?").bind(accountId, method).run();
 }
 
-// W44 P3 — bump the passkey authenticator's signature counter after a successful login
+// Bump the passkey authenticator's signature counter after a successful login
 // (replay-attack detection). Merges into the existing kdf_params rather than a raw column
 // update so the wrapped key row stays a single INSERT OR REPLACE-shaped record.
 export async function updatePasskeyCounter(db: D1Database, accountId: string, counter: number): Promise<void> {

package/adapters/d1/providers.ts

@@ -68,7 +68,7 @@ export async function updateProviderLinkStatus(db: D1Database, id: string, statu
   await db.prepare("UPDATE provider_links SET status = ? WHERE id = ?").bind(status, id).run();
 }
 
-// W44 P4b — a patient approving a support request: flip the link active, stamp its time-box + consent.
+// An owner approving a support request: flip the link active, stamp its time-box + consent.
 export async function grantSupportLink(
   db: D1Database,
   id: string,

package/adapters/d1/vault.ts

@@ -53,7 +53,7 @@ export async function getVault(db: D1Database, vaultId: string): Promise<VaultRo
   return row ? mapVault(row) : null;
 }
 
-/** W75 — the vault whose in-flight rotation has reserved this key. See `commitRotation`. */
+/** The vault whose in-flight rotation has reserved this key. See `commitRotation`. */
 export async function getVaultByStagingR2Key(db: D1Database, r2Key: string): Promise<VaultRow | null> {
   const row = await db.prepare("SELECT * FROM vaults WHERE rotation_staging_r2_key = ?").bind(r2Key).first<VaultRowRaw>();
   return row ? mapVault(row) : null;
@@ -106,7 +106,7 @@ export async function putEnvelope(
 }
 
 /**
- * W71 — swap a vault's whole envelope set atomically.
+ * Swap a vault's whole envelope set atomically.
  *
  * The rotation route used to delete every envelope in a loop and then build the replacements one at a
  * time, decoding each `wrappedDEK` as it went. Two ways that ended in an unrecoverable vault: a
@@ -139,7 +139,7 @@ export async function replaceEnvelopes(
 }
 
 /**
- * W75 — the whole re-key, committed as one D1 batch: swap the envelope set AND repoint the vault at
+ * The whole re-key, committed as one D1 batch: swap the envelope set AND repoint the vault at
  * the freshly-written object, in one implicit transaction.
  *
  * The atomicity is the point. The rotation used to re-encrypt IN PLACE — new DEK into the same r2

package/adapters/r2.ts

@@ -1,14 +1,14 @@
 import type { BlobStore, BlobConditional, StoredBlob } from "../blob-store";
 
 // Minimal structural type for the R2 binding — no @cloudflare/workers-types dependency, and
-// trivially mockable in tests. Moved from apps/health-dash-web/functions/api/vault/[id].ts, which
-// now imports R2Bucket/R2BlobStore from here instead of declaring its own copy.
+// trivially mockable in tests. An adopter's own Pages Function route should import R2Bucket/
+// R2BlobStore from here instead of declaring its own copy.
 export interface R2ObjectBody {
   body: ReadableStream;
-  /** W70 — the version token. Handed to the browser on GET and sent back as If-Match on PUT. */
+  /** The version token. Handed to the browser on GET and sent back as If-Match on PUT. */
   etag: string;
 }
-/** A precondition on a write. Verified against real workerd in tests/unit/r2-conditional-put.test.ts. */
+/** A precondition on a write. Verify this against real `workerd` in an adopter's own test suite — see ARCHITECTURE.md's "Adapters" section. */
 export interface R2Conditional {
   etagMatches?: string;
   etagDoesNotMatch?: string;

package/break-glass.ts

@@ -1,8 +1,9 @@
-// The time-boxed "support agent gets temporary access, then it lapses or is pulled" pattern, used by
-// three routes that used to each hardcode their own TTL clamp, consent-string prefix, and audit shape:
-// functions/api/support/approve.ts (grant, with envelope), functions/api/providers/approve-support.ts
-// (grant, metadata-only), functions/api/support/access.ts (check/expire), and
-// functions/api/providers/[link].ts (revoke). See docs/cross-app/10-open-source-info-security.md step 5.
+// The time-boxed "support agent gets temporary access, then it lapses or is pulled" pattern. It
+// exists because this package's first adopter had several routes that each hardcoded their own TTL
+// clamp, consent-string prefix, and audit shape — one for granting with an envelope, one for
+// granting metadata-only access, one for checking/expiring, one for revoking. Centralizing the
+// pattern here means every one of those routes shares the same TTL clamp, consent format, and audit
+// trail instead of drifting independently.
 
 import type { AuditStore, EnvelopeStore, ProviderLink, ProviderLinkStore } from "./stores";
 

package/crypto.ts

@@ -14,10 +14,11 @@ const deriveKey = (passphrase: string, salt: Uint8Array) => deriveAesKey(subtle,
 
 // Deterministic, non-reversible bearer derived from the passphrase: base64url(SHA-256).
 //
-// No longer called from the browser: it gated /api/chat and /api/raw via CHAT_TOKEN/RAW_TOKEN
-// until those routes moved to requireSession, and both secrets were deleted 2026-08-26. It is
-// still the generator for the one bearer allowlist that survives — scripts/chat-allowlist.ts
-// prints the VAULT_TOKEN value, which vault/[id].ts:73,155 checks and scripts/vault-sync.ts sends.
+// This is a generator for a stable, non-reversible token an adopter can use to gate a script or an
+// allowlisted bearer-token integration off the same passphrase used for the interactive login path,
+// without storing the passphrase itself anywhere. It is not session auth — an interactive route
+// should be protected by a real session cookie/token, not a static bearer derived here. Keep this
+// only for a script-facing bearer allowlist you still rely on; drop it once you don't.
 export async function deriveBearerToken(passphrase: string): Promise<string> {
   const digest = new Uint8Array(await subtle.digest("SHA-256", toAB(enc.encode(passphrase))));
   let bin = "";
@@ -67,7 +68,7 @@ export async function decryptVault<T = Record<string, unknown>>(blob: Uint8Array
   return JSON.parse(dec.decode(plaintext)) as T;
 }
 
-// ── W44 envelope encryption (v2) ─────────────────────────────────────────────
+// ── Envelope encryption (v2) ──────────────────────────────────────────────────
 // v1 above (passphrase → PBKDF2 → AES key → blob) is untouched. v2 splits the key:
 // a random per-vault DEK encrypts the blob, and the DEK is wrapped per principal
 // (owner, provider, support) to their ECDH public key. The passphrase path is gone;
@@ -138,17 +139,18 @@ export async function unwrapPrivateKey(blob: Uint8Array, kek: CryptoKey): Promis
   } catch {
     throw new Error("cannot unwrap private key (wrong KEK or corrupt blob)");
   }
-  // Extractable so an authorized holder can RE-WRAP it — needed to add a login method or regenerate the
-  // recovery code (W44 P8/P8b), which wrap this same key under a new KEK. Same rationale/posture as the
+  // Extractable so an authorized holder can RE-WRAP it — needed to add a login method or regenerate a
+  // recovery code, both of which wrap this same key under a new KEK. Same rationale/posture as the
   // DEK returned by unwrapDEKWithPrivateKey (also extractable for re-granting). The key stays in-memory
   // only, same trust boundary as the session's DEK.
   return subtle.importKey("pkcs8", pkcs8, EC_PARAMS, true, ["deriveKey", "deriveBits"]);
 }
 
 // Import a raw PKCS8 ECDH private key (extractable, so it can be re-wrapped to add a login method —
-// same trust boundary as unwrapPrivateKey's output). W45: the Google path moves the plaintext key
-// over the wire (server-custody), so both server (re-wrap under the server KEK) and client (recover
-// the DEK) import it here instead of unwrapping a KEK-wrapped blob.
+// same trust boundary as unwrapPrivateKey's output). A server-custody login path (e.g. SSO, where
+// the server itself bootstraps the session) moves the plaintext key over the wire instead of a
+// KEK-wrapped blob, so both server (re-wrap under the server KEK) and client (recover the DEK)
+// import it here rather than unwrapping.
 export async function importPrivateKeyPkcs8(pkcs8: Uint8Array): Promise<CryptoKey> {
   return subtle.importKey("pkcs8", toAB(pkcs8), EC_PARAMS, true, ["deriveKey", "deriveBits"]);
 }
@@ -204,7 +206,7 @@ export async function unwrapDEKWithPrivateKey(
   return subtle.importKey("raw", raw, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
 }
 
-// W73 — the DEK wrapped under a KEK, for a provider-issued recovery grant.
+// The DEK wrapped under a KEK, for a provider-issued recovery grant.
 //
 // The raw-key twin of wrapPrivateKey/unwrapPrivateKey above: same AES-GCM, same iv‖ct blob shape, same
 // reasoning. It exists because a recovery grant hands the DEK to a one-time code rather than to a

package/kdf.ts

@@ -1,17 +1,18 @@
-// The passphrase→key derivation shared by every passphrase-encrypted blob in this monorepo.
+// The passphrase→key derivation shared by every passphrase-encrypted blob that builds on this
+// package.
 //
-// W72. Two envelope formats derive their key identically and independently: the QBO token vault
-// (`EB1`, packages/qbo/crypto.ts) and the health-dash v1 vault plus its account KEKs (`HD1`,
-// apps/health-dash-web/src/lib/crypto.ts). Same PBKDF2-SHA256, same 200_000 iterations, same
-// AES-GCM-256, same 16-byte salt and 12-byte IV — written out twice, so a decision to raise the
-// iteration count could be taken in one file and silently not the other. Only the derivation is
-// shared here.
+// This derivation is deliberately factored out on its own, separate from any particular envelope
+// format: PBKDF2-SHA256, 200_000 iterations, AES-GCM-256, a 16-byte salt and a 12-byte IV. An
+// adopter building a second, unrelated encrypted-blob format alongside this package's own HD1
+// envelope (`crypto.ts`) should reuse this file rather than reimplementing the derivation —
+// reimplementing it independently is exactly how a later decision to raise the iteration count
+// gets taken in one copy and silently not the other.
 //
-// WHAT IS DELIBERATELY NOT SHARED: the envelope. `EB1` and `HD1` keep their own magic bytes, their
-// own version handling and their own framing, in their own modules. A unified envelope would make a
-// QBO token blob a syntactically valid input to the vault reader, which is a confusion this
-// separation prevents for free. If you are here to "finish the job" by merging the two files — that
-// is the bug this comment exists to stop.
+// WHAT IS DELIBERATELY NOT SHARED: the envelope. HD1 keeps its own magic bytes, its own version
+// handling and its own framing in its own module — a sibling format should do the same in its own.
+// A unified envelope would make a foreign blob a syntactically valid input to this package's vault
+// reader, which is a confusion this separation prevents for free. If you are here to "finish the
+// job" by merging formats — that is the bug this comment exists to stop.
 //
 // RUNTIME-AGNOSTIC BY CONSTRUCTION: this module imports nothing and touches no global. One caller is
 // Node-only (`node:crypto`'s webcrypto), the others run in the browser and in Workers, so the

package/key-store.ts

@@ -1,4 +1,4 @@
-// W49 — persist the account private key across a browser refresh so a valid hd_session doesn't force
+// Persist the account private key across a browser refresh so a valid session doesn't force
 // re-auth. The key is stored as a NON-EXTRACTABLE CryptoKey (structured-cloned into IndexedDB): it can
 // still unwrap the vault DEK (ECDH deriveKey) on the next load, but its raw bytes can't be read back
 // out, so an XSS payload can't exfiltrate it (it could still USE it while the page is open — inherent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinytars/vault",
-  "version": "0.1.4",
+  "version": "0.1.15",
   "description": "Runtime-agnostic key derivation, authenticated envelope encryption, and storage-agnostic access-control contracts for per-user encrypted data.",
   "license": "MIT",
   "type": "module",

package/stores.ts

@@ -1,11 +1,10 @@
 // Storage-agnostic contracts for the identity/vault/access-control data this package's crypto
 // operates over. No Cloudflare or D1 dependency here by design (see README.md) — an adopter wires
-// these to whatever database they run; health-dash-web's D1 adapter lives at
-// apps/health-dash-web/functions/_lib/d1-identity-store.ts and is one implementation of these,
-// not the definition of them.
+// these to whatever database they run; `adapters/d1/` in this package is one implementation of
+// these contracts, not the definition of them.
 //
-// health-dash-web's own functions/_lib/identity-*.ts modules re-export the types below rather than
-// redeclaring them, so there is exactly one definition of each shape.
+// An adopter's own route handlers should re-export the types below rather than redeclaring them,
+// so there is exactly one definition of each shape.
 
 export type LifecycleStage = "waitlist" | "lead" | "active" | "paying" | "churned";
 export type AuthMethod = "passkey" | "google" | "password" | "recovery";

package/vault-sink.ts

@@ -8,13 +8,14 @@ export interface VaultSink {
 }
 
 /**
- * W70 — the version of each vault blob this browser context last saw.
+ * The version of each vault blob this browser context last saw.
  *
- * Deliberately held HERE rather than threaded through callers. `saveVaultV2` has SEVEN call sites in
- * App.svelte (the queued edit path plus key rotation, leaf-regen persist, Finding refresh, report
- * import, raw upload and onboarding), and only one of them goes through the save queue. Since the
- * precondition is now REQUIRED on the browser path, a call site that forgot to pass an etag would not
- * degrade — it would 428, i.e. a patient unable to save their own record. Keeping the token where the
+ * Deliberately held HERE rather than threaded through callers. A real adopter typically has several
+ * independent call sites that all persist through `saveVaultV2` — a queued-edit path plus things
+ * like key rotation, background regeneration, imports, raw uploads and onboarding — and usually only
+ * one of them goes through a save queue. Since the precondition is REQUIRED on the browser path, a
+ * call site that forgot to pass an etag would not degrade — it would 428, i.e. an owner unable to
+ * save their own record. Keeping the token where the
  * request is built makes every path correct by construction instead of by remembering.
  *
  * One entry per vault id, which is exactly the domain: a browser context has one current view of a
@@ -48,10 +49,10 @@ export class VaultConflictError extends Error {
 /**
  * One hook, so every save path reports a conflict — not just the queued one.
  *
- * Six of `saveVaultV2`'s seven call sites are direct `await`s outside the save queue (key rotation,
- * leaf-regen persist, Finding refresh, report import, raw upload, onboarding). Wiring the conflict
- * state through each would be six chances to miss one, and a missed one is an unhandled rejection on a
- * health record. Every save funnels through this sink, so this is the one place that sees them all.
+ * Most real `saveVaultV2` call sites are direct `await`s outside any save queue (key rotation,
+ * background regeneration, import, raw upload, onboarding). Wiring the conflict state through each
+ * would be one chance to miss it per call site, and a missed one is an unhandled rejection on a
+ * record someone owns. Every save funnels through this sink, so this is the one place that sees them all.
  * The error still throws afterwards, so existing per-path error handling is unchanged.
  */
 let onConflict: ((e: VaultConflictError) => void) | null = null;
@@ -59,10 +60,9 @@ export function setVaultConflictHandler(fn: ((e: VaultConflictError) => void) |
   onConflict = fn;
 }
 
-// Dev-only sink: POSTs the blob to the Vite dev-server middleware, which writes
-// public/data-{id}.enc to disk (see vite.config.ts). Absent from the deployed
-// build — there is no such endpoint in production. The R2 sink (W6) is the
-// second implementation of this interface for remote/mobile save.
+// Dev-only sink: POSTs the blob to a local dev-server middleware, which writes it to disk.
+// Absent from the deployed build — there is no such endpoint in production. The R2 sink below is
+// the second implementation of this interface, for a real remote/mobile save.
 export const localSink: VaultSink = {
   async put(id, blob) {
     const res = await fetch(`/__save-vault?id=${encodeURIComponent(id)}`, {
@@ -76,9 +76,9 @@ export const localSink: VaultSink = {
   },
 };
 
-// Remote sink: PUTs the encrypted blob to the R2-backed Pages Function (W6, re-gated W44).
-// `/api/vault/{id}` only exists in the deployed build; the guard now accepts the hd_session
-// cookie (owner/granted-provider envelope check) — same-origin fetch sends it automatically.
+// Remote sink: PUTs the encrypted blob to an R2-backed Pages Function.
+// `/api/vault/{id}` only exists in the deployed build; the route guard checks the adopter's own
+// session cookie (owner/granted-provider envelope check) — same-origin fetch sends it automatically.
 // The Function stores opaque ciphertext — same as localSink, never plaintext or a key.
 /**
  * One write at a time per vault, so the app never conflicts with ITSELF.
@@ -139,7 +139,7 @@ async function putConditional(id: string, blob: Uint8Array): Promise<void> {
 // wrangler-pages-dev e2e harness) persists to R2 and never references /__save-vault.
 export const vaultSink: VaultSink = import.meta.env.DEV ? localSink : r2Sink;
 
-// W44 — encrypt the vault under its DEK (HD1 v2 envelope) and persist. The DEK is the vault's
+// Encrypt the vault under its DEK (HD1 v2 envelope) and persist. The DEK is the vault's
 // random data key, unwrapped at login from the caller's key envelope; it stays in memory.
 export async function saveVaultV2<T = Record<string, unknown>>(vault: T, id: string, dek: CryptoKey, sink: VaultSink): Promise<void> {
   const blob = await encryptVaultV2(vault, dek);