@promptowl/contextnest-community 1.19.0 → 1.21.0

package/CONFIGURATION.md

@@ -60,7 +60,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `PROMPTOWL_SIGN_IN_GATE` | `open` | Restrict "Sign in with PromptOwl". `open` = anyone may; `admin-only` = only the license owner (admin) may, everyone else uses email/password (admin opens the login page with `?admin=1`); `disabled` = nobody may. Enforced server-side at `POST /auth/promptowl` and surfaced on the health endpoint. Unknown values fall back to `open`. |
 | `MANUAL_SIGN_IN` | `open` | Email + password sign-in mode. `open` = anyone may log in and self-register a new account; `invite-only` = existing/invited users may log in but brand-new self-registration returns `403` (the admin provisions accounts via invite/share/steward and shares the password — there is no self-service "set password", which would be account takeover without email verification); `disabled` = no email/password sign-in at all (`POST /auth/login` and `POST /auth/register` return `403`). Independent of `PROMPTOWL_SIGN_IN_GATE`, so the two methods are controlled separately (e.g. `invite-only` manual + `admin-only` PromptOwl). Also settable from Settings → General. The server refuses `disabled` while PromptOwl sign-in is also `disabled` (that would leave no way to log in). Unknown values fall back to `open`. |
 | `OFFICIAL_COMMUNITY_SSO_SECRET` | `""` | **Official deployment only — leave unset on self-hosted.** Shared HMAC secret enabling the one-click "Open Community" SSO auto-login from PromptOwl. Must exactly match the same-named var on PromptOwl. When unset, `GET /auth/sso` returns `404` and the feature is disabled; self-hosted users keep using the manual device-code flow. |
-| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Three uses. (1) Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another — only when `OFFICIAL_COMMUNITY_SSO_SECRET` is set; when unset, the audience check is skipped. (2) **Set this whenever `OIDC_ENABLED=true`.** It's the base for the OIDC `redirect_uri` sent to your IdP and replayed at token exchange. Unset, that URI is derived from the incoming request's `Host` header — fine when your proxy overwrites `Host` with a trusted value, but a proxy that passes an attacker-supplied `Host` through would feed it straight into the redirect URI. Setting this pins the value regardless of what the proxy forwards. (Your IdP's own redirect-URI allowlist is a second line of defence, not a substitute.) (3) **Set this wherever `POST /nests/:id/context` citations reach users.** The `url` on each node and the `_source:` line in each context block are built from it; unset, they fall back to the request origin, so a proxy forwarding an untrusted `Host` would put an attacker-influenced URL in front of both the model and the reader as a trustworthy citation. |
+| `PUBLIC_BASE_URL` | `""` | This server's canonical external URL (e.g. `https://community.promptowl.ai`). Two uses. (1) Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another — whenever a ticket-signing secret is set (`OFFICIAL_COMMUNITY_SSO_SECRET` on the official deployment, `MCP_SIGNING_SECRET` on a self-hosted one); with neither set no ticket verifies at all, so the audience check is moot. (2) **Set this whenever `OIDC_ENABLED=true`.** It's the base for the OIDC `redirect_uri` sent to your IdP and replayed at token exchange. Unset, that URI is derived from the incoming request's `Host` header — fine when your proxy overwrites `Host` with a trusted value, but a proxy that passes an attacker-supplied `Host` through would feed it straight into the redirect URI. Setting this pins the value regardless of what the proxy forwards. (Your IdP's own redirect-URI allowlist is a second line of defence, not a substitute.) (3) **Set this wherever email- or invite-gated publish links are used.** The magic link mailed by `POST /p/:slug/gate` is built from it; unset, it falls back to the request origin, so a proxy forwarding an attacker-supplied `Host` would send the recipient a one-time access token pointing at the attacker's domain — the classic reset-link poisoning. (4) **Set this wherever `POST /nests/:id/context` citations reach users.** The `url` on each node and the `_source:` line in each context block are built from it; unset, they fall back to the request origin, so a proxy forwarding an untrusted `Host` would put an attacker-influenced URL in front of both the model and the reader as a trustworthy citation. |
 | `OIDC_ENABLED` | `false` | Turn on generic OIDC single sign-on (`GET /auth/oidc/login` / `GET /auth/oidc/callback`). Requires `OIDC_ISSUER`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` — the login-page button only appears once all three are set. Also editable from Settings → Single sign-on. See [Single sign-on (OIDC)](#single-sign-on-oidc). |
 | `OIDC_ISSUER` | `""` | OIDC issuer URL, e.g. `https://login.microsoftonline.com/<tenant>/v2.0` (Microsoft Entra ID) or `https://accounts.google.com` (Google). **`https://` only** — a non-https value is rejected with a warning and SSO stays off. Must serve `<issuer>/.well-known/openid-configuration`. |
 | `OIDC_CLIENT_ID` | `""` | Application (client) ID from your IdP app registration. |
@@ -68,6 +68,11 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `OIDC_ALLOWED_DOMAINS` | `""` (any) | Comma-separated email-domain allowlist, e.g. `acme.com, contractors.acme.com`. When set, only accounts whose asserted email is on a listed domain may sign in (others bounce with `domain_not_allowed`). Empty allows any domain the IdP asserts. |
 | `OIDC_AUTO_PROVISION` | `true` | Create a user automatically on first successful OIDC sign-in (display name from the `name` claim). Set `false` to allow only pre-existing (invited/registered) users — unknown emails bounce with `not_invited`. |
 | `OIDC_DEPARTMENT_TAGGING` | `false` | Auto-tag newly **created** documents with the creator's directory department: `dept:<slugified-department>` (lowercase, spaces → dashes, e.g. `dept:customer-success`) is appended to the document's tags, deduped against user-supplied tags. Applies on create only — never on update, never retroactively — and a user without a stored department is a silent no-op. The department is captured from the OIDC `department` ID-token claim on every SSO login (a login without the claim clears it, so directory moves propagate), so this is only meaningful when your IdP emits that claim — see [Department auto-tagging](#department-auto-tagging). Also editable from Settings → Single sign-on. |
+| `SSO_TOKEN_EXCHANGE_ENABLED` | `false` | Master switch for `POST /auth/token-exchange` — an external agent exchanges an IdP ID token for a short-lived MCP bearer. Also needs `MCP_SIGNING_SECRET` and at least one provider; otherwise the endpoint returns `404`. Security-critical — see [Agent SSO (token exchange)](#agent-sso-token-exchange). |
+| `MCP_SIGNING_SECRET` | `""` | HMAC secret **this** server signs its minted MCP bearers with (distinct from `OFFICIAL_COMMUNITY_SSO_SECRET`, so self-hosted deployments can issue their own). Long random string. `/index` and `/mcp` accept a ticket signed with either secret. Write-only on the Settings API. **Clearing it is the revocation switch** — turning `SSO_TOKEN_EXCHANGE_ENABLED` off stops minting but already-minted bearers stay valid until they expire. |
+| `MCP_TOKEN_TTL_SECONDS` | `300` | Lifetime of a minted MCP bearer, clamped to 30–3600. |
+| `MS_TOKEN_EXCHANGE_ENABLED` / `MS_CLIENT_ID` / `MS_TENANT_ID` | `false` / `""` / `""` | Microsoft Entra provider. `MS_CLIENT_ID` is the audience an inbound token must carry; `MS_TENANT_ID` must be the directory **GUID** (it builds the required issuer `https://login.microsoftonline.com/<tenant>/v2.0` — `common`/`organizations`/a domain name will not match the discovery document and every exchange returns `provider_misconfigured`). |
+| `GOOGLE_TOKEN_EXCHANGE_ENABLED` / `GOOGLE_CLIENT_ID` | `false` / `""` | Google provider. Issuer is fixed (`https://accounts.google.com`); `GOOGLE_CLIENT_ID` is the audience an inbound token must carry. |
 | `ENV_FILE_PATH` | `$DATA_ROOT/.env` | Path to an optional `.env` file the server reads at boot (in addition to `$cwd/.env`). **No longer used for persistence** — the License Setup Page and Settings page now write to the database, not this file (see [Runtime settings persistence](#runtime-settings-persistence)). Kept for operators who bootstrap config from a mounted `.env`. |
 | `TELEMETRY_ENABLED` | `"true"` (set to `"false"` to disable) | Batched, anonymized usage events sent to PromptOwl. Off disables the loop entirely. |
 | `TELEMETRY_INTERVAL_MS` | `3600000` (1 hour) | How often buffered telemetry is flushed to PromptOwl. |
@@ -264,6 +269,83 @@ a toast; codes: `disabled`, `not_configured`, `discovery_failed`,
 
 ---
 
+## Agent SSO (token exchange)
+
+`POST /auth/token-exchange` lets an external agent, acting for a user your IdP
+(Microsoft Entra / Google) has **already** authenticated, exchange that IdP's ID
+token for a short-lived MCP bearer — no second login, no static API key.
+RFC 8693-shaped. **Off by default and security-critical**: it trusts a token
+minted elsewhere and hands back access, so read this section before enabling it.
+
+Configure it with the `SSO_TOKEN_EXCHANGE_ENABLED` / `MCP_SIGNING_SECRET` /
+`MS_*` / `GOOGLE_*` vars above, or from **Settings → Single sign-on → Agent SSO**
+(superadmin). It reuses `OIDC_ALLOWED_DOMAINS` and `OIDC_AUTO_PROVISION` — the
+same who-may-sign-in policy as browser login.
+
+**Who this is for — and who it is not.** The minted bearer is short-lived by
+design (`MCP_TOKEN_TTL_SECONDS`, default 300s, hard ceiling 3600s), and there is
+no refresh token: renewal means calling `POST /auth/token-exchange` again with
+the IdP token. So this fits a **programmatic** client — an agent runtime, a
+backend service, a desktop app that already did an MSAL/Google sign-in — that
+can re-exchange in code before a session or on a `401`, with no human involved.
+
+It does **not** fit a client whose credential is typed once into a config file
+(Claude Desktop, Cursor, any `mcpServers` JSON block): nothing here rewrites that
+file, and the ceiling is an hour, so the connection would break repeatedly. Those
+clients keep using a long-lived API key (`cnst_…`) — this endpoint is additive
+and changes nothing about API-key or browser sign-in.
+
+**What is verified** on the inbound `subject_token`, before anything is minted:
+
+- **signature** against the provider's JWKS, algorithm pinned to `RS256`
+- **issuer** — exact per provider (the tenant-scoped Entra issuer, or Google's)
+- **audience** — your configured client id, so a token minted for *another*
+  application cannot be replayed here
+- **expiry** (30s clock tolerance)
+- the same `email_verified` + domain-allowlist policy as browser login
+  (see [Email-verification trust assumption](#email-verification-trust-assumption))
+
+**Trust model / documented tradeoff.** Unlike the browser flow there is no
+session to bind, so the OIDC `nonce` binding is intentionally dropped; trust
+rests on signature + issuer + audience + expiry + `email_verified`. That is the
+standard token-exchange model, and it is why the audience check (and a
+correctly scoped IdP app registration) carries the weight here.
+
+**Provisioning fails closed.** JIT-provisioning from a token minted elsewhere is
+only allowed when `OIDC_ALLOWED_DOMAINS` bounds who may self-create. With
+auto-provision on and an empty allowlist, every exchange for an unknown email is
+refused with `no_account`, and the Settings page refuses to save that
+combination — otherwise any account at a public IdP (Google = the whole
+internet) could sign itself up and mint a bearer.
+
+**Entra caveat (`preferred_username`).** Entra v2 tokens often omit `email` and
+carry the address in `preferred_username`, which is a directory attribute — in a
+tenant where guests or external identities can set their own mail attribute, a
+token can assert an address that matches an existing local account. Pinning
+`MS_TENANT_ID` to your own directory bounds that to identities your tenant
+admits; treat inviting a guest as granting whatever that email address owns here.
+
+**Rate limiting.** The per-IP cap on this endpoint reads the client IP from
+`X-Forwarded-For`, so it is only a real cap behind a proxy that overwrites that
+header. Deploy accordingly — an internet-facing server with a pass-through
+header can be sprayed from a single host.
+
+**Scope.** The minted bearer carries `scope: "mcp"`. That is a *route*
+allowlist, not a reduced permission set: it reaches `/index`, `/mcp`, and the
+ticket-eligible `/nests/:id/*` routes (including MCP write tools) with the
+user's full stewardship rights. Keep `MCP_TOKEN_TTL_SECONDS` short.
+
+**Revocation.** Turning the master flag off stops *minting* but does not revoke
+bearers already issued — they remain valid until they expire (≤ 1h). Clear
+`MCP_SIGNING_SECRET` to invalidate every outstanding bearer at once.
+
+Error codes returned by the endpoint: `disabled` (404), `rate_limited` (429),
+`bad_request`, `provider_disabled`, `provider_misconfigured` (400),
+`invalid_subject_token` (401), `email_not_verified`, `domain_not_allowed`,
+`no_account` (403), `server_error` (500).
+
+---
+
 ## Database backends
 
 The governance/auth metadata (users, sessions, nests registry, stewards, reviews,

package/README.md

@@ -15,7 +15,7 @@ ContextNest Community Edition is a self-hosted server that lets you:
 - Export a nest as a portable bundle and re-import it on another self-hosted host
 - Apply stewardship workflows — draft, pending review, approved
 - Share nests with collaborators or publish them read-only to the public
-- Serve approved context to AI agents via MCP or HTTP — connect one by pasting a generated setup prompt or downloading a ready `.env`
+- Serve approved context to AI agents via MCP or HTTP — connect one by pasting a generated setup prompt or downloading a ready `.env`, or register the nest in the ctx CLI (`ctx vault add <alias> --url <server>/nests/<id>/mcp --bearer-env CONTEXTNEST_API_KEY`, then `ctx query "#tag" --vault <alias>`)
 - Sync with the PromptOwl hosted platform for multi-user collaboration
 
 The server runs locally or on your own infrastructure. Your PromptOwl account handles authentication, entitlement, and governance metadata.

package/dist/{chunk-FBDEESNJ.js → chunk-4KJGQHWB.js}

@@ -4,19 +4,19 @@ import {
   resolveNestWideRoles,
   resolveStewardsForNode,
   stewardCoverageForUser
-} from "./chunk-3GMGLYTZ.js";
+} from "./chunk-N2DTJFCD.js";
 import {
   grantCoversNode,
   listUserGrants,
   resolveNodeGrant
-} from "./chunk-GSYMJ3A4.js";
+} from "./chunk-XWGEXQU3.js";
 import {
   createVersion,
   getApprovedVersion,
   getApprovedVersions,
   getCurrentVersion,
   setApprovedVersion
-} from "./chunk-BXUVIAMP.js";
+} from "./chunk-IGPJ74O4.js";
 import {
   buildDocContext,
   buildTitleMap,
@@ -28,14 +28,15 @@ import {
   isStewardshipEnabled,
   nestName,
   notifyEmailForNest,
+  notifyReviewRequested,
+  notifyReviewResolved,
   nowExpr,
   opContext,
-  permissionLabel,
   prettyFolderPath,
   resolveNestPermission,
   sendEmailToRecipient,
   titleForNode
-} from "./chunk-ENDHMQPD.js";
+} from "./chunk-6JGQX4GA.js";
 import {
   ConflictError,
   NotFoundError,
@@ -44,175 +45,10 @@ import {
 import {
   config,
   getDb
-} from "./chunk-HYSTFMFG.js";
+} from "./chunk-LPPKPEYI.js";
 
 // src/governance/review-service.ts
-import { v4 as uuid3 } from "uuid";
-
-// src/governance/notify-service.ts
-import { v4 as uuid } from "uuid";
-async function listWatchers(nestId, nodeId) {
-  return await getDb().all(
-    `SELECT id, node_id, user_email, created_by, created_at
-       FROM watchers WHERE nest_id = ? AND node_id = ? ORDER BY created_at`,
-    [nestId, nodeId]
-  );
-}
-async function addWatcher(nestId, nodeId, userEmail, createdBy) {
-  await getDb().run(
-    `INSERT INTO watchers (id, nest_id, node_id, user_email, created_by, created_at)
-     VALUES (?, ?, ?, ?, ?, ?)
-     ON CONFLICT(nest_id, node_id, user_email) DO NOTHING`,
-    [uuid(), nestId, nodeId, userEmail.toLowerCase(), createdBy, (/* @__PURE__ */ new Date()).toISOString()]
-  );
-}
-async function removeWatcher(nestId, nodeId, userEmail) {
-  const db = getDb();
-  const row = await db.get(
-    "SELECT id FROM watchers WHERE nest_id = ? AND node_id = ? AND LOWER(user_email) = LOWER(?)",
-    [nestId, nodeId, userEmail]
-  );
-  if (!row) return false;
-  await db.run("DELETE FROM watchers WHERE id = ?", [row.id]);
-  return true;
-}
-async function notifyReviewRequested(params) {
-  const { nestId, nodeId, requestedBy, reviewId } = params;
-  const db = getDb();
-  try {
-    const rows = await db.all(
-      `SELECT DISTINCT w.user_email, w.node_id AS via
-         FROM watchers w
-        WHERE w.nest_id = ?
-          AND (w.node_id = ?
-               OR w.node_id IN (
-                 SELECT e.from_node FROM edges e
-                   JOIN edge_types t ON t.id = e.type_id
-                  WHERE e.nest_id = ? AND e.to_node = ? AND t.is_flow = 1
-               ))`,
-      [nestId, nodeId, nestId, nodeId]
-    );
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const label = await describeNode(nestId, nodeId);
-    let created = 0;
-    for (const r of rows) {
-      if (r.user_email.toLowerCase() === requestedBy.toLowerCase()) continue;
-      await db.run(
-        `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
-         VALUES (?, ?, ?, 'review_requested', ?, ?, ?)`,
-        [
-          uuid(),
-          nestId,
-          r.user_email.toLowerCase(),
-          reviewId,
-          r.via === nodeId ? `"${label}" has a new version awaiting review (submitted by ${requestedBy})` : `Agent "${await describeNode(nestId, r.via)}" produced output on "${label}" \u2014 awaiting review`,
-          now
-        ]
-      );
-      created++;
-    }
-    return created;
-  } catch (err) {
-    console.error("[notify] review fan-out failed", nestId, nodeId, err);
-    return 0;
-  }
-}
-async function notifyReviewResolved(params) {
-  const { nestId, nodeId, status, resolvedBy, requestedBy, reviewId } = params;
-  const db = getDb();
-  try {
-    const rows = await db.all(
-      `SELECT DISTINCT w.user_email
-         FROM watchers w
-        WHERE w.nest_id = ?
-          AND (w.node_id = ?
-               OR w.node_id IN (
-                 SELECT e.from_node FROM edges e
-                   JOIN edge_types t ON t.id = e.type_id
-                  WHERE e.nest_id = ? AND e.to_node = ? AND t.is_flow = 1
-               ))`,
-      [nestId, nodeId, nestId, nodeId]
-    );
-    const recipients = new Set(rows.map((r) => r.user_email.toLowerCase()));
-    recipients.add(requestedBy.toLowerCase());
-    recipients.delete(resolvedBy.toLowerCase());
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const label = await describeNode(nestId, nodeId);
-    let created = 0;
-    for (const email of recipients) {
-      await db.run(
-        `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?)`,
-        [
-          uuid(),
-          nestId,
-          email,
-          `review_${status}`,
-          reviewId,
-          `"${label}" was ${status} by ${resolvedBy}`,
-          now
-        ]
-      );
-      created++;
-    }
-    return created;
-  } catch (err) {
-    console.error("[notify] resolution fan-out failed", nestId, nodeId, err);
-    return 0;
-  }
-}
-async function notifyNestInvite(params) {
-  const { nestId, inviteeEmail, permission, nestName: nestName2 } = params;
-  try {
-    await getDb().run(
-      `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
-       VALUES (?, ?, ?, 'nest_invite', ?, ?, ?)`,
-      [
-        uuid(),
-        nestId,
-        inviteeEmail.toLowerCase(),
-        nestId,
-        `You were added to "${nestName2}" as ${permissionLabel(permission)}`,
-        (/* @__PURE__ */ new Date()).toISOString()
-      ]
-    );
-  } catch (err) {
-    console.error("[notify] invite inbox insert failed", nestId, inviteeEmail, err);
-  }
-}
-async function listNotifications(userEmail, opts = {}) {
-  const limit = Math.min(opts.limit ?? 50, 200);
-  return await getDb().all(
-    `SELECT n.id, n.nest_id, n.kind, n.subject_id, n.message, n.created_at, n.read_at,
-            COALESCE(
-              rr.node_id,
-              CASE WHEN dr.target_type = 'document' THEN dr.node_id END
-            ) AS node_id
-       FROM notifications n
-       LEFT JOIN review_requests rr ON rr.id = n.subject_id
-       LEFT JOIN deletion_requests dr ON dr.id = n.subject_id
-      WHERE LOWER(n.user_email) = LOWER(?)${opts.unreadOnly ? " AND n.read_at IS NULL" : ""}
-      ORDER BY n.created_at DESC LIMIT ${limit}`,
-    [userEmail]
-  );
-}
-async function markNotificationsRead(userEmail, ids) {
-  const db = getDb();
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  if (ids === "all") {
-    await db.run(
-      "UPDATE notifications SET read_at = ? WHERE LOWER(user_email) = LOWER(?) AND read_at IS NULL",
-      [now, userEmail]
-    );
-    return;
-  }
-  for (const id of ids.slice(0, 200)) {
-    await db.run(
-      "UPDATE notifications SET read_at = ? WHERE id = ? AND LOWER(user_email) = LOWER(?)",
-      [now, id, userEmail]
-    );
-  }
-}
+import { v4 as uuid2 } from "uuid";
 
 // src/workflow/env-routes.ts
 import { Hono as Hono2 } from "hono";
@@ -270,7 +106,7 @@ async function filterAccessible(nestId, userId, userEmail, nodes, approvedVersio
 
 // src/workflow/edge-type-routes.ts
 import { Hono } from "hono";
-import { v4 as uuid2 } from "uuid";
+import { v4 as uuid } from "uuid";
 
 // src/shared/json.ts
 var safeJson = (s) => {
@@ -283,6 +119,20 @@ var safeJson = (s) => {
 };
 
 // src/workflow/flow-graph.ts
+async function nodeTrail(db, nestId, ids) {
+  const unique = [...new Set(ids)];
+  const titles = /* @__PURE__ */ new Map();
+  try {
+    const rows = await db.all(
+      `SELECT node_id, title FROM node_index
+        WHERE nest_id = ? AND node_id IN (${unique.map(() => "?").join(",")})`,
+      [nestId, ...unique]
+    );
+    for (const r of rows) if (r.title) titles.set(r.node_id, r.title);
+  } catch {
+  }
+  return ids.map((id) => `"${titles.get(id) ?? id}"`).join(" \u2192 ");
+}
 async function assertFlowGraphAcyclic(nestId, extraFlowTypeId) {
   const db = getDb();
   const rows = await db.all(
@@ -297,7 +147,7 @@ async function assertFlowGraphAcyclic(nestId, extraFlowTypeId) {
   for (const r of rows) {
     if (r.from_node === r.to_node) {
       throw new ConflictError(
-        `cycle: ["${r.from_node}"] \u2014 a flow edge cannot be a self-loop`
+        `cycle: ${await nodeTrail(db, nestId, [r.from_node])} cannot flow into itself`
       );
     }
     nodes.add(r.from_node);
@@ -363,7 +213,7 @@ async function seedDefaultEdgeTypes(nestId) {
          (id, nest_id, name, description, direction, is_flow, condition_schema, color, created_by, created_at, updated_at)
        VALUES (?, ?, ?, ?, 'directed', ?, NULL, ?, ?, ?, ?)
        ON CONFLICT DO NOTHING`,
-      [uuid2(), nestId, name, description, isFlow, color, createdBy, now, now]
+      [uuid(), nestId, name, description, isFlow, color, createdBy, now, now]
     );
   }
 }
@@ -451,7 +301,7 @@ edgeTypeRoutes.post("/", requireWorkflowPlane, async (c) => {
         `INSERT INTO edge_types
            (id, nest_id, name, description, direction, is_flow, condition_schema, color, created_by, created_at, updated_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-        [uuid2(), nestId, name, body.description.trim(), direction, isFlow, conditionSchema, color, definedBy, now, now]
+        [uuid(), nestId, name, body.description.trim(), direction, isFlow, conditionSchema, color, definedBy, now, now]
       );
     }
   });
@@ -862,31 +712,60 @@ function withNodeWriteLock(key, fn) {
 // src/governance/review-service.ts
 async function submitForReview(params) {
   const db = getDb();
-  const existing = await db.get(
-    "SELECT id FROM review_requests WHERE nest_id = ? AND node_id = ? AND status = 'pending'",
-    [params.nestId, params.nodeId]
-  );
-  if (existing) {
-    throw new Error("A review is already pending for this node");
-  }
-  const id = uuid3();
-  await db.run(
-    `INSERT INTO review_requests
+  const { id, version } = await withNodeWriteLock(
+    nodeWriteKey(params.nestId, params.nodeId),
+    async () => {
+      const existing = await db.get(
+        "SELECT id FROM review_requests WHERE nest_id = ? AND node_id = ? AND status = 'pending'",
+        [params.nestId, params.nodeId]
+      );
+      if (existing) {
+        throw new Error("A review is already pending for this node");
+      }
+      const version2 = await getCurrentVersion(params.nestId, params.nodeId) || params.version;
+      const id2 = uuid2();
+      await db.run(
+        `INSERT INTO review_requests
      (id, nest_id, node_id, version, requested_by, request_note, priority)
      VALUES (?, ?, ?, ?, ?, ?, ?)`,
-    [
-      id,
-      params.nestId,
-      params.nodeId,
-      params.version,
-      params.requestedBy,
-      params.note || null,
-      params.priority || "normal"
-    ]
-  );
-  await db.run(
-    "UPDATE node_versions SET status = 'pending_review' WHERE nest_id = ? AND node_id = ? AND version = ?",
-    [params.nestId, params.nodeId, params.version]
+        [
+          id2,
+          params.nestId,
+          params.nodeId,
+          version2,
+          params.requestedBy,
+          params.note || null,
+          params.priority || "normal"
+        ]
+      );
+      await db.run(
+        "UPDATE node_versions SET status = 'pending_review' WHERE nest_id = ? AND node_id = ? AND version = ?",
+        [params.nestId, params.nodeId, version2]
+      );
+      try {
+        const { storage, versions: versionManager } = await engineCache.get(
+          params.nestId
+        );
+        const node = await storage.readDocument(params.nodeId);
+        const history = await versionManager.getHistory(params.nodeId);
+        const alreadySealed = (history?.versions ?? []).some(
+          (v) => v.version === (node.frontmatter.version ?? 1)
+        );
+        if (!alreadySealed) {
+          await versionManager.createVersion(node, params.requestedBy, {
+            note: params.note || "Submitted for review"
+          });
+        }
+      } catch (err) {
+        console.error(
+          "VersionManager.createVersion failed (submit for review)",
+          params.nestId,
+          params.nodeId,
+          err
+        );
+      }
+      return { id: id2, version: version2 };
+    }
   );
   const reviewCtx = await buildDocContext(params.nestId, params.nodeId, params.baseUrl);
   void dispatchEvent({
@@ -894,18 +773,18 @@ async function submitForReview(params) {
     nestId: params.nestId,
     subjectId: params.nodeId,
     actor: params.requestedBy,
-    message: `Review requested on *${reviewCtx.label}* (v${params.version}) by ${params.requestedBy}${params.note ? ` \u2014 "${params.note}"` : ""}`
+    message: `Review requested on *${reviewCtx.label}* (v${version}) by ${params.requestedBy}${params.note ? ` \u2014 "${params.note}"` : ""}`
   });
   void notifyNestEvent(
     params.nestId,
-    `:memo: Review requested on *${reviewCtx.label}* (v${params.version}) by ${params.requestedBy}${params.note ? ` \u2014 "${params.note}"` : ""}`,
+    `:memo: Review requested on *${reviewCtx.label}* (v${version}) by ${params.requestedBy}${params.note ? ` \u2014 "${params.note}"` : ""}`,
     {
       status: "pending_review",
       docTitle: reviewCtx.docTitle,
       path: reviewCtx.path,
       link: reviewCtx.link,
       actor: params.requestedBy,
-      version: params.version,
+      version,
       note: params.note || null
     }
   );
@@ -929,7 +808,7 @@ async function submitForReview(params) {
         path: reviewCtx.path,
         link: reviewCtx.link,
         actor: params.requestedBy,
-        version: params.version,
+        version,
         note: params.note || null
       });
     }
@@ -1168,6 +1047,18 @@ async function cancelReview(params) {
       [params.nestId, params.nodeId]
     );
     if (!pending) return null;
+    if (String(pending.requested_by).toLowerCase() !== params.cancelledBy.toLowerCase()) {
+      const verdict = await canUserApprove(
+        params.nestId,
+        params.nodeId,
+        params.cancelledBy
+      );
+      if (!verdict.allowed) {
+        throw new Error(
+          "Only the submitter or a reviewer can withdraw this review"
+        );
+      }
+    }
     await db.run(
       `UPDATE review_requests
      SET status = 'cancelled', resolved_by = ?, resolved_at = ${nowExpr(db)}
@@ -1258,9 +1149,12 @@ async function getPendingReview(nestId, nodeId) {
   );
   return row ? rowToReviewRequest(row) : null;
 }
+function isNestTarget(t) {
+  return t === "nest" || t === "nest_archive";
+}
 async function deletionTargetTitle(request, titles) {
   if (request.targetType === "folder") return prettyFolderPath(request.nodeId);
-  if (request.targetType === "nest") return await nestName(request.nestId);
+  if (isNestTarget(request.targetType)) return await nestName(request.nestId);
   return titles?.get(request.nodeId) ?? await titleForNode(request.nestId, request.nodeId);
 }
 async function nestAdminEmails(nestId) {
@@ -1282,7 +1176,7 @@ async function inboxInsert(nestId, recipients, kind, subjectId, message) {
       await db.run(
         `INSERT INTO notifications (id, nest_id, user_email, kind, subject_id, message, created_at)
          VALUES (?, ?, ?, ?, ?, ?, ?)`,
-        [uuid3(), nestId, email.toLowerCase(), kind, subjectId, message, now]
+        [uuid2(), nestId, email.toLowerCase(), kind, subjectId, message, now]
       );
     } catch (err) {
       console.error("[notify] deletion inbox insert failed", nestId, email, err);
@@ -1297,7 +1191,7 @@ async function deletionTargetContext(request, baseUrl) {
   const name = await nestName(request.nestId);
   const label = request.targetType === "folder" ? prettyFolderPath(request.nodeId) : name;
   return {
-    noun: request.targetType,
+    noun: request.targetType === "nest_archive" ? "nest" : request.targetType,
     label,
     docTitle: label,
     path: name,
@@ -1362,7 +1256,8 @@ async function notifyDeletionRequested(request, baseUrl) {
 async function notifyDeletionResolved(params) {
   try {
     const { outcome, resolvedBy, note } = params;
-    const verb = outcome === "deleted" ? "deleted" : "rejected the deletion of";
+    const archivedInstead = outcome === "deleted" && params.targetType === "nest_archive";
+    const verb = archivedInstead ? "archived" : outcome === "deleted" ? "deleted" : "rejected the deletion of";
     const line = `${resolvedBy} ${verb} *${params.docTitle}*${note ? ` \u2014 "${note}"` : ""}`;
     const recipient = params.requestedBy.toLowerCase();
     const canInbox = !(params.targetType === "nest" && outcome === "deleted");
@@ -1372,7 +1267,7 @@ async function notifyDeletionResolved(params) {
         [recipient],
         `deletion_${outcome}`,
         params.requestId,
-        outcome === "deleted" ? `"${params.docTitle}" was deleted by ${resolvedBy} \u2014 your request was accepted` : `Your deletion request for "${params.docTitle}" was rejected by ${resolvedBy}${note ? ` \u2014 "${note}"` : ""}`
+        outcome === "deleted" ? `"${params.docTitle}" was ${archivedInstead ? "archived" : "deleted"} by ${resolvedBy} \u2014 your request was accepted` : `Your deletion request for "${params.docTitle}" was rejected by ${resolvedBy}${note ? ` \u2014 "${note}"` : ""}`
       );
     }
     void dispatchEvent({
@@ -1392,7 +1287,10 @@ async function notifyDeletionResolved(params) {
     if (recipient !== resolvedBy.toLowerCase()) {
       const link = params.baseUrl ? `${params.baseUrl}/?nest=${encodeURIComponent(params.nestId)}` : "";
       void sendEmailToRecipient(recipient, {
-        status: outcome === "deleted" ? "deletion_deleted" : "deletion_declined",
+        // The email has to agree with the inbox row and the channel line above:
+        // an honoured archive is not a deletion, and the deletion template says
+        // the nest is gone.
+        status: archivedInstead ? "deletion_archived" : outcome === "deleted" ? "deletion_deleted" : "deletion_declined",
         docTitle: params.docTitle,
         path: params.nestId,
         link: outcome === "deleted" ? link : void 0,
@@ -1413,14 +1311,15 @@ async function requestDeletion(params) {
   const db = getDb();
   const targetType = params.targetType || "document";
   const noun = targetType === "document" ? "node" : targetType === "folder" ? "folder" : "nest";
+  const kind = targetType === "nest_archive" ? "An archive request" : "A deletion request";
   const existing = await db.get(
     "SELECT id FROM deletion_requests WHERE nest_id = ? AND node_id = ? AND target_type = ? AND status = 'pending'",
     [params.nestId, params.nodeId, targetType]
   );
   if (existing) {
-    throw new ConflictError(`A deletion request is already pending for this ${noun}`);
+    throw new ConflictError(`${kind} is already pending for this ${noun}`);
   }
-  const id = uuid3();
+  const id = uuid2();
   try {
     await db.run(
       `INSERT INTO deletion_requests (id, nest_id, node_id, target_type, requested_by, reason)
@@ -1441,7 +1340,7 @@ async function requestDeletion(params) {
       params.nodeId,
       err
     );
-    throw new ConflictError(`A deletion request is already pending for this ${noun}`);
+    throw new ConflictError(`${kind} is already pending for this ${noun}`);
   }
   const request = await getDeletionRequest(id);
   await notifyDeletionRequested(request, params.baseUrl);
@@ -1584,17 +1483,12 @@ function rowToReviewRequest(row) {
 }
 
 export {
-  listWatchers,
-  addWatcher,
-  removeWatcher,
-  notifyNestInvite,
-  listNotifications,
-  markNotificationsRead,
   resolveCallerEmail,
   canReadNode,
   canRequestDeletion,
   filterAccessible,
   safeJson,
+  nodeTrail,
   requireWorkflowPlane,
   seedDefaultEdgeTypes,
   parseConditionSchema,
@@ -1616,6 +1510,7 @@ export {
   getReviewQueue,
   getReviewHistory,
   getPendingReview,
+  isNestTarget,
   deletionTargetTitle,
   notifyDeletionResolved,
   requestDeletion,