@promptowl/contextnest-community 1.8.0 → 1.10.0

package/CONFIGURATION.md

@@ -56,17 +56,28 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `DB_SSL_CA` | `""` | Path to a CA certificate (PEM) for verify-ca/verify-full TLS when `DB_SSL=true`. |
 | `AUTH_MODE` | `key` | `key` or `open`. See above. |
 | `PROMPTOWL_API_URL` | `https://app.promptowl.ai` | PromptOwl's API origin — used for device auth, license validation, telemetry. Override for air-gapped or test setups. |
-| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to `ENV_FILE_PATH`. |
+| `PROMPTOWL_KEY` | `""` | Your PromptOwl Community License key (`pk_...`). Unlicensed instances still run and serve reads, but every write returns `503` until a valid key is installed. Can also be set via the browser License Setup Page, which persists it to the database (`server_settings` table) so it survives a rebuild and reaches every instance — see [Runtime settings persistence](#runtime-settings-persistence). Setting it here in the deploy environment takes precedence on the next boot. |
 | `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`). Checked against the SSO ticket's `aud` claim so a ticket minted for this server can't be replayed against another. Only relevant when `OFFICIAL_COMMUNITY_SSO_SECRET` is set; when unset, the audience check is skipped. |
-| `ENV_FILE_PATH` | `$DATA_ROOT/.env` | Path to the `.env` file the license install flow writes `PROMPTOWL_KEY` into (alongside existing vars), and which the server also reads at boot. Defaults **under `DATA_ROOT`** so the browser License Setup Page persists durably in containers — `$cwd` is `/app` in the official image (root-owned, discarded on container recreate), which silently lost the key. Override only if your writable, persisted `.env` lives elsewhere. In containers, providing `PROMPTOWL_KEY` directly via the environment also works and is read at boot. |
+| `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. |
+| `TRACE_RETENTION_DAYS` | `14` | Activity-trace retention window in days (the `api_events` rows behind `GET /admin/trace` and `GET /nests/:id/trace`). Rows older than this are pruned opportunistically (every ~500 inserts). `0` = keep forever (pruning is skipped entirely). Capped at `3650`; invalid/negative values fall back to `14`. Also editable from Settings → Advanced. |
 | `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
 | `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. |
 | `LOGO_URL` | _(unset)_ | Custom logo shown in the UI header + login screen. Must start with `https://`, `http://`, or `data:image/` — other schemes (`file://`, relative, `javascript:`) are rejected with a warning and the bundled icon is used. |
+| `FEATURE_WORKFLOW_PLANE` | _(unset — off)_ | Enables the workflow plane: typed edges, edge-type registry, governed runs. Optional feature; also toggleable from Settings. |
+| `FEATURE_SUBAGENT_RUNS` | _(unset — off)_ | Lets runs spawn nested sub-agent runs (recursion). Gated separately from the plane; requires `FEATURE_WORKFLOW_PLANE`. Also toggleable from Settings → Advanced (turning the plane off forces this off too). Opens a recursion surface — enable only after reviewing the depth/fan-out caps. |
+| `SUBAGENT_MAX_DEPTH` | `8` | Max sub-agent nesting depth (clamped 1..32) — bounds the call tree's HEIGHT so it stays finite/haltable. |
+| `SUBAGENT_MAX_CHILDREN` | `16` | Max direct children a single run may spawn (clamped 1..128) — bounds the call tree's WIDTH. Together with `SUBAGENT_MAX_DEPTH` this caps total tree size so a runner can't fork-bomb the DB. |
+| `RUN_MAX_STEPS` | `10000` | Max steps a single run may accumulate (clamped 10..100000) — bounds a runaway/hostile runner's step log. |
 | `SLACK_WEBHOOK_URL` | _(unset — connector off)_ | Slack incoming-webhook URL for governance-event notifications (review submitted/approved/rejected, collaborator added). `https://` only — the URL embeds a secret. Also editable from Settings in the UI. |
+| `SMTP_URL` | _(unset — connector off)_ | SMTP connection URL for email notifications (`smtp://` or `smtps://`, credentials inline). Requires `NOTIFY_EMAIL_FROM` and `NOTIFY_EMAIL_TO`. Also editable from Settings. |
+| `NOTIFY_EMAIL_FROM` | _(unset)_ | From address for notification emails. |
+| `NOTIFY_EMAIL_TO` | _(unset)_ | Comma-separated recipients for notification emails. |
+| `NOTIFY_DEBOUNCE_MS` | `15000` | Per-nest buffer window before notifications flush; bursts collapse into one digest message. |
 
 ---
 
@@ -94,6 +105,31 @@ Postgres backend starts empty.
 > shared storage — e.g. mount a GCS bucket via Cloud Storage FUSE, or use a
 > persistent volume — otherwise documents will disappear on redeploy/scale-in.
 
+### Runtime settings persistence
+
+Settings you change at runtime — everything on the **Settings page** (`/admin/settings`:
+sign-in gate, logo, base URL, upload limit, feature flags, Slack/SMTP connectors)
+plus the **installed license key** — are stored in the database (`server_settings`
+table), **not** in a `.env` file. This is deliberate: on Cloud Run the container
+filesystem is ephemeral, so a file-based value was wiped by every rebuild, and each
+horizontally-scaled instance had its own filesystem, so a change on one never
+reached the others. The database (Cloud SQL in production) is durable **and** shared,
+so a UI change persists across rebuilds and is seen by every instance. Rows are
+loaded into the process environment at boot.
+
+**Precedence between the deploy environment and a UI change.** Each stored row
+remembers the deploy-env value in effect when it was written. At boot:
+
+- If the deploy env value for that key is **unchanged**, the stored UI change wins
+  (your Settings-page edit survives an identical rebuild).
+- If the deploy env value **changed** (you redeployed with a new value for that
+  variable), the deploy env wins and the stored row is re-synced to it.
+
+So you can always override any setting from the deploy config, while UI edits made
+to keys you don't set in the environment stay put. Clearing a setting in the UI
+writes a tombstone, so a value you removed is not resurrected from the environment
+on the next boot.
+
 ### Cloud Run + Cloud SQL (PostgreSQL)
 
 Attach the Cloud SQL instance to the service (`--add-cloudsql-instances`) so the

package/dist/chunk-3JTODC3Y.js

@@ -0,0 +1,48 @@
+// src/shared/errors.ts
+var AppError = class extends Error {
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "AppError";
+  }
+  statusCode;
+};
+var NotFoundError = class extends AppError {
+  constructor(message = "Not found") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+};
+var ForbiddenError = class extends AppError {
+  constructor(message = "Forbidden") {
+    super(403, message);
+    this.name = "ForbiddenError";
+  }
+};
+var ValidationError = class extends AppError {
+  constructor(message) {
+    super(400, message);
+    this.name = "ValidationError";
+  }
+};
+var ConflictError = class extends AppError {
+  constructor(message) {
+    super(409, message);
+    this.name = "ConflictError";
+  }
+};
+var LockedError = class extends AppError {
+  constructor(message = "Locked") {
+    super(423, message);
+    this.name = "LockedError";
+  }
+};
+
+export {
+  AppError,
+  NotFoundError,
+  ForbiddenError,
+  ValidationError,
+  ConflictError,
+  LockedError
+};

package/dist/chunk-7PQREKSM.js

@@ -0,0 +1,103 @@
+import {
+  ValidationError
+} from "./chunk-3JTODC3Y.js";
+import {
+  getDb
+} from "./chunk-BC6KFUZH.js";
+
+// src/governance/grants-service.ts
+import { v4 as uuid } from "uuid";
+var rank = (r) => r === "write" ? 2 : 1;
+async function resolveNodeGrant(nestId, userId, nodeId) {
+  if (!userId || !nodeId) return null;
+  const rows = await getDb().all(
+    "SELECT target, role FROM grants WHERE nest_id = ? AND user_id = ?",
+    [nestId, userId]
+  );
+  let best = null;
+  for (const r of rows) {
+    if (nodeId === r.target || nodeId.startsWith(r.target + "/")) {
+      if (!best || rank(r.role) > rank(best)) best = r.role;
+    }
+  }
+  return best;
+}
+async function hasAnyGrant(nestId, userId) {
+  if (!userId) return false;
+  const row = await getDb().get(
+    "SELECT 1 AS x FROM grants WHERE nest_id = ? AND user_id = ? LIMIT 1",
+    [nestId, userId]
+  );
+  return !!row;
+}
+async function listUserGrants(nestId, userId) {
+  if (!userId) return [];
+  return await getDb().all(
+    "SELECT target, role FROM grants WHERE nest_id = ? AND user_id = ?",
+    [nestId, userId]
+  );
+}
+function grantCoversNode(grants, nodeId) {
+  return grants.some(
+    (g) => nodeId === g.target || nodeId.startsWith(g.target + "/")
+  );
+}
+async function createGrant(params) {
+  const { nestId, targetType, target, userId, role, grantedBy } = params;
+  if (!["document", "folder"].includes(targetType)) {
+    throw new ValidationError("target_type must be document | folder");
+  }
+  if (!["read", "write"].includes(role)) {
+    throw new ValidationError("role must be read | write");
+  }
+  if (!target.trim()) throw new ValidationError("target is required");
+  if (targetType === "folder") {
+    const t = target.trim().replace(/\/+$/, "");
+    if (t === "nodes" || t === "") {
+      throw new ValidationError("folder target must name a subfolder, not the nest root");
+    }
+  }
+  const db = getDb();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const existing = await db.get(
+    "SELECT id FROM grants WHERE nest_id = ? AND target_type = ? AND target = ? AND user_id = ?",
+    [nestId, targetType, target, userId]
+  );
+  if (existing) {
+    await db.run(
+      "UPDATE grants SET role = ?, granted_by = ?, updated_at = ? WHERE id = ?",
+      [role, grantedBy, now, existing.id]
+    );
+    return await db.get("SELECT * FROM grants WHERE id = ?", [existing.id]);
+  }
+  const id = uuid();
+  await db.run(
+    `INSERT INTO grants (id, nest_id, target_type, target, user_id, role, granted_by, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [id, nestId, targetType, target, userId, role, grantedBy, now, now]
+  );
+  return await db.get("SELECT * FROM grants WHERE id = ?", [id]);
+}
+async function listGrants(nestId) {
+  return await getDb().all(
+    "SELECT * FROM grants WHERE nest_id = ? ORDER BY target_type, target",
+    [nestId]
+  );
+}
+async function deleteGrant(nestId, id) {
+  const db = getDb();
+  const row = await db.get("SELECT id FROM grants WHERE id = ? AND nest_id = ?", [id, nestId]);
+  if (!row) return false;
+  await db.run("DELETE FROM grants WHERE id = ?", [id]);
+  return true;
+}
+
+export {
+  resolveNodeGrant,
+  hasAnyGrant,
+  listUserGrants,
+  grantCoversNode,
+  createGrant,
+  listGrants,
+  deleteGrant
+};