@noy-db/hub 0.2.0-pre.9 → 0.3.0-pre.1

package/dist/chunk-UDRIWL7A.js

@@ -0,0 +1,382 @@
+import {
+  listUserEnvelopeIds,
+  loadUserEnvelope,
+  persistUserVisibility,
+  readUserVisibility,
+  saveUserEnvelope
+} from "./chunk-ITNUCOXM.js";
+import {
+  PolicyDeniedError
+} from "./chunk-ZYUC53LT.js";
+
+// src/with-party/directory/user-envelope/api.ts
+var UserApi = class {
+  /** keyringId → set of listeners. Wildcard '*' fires on every change. */
+  listeners = /* @__PURE__ */ new Map();
+  adapter;
+  vaultName;
+  /** The writer's own keyringId. Frozen at construction time. */
+  writerKeyringId;
+  getDek;
+  /**
+   * Policy-gate validator. When omitted, gates are skipped — useful
+   * for low-level tests that exercise the storage layer directly.
+   * Production paths always wire the Noydb-backed implementation.
+   */
+  checkGate;
+  /**
+   * Noydb-backed `exportMyAccessibleData`, injected by the Vault
+   * (which holds the keyring + bundle machinery). Omitted in low-level tests.
+   */
+  exportAccessible;
+  /**
+   * Noydb-backed `unilateralWithdrawal`, injected by the Vault.
+   * Destructive — extract + dispose (delete | freeze). Omitted in low-level tests.
+   */
+  unilateralWithdraw;
+  /**
+   * Noydb-backed two-party withdrawal ceremony, injected by the
+   * Vault. requestWithdraw = requester side; the rest = owner side.
+   */
+  requestWithdraw;
+  listWithdrawals;
+  approveWithdraw;
+  rejectWithdraw;
+  constructor(deps) {
+    this.adapter = deps.adapter;
+    this.vaultName = deps.vaultName;
+    this.writerKeyringId = deps.writerKeyringId;
+    this.getDek = deps.getDek;
+    this.checkGate = deps.checkGate;
+    this.exportAccessible = deps.exportAccessible;
+    this.unilateralWithdraw = deps.unilateralWithdraw;
+    this.requestWithdraw = deps.requestWithdraw;
+    this.listWithdrawals = deps.listWithdrawals;
+    this.approveWithdraw = deps.approveWithdraw;
+    this.rejectWithdraw = deps.rejectWithdraw;
+  }
+  /**
+   * File a two-party withdrawal request for the caller's accessible
+   * scope. Non-destructive (writes a pending request); an owner later approves
+   * or rejects. This is the path for read-only roles (`client`/`viewer`) that
+   * cannot self-serve a destructive `unilateralWithdrawal`. Gated by
+   * `user-request-withdrawal` (enabled by default).
+   */
+  async requestWithdrawal(opts = {}) {
+    if (this.checkGate) await this.checkGate("user-request-withdrawal");
+    if (!this.requestWithdraw) {
+      throw new Error("requestWithdrawal requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.requestWithdraw(opts);
+  }
+  /** Owner side: list filed withdrawal requests (optionally by status). */
+  async listWithdrawalRequests(opts = {}) {
+    if (!this.listWithdrawals) {
+      throw new Error("listWithdrawalRequests requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.listWithdrawals(opts);
+  }
+  /**
+   * Owner side: approve a pending request. Extracts the requester's
+   * recorded scope under firm authority, disposes of the source per the
+   * request's disposition, and returns the re-keyed bundle to hand back. Gated
+   * by `approve-user-withdrawal` (tier-2 default) + owner/admin role.
+   */
+  async approveWithdrawal(requestId, opts = {}) {
+    if (this.checkGate) await this.checkGate("approve-user-withdrawal");
+    if (!this.approveWithdraw) {
+      throw new Error("approveWithdrawal requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.approveWithdraw(requestId, opts);
+  }
+  /** Owner side: reject a pending request (no data is touched). */
+  async rejectWithdrawal(requestId, opts = {}) {
+    if (this.checkGate) await this.checkGate("approve-user-withdrawal");
+    if (!this.rejectWithdraw) {
+      throw new Error("rejectWithdrawal requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.rejectWithdraw(requestId, opts);
+  }
+  /**
+   * Single-party withdrawal: export the caller's accessible scope
+   * (re-keyed) and dispose of the source (`delete` or `freeze`). Gated by the
+   * fail-closed built-in `client-unilateral-withdraw` policy — undefined or
+   * disabled → throws (use `requestWithdrawal`). The firm enables it at vault
+   * creation.
+   */
+  async unilateralWithdrawal(opts) {
+    if (this.checkGate) await this.checkGate("client-unilateral-withdraw");
+    if (!this.unilateralWithdraw) {
+      throw new Error("unilateralWithdrawal requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.unilateralWithdraw(opts);
+  }
+  /**
+   * Export the calling user's accessible scope as a portable, re-keyed
+   * `.noydb` bundle. Non-destructive and **always allowed** (data sovereignty
+   * by construction) but audited. Scope = the caller's DEK access set.
+   */
+  async exportMyAccessibleData(opts = {}) {
+    if (!this.exportAccessible) {
+      throw new Error("exportMyAccessibleData requires a Noydb-backed vault (not a bare UserApi)");
+    }
+    return this.exportAccessible(opts);
+  }
+  // ─── Write-self ──────────────────────────────────────────────────────
+  /** Read the writer's own envelope. Returns null if never written. */
+  async me() {
+    const dek = await this.getDek();
+    return loadUserEnvelope(this.adapter, this.vaultName, this.writerKeyringId, dek);
+  }
+  /**
+   * Deep-merge a partial patch into the writer's own envelope. Creates
+   * the envelope on first call. Optimistic-concurrency safe — a stale
+   * `_v` (parallel writer on another device) throws `ConflictError`.
+   *
+   * Patch semantics:
+   *   - `undefined` (or omitted key) — skip; existing value preserved
+   *   - `null` — delete the field from the merged result
+   *   - any other value — overwrite (deep-merge for plain objects,
+   *     replace for primitives / arrays)
+   *
+   * To clear a field, pass `null` rather than `undefined`. Callers
+   * with shape `T = string | null` where `null` is a meaningful value
+   * should use `setMe` for that specific field instead — `null` here
+   * always means delete.
+   *
+   * Gated by the `edit-own-profile` policy gate (default `minTier: 3`).
+   * Pass `presented` to satisfy tightened policies that require a
+   * factor proof (e.g. STRICT_POLICY's TOTP requirement).
+   */
+  async updateMe(patch, presented) {
+    if (this.checkGate) await this.checkGate("edit-own-profile", presented);
+    const dek = await this.getDek();
+    const current = await loadUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      dek
+    );
+    const merged = current ? deepMerge(current.data, patch) : patch;
+    const written = await saveUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      merged,
+      dek,
+      current?._v ?? 0
+    );
+    this.fireChange(this.writerKeyringId, written);
+    return written;
+  }
+  /**
+   * Replace the writer's own envelope with `payload`. Use sparingly —
+   * `updateMe` is the canonical mutation. No `expectedVersion` check;
+   * callers explicitly take last-write-wins semantics.
+   *
+   * Gated by `edit-own-profile`. See `updateMe` for `presented` usage.
+   */
+  async setMe(payload, presented) {
+    if (this.checkGate) await this.checkGate("edit-own-profile", presented);
+    const dek = await this.getDek();
+    const written = await saveUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      payload,
+      dek
+    );
+    this.fireChange(this.writerKeyringId, written);
+    return written;
+  }
+  // ─── Visibility ──────────────────────────────────────────────────────
+  /**
+   * Read the current user's visibility flag from
+   * `_meta/visibility/<keyringId>`. Returns `{ hidden: false }` when no
+   * document has been persisted (the default-visible case).
+   */
+  async getMyVisibility() {
+    const persisted = await readUserVisibility(this.adapter, this.vaultName, this.writerKeyringId);
+    return persisted ?? { hidden: false };
+  }
+  /**
+   * Update the current user's visibility in the team directory.
+   *
+   * - `hidden: true` — opt out of the default `listUsersWithEnvelopes`
+   *   listing. `owner`/`admin` callers can still see the user by passing
+   *   `{ includeHidden: true }`.
+   * - `hidden: false` — opt back in.
+   *
+   * Own-only by construction: the keyringId argument doesn't exist on
+   * this method, so no caller can hide or unhide another principal.
+   *
+   * Honest caveat: this is a UX flag, not a privacy guarantee. The
+   * envelope ciphertext at `_users/<keyringId>` and the keyring file at
+   * `_keyring/<userId>` are both still observable to anyone with direct
+   * store read access. See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+   * "Directory visibility".
+   */
+  async setMyVisibility(visibility) {
+    await persistUserVisibility(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      { hidden: visibility.hidden }
+    );
+  }
+  // ─── Read-anyone ─────────────────────────────────────────────────────
+  /**
+   * Read another principal's envelope by their keyringId. Returns null
+   * if the principal exists but has no envelope yet, or if the
+   * keyringId does not exist at all.
+   *
+   * Gated by `view-team-profiles` (default `minTier: 2`) — but ONLY for
+   * cross-principal reads. Reading your own envelope (`keyringId ===
+   * self`) is never gated; that's just `me()` written long-form.
+   */
+  async get(keyringId, presented) {
+    if (this.checkGate && keyringId !== this.writerKeyringId) {
+      await this.checkGate("view-team-profiles", presented);
+    }
+    const dek = await this.getDek();
+    return loadUserEnvelope(this.adapter, this.vaultName, keyringId, dek);
+  }
+  /**
+   * Read every persisted envelope in the vault. Order is store-defined.
+   *
+   * Gated by `view-team-profiles`. Default policy (`minTier: 2`) lets
+   * any authenticated session read all envelopes. Two privacy-strict
+   * opt-outs:
+   *
+   *  - `view-team-profiles.enabled: false` → list() returns only the
+   *    caller's own envelope (silent self-fallback, no thrown error).
+   *  - `view-team-profiles.minTier: 1` + insufficient tier → throws
+   *    `PolicyDeniedError` with `reason: 'insufficient-tier'`. The
+   *    caller is expected to elevate, not silently degrade.
+   *
+   * The asymmetry is deliberate: `enabled: false` is a deliberate
+   * design choice ("nobody sees teammate profiles in this app");
+   * `insufficient-tier` is "you need to authenticate further". Different
+   * UX prompts for different intents.
+   */
+  async list(presented) {
+    if (this.checkGate) {
+      try {
+        await this.checkGate("view-team-profiles", presented);
+      } catch (err) {
+        if (err instanceof PolicyDeniedError && err.reason === "disabled") {
+          const me = await this.me();
+          return me ? [me] : [];
+        }
+        throw err;
+      }
+    }
+    const dek = await this.getDek();
+    const ids = await listUserEnvelopeIds(this.adapter, this.vaultName);
+    const envelopes = await Promise.all(
+      ids.map((id) => loadUserEnvelope(this.adapter, this.vaultName, id, dek))
+    );
+    return envelopes.filter((e) => e !== null);
+  }
+  // ─── Reactive ────────────────────────────────────────────────────────
+  /**
+   * Listen for changes to a specific keyringId's envelope. The callback
+   * fires synchronously after every successful local `updateMe` /
+   * `setMe` for that principal.
+   *
+   * Cross-instance changes (a teammate edits their profile on their
+   * device, the sync engine pulls the diff onto this device) will fire
+   * subscribers when the sync layer replays the write through this API.
+   * In v1, subscribers do NOT fire on raw store changes — wire your sync
+   * layer to call back through `vault.user.setMe` / `updateMe` if you
+   * need that.
+   *
+   * Pass keyringId `'*'` to fire on every change in the vault.
+   */
+  subscribe(keyringId, cb) {
+    let listeners = this.listeners.get(keyringId);
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.listeners.set(keyringId, listeners);
+    }
+    const wrapped = cb;
+    listeners.add(wrapped);
+    return () => {
+      listeners?.delete(wrapped);
+      if (listeners && listeners.size === 0) {
+        this.listeners.delete(keyringId);
+      }
+    };
+  }
+  /**
+   * Reactive handle that caches the current value and re-reads on every
+   * change for the given keyringId. Convenient for framework bindings:
+   *
+   *   const live = vault.user.live<UserShape>(vault.userId)
+   *   live.subscribe(env => render(env?.data))
+   *
+   * Initial value is `null` until the first `current()` call materializes
+   * it via `vault.user.get()`. Call `stop()` when done to release the
+   * subscription.
+   */
+  live(keyringId) {
+    let value = null;
+    let primed = false;
+    const unsubscribe = this.subscribe(keyringId, (env) => {
+      value = env;
+    });
+    return {
+      current() {
+        if (!primed) {
+          primed = true;
+        }
+        return value;
+      },
+      subscribe: (cb) => this.subscribe(keyringId, cb),
+      stop: unsubscribe
+    };
+  }
+  // ─── Internal: change emission ───────────────────────────────────────
+  fireChange(keyringId, env) {
+    const targeted = this.listeners.get(keyringId);
+    if (targeted) for (const l of targeted) l(env);
+    const wildcard = this.listeners.get("*");
+    if (wildcard) for (const l of wildcard) l(env);
+  }
+};
+var createUserApi = (deps) => new UserApi(deps);
+function deepMerge(source, patch) {
+  if (!isPlainObject(source) || !isPlainObject(patch)) {
+    return patch;
+  }
+  const out = { ...source };
+  for (const [key, patchVal] of Object.entries(patch)) {
+    if (patchVal === void 0) {
+      continue;
+    }
+    if (patchVal === null) {
+      delete out[key];
+      continue;
+    }
+    const sourceVal = source[key];
+    if (isPlainObject(patchVal)) {
+      const recurseSource = isPlainObject(sourceVal) ? sourceVal : {};
+      out[key] = deepMerge(recurseSource, patchVal);
+    } else {
+      out[key] = patchVal;
+    }
+  }
+  return out;
+}
+function isPlainObject(x) {
+  if (x === null || typeof x !== "object") return false;
+  if (Array.isArray(x)) return false;
+  const proto = Object.getPrototypeOf(x);
+  return proto === Object.prototype || proto === null;
+}
+
+export {
+  UserApi,
+  createUserApi
+};
+//# sourceMappingURL=chunk-UDRIWL7A.js.map

package/dist/chunk-UDRIWL7A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/directory/user-envelope/api.ts"],"sourcesContent":["/**\n * Public `vault.user.*` API surface.\n *\n * Three families:\n *  - Write-self: `me` / `updateMe` / `setMe` — always target the writer's\n *    own keyringId. **Own-only write rule** is structural — no method\n *    exists to write someone else's envelope.\n *  - Read-anyone: `get` / `list` — read other principals' envelopes\n *    (subject to `view-team-profiles` policy gate).\n *  - Reactive: `subscribe` / `live` — in-process event emission on local\n *    writes. Cross-instance updates land via the team/sync engine and\n *    surface to subscribers when the sync diff replays through this API.\n *\n * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md\n *\n * @module\n */\nimport { PolicyDeniedError } from '../../../kernel/errors.js'\nimport {\n  loadUserEnvelope,\n  saveUserEnvelope,\n  listUserEnvelopeIds,\n} from './storage.js'\nimport type {\n  UserEnvelope,\n  DeepPartialOrNull,\n  Unsubscribe,\n  UserEnvelopePresented,\n  LiveUserEnvelope,\n  VaultUserApi,\n  UserApiDeps,\n  UserApiFactory,\n} from '../../../kernel/types.js'\nimport {\n  persistUserVisibility,\n  readUserVisibility,\n} from '../visibility.js'\nimport type { UserVisibility } from '../types.js'\nimport type { ExportAccessibleOptions } from '../../../with-audit/portability/export-accessible.js'\nimport type { WithdrawAccessibleOptions, WithdrawResult } from '../../../with-audit/portability/withdraw-accessible.js'\nimport type {\n  RequestWithdrawalOptions,\n  RequestWithdrawalResult,\n  WithdrawalRequest,\n  WithdrawalRequestStatus,\n  ApproveWithdrawalOptions,\n  RejectWithdrawalOptions,\n} from '../../../with-audit/portability/request-withdrawal.js'\n\ninterface ChangeListener<T = unknown> {\n  (env: UserEnvelope<T> | null): void\n}\n\n/**\n * Implementation behind `vault.user`. Constructed once per Vault via\n * {@link createUserApi}, holds the writer's keyringId in closure so\n * `updateMe`/`setMe` cannot target any other principal — the own-only\n * rule is enforced at the type level (no `set(otherKeyringId, …)`\n * method) AND at runtime (the keyringId argument simply doesn't exist\n * on the write path).\n */\nexport class UserApi implements VaultUserApi {\n  /** keyringId → set of listeners. Wildcard '*' fires on every change. */\n  private readonly listeners = new Map<string, Set<ChangeListener>>()\n\n  private readonly adapter: UserApiDeps['adapter']\n  private readonly vaultName: UserApiDeps['vaultName']\n  /** The writer's own keyringId. Frozen at construction time. */\n  private readonly writerKeyringId: UserApiDeps['writerKeyringId']\n  private readonly getDek: UserApiDeps['getDek']\n  /**\n   * Policy-gate validator. When omitted, gates are skipped — useful\n   * for low-level tests that exercise the storage layer directly.\n   * Production paths always wire the Noydb-backed implementation.\n   */\n  private readonly checkGate?: UserApiDeps['checkGate']\n  /**\n   * Noydb-backed `exportMyAccessibleData`, injected by the Vault\n   * (which holds the keyring + bundle machinery). Omitted in low-level tests.\n   */\n  private readonly exportAccessible?: UserApiDeps['exportAccessible']\n  /**\n   * Noydb-backed `unilateralWithdrawal`, injected by the Vault.\n   * Destructive — extract + dispose (delete | freeze). Omitted in low-level tests.\n   */\n  private readonly unilateralWithdraw?: UserApiDeps['unilateralWithdraw']\n  /**\n   * Noydb-backed two-party withdrawal ceremony, injected by the\n   * Vault. requestWithdraw = requester side; the rest = owner side.\n   */\n  private readonly requestWithdraw?: UserApiDeps['requestWithdraw']\n  private readonly listWithdrawals?: UserApiDeps['listWithdrawals']\n  private readonly approveWithdraw?: UserApiDeps['approveWithdraw']\n  private readonly rejectWithdraw?: UserApiDeps['rejectWithdraw']\n\n  constructor(deps: UserApiDeps) {\n    this.adapter = deps.adapter\n    this.vaultName = deps.vaultName\n    this.writerKeyringId = deps.writerKeyringId\n    this.getDek = deps.getDek\n    this.checkGate = deps.checkGate\n    this.exportAccessible = deps.exportAccessible\n    this.unilateralWithdraw = deps.unilateralWithdraw\n    this.requestWithdraw = deps.requestWithdraw\n    this.listWithdrawals = deps.listWithdrawals\n    this.approveWithdraw = deps.approveWithdraw\n    this.rejectWithdraw = deps.rejectWithdraw\n  }\n\n  /**\n   * File a two-party withdrawal request for the caller's accessible\n   * scope. Non-destructive (writes a pending request); an owner later approves\n   * or rejects. This is the path for read-only roles (`client`/`viewer`) that\n   * cannot self-serve a destructive `unilateralWithdrawal`. Gated by\n   * `user-request-withdrawal` (enabled by default).\n   */\n  async requestWithdrawal(opts: RequestWithdrawalOptions = {}): Promise<RequestWithdrawalResult> {\n    if (this.checkGate) await this.checkGate('user-request-withdrawal')\n    if (!this.requestWithdraw) {\n      throw new Error('requestWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.requestWithdraw(opts)\n  }\n\n  /** Owner side: list filed withdrawal requests (optionally by status). */\n  async listWithdrawalRequests(opts: { status?: WithdrawalRequestStatus } = {}): Promise<WithdrawalRequest[]> {\n    if (!this.listWithdrawals) {\n      throw new Error('listWithdrawalRequests requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.listWithdrawals(opts)\n  }\n\n  /**\n   * Owner side: approve a pending request. Extracts the requester's\n   * recorded scope under firm authority, disposes of the source per the\n   * request's disposition, and returns the re-keyed bundle to hand back. Gated\n   * by `approve-user-withdrawal` (tier-2 default) + owner/admin role.\n   */\n  async approveWithdrawal(requestId: string, opts: ApproveWithdrawalOptions = {}): Promise<WithdrawResult> {\n    if (this.checkGate) await this.checkGate('approve-user-withdrawal')\n    if (!this.approveWithdraw) {\n      throw new Error('approveWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.approveWithdraw(requestId, opts)\n  }\n\n  /** Owner side: reject a pending request (no data is touched). */\n  async rejectWithdrawal(requestId: string, opts: RejectWithdrawalOptions = {}): Promise<WithdrawalRequest> {\n    if (this.checkGate) await this.checkGate('approve-user-withdrawal')\n    if (!this.rejectWithdraw) {\n      throw new Error('rejectWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.rejectWithdraw(requestId, opts)\n  }\n\n  /**\n   * Single-party withdrawal: export the caller's accessible scope\n   * (re-keyed) and dispose of the source (`delete` or `freeze`). Gated by the\n   * fail-closed built-in `client-unilateral-withdraw` policy — undefined or\n   * disabled → throws (use `requestWithdrawal`). The firm enables it at vault\n   * creation.\n   */\n  async unilateralWithdrawal(opts: WithdrawAccessibleOptions): Promise<WithdrawResult> {\n    if (this.checkGate) await this.checkGate('client-unilateral-withdraw')\n    if (!this.unilateralWithdraw) {\n      throw new Error('unilateralWithdrawal requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.unilateralWithdraw(opts)\n  }\n\n  /**\n   * Export the calling user's accessible scope as a portable, re-keyed\n   * `.noydb` bundle. Non-destructive and **always allowed** (data sovereignty\n   * by construction) but audited. Scope = the caller's DEK access set.\n   */\n  async exportMyAccessibleData(opts: ExportAccessibleOptions = {}): Promise<Uint8Array> {\n    if (!this.exportAccessible) {\n      throw new Error('exportMyAccessibleData requires a Noydb-backed vault (not a bare UserApi)')\n    }\n    return this.exportAccessible(opts)\n  }\n\n  // ─── Write-self ──────────────────────────────────────────────────────\n\n  /** Read the writer's own envelope. Returns null if never written. */\n  async me<T = unknown>(): Promise<UserEnvelope<T> | null> {\n    const dek = await this.getDek()\n    return loadUserEnvelope<T>(this.adapter, this.vaultName, this.writerKeyringId, dek)\n  }\n\n  /**\n   * Deep-merge a partial patch into the writer's own envelope. Creates\n   * the envelope on first call. Optimistic-concurrency safe — a stale\n   * `_v` (parallel writer on another device) throws `ConflictError`.\n   *\n   * Patch semantics:\n   *   - `undefined` (or omitted key) — skip; existing value preserved\n   *   - `null` — delete the field from the merged result\n   *   - any other value — overwrite (deep-merge for plain objects,\n   *     replace for primitives / arrays)\n   *\n   * To clear a field, pass `null` rather than `undefined`. Callers\n   * with shape `T = string | null` where `null` is a meaningful value\n   * should use `setMe` for that specific field instead — `null` here\n   * always means delete.\n   *\n   * Gated by the `edit-own-profile` policy gate (default `minTier: 3`).\n   * Pass `presented` to satisfy tightened policies that require a\n   * factor proof (e.g. STRICT_POLICY's TOTP requirement).\n   */\n  async updateMe<T extends object = Record<string, unknown>>(\n    patch: DeepPartialOrNull<T>,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T>> {\n    if (this.checkGate) await this.checkGate('edit-own-profile', presented)\n    const dek = await this.getDek()\n    const current = await loadUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      dek,\n    )\n    const merged: T = current ? deepMerge(current.data, patch) : (patch as unknown as T)\n    const written = await saveUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      merged,\n      dek,\n      current?._v ?? 0,\n    )\n    this.fireChange(this.writerKeyringId, written)\n    return written\n  }\n\n  /**\n   * Replace the writer's own envelope with `payload`. Use sparingly —\n   * `updateMe` is the canonical mutation. No `expectedVersion` check;\n   * callers explicitly take last-write-wins semantics.\n   *\n   * Gated by `edit-own-profile`. See `updateMe` for `presented` usage.\n   */\n  async setMe<T = unknown>(\n    payload: T,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T>> {\n    if (this.checkGate) await this.checkGate('edit-own-profile', presented)\n    const dek = await this.getDek()\n    const written = await saveUserEnvelope<T>(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      payload,\n      dek,\n    )\n    this.fireChange(this.writerKeyringId, written)\n    return written\n  }\n\n  // ─── Visibility ──────────────────────────────────────────────────────\n\n  /**\n   * Read the current user's visibility flag from\n   * `_meta/visibility/<keyringId>`. Returns `{ hidden: false }` when no\n   * document has been persisted (the default-visible case).\n   */\n  async getMyVisibility(): Promise<UserVisibility> {\n    const persisted = await readUserVisibility(this.adapter, this.vaultName, this.writerKeyringId)\n    return persisted ?? { hidden: false }\n  }\n\n  /**\n   * Update the current user's visibility in the team directory.\n   *\n   * - `hidden: true` — opt out of the default `listUsersWithEnvelopes`\n   *   listing. `owner`/`admin` callers can still see the user by passing\n   *   `{ includeHidden: true }`.\n   * - `hidden: false` — opt back in.\n   *\n   * Own-only by construction: the keyringId argument doesn't exist on\n   * this method, so no caller can hide or unhide another principal.\n   *\n   * Honest caveat: this is a UX flag, not a privacy guarantee. The\n   * envelope ciphertext at `_users/<keyringId>` and the keyring file at\n   * `_keyring/<userId>` are both still observable to anyone with direct\n   * store read access. See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →\n   * \"Directory visibility\".\n   */\n  async setMyVisibility(visibility: UserVisibility): Promise<void> {\n    await persistUserVisibility(\n      this.adapter,\n      this.vaultName,\n      this.writerKeyringId,\n      { hidden: visibility.hidden },\n    )\n  }\n\n  // ─── Read-anyone ─────────────────────────────────────────────────────\n\n  /**\n   * Read another principal's envelope by their keyringId. Returns null\n   * if the principal exists but has no envelope yet, or if the\n   * keyringId does not exist at all.\n   *\n   * Gated by `view-team-profiles` (default `minTier: 2`) — but ONLY for\n   * cross-principal reads. Reading your own envelope (`keyringId ===\n   * self`) is never gated; that's just `me()` written long-form.\n   */\n  async get<T = unknown>(\n    keyringId: string,\n    presented?: UserEnvelopePresented,\n  ): Promise<UserEnvelope<T> | null> {\n    if (this.checkGate && keyringId !== this.writerKeyringId) {\n      await this.checkGate('view-team-profiles', presented)\n    }\n    const dek = await this.getDek()\n    return loadUserEnvelope<T>(this.adapter, this.vaultName, keyringId, dek)\n  }\n\n  /**\n   * Read every persisted envelope in the vault. Order is store-defined.\n   *\n   * Gated by `view-team-profiles`. Default policy (`minTier: 2`) lets\n   * any authenticated session read all envelopes. Two privacy-strict\n   * opt-outs:\n   *\n   *  - `view-team-profiles.enabled: false` → list() returns only the\n   *    caller's own envelope (silent self-fallback, no thrown error).\n   *  - `view-team-profiles.minTier: 1` + insufficient tier → throws\n   *    `PolicyDeniedError` with `reason: 'insufficient-tier'`. The\n   *    caller is expected to elevate, not silently degrade.\n   *\n   * The asymmetry is deliberate: `enabled: false` is a deliberate\n   * design choice (\"nobody sees teammate profiles in this app\");\n   * `insufficient-tier` is \"you need to authenticate further\". Different\n   * UX prompts for different intents.\n   */\n  async list<T = unknown>(presented?: UserEnvelopePresented): Promise<UserEnvelope<T>[]> {\n    if (this.checkGate) {\n      try {\n        await this.checkGate('view-team-profiles', presented)\n      } catch (err) {\n        if (err instanceof PolicyDeniedError && err.reason === 'disabled') {\n          // Privacy-strict opt-out: quietly return only self.\n          const me = await this.me<T>()\n          return me ? [me] : []\n        }\n        throw err\n      }\n    }\n    const dek = await this.getDek()\n    const ids = await listUserEnvelopeIds(this.adapter, this.vaultName)\n    const envelopes = await Promise.all(\n      ids.map((id) => loadUserEnvelope<T>(this.adapter, this.vaultName, id, dek)),\n    )\n    return envelopes.filter((e): e is UserEnvelope<T> => e !== null)\n  }\n\n  // ─── Reactive ────────────────────────────────────────────────────────\n\n  /**\n   * Listen for changes to a specific keyringId's envelope. The callback\n   * fires synchronously after every successful local `updateMe` /\n   * `setMe` for that principal.\n   *\n   * Cross-instance changes (a teammate edits their profile on their\n   * device, the sync engine pulls the diff onto this device) will fire\n   * subscribers when the sync layer replays the write through this API.\n   * In v1, subscribers do NOT fire on raw store changes — wire your sync\n   * layer to call back through `vault.user.setMe` / `updateMe` if you\n   * need that.\n   *\n   * Pass keyringId `'*'` to fire on every change in the vault.\n   */\n  subscribe<T = unknown>(\n    keyringId: string,\n    cb: (env: UserEnvelope<T> | null) => void,\n  ): Unsubscribe {\n    let listeners = this.listeners.get(keyringId)\n    if (!listeners) {\n      listeners = new Set()\n      this.listeners.set(keyringId, listeners)\n    }\n    const wrapped: ChangeListener = cb as ChangeListener\n    listeners.add(wrapped)\n    return () => {\n      listeners?.delete(wrapped)\n      if (listeners && listeners.size === 0) {\n        this.listeners.delete(keyringId)\n      }\n    }\n  }\n\n  /**\n   * Reactive handle that caches the current value and re-reads on every\n   * change for the given keyringId. Convenient for framework bindings:\n   *\n   *   const live = vault.user.live<UserShape>(vault.userId)\n   *   live.subscribe(env => render(env?.data))\n   *\n   * Initial value is `null` until the first `current()` call materializes\n   * it via `vault.user.get()`. Call `stop()` when done to release the\n   * subscription.\n   */\n  live<T = unknown>(keyringId: string): LiveUserEnvelope<T> {\n    let value: UserEnvelope<T> | null = null\n    let primed = false\n    const unsubscribe = this.subscribe<T>(keyringId, (env) => {\n      value = env\n    })\n\n    return {\n      current(): UserEnvelope<T> | null {\n        if (!primed) {\n          primed = true\n          // First call: kick off a read but return synchronously. The\n          // subscriber will be re-fired by the next write or the caller\n          // can await `vault.user.get()` directly for an immediate read.\n        }\n        return value\n      },\n      subscribe: (cb) => this.subscribe<T>(keyringId, cb),\n      stop: unsubscribe,\n    }\n  }\n\n  // ─── Internal: change emission ───────────────────────────────────────\n\n  private fireChange<T>(keyringId: string, env: UserEnvelope<T> | null): void {\n    const targeted = this.listeners.get(keyringId)\n    if (targeted) for (const l of targeted) l(env)\n    const wildcard = this.listeners.get('*')\n    if (wildcard) for (const l of wildcard) l(env)\n  }\n}\n\n/**\n * Build the `vault.user` API implementation from its dependencies. This is\n * the real {@link UserApiFactory} — `createNoydb()` dynamically imports it\n * and stashes it on the `Noydb` instance so `Vault`'s constructor can call\n * it synchronously.\n */\nexport const createUserApi: UserApiFactory = (deps: UserApiDeps): VaultUserApi => new UserApi(deps)\n\n/**\n * Recursive plain-object deep merge with delete intent.\n *\n * Patch semantics:\n *   - `undefined` — skip the key; source value preserved\n *   - `null` — delete the key from output (lodash `_.merge` /\n *     Firestore `FieldValue.delete()` semantics)\n *   - plain object — recurse (deep merge)\n *   - any other value — replace (arrays are replaced, not concatenated)\n *\n * Safe against the JS quirk where an own property explicitly set to\n * `undefined` is iterated by `Object.entries`. We dispatch on the value\n * BEFORE writing, so `{ k: undefined }` triggers the skip branch rather\n * than overwriting `out[k]` with undefined.\n */\nfunction deepMerge<T>(source: T, patch: DeepPartialOrNull<T>): T {\n  if (!isPlainObject(source) || !isPlainObject(patch)) {\n    // Top-level non-object replace. `null` patch at the leaf level\n    // would have been caught by the parent recursion's branch table;\n    // at the top level it means \"set the whole envelope to null,\"\n    // which the type system already prevents (T extends object).\n    return patch as unknown as T\n  }\n  const out: Record<string, unknown> = { ...(source as Record<string, unknown>) }\n  for (const [key, patchVal] of Object.entries(patch as Record<string, unknown>)) {\n    if (patchVal === undefined) {\n      // Skip — preserve the source value at this key. Matches the\n      // pre-existing behavior so callers who never used `null` see no diff.\n      continue\n    }\n    if (patchVal === null) {\n      // Delete intent. `delete` rather than `out[key] = undefined`\n      // because JSON.stringify drops undefined fields silently and\n      // we want the deletion to be visible to consumers iterating\n      // the merged object (e.g. `Object.keys(merged.profile)`).\n      delete out[key]\n      continue\n    }\n    const sourceVal = (source as Record<string, unknown>)[key]\n    if (isPlainObject(patchVal)) {\n      // Recurse for any plain-object patch — including the \"source is\n      // missing this key\" case. Without recursing through a synthetic\n      // empty source, nested `null` deletions in the patch would land\n      // as literal `null` values instead of triggering the delete\n      // branch (e.g. `{ app: { signature: null } }` against a missing\n      // `app` would emit `{ app: { signature: null } }` instead of\n      // `{ app: {} }`).\n      const recurseSource = isPlainObject(sourceVal) ? sourceVal : {}\n      out[key] = deepMerge(recurseSource, patchVal as DeepPartialOrNull<typeof recurseSource>)\n    } else {\n      out[key] = patchVal\n    }\n  }\n  return out as T\n}\n\nfunction isPlainObject(x: unknown): x is Record<string, unknown> {\n  if (x === null || typeof x !== 'object') return false\n  if (Array.isArray(x)) return false\n  const proto = Object.getPrototypeOf(x) as object | null\n  return proto === Object.prototype || proto === null\n}\n"],"mappings":"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","names":[]}