@promptowl/contextnest-community 1.10.0 → 1.11.0

package/CONFIGURATION.md

@@ -60,7 +60,14 @@ 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`). 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. |
+| `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 — 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.) |
+| `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. |
+| `OIDC_CLIENT_SECRET` | `""` | Client secret from your IdP app registration. Write-only on the Settings API — `GET /admin/settings` reports only `oidc_client_secret_set: true/false`, never the value. |
+| `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. |
 | `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. |
@@ -68,6 +75,7 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `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. |
+| `PROMPTOWL_TEAMS_ENABLED` | _(unset — off)_ | Lets users who signed in with PromptOwl import their PromptOwl teams as local teams. Off by default; set `true` to enable, or toggle from Settings → Advanced. When off, `GET/POST /teams/promptowl` return `404` and the PromptOwl Teams panel is hidden. Independent of `PROMPTOWL_SIGN_IN_GATE`. |
 | `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. |
@@ -81,6 +89,119 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 
 ---
 
+## Single sign-on (OIDC)
+
+Generic OpenID Connect sign-in against any spec-compliant identity provider —
+Microsoft Entra ID and Google are the first-class presets in **Settings →
+Single sign-on**. The server runs a standard authorization-code flow with PKCE:
+`GET /auth/oidc/login` redirects to your IdP, `GET /auth/oidc/callback` verifies
+the returned ID token (issuer, audience, nonce, signature against the issuer's
+JWKS) and starts a normal browser session. Users are looked up by email;
+unknown emails are created automatically when `OIDC_AUTO_PROVISION` is on.
+
+All seven `OIDC_*` values are also editable at runtime from **Settings → Single
+sign-on** (superadmin only) — no restart needed. The Settings page shows the
+exact **redirect URI** to register with your IdP:
+
+```
+<PUBLIC_BASE_URL or server origin>/auth/oidc/callback
+```
+
+Set `PUBLIC_BASE_URL` when the server sits behind a reverse proxy so the
+redirect URI is derived from the canonical address rather than the incoming
+Host header.
+
+### Connect Microsoft Entra ID
+
+1. **Register an app.** Entra admin center → *Identity → Applications → App
+   registrations → New registration*. Name it (e.g. "ContextNest"), leave the
+   account type at *Accounts in this organizational directory only*.
+2. **Add the redirect URI.** In the registration: *Authentication → Add a
+   platform → Web*, and paste the redirect URI shown on the ContextNest
+   Settings page (`https://<your-server>/auth/oidc/callback`).
+3. **Create a client secret.** *Certificates & secrets → New client secret*.
+   Copy the secret **value** (not the ID) immediately — it's shown once.
+4. **Collect the IDs.** On the app's *Overview* page copy the **Application
+   (client) ID** and the **Directory (tenant) ID**.
+5. **Fill in ContextNest.** Settings → Single sign-on: click **Microsoft Entra
+   ID**, paste the tenant ID when prompted (issuer becomes
+   `https://login.microsoftonline.com/<tenant>/v2.0`), then paste the client
+   ID and the secret value. Optionally restrict **Allowed email domains** to
+   your org's domain. Save, then flip the toggle **On** and save again (or in
+   the same save).
+6. **Test.** Open the login page in a private window — a **Sign in with
+   Microsoft** button appears and round-trips through Entra. Entra accounts
+   without an `email` claim fall back to `preferred_username` (the UPN).
+
+For **Google**: create an OAuth client ID (type *Web application*) in the
+Google Cloud console, add the same redirect URI under *Authorized redirect
+URIs*, and use the **Google** preset (issuer `https://accounts.google.com`)
+with that client ID/secret.
+
+### Department auto-tagging
+
+With `OIDC_DEPARTMENT_TAGGING` on (Settings → Single sign-on → **Department
+auto-tagging**), every document a user **creates** is tagged
+`dept:<slugified-department>` from their directory department — e.g. a user in
+*Customer Success* creates docs tagged `dept:customer-success`. Create-only:
+edits never add or change the tag, and existing documents are never
+retro-tagged. Users without a department (password accounts, or an IdP that
+doesn't emit the claim) create untagged documents — never an error.
+
+The department is read from the **`department` claim** in the OIDC ID token
+and stored on the user at every SSO login: a new value updates it, an absent
+claim clears it, so directory moves propagate on the user's next sign-in.
+
+Microsoft Entra ID does **not** emit the claim by default — add it to the app
+registration: *Token configuration → Add optional claim → Token type: **ID**
+→ select **department** → Add* (grant the suggested Microsoft Graph
+permission if prompted), and make sure the users' *Department* field is
+populated in Entra. Other IdPs work too as long as they emit a string
+`department` claim in the ID token (e.g. a Keycloak user-attribute mapper).
+
+> **Privacy note:** the `dept:<slug>` tag becomes part of the document's
+> visible metadata — anyone who can read the document (collaborators, shared
+> nests, public nests) can see the creator's directory department. That's
+> PII-adjacent organizational data; consider this before enabling on servers
+> where documents are shared beyond the creator's own team or made public.
+
+### Revoking access (offboarding)
+
+Disabling a user **at the IdP** only blocks *new* sign-ins — an existing
+ContextNest session stays valid until it expires (30 days). To cut access
+immediately, **remove the user in ContextNest** (Settings → users): that wipes
+all of their active sessions at once. Real offboarding is therefore two steps —
+disable at the IdP *and* remove in ContextNest — with the ContextNest step being
+the one that ends live sessions.
+
+When a user signs themselves out, ContextNest performs an **RP-initiated
+logout**: if the IdP advertises an `end_session_endpoint` (Entra, Okta,
+Keycloak do; Google does not), the browser is bounced through it so the IdP
+session ends too and the next "Sign in with SSO" click doesn't silently
+re-authenticate. Where the IdP has no logout endpoint, the local session is
+cleared and the user lands back on the login page (the IdP session persists —
+that's the IdP's own timeout to manage).
+
+### Email-verification trust assumption
+
+An ID token whose `email_verified` claim is **explicitly `false`** is refused
+(`?sso_error=email_not_verified`). When the claim is **absent**, the server
+trusts the email claim — Microsoft Entra ID v2 tokens frequently omit it, and
+both Entra and Google guarantee address ownership, so refusing on absence
+would break the primary providers. This is a deliberate trust assumption:
+**when your IdP allows unverified self-registered emails (e.g. an open
+Keycloak realm), configure `oidc_allowed_domains` and disable self-registration
+at the IdP** — otherwise anyone able to assert an arbitrary email at your IdP
+could sign in as the matching local account.
+
+Sign-in failures bounce back to the app as `/?sso_error=<code>` and surface as
+a toast; codes: `disabled`, `not_configured`, `discovery_failed`,
+`provider_error`, `state_mismatch`, `exchange_failed`, `invalid_token`,
+`email_not_verified`, `domain_not_allowed`, `not_invited`, `rate_limited`,
+`service_error`.
+
+---
+
 ## Database backends
 
 The governance/auth metadata (users, sessions, nests registry, stewards, reviews,
@@ -108,7 +229,7 @@ Postgres backend starts empty.
 ### 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)
+sign-in gate, logo, base URL, upload limit, feature flags, OIDC SSO, 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

package/README.md

@@ -105,7 +105,8 @@ For redistribution, hosted-service, OEM, or regulated-industry licensing, contac
 | Steward version revert | ✅ | ✅ |
 | MCP server for AI agents | ✅ | ✅ |
 | Centralized multi-tenant admin console | — | ✅ |
-| SSO / SAML / SCIM | — | ✅ |
+| Single sign-on (OIDC — Entra ID, Google, Okta, Keycloak) | ✅ | ✅ |
+| SAML / SCIM provisioning | — | ✅ |
 | Audit log streaming | — | ✅ |
 | Policy transforms (redaction, summarization) | — | ✅ |
 | Priority support and SLA | — | ✅ |

package/dist/{chunk-BC6KFUZH.js → chunk-3M7677XW.js}

@@ -28,6 +28,7 @@ var canonicalEnvLoaded = null;
 var slackUrlWarned = false;
 var emailFromWarned = false;
 var emailToWarned = false;
+var oidcIssuerWarned = false;
 function isEmailish(v) {
   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) && !/[\r\n]/.test(v);
 }
@@ -124,6 +125,16 @@ var config = {
   get PROMPTOWL_KEY() {
     return process.env.PROMPTOWL_KEY || "";
   },
+  /**
+   * Whether importing/syncing teams FROM PromptOwl is offered. Default OFF
+   * (only an explicit "true" enables) — an operator opts the PO-team surface
+   * in from Settings or env. When off, the /teams/promptowl routes 404 and the
+   * UI hides the panel. Independent of PROMPTOWL_SIGN_IN_GATE: a user may sign
+   * in with PromptOwl yet not be allowed to pull their PO teams in.
+   */
+  get PROMPTOWL_TEAMS_ENABLED() {
+    return process.env.PROMPTOWL_TEAMS_ENABLED === "true";
+  },
   /** Vercel automation-bypass secret for PO calls; unset = no bypass. */
   get PROMPTOWL_BYPASS_SECRET() {
     return process.env.PROMPTOWL_BYPASS_SECRET || "";
@@ -194,6 +205,80 @@ var config = {
     const v = (process.env.MANUAL_SIGN_IN || "open").trim().toLowerCase();
     return v === "invite-only" || v === "disabled" ? v : "open";
   },
+  /**
+   * Generic OIDC single sign-on (Microsoft Entra ID, Google, any spec-
+   * compliant IdP). Off by default; superadmin-configurable at runtime via
+   * /admin/settings. When enabled AND fully configured (issuer + client id +
+   * client secret), GET /auth/oidc/login starts an authorization-code + PKCE
+   * flow and GET /auth/oidc/callback finishes it with a normal browser
+   * session — exactly like a password login.
+   */
+  get OIDC_ENABLED() {
+    return process.env.OIDC_ENABLED === "true";
+  },
+  /**
+   * OIDC issuer URL, e.g. "https://login.microsoftonline.com/<tenant>/v2.0"
+   * or "https://accounts.google.com". https only — tokens and the client
+   * secret ride this trust root, so a plaintext issuer is refused (warn once,
+   * treated as unset). Trailing slash stripped so discovery-doc comparison is
+   * canonical.
+   */
+  get OIDC_ISSUER() {
+    const raw = (process.env.OIDC_ISSUER || "").trim().replace(/\/$/, "");
+    if (!raw) return "";
+    let ok = false;
+    try {
+      ok = new URL(raw).protocol === "https:";
+    } catch {
+      ok = false;
+    }
+    if (!ok) {
+      if (!oidcIssuerWarned) {
+        oidcIssuerWarned = true;
+        console.warn(
+          "[config] OIDC_ISSUER rejected: must be a valid https:// URL. OIDC sign-in disabled."
+        );
+      }
+      return "";
+    }
+    return raw;
+  },
+  get OIDC_CLIENT_ID() {
+    return (process.env.OIDC_CLIENT_ID || "").trim();
+  },
+  get OIDC_CLIENT_SECRET() {
+    return (process.env.OIDC_CLIENT_SECRET || "").trim();
+  },
+  /**
+   * Comma-separated email-domain allowlist for OIDC sign-in (e.g.
+   * "acme.com, contractors.acme.com"). Empty = any domain the IdP asserts.
+   * Entries are normalized to lowercase; matching is on the part after the
+   * final "@" of the asserted email.
+   */
+  get OIDC_ALLOWED_DOMAINS() {
+    return (process.env.OIDC_ALLOWED_DOMAINS || "").split(",").map((d) => d.trim().toLowerCase()).filter(Boolean);
+  },
+  /**
+   * Auto-provision (JIT-create) an unknown user on first successful OIDC
+   * sign-in. Default true. When false, only emails that already have a user
+   * row (invited / registered) may sign in via OIDC — everyone else bounces
+   * with ?sso_error=not_invited.
+   */
+  get OIDC_AUTO_PROVISION() {
+    return process.env.OIDC_AUTO_PROVISION !== "false";
+  },
+  /**
+   * Auto-tag content created by SSO users with their directory department:
+   * when on, node CREATE appends `dept:<slugified-department>` to the new
+   * node's tags (never on update, never retroactively). The department is
+   * captured from the OIDC `department` claim at login (see oidc.ts), so
+   * this is only meaningful alongside an IdP that emits that claim — but
+   * there is no hard dependency on OIDC_ENABLED. Default off; superadmin-
+   * togglable at runtime via /admin/settings.
+   */
+  get OIDC_DEPARTMENT_TAGGING() {
+    return process.env.OIDC_DEPARTMENT_TAGGING === "true";
+  },
   /**
    * Path to the .env file the server reads its config from and the license
    * install flow persists PROMPTOWL_KEY into. Defaults UNDER DATA_ROOT (not
@@ -271,6 +356,21 @@ var config = {
   get FEATURE_WORKFLOW_PLANE() {
     return process.env.FEATURE_WORKFLOW_PLANE === "true";
   },
+  /**
+   * Content-type toggles — soft-disable a node type server-wide. DEFAULT ON:
+   * missing/unset/anything-but-"false" = enabled, so existing deployments see
+   * zero behavior change. Only CREATION of the type is refused when disabled;
+   * existing nodes of that type still read/render/version (never data loss).
+   * Runnable types (agent/skill/tool) are NOT governed here — they stay gated
+   * by FEATURE_WORKFLOW_PLANE. Superadmin-editable at runtime via
+   * /admin/settings (type_artifact_enabled / type_table_enabled).
+   */
+  get TYPE_ARTIFACT_ENABLED() {
+    return process.env.TYPE_ARTIFACT_ENABLED !== "false";
+  },
+  get TYPE_TABLE_ENABLED() {
+    return process.env.TYPE_TABLE_ENABLED !== "false";
+  },
   /**
    * Sub-agent runs: lets a run spawn nested runs (an external runner calling
    * back into POST /run for a child agent). Gated SEPARATELY from the base
@@ -1261,6 +1361,64 @@ function runMigrations(db) {
     })();
     recordMigration("026_api_events_nest_index");
   }
+  if (!hasMigration("027_teams")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS teams (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+          members TEXT NOT NULL DEFAULT '[]',   -- JSON [{userId, email, role}]
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_teams_owner ON teams(owner_id);
+      `);
+      const nestColsNow = db.prepare("PRAGMA table_info(nests)").all().map((c) => c.name);
+      if (!nestColsNow.includes("shared_teams")) {
+        db.exec("ALTER TABLE nests ADD COLUMN shared_teams TEXT NOT NULL DEFAULT '[]'");
+      }
+    })();
+    recordMigration("027_teams");
+  }
+  if (!hasMigration("028_user_department")) {
+    db.transaction(() => {
+      const userColsNow = db.prepare("PRAGMA table_info(users)").all().map((c) => c.name);
+      if (!userColsNow.includes("department")) {
+        db.exec("ALTER TABLE users ADD COLUMN department TEXT");
+      }
+    })();
+    recordMigration("028_user_department");
+  }
+  if (!hasMigration("029_super_admins")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS super_admins (
+          email TEXT PRIMARY KEY,          -- stored lowercased
+          granted_by TEXT NOT NULL,        -- email of the granting admin
+          granted_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+      `);
+    })();
+    recordMigration("029_super_admins");
+  }
+  if (!hasMigration("031_team_source")) {
+    db.transaction(() => {
+      const teamCols = db.prepare("PRAGMA table_info(teams)").all().map((c) => c.name);
+      if (!teamCols.includes("source")) {
+        db.exec("ALTER TABLE teams ADD COLUMN source TEXT");
+      }
+      if (!teamCols.includes("external_id")) {
+        db.exec("ALTER TABLE teams ADD COLUMN external_id TEXT");
+      }
+      db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_teams_external
+          ON teams(owner_id, source, external_id)
+          WHERE external_id IS NOT NULL;
+      `);
+    })();
+    recordMigration("031_team_source");
+  }
 }
 function mergeCaseCollidingUsers(db) {
   const groups = db.prepare(
@@ -1478,7 +1636,7 @@ async function initDb() {
   if (config.DB_DRIVER === "postgres") {
     const { Pool } = await import("pg");
     const { PostgresAdapter } = await import("./adapter.postgres-YOODX2BI.js");
-    const { runPostgresMigrations } = await import("./migrations.postgres-4XYY3CTF.js");
+    const { runPostgresMigrations } = await import("./migrations.postgres-BRXZY2GE.js");
     const pool = new Pool(buildPgConfig());
     adapter = new PostgresAdapter(pool);
     await runPostgresMigrations(adapter);