@noy-db/hub 0.4.0-pre.1 → 0.4.0-pre.10

package/dist/{chunk-RND5ZPNP.js → chunk-G6WWZNJP.js}

@@ -1,21 +1,21 @@
 import {
   loadVaultPolicy,
   saveVaultPolicy
-} from "./chunk-CBSY2N76.js";
+} from "./chunk-WLXMTYGO.js";
 import {
   PolicyDeniedError,
   ValidationError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-QZWTRENR.js";
 
 // src/with-party/policy/presets.ts
 var PERSONAL_POLICY = Object.freeze({
-  passphrase: {
+  secret: {
     minWords: 6,
     minWordLength: 3,
     rejectRepeatedAdjacent: true
   },
   gates: {
-    "rotate-passphrase": {
+    "rotate-secret": {
       minTier: 1,
       // Any second factor satisfies the gate — off-device kinds (TOTP,
       // email-OTP, paper recovery, roaming WebAuthn) are the strongest;
@@ -35,13 +35,13 @@ var PERSONAL_POLICY = Object.freeze({
         ]
       }]
     },
-    "recover-passphrase": {
+    "recover-secret": {
       minTier: 1,
       enabled: true
     },
     // rotate-recovery: deliberate paper-sheet regeneration
-    // when the user remembers their passphrase. PERSONAL allows tier-1 —
-    // knowing the passphrase is enough.
+    // when the user remembers their secret. PERSONAL allows tier-1 —
+    // knowing the secret is enough.
     "rotate-recovery": { minTier: 1 },
     "enroll-authenticator": { minTier: 1 },
     "remove-authenticator": { minTier: 1 },
@@ -99,17 +99,17 @@ var PERSONAL_POLICY = Object.freeze({
   }
 });
 var STRICT_POLICY = Object.freeze({
-  passphrase: {
+  secret: {
     minWords: 8,
     minWordLength: 3,
     rejectRepeatedAdjacent: true
   },
   gates: {
-    "rotate-passphrase": {
+    "rotate-secret": {
       minTier: 1,
       factors: [{ anyOf: ["totp", "email-otp", "recovery"], count: 2 }]
     },
-    "recover-passphrase": {
+    "recover-secret": {
       minTier: 1,
       enabled: true
     },
@@ -216,9 +216,9 @@ var STRICT_POLICY = Object.freeze({
 });
 function mergePolicy(base, override) {
   if (!override) return base;
-  const passphrase = override.passphrase ?? base.passphrase;
+  const secret = override.secret ?? base.secret;
   return {
-    ...passphrase !== void 0 ? { passphrase } : {},
+    ...secret !== void 0 ? { secret } : {},
     gates: {
       ...base.gates,
       ...override.gates ?? {}
@@ -364,4 +364,4 @@ export {
   describeGate,
   createNoydbPolicy
 };
-//# sourceMappingURL=chunk-RND5ZPNP.js.map
+//# sourceMappingURL=chunk-G6WWZNJP.js.map

package/dist/chunk-G6WWZNJP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/policy/presets.ts","../src/with-party/policy/engine.ts","../src/with-party/policy/noydb-facade.ts"],"sourcesContent":["import type { VaultPolicy } from '../../kernel/types.js'\n\n/**\n * Default policy for personal vaults and SMB deployments — the gates\n * that need an off-device factor get one (TOTP / email-OTP / paper\n * recovery), the rest take a tier-1 unlock alone. Tier-3 (PIN) is the\n * floor only for `rotate-unlock` because that's the\n * \"change my PIN\" flow.\n *\n * The unspecified gates (e.g. `view-user-auth`) inherit the engine\n * default of `{ enabled: false, minTier: 1 }` — they fail closed.\n *\n * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Built-in gates\n */\nexport const PERSONAL_POLICY: VaultPolicy = Object.freeze({\n  secret: {\n    minWords: 6,\n    minWordLength: 3,\n    rejectRepeatedAdjacent: true,\n  },\n  gates: {\n    'rotate-secret': {\n      minTier: 1,\n      // Any second factor satisfies the gate — off-device kinds (TOTP,\n      // email-OTP, paper recovery, roaming WebAuthn) are the strongest;\n      // platform-bound kinds (platform WebAuthn, password, PIN) are\n      // accepted because requiring \"something off-device\" is overkill\n      // for personal/SMB threat models. Consumers needing the off-device\n      // guarantee should use STRICT_POLICY or override this gate.\n      factors: [{\n        anyOf: [\n          'totp', 'email-otp', 'recovery',\n          'webauthn-roaming', 'webauthn-platform',\n          'password', 'pin',\n        ],\n      }],\n    },\n    'recover-secret': {\n      minTier: 1,\n      enabled: true,\n    },\n    // rotate-recovery: deliberate paper-sheet regeneration\n    // when the user remembers their secret. PERSONAL allows tier-1 —\n    // knowing the secret is enough.\n    'rotate-recovery': { minTier: 1 },\n    'enroll-authenticator': { minTier: 1 },\n    'remove-authenticator': { minTier: 1 },\n    // update-authenticator: meta-only mutation (slot rename, label\n    // changes). Symmetric with enroll/remove under PERSONAL — tier-1\n    // unlock alone. The structural anti-slot-swap guard inside the\n    // implementation enforces wrap-material/id/method immutability\n    // regardless of this gate's settings.\n    'update-authenticator': { minTier: 1 },\n    'rotate-unlock': { minTier: 2 },\n    'enroll-user': { minTier: 1 },\n    'revoke-user': { minTier: 1 },\n    // Peer-recovery is a high-trust intentional op — co-owners\n    // recovering each other should not need an off-device factor in\n    // the personal/SMB threat model (the partner is already vetted by\n    // virtue of being a co-owner). Tier-1 unlock is the floor; the\n    // STRICT preset adds a recovery/email-OTP requirement.\n    'peer-recover-user': { minTier: 1 },\n    // update-user: post-grant identity mutation (role/displayName/\n    // permissions). PERSONAL_POLICY treats this on par with enroll-user\n    // / revoke-user — tier-1 unlock alone. The role-elevation guard\n    // inside the implementation is the structural backstop that this\n    // gate's settings cannot weaken.\n    'update-user': { minTier: 1 },\n    'export-bundle': { minTier: 1 },\n    'export-plaintext': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'view-user-auth': {\n      minTier: 1,\n      enabled: false,\n    },\n    // ─── User envelope gates ──────────────────────────────────────────\n    // edit-own-profile: tier 3 floor — any active session can edit their\n    //   own profile/preferences. Tightening to require a TOTP for\n    //   profile changes is a one-line override.\n    // view-team-profiles: tier 2 floor — an authenticated session can\n    //   read teammates' profiles (display names, avatars, locales).\n    //   Setting `enabled: false` makes vault.user.list() return only\n    //   self (privacy-strict opt-out).\n    'edit-own-profile': { minTier: 3 },\n    'view-team-profiles': { minTier: 2 },\n    // client-unilateral-withdraw: a non-owner's self-service DESTRUCTIVE\n    // withdrawal (export-and-delete/freeze). Fail-closed by default —\n    // the firm opts in per jurisdiction/contract (e.g. GDPR Art. 17).\n    // Listed explicitly (not just relying on the built-in default) so it is\n    // discoverable in describeGate / policy dumps.\n    'client-unilateral-withdraw': { minTier: 1, enabled: false },\n    // Two-party withdrawal: filing a request is non-destructive\n    // (tier-1, enabled so a read-only client can ask); deciding it is the\n    // destructive step (tier-2 floor + owner/admin role, enforced in code).\n    'user-request-withdrawal': { minTier: 1 },\n    'approve-user-withdrawal': { minTier: 2 },\n  },\n}) as VaultPolicy\n\n/**\n * Strict policy for regulated deployments and shared workstations —\n * raises the phrase floor to 8 words, demands two distinct factors for\n * exports, and blocks export-on-shared-device. Use as a base for\n * `policy: { ...STRICT_POLICY, gates: { ...STRICT_POLICY.gates, ... } }`\n * tweaks.\n */\nexport const STRICT_POLICY: VaultPolicy = Object.freeze({\n  secret: {\n    minWords: 8,\n    minWordLength: 3,\n    rejectRepeatedAdjacent: true,\n  },\n  gates: {\n    'rotate-secret': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp', 'recovery'], count: 2 }],\n    },\n    'recover-secret': {\n      minTier: 1,\n      enabled: true,\n    },\n    // rotate-recovery: STRICT requires an off-device factor —\n    // rotating recovery is an off-site-trust event; a stolen unlocked\n    // laptop must not be able to silently mint a new sheet for the\n    // attacker. Matches the `peer-recover-user` STRICT default.\n    'rotate-recovery': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp', 'webauthn-roaming'] }],\n    },\n    'enroll-authenticator': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'remove-authenticator': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    // STRICT update-authenticator: same factor floor as enroll/remove.\n    // Even though meta changes don't touch wrap material, a malicious\n    // rename could mislead the user about which device a slot\n    // corresponds to (\"MacBook Touch ID\" → \"iPhone Touch ID\" on a\n    // shared workstation). STRICT requires a fresh factor proof.\n    'update-authenticator': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'rotate-unlock': { minTier: 1 },\n    'enroll-user': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'revoke-user': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    // STRICT peer-recovery: the issuer must present a recovery code\n    // OR a fresh off-device second factor at the moment of recovery.\n    // This binds the high-trust operation to a verifiable proof\n    // (recovery sheet photographed by an attacker won't suffice —\n    // they'd also need tier-1 unlock first; this gate is the freshness\n    // binding on top). Roaming WebAuthn (YubiKey-class hardware key)\n    // accepted; platform-bound kinds (Touch ID, password, PIN)\n    // intentionally excluded under STRICT because they don't survive\n    // device theft — the off-device requirement is the whole point.\n    'peer-recover-user': {\n      minTier: 1,\n      factors: [{ anyOf: ['recovery', 'totp', 'email-otp', 'webauthn-roaming'] }],\n    },\n    // STRICT update-user: matches the enroll-user / revoke-user shape\n    // (off-device factor required). Update-user is admin-shaped — it\n    // mutates someone else's role/permissions; STRICT requires a fresh\n    // off-device factor proof so the operator affirmatively re-asserts\n    // identity at the moment of mutation. Platform-bound factors\n    // (Touch ID / password / PIN) intentionally excluded: same logic as\n    // peer-recover-user — the off-device requirement is the whole\n    // point under STRICT.\n    'update-user': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'export-bundle': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n      warn: { sharedDevice: 'block' },\n    },\n    'export-plaintext': {\n      minTier: 1,\n      factors: [{ anyOf: ['totp', 'email-otp'], count: 2 }],\n      warn: { sharedDevice: 'block' },\n    },\n    'view-user-auth': {\n      minTier: 1,\n      enabled: false,\n    },\n    // ─── User envelope gates ──────────────────────────────────────────\n    // STRICT: profile edits require a TOTP/email-OTP factor (typical\n    // shared-workstation hardening — your name/avatar shouldn't change\n    // without a fresh second-factor proof).\n    'edit-own-profile': {\n      minTier: 2,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n    },\n    'view-team-profiles': { minTier: 2 },\n    // STRICT: still fail-closed, but if a regulated firm flips enabled:true\n    // they inherit a two-factor proof + shared-device block for the\n    // destructive withdrawal (mirrors export-plaintext's hardening).\n    'client-unilateral-withdraw': {\n      minTier: 1,\n      enabled: false,\n      factors: [{ anyOf: ['totp', 'email-otp'], count: 2 }],\n      warn: { sharedDevice: 'block' },\n    },\n    // STRICT: filing stays tier-1; the destructive APPROVE demands an\n    // off-device factor + shared-device block (mirrors export-bundle).\n    'user-request-withdrawal': { minTier: 1 },\n    'approve-user-withdrawal': {\n      minTier: 2,\n      factors: [{ anyOf: ['totp', 'email-otp'] }],\n      warn: { sharedDevice: 'block' },\n    },\n  },\n}) as VaultPolicy\n\n/**\n * Merge a developer override onto a preset. Unspecified gates inherit;\n * specified gates fully replace the preset's entry for that gate.\n *\n * Example:\n *\n * ```ts\n * mergePolicy(PERSONAL_POLICY, {\n *   gates: {\n *     'app:approve-large-payment': { minTier: 2, factors: [{ anyOf: ['totp'] }] },\n *   },\n * })\n * // → PERSONAL_POLICY plus the new app gate; existing gates intact.\n * ```\n */\nexport function mergePolicy(\n  base: VaultPolicy,\n  override?: Partial<VaultPolicy>,\n): VaultPolicy {\n  if (!override) return base\n  const secret = override.secret ?? base.secret\n  return {\n    ...(secret !== undefined ? { secret } : {}),\n    gates: {\n      ...base.gates,\n      ...(override.gates ?? {}),\n    },\n  }\n}\n","/**\n * Policy gate engine — the {@link checkGate} entry point.\n *\n * Given a configured {@link VaultPolicy}, an active session tier, and\n * the factor proofs an actor is presenting, decide whether the gate\n * permits the action. On denial, throws {@link PolicyDeniedError} with\n * a stable {@link PolicyDenyReason} so consumers can branch in error\n * UIs.\n *\n * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → checkGate() API\n *\n * @module\n */\nimport { PolicyDeniedError, type PolicyDenyReason } from '../../kernel/errors.js'\nimport type {\n  ActiveTier,\n  FactorProof,\n  GateName,\n  GatePolicy,\n  VaultPolicy,\n  FactorRequirement,\n} from '../../kernel/types.js'\n\n/** Default freshness window — 5 minutes. */\nexport const DEFAULT_FRESHNESS_MS = 5 * 60 * 1000\n\n/** Caller-supplied context for one `checkGate` invocation. */\nexport interface CheckGateContext {\n  /** Tier the active session currently holds. */\n  readonly activeTier: ActiveTier\n  /** Proofs the actor is presenting for this gate. */\n  readonly factors?: ReadonlyArray<FactorProof>\n  /**\n   * If the host knows the actor is on a shared device, set this to\n   * `true` so the engine can apply `warn.sharedDevice` rules. Defaults\n   * to `false`.\n   */\n  readonly sharedDevice?: boolean\n  /**\n   * Override `now()` for tests. Defaults to `Date.now()`.\n   * @internal\n   */\n  readonly now?: number\n}\n\n/**\n * Decide whether `gate` permits the action under `context`. Throws\n * {@link PolicyDeniedError} on denial; resolves with `void` on success.\n *\n * Lookup rules:\n * - **Built-in gates** without a configured policy fail closed\n *   (`enabled: false`).\n * - **App-defined gates** (`app:*`) without a configured policy are\n *   treated as no-op (allow). The developer registered the policy if\n *   they wanted enforcement; absence means the gate is informational.\n */\nexport async function checkGate(\n  policy: VaultPolicy,\n  gate: GateName,\n  context: CheckGateContext,\n): Promise<void> {\n  const configured = policy.gates[gate]\n  if (!configured) {\n    if (gate.startsWith('app:')) {\n      // Custom app gate without a policy — the developer hasn't\n      // registered one; engine treats it as an unenforced label.\n      return\n    }\n    // Built-in gate without a policy — fail closed.\n    throw deny(gate, 'disabled', { minTier: 1, enabled: false })\n  }\n\n  if (configured.enabled === false) {\n    throw deny(gate, 'disabled', configured)\n  }\n\n  // Tier check first — cheap and a hard prerequisite.\n  if (context.activeTier > configured.minTier) {\n    // Higher number is a LOWER tier in this model (1 is most privileged).\n    throw deny(gate, 'insufficient-tier', configured)\n  }\n\n  // Factor checks — every requirement entry must be satisfied.\n  if (configured.factors && configured.factors.length > 0) {\n    const presented = context.factors ?? []\n    const now = context.now ?? Date.now()\n    for (const requirement of configured.factors) {\n      const matches = countMatchingFactors(presented, requirement, now)\n      const need = requirement.count ?? 1\n      if (matches.fresh < need) {\n        if (matches.totalKindMatches < need) {\n          throw deny(gate, 'missing-factor', configured)\n        }\n        // Some matched the kind list but not the freshness window.\n        throw deny(gate, 'stale-proof', configured)\n      }\n    }\n  }\n\n  // Soft signals — only `'block'` raises here.\n  if (configured.warn?.sharedDevice === 'block' && context.sharedDevice === true) {\n    throw deny(gate, 'shared-device-blocked', configured)\n  }\n}\n\n/**\n * Same as {@link checkGate} but returns a structured verdict instead\n * of throwing. Useful when an error UI wants to show the user\n * \"you'll need TOTP plus a recovery code to do that\" without first\n * triggering the action.\n */\nexport async function describeGate(\n  policy: VaultPolicy,\n  gate: GateName,\n  context: CheckGateContext,\n): Promise<{ ok: true } | { ok: false; reason: PolicyDenyReason; required: GatePolicy }> {\n  try {\n    await checkGate(policy, gate, context)\n    return { ok: true }\n  } catch (err) {\n    if (err instanceof PolicyDeniedError) {\n      return { ok: false, reason: err.reason, required: err.required }\n    }\n    throw err\n  }\n}\n\nfunction countMatchingFactors(\n  presented: ReadonlyArray<FactorProof>,\n  requirement: FactorRequirement,\n  now: number,\n): { totalKindMatches: number; fresh: number } {\n  const freshnessMs = requirement.freshnessMs ?? DEFAULT_FRESHNESS_MS\n  let totalKindMatches = 0\n  let fresh = 0\n  for (const proof of presented) {\n    if (!requirement.anyOf.includes(proof.kind)) continue\n    totalKindMatches += 1\n    const minted = proof.mintedAt ? Date.parse(proof.mintedAt) : now\n    if (Number.isFinite(minted) && now - minted <= freshnessMs) {\n      fresh += 1\n    }\n  }\n  return { totalKindMatches, fresh }\n}\n\nfunction deny(gate: GateName, reason: PolicyDenyReason, required: GatePolicy): PolicyDeniedError {\n  return new PolicyDeniedError(gate, reason, required)\n}\n","/**\n * Noydb-side policy / session-policy facade.\n *\n * Holds the vault-policy read/update/bootstrap logic (`getPolicy`,\n * `updatePolicy`, `bootstrapPolicy`) and the per-vault session-policy\n * enforcer wiring (`touchPolicy`, `checkPolicyOperation`). The session\n * *timer* and the managed-recovery enrolment check stay kernel-resident on\n * `Noydb` (interleaved with the instance lifecycle) and arrive here as the\n * `resetSessionTimer` / `assertRecoveryEnrolled` callbacks. The policy cache\n * and the enforcer map stay `Noydb`-resident too (touched by\n * `openVault`/`close`) and arrive by reference; behaviour is byte-identical\n * to the inline `Noydb` methods it replaced — every other dependency the\n * moving code touched on `this.*` arrives via {@link NoydbPolicyDeps}.\n *\n * Internal service — reached through `noydb.getPolicy(...)` etc. Public\n * contract ({@link NoydbPolicyApi} / {@link NoydbPolicyDeps} /\n * {@link NoydbPolicyFactory}) lives in the kernel spine; `createNoydb()`\n * wires this file's {@link createNoydbPolicy} in via a pre-resolved dynamic\n * import (the S4 gate recipe).\n */\nimport { ValidationError } from '../../kernel/errors.js'\nimport { PERSONAL_POLICY, mergePolicy } from './presets.js'\nimport { loadVaultPolicy, saveVaultPolicy } from './storage.js'\nimport type { VaultPolicy, ReAuthOperation, NoydbPolicyApi, NoydbPolicyDeps, NoydbPolicyFactory } from '../../kernel/types.js'\n\nexport class NoydbPolicy implements NoydbPolicyApi {\n  constructor(private readonly deps: NoydbPolicyDeps) {}\n\n  /**\n   * Touch the policy enforcer for a vault (records activity, resets\n   * idle timer). Also touches the legacy session timer. No-op if no enforcer.\n   */\n  touchPolicy(vault?: string): void {\n    this.deps.resetSessionTimer()\n    if (vault) {\n      this.deps.policyEnforcers.get(vault)?.touch()\n    }\n  }\n\n  /**\n   * Check that a policy-guarded operation is permitted.\n   * Throws `SessionPolicyError` if re-auth is required.\n   */\n  checkPolicyOperation(vault: string, op: ReAuthOperation): void {\n    this.deps.policyEnforcers.get(vault)?.checkOperation(op)\n  }\n\n  /**\n   * Read the active policy for a vault. Loads from `_meta/policy` on\n   * first call; subsequent calls hit the in-memory cache. Throws\n   * `ValidationError` if the vault has not been opened.\n   */\n  async getPolicy(vault: string): Promise<VaultPolicy> {\n    if (this.deps.isClosed()) throw new ValidationError('Instance is closed')\n    const cached = this.deps.policyCache.get(vault)\n    if (cached) return cached\n    await this.bootstrapPolicy(vault)\n    return this.deps.policyCache.get(vault) ?? PERSONAL_POLICY\n  }\n\n  /**\n   * Replace the policy document at `_meta/policy` and update the\n   * in-memory cache. Gated by the `enroll-user` policy (a policy\n   * change is fundamentally a privilege-management action).\n   */\n  async updatePolicy(vault: string, override: Partial<VaultPolicy>): Promise<VaultPolicy> {\n    if (this.deps.isClosed()) throw new ValidationError('Instance is closed')\n    const current = await this.getPolicy(vault)\n    const merged = mergePolicy(current, override)\n    if (this.deps.encrypted) {\n      await saveVaultPolicy(this.deps.store, vault, merged)\n    }\n    this.deps.policyCache.set(vault, merged)\n    return merged\n  }\n\n  /** Read or persist the vault policy at `_meta/policy` on first open. */\n  async bootstrapPolicy(\n    vault: string,\n    opts?: { skipManagedCheck?: boolean },\n  ): Promise<void> {\n    const onDisk = await loadVaultPolicy(this.deps.store, vault)\n    if (onDisk) {\n      // Honour the on-disk document; developer overrides cannot\n      // weaken what the vault committed to at creation time.\n      this.deps.policyCache.set(vault, onDisk)\n      await this.deps.assertRecoveryEnrolled(vault, onDisk, opts)\n      return\n    }\n    // First time — persist the developer's policy (or default preset).\n    const initial = this.deps.policyOption\n      ? mergePolicy(PERSONAL_POLICY, this.deps.policyOption)\n      : PERSONAL_POLICY\n    await saveVaultPolicy(this.deps.store, vault, initial)\n    this.deps.policyCache.set(vault, initial)\n    await this.deps.assertRecoveryEnrolled(vault, initial, opts)\n  }\n}\n\n/**\n * Factory that builds the `NoydbPolicy` service. `createNoydb()`\n * pre-resolves this via a dynamic import (mirrors\n * `with-party/directory/user-envelope/api.js#createUserApi`) and threads\n * it through `NoydbOptions.policyFactory` so `Noydb`'s constructor can\n * build `this.policyManager` synchronously.\n */\nexport const createNoydbPolicy: NoydbPolicyFactory = (deps) => new NoydbPolicy(deps)\n"],"mappings":"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","names":[]}

package/dist/chunk-GJW4HX2O.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-GJW4HX2O.js.map

package/dist/{chunk-T6GU5PPZ.js → chunk-GU3IP74F.js}

@@ -201,7 +201,7 @@ var engineCtx = (ctx) => ({
 function withClassified() {
   return {
     async reveal(ctx, id, field) {
-      const { revealSealedField } = await import("./reveal-LGBOM2BO.js");
+      const { revealSealedField } = await import("./reveal-CL2BCW6A.js");
       const value = await revealSealedField({
         collection: ctx.collection,
         encrypted: ctx.encrypted,
@@ -213,26 +213,26 @@ function withClassified() {
       return value;
     },
     async verify(ctx, id, field, candidate) {
-      const { verifyDigestField } = await import("./verify-26Y5GNMK.js");
+      const { verifyDigestField } = await import("./verify-7XWHJWUN.js");
       const verdict = await verifyDigestField(engineCtx(ctx), id, field, candidate, policyOf(ctx.spec));
       await ctx.onAccess?.("verify", id);
       return verdict;
     },
     async verifyText(ctx, id, field, candidate) {
-      const { verifyTextField } = await import("./verify-26Y5GNMK.js");
+      const { verifyTextField } = await import("./verify-7XWHJWUN.js");
       const verdict = await verifyTextField(engineCtx(ctx), id, field, candidate, ctx.spec.verifyNormalize ?? "password");
       await ctx.onAccess?.("verify", id);
       return verdict;
     },
     async matchGroup(ctx, id, answers, opts) {
-      const { matchGroupFields } = await import("./verify-26Y5GNMK.js");
+      const { matchGroupFields } = await import("./verify-7XWHJWUN.js");
       const members = (ctx.groupMembers ?? []).map((m) => ({ field: m.field, policy: policyOf(m.spec) }));
       const result = await matchGroupFields(engineCtx(ctx), id, answers, members, opts);
       await ctx.onAccess?.("verify", id);
       return result;
     },
     async computeTarget(ctx, field, candidate, costByte) {
-      const { computeBidxTarget } = await import("./find-YS6XWB46.js");
+      const { computeBidxTarget } = await import("./find-OZMTRIK3.js");
       const dek = await ctx.getDEK();
       return computeBidxTarget(candidate, policyOf(ctx.spec).normalize, dek, ctx.collection, field, costByte);
     }
@@ -244,4 +244,4 @@ export {
   classified,
   withClassified
 };
-//# sourceMappingURL=chunk-T6GU5PPZ.js.map
+//# sourceMappingURL=chunk-GU3IP74F.js.map

package/dist/{chunk-5OI6BR4H.js → chunk-GWWOGNBK.js}

@@ -1,15 +1,15 @@
 import {
   assertTierAccess,
   dekKey
-} from "./chunk-UC2ETWF3.js";
+} from "./chunk-PTHKZWEH.js";
 import {
   liveRecordIsElevated,
   liveRecordTier
-} from "./chunk-DRWBEDYO.js";
+} from "./chunk-JYJFGD2H.js";
 import {
   openEnvelopeJson,
   writeEnvelopeBody
-} from "./chunk-DVUZMT2W.js";
+} from "./chunk-G2JUIDFA.js";
 import {
   base64ToBuffer,
   bufferToBase64,
@@ -21,19 +21,53 @@ import {
   sha256Hex,
   unwrapCek,
   wrapCek
-} from "./chunk-HOONYZY2.js";
+} from "./chunk-AKKRXT23.js";
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-LSASLXGC.js";
+} from "./chunk-QBAC3GXA.js";
 import {
   BlobIntentPendingError,
+  BlobOfflineError,
   ConflictError,
   NotFoundError,
   TamperedError,
   TierNotGrantedError,
   UnsupportedTierCompositionError,
   ValidationError
-} from "./chunk-W2OG6JOL.js";
+} from "./chunk-QZWTRENR.js";
+
+// src/with-shape/blobs/blob-pinning.ts
+function memoryBlobPinStore() {
+  const rows = /* @__PURE__ */ new Map();
+  return {
+    async get(key) {
+      return rows.get(key) ?? null;
+    },
+    async set(key, entry) {
+      rows.set(key, entry);
+    },
+    async delete(key) {
+      rows.delete(key);
+    },
+    async entries(prefix) {
+      const out = [];
+      for (const [key, entry] of rows) {
+        if (key.startsWith(prefix)) out.push({ key, entry });
+      }
+      return out;
+    }
+  };
+}
+function createBlobPinCache(store) {
+  return {
+    store: store ?? memoryBlobPinStore(),
+    stats: { hits: 0, misses: 0, bytesDownloaded: 0 }
+  };
+}
+function blobPinKey(vault, collection, recordId, slotName) {
+  const prefix = `${vault}::${collection}::${recordId}::`;
+  return slotName === void 0 ? prefix : prefix + slotName;
+}
 
 // src/with-shape/blobs/mime-magic.ts
 function hex(s) {
@@ -403,6 +437,12 @@ var BlobSet = class _BlobSet {
   objectStore;
   blobFields;
   keyring;
+  /**
+   * Device-local pin registry + external side-cache + KPI counters (#808).
+   * Injected by `withBlobs()` (one shared instance per strategy — per
+   * "device"); absent on a direct construction that never threads one.
+   */
+  pinCache;
   /**
    * Set only on the cleared clone `atTier()` returns (#749) — never by
    * `openSlot`/`Collection.blob()`. Its presence is what makes a `BlobSet`
@@ -425,6 +465,7 @@ var BlobSet = class _BlobSet {
     this.blobFields = opts.blobFields;
     this.keyring = opts.keyring;
     this.clearedTier = opts.clearedTier;
+    this.pinCache = opts.pinCache;
   }
   /**
    * #724 I1 completion: a legacy (non-`perRecordKeys`) blob has no per-blob
@@ -435,7 +476,7 @@ var BlobSet = class _BlobSet {
    * DECLARED; a collection with an undeclared field (or no `blobFields` at
    * all) constructs fine and reaches this write path unguarded. Refuse the
    * write itself instead of broadening the construction mandate, which
-   * would over-refuse blobless tiered collections (`blobStrategy` is
+   * would over-refuse blobless tiered collections (`blobsStrategy` is
    * vault-wide, not per-collection). Called from every content-write entry
    * (`put()`, `publish()`) — never from a read path, so a pre-existing
    * legacy blob stays readable (back-compat).
@@ -582,7 +623,8 @@ var BlobSet = class _BlobSet {
       ...this.userId !== void 0 ? { userId: this.userId } : {},
       ...this.maxBlobBytes !== void 0 ? { maxBlobBytes: this.maxBlobBytes } : {},
       ...this.objectStore !== void 0 ? { objectStore: this.objectStore } : {},
-      ...this.blobFields !== void 0 ? { blobFields: this.blobFields } : {}
+      ...this.blobFields !== void 0 ? { blobFields: this.blobFields } : {},
+      ...this.pinCache !== void 0 ? { pinCache: this.pinCache } : {}
     });
   }
   /** The internal collection that holds slot metadata for this collection's blobs. */
@@ -1115,6 +1157,13 @@ var BlobSet = class _BlobSet {
    * which are fixed for the operation's lifetime in the marker (C1/C2).
    */
   async shredAllForRecord(ownerTier) {
+    if (this.pinCache) {
+      try {
+        const rows = await this.pinCache.store.entries(blobPinKey(this.vault, this.collection, this.recordId));
+        for (const { key } of rows) await this.pinCache.store.delete(key);
+      } catch {
+      }
+    }
     const tierArg = ownerTier ?? 0;
     const intent = await this.resolveShredIntent(tierArg);
     if (!intent) return this.unmarkedShred(tierArg);
@@ -1988,8 +2037,11 @@ var BlobSet = class _BlobSet {
     for (let i = 0; i < blob.chunkCount; i++) {
       const chunk = await this.readChunk(blob.eTag, i, blob.chunkCount, chunkKey);
       if (!chunk) {
-        throw new NotFoundError(
-          `Blob chunk ${i}/${blob.chunkCount} missing for eTag "${blob.eTag}" on record "${this.recordId}"`
+        throw new BlobOfflineError(
+          this.collection,
+          this.recordId,
+          void 0,
+          `chunk ${i}/${blob.chunkCount} for eTag "${blob.eTag}" is absent from the local store \u2014 content not yet synced to this device, or evicted (#808)`
         );
       }
       chunks.push(chunk);
@@ -2310,7 +2362,11 @@ var BlobSet = class _BlobSet {
   /**
    * Fetch all bytes for the named slot.
    * Returns `null` if the slot does not exist.
-   * Throws `NotFoundError` if the index entry exists but a chunk is missing.
+   * Throws `BlobOfflineError` if the content is not available locally (#808):
+   * an internal blob whose chunk envelopes are absent from the local store, or
+   * an external slot with no local cached copy while the object store is
+   * unreachable. External reads populate the device-local encrypted
+   * side-cache, so a repeat read is served locally (see `pin()`).
    */
   async get(slotName) {
     if (await this.ownerRecordElevated()) return null;
@@ -2318,15 +2374,14 @@ var BlobSet = class _BlobSet {
     const slot = slots[slotName];
     if (!slot) return null;
     if (slot.external) {
-      if (!this.objectStore) {
-        throw new NotFoundError(`Blob slot "${slotName}" is external but no objectStore is configured`);
-      }
-      return this.objectStore.getObject(slot.external.key);
+      return this.readExternal(slotName, slot);
     }
     const result = await this.loadBlobObject(slot.eTag);
     if (!result) return null;
     const blobDEK = this.encrypted ? await this.getDEK(dekKey(BLOB_COLLECTION, result.atTier)) : void 0;
-    return this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    const bytes = await this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    await this.recordLocalHit(slotName);
+    return bytes;
   }
   /**
    * A URL to fetch an `external` slot's object directly — presigned
@@ -2437,15 +2492,35 @@ var BlobSet = class _BlobSet {
   /**
    * List all slot entries for this record.
    * Returns metadata only — no chunk data is loaded.
+   *
+   * #808: when a pin registry is present (`withBlobs()`), each entry is
+   * annotated with this DEVICE's view — `pinned` / `lastAccessAt` /
+   * `cachedBytes` (see their `SlotInfo` doc comments). The annotations come
+   * from the device-local registry, never the vault store, and are what
+   * `vault.compact()`'s pin exemption + cache-budget LRU pass key off.
    */
   async list() {
     if (await this.ownerRecordElevated()) return [];
     const { slots } = await this.loadSlots();
-    return Object.entries(slots).map(([name, slot]) => {
+    const infos = Object.entries(slots).map(([name, slot]) => {
       const pub = { ...slot };
       delete pub.pendingRelease;
       return { name, ...pub };
     });
+    if (!this.pinCache) return infos;
+    const prefix = blobPinKey(this.vault, this.collection, this.recordId);
+    const rows = await this.pinCache.store.entries(prefix);
+    const byName = new Map(rows.map(({ key, entry }) => [key.slice(prefix.length), entry]));
+    return infos.map((info) => {
+      const entry = byName.get(info.name);
+      if (!entry) return info;
+      return {
+        ...info,
+        ...entry.pinned ? { pinned: true } : {},
+        ...entry.lastAccessAt !== void 0 ? { lastAccessAt: entry.lastAccessAt } : {},
+        ...entry.cachedBytes !== void 0 ? { cachedBytes: entry.cachedBytes } : {}
+      };
+    });
   }
   /**
    * Delete the named slot from this record.
@@ -2471,6 +2546,218 @@ var BlobSet = class _BlobSet {
       await this.releaseRef(eTagToRelease, 1, false).catch(() => {
       });
     }
+    if (this.pinCache) {
+      await this.pinCache.store.delete(this.pinKeyFor(slotName)).catch(() => {
+      });
+    }
+  }
+  // ─── Public API: Offline pinning + device-local cache (#808) ──────
+  /**
+   * Pin the named slot for offline availability ON THIS DEVICE.
+   *
+   * - Downloads eagerly (call while online): an internal blob's chunks are
+   *   fetched once to prove they are locally readable; an `external` slot's
+   *   bytes are fetched from the object store and kept in the device-local
+   *   side-cache, **encrypted** under the vault's `_blob` DEK via the same
+   *   enclave path as chunk encryption (the object-store copy sits outside
+   *   the ZK envelope by design; the local copy does not).
+   * - A pinned slot is EXEMPT from `vault.compact()` eviction — both the
+   *   `blobFields` policy pass and the `cacheBudget` LRU pass.
+   * - Pin state is device-local (never synced): it lives in the `withBlobs()`
+   *   pin registry, not in the vault store. Each device pins for itself.
+   *
+   * Throws `NotFoundError` for a missing slot and `BlobOfflineError` when the
+   * eager download cannot complete (offline).
+   */
+  async pin(slotName) {
+    this.assertKeyPartSafe(this.recordId, "record id");
+    this.assertKeyPartSafe(slotName, "slot name");
+    const pc = this.requirePinCache("pin");
+    if (await this.ownerRecordElevated()) {
+      throw new NotFoundError(`Slot "${slotName}" not found on record "${this.recordId}"`);
+    }
+    const { slots } = await this.loadSlots();
+    const slot = slots[slotName];
+    if (!slot) throw new NotFoundError(`Slot "${slotName}" not found on record "${this.recordId}"`);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (slot.external) {
+      const bytes = await this.readExternal(slotName, slot);
+      if (bytes === null) {
+        throw new NotFoundError(`External object for blob slot "${slotName}" is missing from the object store`);
+      }
+      const key2 = this.pinKeyFor(slotName);
+      const entry = await pc.store.get(key2);
+      if (entry?.cipher) {
+        await pc.store.set(key2, { ...entry, pinned: true, pinnedAt: entry.pinnedAt ?? now });
+      } else {
+        await this.cacheExternalCopy(slotName, bytes, { pin: true });
+      }
+      return;
+    }
+    const result = await this.loadBlobObject(slot.eTag);
+    if (!result) throw new NotFoundError(`BlobObject ${slot.eTag} not found`);
+    const blobDEK = this.encrypted ? await this.getDEK(dekKey(BLOB_COLLECTION, result.atTier)) : void 0;
+    await this.fetchAllChunks(result.blob, blobDEK, this.flatFallbackVerifyETag(slot.eTag, result.atTier));
+    const key = this.pinKeyFor(slotName);
+    const prev = await pc.store.get(key);
+    await pc.store.set(key, { ...prev ?? {}, pinned: true, pinnedAt: now, lastAccessAt: now });
+  }
+  /**
+   * Unpin the named slot on this device — it returns to the normal lifecycle:
+   * `blobFields` policy eviction applies again, and any local cached copy
+   * (external slots) stays but becomes budget-managed (`cacheBudget` LRU).
+   * A no-op when the slot is not pinned here.
+   */
+  async unpin(slotName) {
+    this.assertKeyPartSafe(slotName, "slot name");
+    const pc = this.requirePinCache("unpin");
+    const key = this.pinKeyFor(slotName);
+    const entry = await pc.store.get(key);
+    if (!entry?.pinned) return;
+    const rest = { ...entry, pinned: false };
+    delete rest.pinnedAt;
+    await pc.store.set(key, rest);
+  }
+  /** Whether the named slot is pinned for offline ON THIS DEVICE (#808). */
+  async isPinned(slotName) {
+    const pc = this.requirePinCache("isPinned");
+    const entry = await pc.store.get(this.pinKeyFor(slotName));
+    return entry?.pinned === true;
+  }
+  /**
+   * Drop this slot's device-local cached copy (the encrypted external
+   * side-cache) WITHOUT touching the slot, the vault store, or the object
+   * store. Returns the plaintext bytes freed (0 when nothing was cached, the
+   * slot is pinned — pinned copies are exempt — or no registry is present).
+   * The cache-budget pass inside `vault.compact()` is the expected caller;
+   * the LRU access row itself is kept.
+   */
+  async dropLocalCache(slotName) {
+    const pc = this.pinCache;
+    if (!pc) return 0;
+    const key = this.pinKeyFor(slotName);
+    const entry = await pc.store.get(key);
+    if (!entry || entry.pinned || !entry.cipher) return 0;
+    const freed = entry.cachedBytes ?? 0;
+    const rest = { ...entry };
+    delete rest.cipher;
+    delete rest.cachedBytes;
+    await pc.store.set(key, rest);
+    return freed;
+  }
+  // ─── Internal: device-local pin registry plumbing (#808) ──────────
+  /** This slot's registry key — see {@link blobPinKey}. */
+  pinKeyFor(slotName) {
+    return blobPinKey(this.vault, this.collection, this.recordId, slotName);
+  }
+  /** AAD binding for a cached external copy: the row's own registry key. */
+  pinCopyAAD(slotName) {
+    return new TextEncoder().encode(`pin:${this.pinKeyFor(slotName)}`);
+  }
+  requirePinCache(op) {
+    if (!this.pinCache) {
+      throw new ValidationError(
+        `BlobSet.${op}() requires the withBlobs() pin registry \u2014 this handle was constructed without one (#808)`
+      );
+    }
+    return this.pinCache;
+  }
+  /** KPI hit + LRU access stamp for a successful LOCAL read. No-op without a registry. */
+  async recordLocalHit(slotName, prev) {
+    const pc = this.pinCache;
+    if (!pc) return;
+    pc.stats.hits += 1;
+    const key = this.pinKeyFor(slotName);
+    const entry = prev ?? await pc.store.get(key);
+    await pc.store.set(key, { ...entry ?? { pinned: false }, lastAccessAt: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  /**
+   * Read an `external` slot (#808 taxonomy): local encrypted side-cache first
+   * (hit); else the object store (miss + `bytesDownloaded`), auto-caching the
+   * fetched bytes so the NEXT read — and any later offline read — is local.
+   * A network failure with no local copy is the typed `BlobOfflineError`;
+   * a genuinely absent object (fetch succeeded, nothing there) stays `null`.
+   */
+  async readExternal(slotName, slot) {
+    const pc = this.pinCache;
+    if (pc) {
+      const key = this.pinKeyFor(slotName);
+      const entry = await pc.store.get(key);
+      const cached = entry?.cipher ? await this.decryptCachedCopy(slotName, entry.cipher) : null;
+      if (cached) {
+        await this.recordLocalHit(slotName, entry);
+        return cached;
+      }
+    }
+    if (!this.objectStore) {
+      throw new NotFoundError(`Blob slot "${slotName}" is external but no objectStore is configured`);
+    }
+    let bytes;
+    try {
+      bytes = await this.objectStore.getObject(slot.external.key);
+    } catch (err) {
+      throw new BlobOfflineError(
+        this.collection,
+        this.recordId,
+        slotName,
+        "no local cached copy and the object store is unreachable \u2014 pin() the slot while online to keep it readable offline (#808)",
+        err
+      );
+    }
+    if (bytes === null) return null;
+    if (pc) {
+      pc.stats.misses += 1;
+      pc.stats.bytesDownloaded += bytes.byteLength;
+      await this.cacheExternalCopy(slotName, bytes).catch(() => {
+      });
+    }
+    return bytes;
+  }
+  /**
+   * Decrypt a cached external copy. `null` (treated as a cache miss → network
+   * refresh) when the vault keys can no longer open it — e.g. the copy was
+   * cached before the owning record moved tiers, so it is sealed under a DEK
+   * this handle no longer resolves. Genuine non-crypto failures propagate.
+   */
+  async decryptCachedCopy(slotName, cipher) {
+    if (!this.encrypted) return base64ToBuffer(cipher.data);
+    const dek = await this.getDEK(dekKey(BLOB_COLLECTION, await this.ownerTier()));
+    try {
+      return await decryptBytesWithAAD(cipher.iv, cipher.data, dek, this.pinCopyAAD(slotName));
+    } catch (err) {
+      if (err instanceof TamperedError) return null;
+      throw err;
+    }
+  }
+  /**
+   * Write an external slot's bytes into the device-local side-cache —
+   * ENCRYPTED under the vault's `_blob` DEK (owner tier) via the enclave's
+   * AAD-bound path, mirroring chunk encryption; base64 plaintext with
+   * `iv: ''` only on an unencrypted vault (the envelope convention). A
+   * pre-existing pin flag survives the rewrite.
+   */
+  async cacheExternalCopy(slotName, bytes, opts) {
+    const pc = this.pinCache;
+    if (!pc) return;
+    let cipher;
+    if (this.encrypted) {
+      const dek = await this.getDEK(dekKey(BLOB_COLLECTION, await this.ownerTier()));
+      const enc = await encryptBytesWithAAD(bytes, dek, this.pinCopyAAD(slotName));
+      cipher = { iv: enc.iv, data: enc.data };
+    } else {
+      cipher = { iv: "", data: bufferToBase64(bytes) };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const key = this.pinKeyFor(slotName);
+    const prev = await pc.store.get(key);
+    const pinned = opts?.pin === true || prev?.pinned === true;
+    await pc.store.set(key, {
+      pinned,
+      ...pinned ? { pinnedAt: (opts?.pin === true ? now : prev?.pinnedAt) ?? now } : {},
+      lastAccessAt: now,
+      cachedBytes: bytes.byteLength,
+      cipher
+    });
   }
   /**
    * Return a native `Response` whose body streams the decrypted,
@@ -2763,6 +3050,9 @@ async function plainSha256Hex(data) {
 }
 
 export {
+  memoryBlobPinStore,
+  createBlobPinCache,
+  blobPinKey,
   detectMimeType,
   detectMagic,
   isPreCompressed,
@@ -2779,4 +3069,4 @@ export {
   DEFAULT_CHUNK_SIZE,
   BlobSet
 };
-//# sourceMappingURL=chunk-5OI6BR4H.js.map
+//# sourceMappingURL=chunk-GWWOGNBK.js.map