streamby-core 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.42.0
+
+### Added
+
+- **Project documents**: markdown a project's team reads and edits in the UI, and agents read and
+  keep up to date through the MCP server, with every save a version (who saved it, and when). The
+  README's Documents section documents them.
+  - **New tables: `documents` and `document_versions`.** They're created at startup in the main
+    database (collections in MongoDB; in memory without one).
+  - Routes under `/projects/:projectId/documents`: the tree, a document, creating, a new version
+    (`PATCH` with `baseVersion`; 409 with the document as it is now when it changed since), a
+    section's (`PATCH .../sections`), moving and marking exportable, the history
+    (`.../versions[/:version]`), publishing a version (`POST .../publish`) and deleting (a folder
+    with everything in it). Deleting a project deletes its documents.
+  - Permissions `docs:read`, `docs:write`, `docs:publish` and `docs:delete`. Publishing (a
+    version for the exports, or whether they deliver it: `POST .../publish`, `PATCH` with
+    `exportable`) needs `docs:publish`, not `docs:write`. The OAuth scopes grant reading
+    (`streamby:read`) and writing (`streamby:write`); an app publishes and deletes none, whatever
+    its scopes: what it edits stays a draft.
+  - In MongoDB, a save writes the document and its version in a transaction when the server has
+    them (a replica set or a sharded cluster); on a standalone server, two writes.
+  - MCP tools `list_documents`, `get_document`, `list_document_versions`, `create_document`,
+    `update_document` and `update_document_section`.
+  - An export's `documentsNode` delivers the published version of the project's exportable
+    documents (all, one folder's, or some), never a draft.
+  - A `documentEvent` to the project's active members on each change.
+  - Types `ProjectDocument`, `DocumentVersion`, `DocumentAuthor` and `DocumentKind`.
+
+## 0.41.0
+
+### Added
+
+- **OAuth access tokens**: apps the user signs in to with their account (claude.ai's
+  connector) work with StreamBy and its MCP server, as a protected resource (RFC 9728). The
+  README documents the setup, and how to add the connector in claude.ai.
+  - `createOAuthTokenVerifier({ issuer, audiences, jwks })` checks a token with the
+    authorization server's keys (RS256, from its JWKS URL or a function), its issuer, its
+    audience (one of StreamBy's resources, RFC 8707) and its expiry. The host's `authProvider`
+    returns its user with `apiToken: verified.scope` and `oauth: { clientId, clientName? }`.
+  - Scopes map to permissions: `streamby:read` to every `:read` one, `streamby:write` to those
+    and making and changing; none to deleting nor managing members (`OAUTH_SCOPE_PERMISSIONS`,
+    `permissionsForOAuthScopes`). The user's role in each project still applies.
+  - An app deletes nothing: its `DELETE` requests answer 403 whatever their route's permission
+    (`project:update`, `workflow:write` and `exports:write` reach some that delete), but taking
+    a deliverable's mark off. API tokens are unchanged.
+  - The router's `oauth` config (`{ issuer, resource, resourceMetadataUrl?, resourceName? }`)
+    makes a request without a valid token answer 401 with
+    `WWW-Authenticate: Bearer resource_metadata="..."`, and serves the metadata at
+    `GET /.well-known/oauth-protected-resource`; `protectedResourceMetadata` builds it for the
+    host to serve at its root too.
+  - `looksLikeOAuthAccessToken` tells an access token from a host's session tokens.
+- `Auth.oauth`: the app a request comes from. A request with it and without `apiToken` is
+  refused (an app never gets all of its user's access).
+
+### Changed
+
+- The MCP server takes an OAuth access token too. An app's requests are limited per user it acts
+  for, and its tool calls are recorded in `mcp_audit` by its client (`oauthClientId`, a new
+  column added at startup) with no `tokenId` (now nullable).
+
 ## 0.40.0
 
 ### ⚠️ Breaking changes

package/README.md

@@ -134,6 +134,7 @@ hash is stored, with a short prefix to tell it apart.
 | Exports | `exports:read`, `exports:write` | The project's exports. |
 | Rights | `rights:read`, `rights:write` | Assets' rights. |
 | Jobs | `jobs:read`, `jobs:run` | Following jobs; starting them (transcoding, rendering, AI, publishing a deliverable). |
+| Documents | `docs:read`, `docs:write`, `docs:publish`, `docs:delete` | The project's documents: reading them and their history; creating, editing and moving them; publishing them (the version its exports deliver, and whether they deliver it); deleting them. |
 | Account | `projects:create` | Creating projects. A user's token only; the token reaches what it creates. |
 
 `PROJECT_PERMISSIONS` and `ACCOUNT_PERMISSIONS` are exported. A route no permission covers
@@ -173,19 +174,107 @@ list shows only the token's projects.
 
 ---
 
+## 🔐 OAuth: apps the user signs in to
+
+An app the user signs in to with their account, such as claude.ai's connector, works with
+StreamBy through an **OAuth access token**, not an API token. StreamBy is the protected resource
+(RFC 9728); the tokens are issued by the host's authorization server (for Nhexa, Nhexa-API).
+
+A token is a JWT the server signs with RS256 for one resource (its audience, RFC 8707), checked
+with the server's published keys (JWKS) alone: no secret is shared. It reaches what the user
+approved, and never more than the user can: their role in each project still applies.
+
+| Scope | Permissions |
+|---|---|
+| `streamby:read` | Every `:read` permission: `project:read`, `members:read`, `assets:read`, `production:read`, `workflow:read`, `exports:read`, `rights:read`, `jobs:read`, `docs:read`. |
+| `streamby:write` | Those, and making and changing: `project:update`, `assets:write`, `production:write`, `workflow:write`, `exports:write`, `rights:write`, `jobs:run`, `projects:create`, `docs:write`. |
+
+No scope grants deleting (`*:delete`, `project:delete`) nor managing members. And since some
+write permissions also reach routes that delete (`project:update` a connection, a worker or an
+integration; `workflow:write` a pipeline; `exports:write` an export), **an app's `DELETE` is
+refused (403) whatever its route**, but taking a deliverable's mark off, which only forgets the
+mark (the asset stays). Nor does an app publish a document (`POST .../publish`, or a `PATCH`
+changing `exportable`), whatever its scopes: what it edits stays a draft until someone publishes
+it. API tokens aren't affected. Other scopes (`profile`, `email`) grant nothing in StreamBy. `OAUTH_SCOPE_PERMISSIONS` is exported.
+
+**Telling clients where to sign in**
+
+Set `oauth` in the router's config. A request without a valid token then gets a 401 with
+`WWW-Authenticate: Bearer resource_metadata="..."`, and the metadata says which authorization
+server to use. The router serves it at `GET /streamby/.well-known/oauth-protected-resource`;
+serve it at your root too, where RFC 9728 puts it (`resourceMetadataUrl` defaults to that):
+
+```ts
+import express from 'express';
+import { createStreamByRouter, protectedResourceMetadata } from 'streamby-core';
+
+const oauth = { issuer: 'https://api.example.com', resource: 'https://api.example.com/streamby/mcp' };
+app.get('/.well-known/oauth-protected-resource/streamby/mcp', (_req, res) => res.json(protectedResourceMetadata(oauth)));
+app.use('/streamby', createStreamByRouter({ /* ... */ oauth }));
+```
+
+**Validating a token (your `authProvider`)**
+
+Your `authProvider` checks the token with `createOAuthTokenVerifier` and returns the user, with
+the token's scope in `apiToken` and the app in `oauth`. A request with `oauth` but no `apiToken`
+is refused, so an app never gets all of its user's access. `looksLikeOAuthAccessToken` tells the
+token from your own session tokens.
+
+```ts
+import { createOAuthTokenVerifier, looksLikeOAuthAccessToken, API_TOKEN_PREFIX } from 'streamby-core';
+
+const verifyOAuthToken = createOAuthTokenVerifier({
+  issuer: 'https://api.example.com',
+  // What a token may be for: StreamBy's resources.
+  audiences: ['https://api.example.com/streamby', 'https://api.example.com/streamby/mcp'],
+  // The server's JWKS URL, or a function giving its keys (when the host is the server itself).
+  jwks: 'https://api.example.com/.well-known/jwks.json',
+});
+
+createStreamByRouter({
+  // ...
+  authProvider: async (req) => {
+    const bearer = req.headers.authorization?.replace(/^Bearer /, '');
+    if (bearer?.startsWith(API_TOKEN_PREFIX)) { /* an API token, as above */ }
+    if (looksLikeOAuthAccessToken(bearer)) {
+      const verified = await verifyOAuthToken(bearer); // null: forged, expired, or for another resource
+      if (!verified) throw new Error('Invalid OAuth access token');
+      // Optional but recommended: has the user taken the app's access away? (your own records)
+      if (!(await stillConnected(verified.userId, verified.clientId))) throw new Error('Access revoked');
+      const user = await findUser(verified.userId);
+      return {
+        userId: user.id, username: user.username, role: user.role,
+        apiToken: verified.scope,
+        oauth: { clientId: verified.clientId, clientName: 'Claude' }, // the name, if you know it
+      };
+    }
+    // ...your session-based authentication
+  },
+});
+```
+
+The verifier keeps the keys for 5 minutes (`jwksCacheMs`) and fetches them again for a key id it
+doesn't know (a rotation), at most once a minute. It doesn't know whether the user has since
+taken the app's access away: without that check, a revoked app keeps its access until its access
+token expires (Nhexa's last an hour). Nhexa-API checks the user's consent on every request, so
+taking the access away in accounts.nhexa.cl ends it at once.
+
+---
+
 ## 🤖 MCP server
 
 StreamBy serves an [MCP](https://modelcontextprotocol.io) server at `POST /streamby/mcp`
 (Streamable HTTP, stateless). Agents such as Claude Code use it to read and work on StreamBy
-projects with an API token (see above). It takes only an API token; a browser session gets 401.
+projects with an API token, and apps the user signed in to (claude.ai's connector) with an OAuth
+access token (see above). A browser session gets 401.
 
 Each tool calls StreamBy's own REST API with the caller's token. So it reaches exactly what the
-token allows (and, for a user's token, what its user's role in each project allows), and a
+token allows (and, for a user's token or an app, what the user's role in each project allows), and a
 change is saved just like one made from the UI, which shows it when it loads the project.
 
 **Tools**
 
-A token sees only the tools whose permissions it has.
+A token sees only the tools whose permissions it has (an app: those its scopes grant).
 
 | Tools | Permissions |
 |---|---|
@@ -210,6 +299,8 @@ A token sees only the tools whose permissions it has.
 | `delete_sequence`, `delete_shot`, `delete_task` | `production:delete` |
 | `list_asset_versions`, `get_asset_download_url`, `list_deliverables` | `assets:read` |
 | `request_asset_upload`, `mark_deliverable`, `remove_deliverable` | `assets:write` |
+| `list_documents`, `get_document`, `list_document_versions` | `docs:read` |
+| `create_document`, `update_document`, `update_document_section` | `docs:write` |
 
 The tools take the path a user does in the UI, and each one's description says where its
 result shows there. Production data lives under a production node of the project's workflow:
@@ -273,13 +364,14 @@ code there that downloads the URL and imports the file (in Blender,
 
 **Limits and audit**
 
-- Each token can make at most 120 requests a minute (a sliding window). Past that, StreamBy
-  answers 429 with `Retry-After`. Each instance counts its own requests. Change the limit with
-  `mcp.rateLimit`.
+- Each token can make at most 120 requests a minute (a sliding window); an app, per user it acts
+  for. Past that, StreamBy answers 429 with `Retry-After`. Each instance counts its own
+  requests. Change the limit with `mcp.rateLimit`.
 - Every tool call is recorded in the `mcp_audit` table, created at startup in the main database.
-  Each row has the user (a project's token: the token itself), the token's id, the project, the
-  tool, whether it went through, the status, the error and the duration. A row never includes
-  the arguments or the token.
+  Each row has the user (a project's token: the token itself), the token's id (an app's call:
+  its OAuth client, in `oauthClientId`, and no token), the project, the tool, whether it went
+  through, the status, the error and the duration. A row never includes the arguments or the
+  token.
 
 ```ts
 createStreamByRouter({
@@ -337,7 +429,67 @@ and an expiry:
 }
 ```
 
-The claude.ai connector needs OAuth, which isn't available yet: it's for API tokens only for now.
+### Connecting from claude.ai
+
+claude.ai connects through a custom connector, which signs in with OAuth (see above): nobody on
+the team sets up a token or a file. Each person signs in with their own account and approves what
+Claude may do, and Claude reaches only that, and only what their role in each project allows.
+
+- **For yourself**: in claude.ai, Settings → Connectors → Add custom connector. Give it a name
+  (StreamBy) and the server's URL, `https://your-host/streamby/mcp`, and add it. Then Connect:
+  claude.ai opens the sign-in page, and after you sign in, the consent screen, with what it asks
+  for (`streamby:read`, and `streamby:write` to make and change things). Approve it.
+- **For your organization** (Team and Enterprise plans): an owner adds it once in Organization
+  settings → Connectors, with the same URL; each member then connects it with their own account
+  from their Settings → Connectors.
+
+claude.ai registers itself with the authorization server (dynamic client registration or a
+client ID metadata document), so there's nothing to set up there. To take its access away, the
+person removes it in their account's connected apps (in Nhexa, accounts.nhexa.cl → Aplicaciones
+→ Quitar acceso), or disconnects it in claude.ai.
+
+---
+
+## 📄 Documents
+
+Each project keeps its documents: markdown its team reads and edits (its concept, its
+architecture, its decisions), and agents read and keep up to date through the MCP server. They're
+kept in the main database (the `documents` and `document_versions` tables, created at startup,
+or collections), each one in a single project, in folders.
+
+- **Every save is a version**, with who saved it and when: a user, an API token, or an app on a
+  user's behalf (`{ userId, username, via: 'session' | 'apiToken' | 'oauth', tokenId?, clientId?, clientName? }`).
+- **Nothing is overwritten without notice.** A change says the version it was made on
+  (`baseVersion`); if someone saved another one since, it's refused with a 409 and the document
+  as it is now, to read again.
+- **A section** is what's under a heading (`## Architecture`), up to the next one of the same
+  level or above: it can be replaced alone, the rest untouched.
+- **Drafts and published versions.** A document marked exportable delivers, through the project's
+  exports, only the version published from its history; editing it changes nothing exported until
+  another version is published. An export's `documentsNode` (on the StreamBy node's data input)
+  delivers them, `[{ id, title, parentId, position, version, content, publishedAt }]`: all the
+  project's, those in one folder (`data.folderId`), or some (`data.documentIds`).
+- **In real time**, a `documentEvent` reaches the project's active members on each change:
+  `{ projectId, action: 'created' | 'saved' | 'changed' | 'deleted', documentIds, version?, title?, author }`
+  (`saved` is a new version; `changed`, a move or a publication).
+
+| Route | Permission |
+|---|---|
+| `GET /projects/:projectId/documents`: the tree, without contents | `docs:read` |
+| `POST /projects/:projectId/documents` `{ title, content?, kind?: 'document' \| 'folder', parentId?, position? }` | `docs:write` |
+| `GET /projects/:projectId/documents/:docId` | `docs:read` |
+| `PATCH /projects/:projectId/documents/:docId` `{ baseVersion, title?, content? }` (a new version) and/or `{ parentId?, position? }` | `docs:write` |
+| `PATCH /projects/:projectId/documents/:docId` `{ exportable }` | `docs:write` and `docs:publish` |
+| `PATCH /projects/:projectId/documents/:docId/sections` `{ baseVersion, heading, content }` | `docs:write` |
+| `GET /projects/:projectId/documents/:docId/versions` and `/versions/:version` | `docs:read` |
+| `POST /projects/:projectId/documents/:docId/publish` `{ version }` (`null`: none) | `docs:publish` |
+| `DELETE /projects/:projectId/documents/:docId` (a folder, with everything in it) | `docs:delete` |
+
+Editors and admins create, edit, publish and delete them; viewers read them. An app connected
+with OAuth reads and edits them, but publishes and deletes none: what it edits stays a draft.
+
+In MongoDB, a save writes the document and its version in a transaction when the server has them
+(a replica set or a sharded cluster). A standalone server doesn't: there they're two writes.
 
 ---
 
@@ -455,7 +607,7 @@ What a user can do in a project depends on their role in that project, as an act
 | Role | Can |
 |---|---|
 | `viewer` | See the project and its content, and archive the project in their own list. |
-| `editor` | Everything a viewer can, plus change the project: its details, connections, exports, files and folders, workflow, pipelines, production, reviews, rights, and start jobs. |
+| `editor` | Everything a viewer can, plus change the project: its details, connections, exports, files and folders, workflow, pipelines, production, reviews, rights, documents, and start jobs. |
 | `admin` | Everything an editor can, plus manage the project's members and delete the project. |
 
 A project's public exports (`GET /streamby/:projectId/export/:exportName`) are read without a

package/dist/adapters/database/connectionManager.js

@@ -249,8 +249,43 @@ const createTables = async (pool) => {
         "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
       );
       CREATE INDEX IF NOT EXISTS mcp_audit_token_idx ON streamby.mcp_audit ("tokenId", "createdAt");
+      -- An app's calls (an OAuth access token) are recorded by its client, with no token.
+      ALTER TABLE streamby.mcp_audit ADD COLUMN IF NOT EXISTS "oauthClientId" VARCHAR(255);
+      ALTER TABLE streamby.mcp_audit ALTER COLUMN "tokenId" DROP NOT NULL;
     `);
         console.log('✅ "mcp_audit" table ensured to exist.');
+        // Projects' documents and their versions (see services/documents). Main db only.
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.documents (
+        id                  TEXT PRIMARY KEY,
+        "projectId"         VARCHAR(255) NOT NULL,
+        kind                VARCHAR(20) NOT NULL DEFAULT 'document',
+        title               TEXT NOT NULL,
+        "parentId"          TEXT,
+        position            INTEGER NOT NULL DEFAULT 0,
+        content             TEXT NOT NULL DEFAULT '',
+        version             INTEGER NOT NULL,
+        exportable          BOOLEAN NOT NULL DEFAULT FALSE,
+        "publishedVersion"  INTEGER,
+        "createdAt"         TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        "createdBy"         JSONB NOT NULL,
+        "updatedAt"         TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        "updatedBy"         JSONB NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS documents_project_idx ON streamby.documents ("projectId");
+      CREATE TABLE IF NOT EXISTS streamby.document_versions (
+        "documentId"  TEXT NOT NULL,
+        "projectId"   VARCHAR(255) NOT NULL,
+        version       INTEGER NOT NULL,
+        title         TEXT NOT NULL,
+        content       TEXT NOT NULL,
+        author        JSONB NOT NULL,
+        "createdAt"   TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+        PRIMARY KEY ("documentId", version)
+      );
+      CREATE INDEX IF NOT EXISTS document_versions_project_idx ON streamby.document_versions ("projectId");
+    `);
+        console.log('✅ "documents" and "document_versions" tables ensured to exist.');
     }
     catch (error) {
         console.error('❌ Error ensuring tables exist:', error);

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { createStreamByRouter } from './middleware/createRouter';
 export { emitToUser } from './services/wsHub';
 export { createNotification } from './services/notification';
-export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenKind, ApiTokenPermission, ProjectPermission, AccountPermission } from './types';
+export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenKind, ApiTokenPermission, ProjectPermission, AccountPermission, OAuthClientInfo, OAuthResourceConfig, ProjectDocument, DocumentVersion, DocumentAuthor, DocumentKind } from './types';
 export { resolveApiToken, API_TOKEN_PREFIX } from './services/apiTokens';
 export { PROJECT_PERMISSIONS, ACCOUNT_PERMISSIONS } from './services/apiTokenPermissions';
 export type { ResolvedApiToken } from './services/apiTokens';
+export { createOAuthTokenVerifier, looksLikeOAuthAccessToken, protectedResourceMetadata, defaultResourceMetadataUrl, permissionsForOAuthScopes, OAUTH_SCOPES, OAUTH_SCOPE_PERMISSIONS, } from './services/oauthTokens';
+export type { VerifiedOAuthToken, OAuthTokenVerifierOptions, Jwks, Jwk, OAuthScope } from './services/oauthTokens';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACCOUNT_PERMISSIONS = exports.PROJECT_PERMISSIONS = exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
+exports.OAUTH_SCOPE_PERMISSIONS = exports.OAUTH_SCOPES = exports.permissionsForOAuthScopes = exports.defaultResourceMetadataUrl = exports.protectedResourceMetadata = exports.looksLikeOAuthAccessToken = exports.createOAuthTokenVerifier = exports.ACCOUNT_PERMISSIONS = exports.PROJECT_PERMISSIONS = exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
 var createRouter_1 = require("./middleware/createRouter");
 Object.defineProperty(exports, "createStreamByRouter", { enumerable: true, get: function () { return createRouter_1.createStreamByRouter; } });
 var wsHub_1 = require("./services/wsHub");
@@ -13,3 +13,11 @@ Object.defineProperty(exports, "API_TOKEN_PREFIX", { enumerable: true, get: func
 var apiTokenPermissions_1 = require("./services/apiTokenPermissions");
 Object.defineProperty(exports, "PROJECT_PERMISSIONS", { enumerable: true, get: function () { return apiTokenPermissions_1.PROJECT_PERMISSIONS; } });
 Object.defineProperty(exports, "ACCOUNT_PERMISSIONS", { enumerable: true, get: function () { return apiTokenPermissions_1.ACCOUNT_PERMISSIONS; } });
+var oauthTokens_1 = require("./services/oauthTokens");
+Object.defineProperty(exports, "createOAuthTokenVerifier", { enumerable: true, get: function () { return oauthTokens_1.createOAuthTokenVerifier; } });
+Object.defineProperty(exports, "looksLikeOAuthAccessToken", { enumerable: true, get: function () { return oauthTokens_1.looksLikeOAuthAccessToken; } });
+Object.defineProperty(exports, "protectedResourceMetadata", { enumerable: true, get: function () { return oauthTokens_1.protectedResourceMetadata; } });
+Object.defineProperty(exports, "defaultResourceMetadataUrl", { enumerable: true, get: function () { return oauthTokens_1.defaultResourceMetadataUrl; } });
+Object.defineProperty(exports, "permissionsForOAuthScopes", { enumerable: true, get: function () { return oauthTokens_1.permissionsForOAuthScopes; } });
+Object.defineProperty(exports, "OAUTH_SCOPES", { enumerable: true, get: function () { return oauthTokens_1.OAUTH_SCOPES; } });
+Object.defineProperty(exports, "OAUTH_SCOPE_PERMISSIONS", { enumerable: true, get: function () { return oauthTokens_1.OAUTH_SCOPE_PERMISSIONS; } });

package/dist/mcp/audit.d.ts

@@ -1,7 +1,8 @@
-import { StreamByConfig } from '../types';
+import { Auth, StreamByConfig } from '../types';
 export interface McpAuditEntry {
     userId: string;
-    tokenId: string;
+    tokenId: string | null;
+    oauthClientId: string | null;
     projectId: string | null;
     tool: string;
     ok: boolean;
@@ -9,4 +10,6 @@ export interface McpAuditEntry {
     error: string | null;
     durationMs: number;
 }
+/** Who made an MCP request, as the audit log keeps it. */
+export declare const auditCallerOf: (auth: Auth) => Pick<McpAuditEntry, "userId" | "tokenId" | "oauthClientId">;
 export declare function recordMcpCall(entry: McpAuditEntry, config: StreamByConfig): Promise<void>;

package/dist/mcp/audit.js

@@ -3,9 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditCallerOf = void 0;
 exports.recordMcpCall = recordMcpCall;
 const crypto_1 = __importDefault(require("crypto"));
 const manager_1 = require("../models/manager");
+/** Who made an MCP request, as the audit log keeps it. */
+const auditCallerOf = (auth) => ({
+    userId: auth.userId,
+    tokenId: auth.oauth ? null : auth.apiToken?.tokenId ?? null,
+    oauthClientId: auth.oauth?.clientId ?? null,
+});
+exports.auditCallerOf = auditCallerOf;
 async function recordMcpCall(entry, config) {
     try {
         const dbType = config.databases?.find(db => db.main)?.type ?? 'nosql';

package/dist/mcp/server.js

@@ -40,7 +40,7 @@ function createMcpServer(auth, api, config, version) {
                     const refused = await (0, workflowNodes_1.ensureWorkflowNode)(tool.workflowNode, tool.projectOf?.(args), auth, api);
                     if (refused) {
                         await (0, audit_1.recordMcpCall)({
-                            userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                            ...(0, audit_1.auditCallerOf)(auth), projectId, tool: tool.name,
                             ok: false, status: null, error: refused, durationMs: Date.now() - started,
                         }, config);
                         return { isError: true, content: [{ type: 'text', text: refused }] };
@@ -50,7 +50,7 @@ function createMcpServer(auth, api, config, version) {
                 status = answer.status;
                 const ok = status >= 200 && status < 300;
                 await (0, audit_1.recordMcpCall)({
-                    userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                    ...(0, audit_1.auditCallerOf)(auth), projectId, tool: tool.name,
                     ok, status, error: ok ? null : errorText(answer.body, status), durationMs: Date.now() - started,
                 }, config);
                 if (!ok)
@@ -61,7 +61,7 @@ function createMcpServer(auth, api, config, version) {
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 await (0, audit_1.recordMcpCall)({
-                    userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                    ...(0, audit_1.auditCallerOf)(auth), projectId, tool: tool.name,
                     ok: false, status, error: message, durationMs: Date.now() - started,
                 }, config);
                 return { isError: true, content: [{ type: 'text', text: `The call failed: ${message}` }] };

package/dist/mcp/tools.js

@@ -358,6 +358,74 @@ exports.TOOLS = [
         call: ({ projectId, jobId }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/jobs/${enc(jobId)}/retry` }),
         pick: (data) => data?.job,
     }),
+    // ── Documents ──
+    tool({
+        name: 'list_documents', title: 'List documents', permissions: ['docs:read'],
+        description: "A project's documents (its concept, architecture, decisions...), as the tree of its Documents section shows them: each one's id, title, folder (parentId; a folder's kind is 'folder'), position, current version and the version published through its exports, without their content (read one with get_document).",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/documents` }),
+        pick: (data) => data?.documents ?? [],
+    }),
+    tool({
+        name: 'get_document', title: 'Read a document', permissions: ['docs:read'],
+        description: "A document's markdown and its current version, the one an update is made on. With `version`, that past version instead (see list_document_versions).",
+        input: { projectId, documentId: id('document'), version: zod_1.z.number().int().min(1).optional().describe('A past version to read; the current one if not given') },
+        projectOf: byProject,
+        call: ({ projectId, documentId, version }) => ({
+            method: 'GET',
+            path: `/projects/${enc(projectId)}/documents/${enc(documentId)}${version ? `/versions/${version}` : ''}`,
+        }),
+        pick: (data) => data?.document ?? data?.version,
+    }),
+    tool({
+        name: 'list_document_versions', title: "List a document's versions", permissions: ['docs:read'],
+        description: "A document's history, the latest first: each version's number, title, who saved it (a user, an API token, or an app on a user's behalf) and when.",
+        input: { projectId, documentId: id('document') },
+        projectOf: byProject,
+        call: ({ projectId, documentId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}/versions` }),
+        pick: (data) => data?.versions ?? [],
+    }),
+    tool({
+        name: 'create_document', title: 'Create a document', permissions: ['docs:write'], write: true,
+        description: "Creates a markdown document (or, with kind 'folder', a folder to group them) in a project's Documents section, at the end of its folder. It's a draft: nothing is exported until someone publishes a version of it in the UI.",
+        input: {
+            projectId,
+            title: zod_1.z.string().min(1),
+            content: zod_1.z.string().optional().describe('Its markdown'),
+            kind: zod_1.z.enum(['document', 'folder']).optional(),
+            parentId: zod_1.z.string().optional().describe("The folder it goes in (a folder's id); at the top if not given"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/documents`, body: defined(fields) }),
+        pick: (data) => data?.document,
+    }),
+    tool({
+        name: 'update_document', title: 'Update a document', permissions: ['docs:write'], write: true,
+        description: "Saves a new version of a document: its whole markdown, its title, or both. `baseVersion` is the version it was read at (get_document): if someone saved another one since, nothing is saved and the answer says so; read it again and make the change on the new version. To change one part, update_document_section rewrites less.",
+        input: {
+            projectId, documentId: id('document'),
+            baseVersion: zod_1.z.number().int().min(1).describe('The version the change was made on'),
+            title: zod_1.z.string().min(1).optional(),
+            content: zod_1.z.string().optional().describe('The whole new markdown'),
+        },
+        projectOf: byProject,
+        call: ({ projectId, documentId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}`, body: defined(fields) }),
+        pick: (data) => data?.document,
+    }),
+    tool({
+        name: 'update_document_section', title: "Update a document's section", permissions: ['docs:write'], write: true,
+        description: "Saves a new version of a document with only what's under one of its headings replaced (up to the next heading of the same level or above), the rest untouched. `heading` is the heading as written (\"## Architecture\") or its title alone. `baseVersion` is the version it was read at: if the document changed since, nothing is saved; read it again.",
+        input: {
+            projectId, documentId: id('document'),
+            baseVersion: zod_1.z.number().int().min(1).describe('The version the change was made on'),
+            heading: zod_1.z.string().min(1).describe('The section\'s heading, e.g. "## Architecture"'),
+            content: zod_1.z.string().describe("The section's new markdown, without its heading"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, documentId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/documents/${enc(documentId)}/sections`, body: fields }),
+        pick: (data) => data?.document,
+    }),
     // ── Projects ──
     tool({
         name: 'create_project', title: 'Create a project', permissions: ['projects:create'], write: true,

package/dist/middleware/createRouter.js

@@ -28,6 +28,7 @@ const dbConnection_1 = require("./routes/dbConnection");
 const storageConnection_1 = require("./routes/storageConnection");
 const userIntegration_1 = require("./routes/userIntegration");
 const oauth_1 = require("./routes/oauth");
+const oauthResource_1 = require("./routes/oauthResource");
 const notification_1 = require("./routes/notification");
 const subscription_1 = require("./routes/subscription");
 const media_1 = require("./routes/media");
@@ -43,11 +44,14 @@ const worker_1 = require("./routes/worker");
 const workerCallback_1 = require("./routes/workerCallback");
 const workerJobs_1 = require("../services/workerJobs");
 const deliverable_1 = require("./routes/deliverable");
+const document_1 = require("./routes/document");
+const documents_1 = require("../services/documents");
 function createStreamByRouter(config) {
     const router = express_1.default.Router();
     if (config.encrypt)
         (0, encryption_1.setEncryptionKey)(config.encrypt, config.encryptPreviousKeys);
     (0, jobStore_1.setJobStoreDatabase)(config);
+    (0, documents_1.setDocumentStoreDatabase)(config);
     // Establish DB connections asynchronously (Postgres/Mongo + schema migrations).
     // Until they're ready, HOLD incoming requests instead of letting them through —
     // route handlers resolve projects/exports (e.g. the /menu-list export) against a
@@ -112,6 +116,8 @@ function createStreamByRouter(config) {
     if (config.websocket?.server) {
         (0, wsHub_1.initWsHub)(config.websocket.server, config);
     }
+    // Where to sign in for a token (RFC 9728): open, before anything asks for one.
+    router.use((0, oauthResource_1.oauthResourceRouter)(config));
     // /auth answers whether there's a session (it reads it itself); everything after needs one,
     // but for the public export route (see authenticate).
     router.use((0, auth_2.authRouter)(config));
@@ -146,5 +152,6 @@ function createStreamByRouter(config) {
     router.use((0, pipeline_1.pipelineRouter)(config));
     router.use((0, worker_1.workerRouter)({ ...config, adapter }));
     router.use((0, deliverable_1.deliverableRouter)({ ...config, adapter }));
+    router.use((0, document_1.documentRouter)(config));
     return router;
 }

package/dist/middleware/routes/document.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import { StreamByConfig } from '../../types';
+export declare function documentRouter(_config: StreamByConfig): Router;