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

package/dist/chunk-LASZKVMO.js

@@ -0,0 +1,382 @@
+import {
+  listUserEnvelopeIds,
+  loadUserEnvelope,
+  persistUserVisibility,
+  readUserVisibility,
+  saveUserEnvelope
+} from "./chunk-4JBYV75E.js";
+import {
+  PolicyDeniedError
+} from "./chunk-BIOUI4HL.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-LASZKVMO.js.map