streamby-core 0.40.0 → 0.42.0

package/dist/middleware/routes/document.js

@@ -0,0 +1,343 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.documentRouter = documentRouter;
+const express_1 = require("express");
+const crypto_1 = __importDefault(require("crypto"));
+const manager_1 = require("../../models/manager");
+const auth_1 = require("../../utils/auth");
+const wsHub_1 = require("../../services/wsHub");
+const documents_1 = require("../../services/documents");
+const auth_2 = require("../../services/auth");
+const MAX_TITLE = 200;
+const MAX_CONTENT = 1000000;
+// What happened to a project's documents, to whoever is in it now: a view of a document
+// refreshes itself, an editor warns of a newer version. `version` and `author` come with a save.
+function broadcast(project, data) {
+    const projectId = String(project._id ?? project.id);
+    for (const member of project.members ?? []) {
+        if ((0, auth_1.activeMemberOf)(project, member.userId))
+            (0, wsHub_1.emitToUser)(member.userId, { type: 'documentEvent', data: { projectId, ...data } });
+    }
+}
+const isVersion = (value) => Number.isInteger(value) && value >= 1;
+function checkTitle(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return { error: 'A title is required' };
+    if (value.trim().length > MAX_TITLE)
+        return { error: `A title has at most ${MAX_TITLE} characters` };
+    return value.trim();
+}
+function checkContent(value) {
+    if (typeof value !== 'string')
+        return { error: 'content must be text (markdown)' };
+    if (value.length > MAX_CONTENT)
+        return { error: `A document has at most ${MAX_CONTENT} characters` };
+    return value;
+}
+// Where a document may go: the top (null), or a folder of the same project that isn't the
+// document itself nor inside it.
+function checkParent(value, documents, movingId) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        return { error: 'parentId must be a folder\'s id, or null' };
+    const parent = documents.find(d => d.id === value);
+    if (!parent)
+        return { error: 'No such folder in this project' };
+    if (parent.kind !== 'folder')
+        return { error: 'A document goes in a folder, not in another document' };
+    if (movingId && (0, documents_1.withDescendants)(documents, movingId).includes(value))
+        return { error: 'A folder can\'t go inside itself' };
+    return value;
+}
+const failed = (value) => typeof value === 'object' && value !== null && 'error' in value;
+function documentRouter(_config) {
+    const router = (0, express_1.Router)();
+    const Project = (0, manager_1.getModel)('projects');
+    // The project, if the caller may see it (or, with `edit`, change it); otherwise the answer.
+    async function projectFor(req, res, edit = false) {
+        const auth = req.auth;
+        const project = await Project.findOne({ _id: req.params.projectId });
+        if (!project) {
+            res.status(404).json({ message: 'Project not found' });
+            return null;
+        }
+        if (!(edit ? auth_1.canEditProject : auth_1.isProjectMember)(project, auth.userId)) {
+            res.status(403).json({ message: 'Unauthorized' });
+            return null;
+        }
+        return { project, auth, projectId: String(req.params.projectId) };
+    }
+    const conflict = (res, current) => res.status(409).json({
+        message: `The document changed: it's at version ${current.version} now. Read it again, and make the change on that version.`,
+        document: current,
+    });
+    router.get('/projects/:projectId/documents', async (req, res) => {
+        try {
+            const found = await projectFor(req, res);
+            if (!found)
+                return;
+            res.json({ documents: await (0, documents_1.documentStore)().list(found.projectId) });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    router.post('/projects/:projectId/documents', async (req, res) => {
+        try {
+            const found = await projectFor(req, res, true);
+            if (!found)
+                return;
+            const { project, auth, projectId } = found;
+            const kind = req.body?.kind === 'folder' ? 'folder' : 'document';
+            if (req.body?.kind !== undefined && !['document', 'folder'].includes(req.body.kind))
+                return res.status(400).json({ message: "kind is 'document' or 'folder'" });
+            const title = checkTitle(req.body?.title);
+            if (failed(title))
+                return res.status(400).json({ message: title.error });
+            if (kind === 'folder' && req.body?.content)
+                return res.status(400).json({ message: 'A folder has no content' });
+            const content = kind === 'folder' ? '' : checkContent(req.body?.content ?? '');
+            if (failed(content))
+                return res.status(400).json({ message: content.error });
+            const store = (0, documents_1.documentStore)();
+            const documents = await store.list(projectId);
+            const parentId = checkParent(req.body?.parentId ?? null, documents);
+            if (failed(parentId))
+                return res.status(400).json({ message: parentId.error });
+            if (req.body?.position !== undefined && !Number.isInteger(req.body.position))
+                return res.status(400).json({ message: 'position must be a whole number' });
+            // At the end of its folder, unless placed.
+            const siblings = documents.filter(d => d.parentId === parentId);
+            const position = req.body?.position ?? (siblings.length ? Math.max(...siblings.map(d => d.position)) + 1 : 0);
+            const now = new Date();
+            const author = (0, documents_1.authorOf)(auth);
+            const document = await store.create({
+                id: crypto_1.default.randomUUID(), projectId, kind, title, parentId, position, content, version: 1,
+                exportable: false, publishedVersion: null, createdAt: now, createdBy: author, updatedAt: now, updatedBy: author,
+            });
+            broadcast(project, { action: 'created', documentIds: [document.id], version: 1, title, author });
+            res.status(201).json({ document });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    router.get('/projects/:projectId/documents/:docId', async (req, res) => {
+        try {
+            const found = await projectFor(req, res);
+            if (!found)
+                return;
+            const document = await (0, documents_1.documentStore)().get(found.projectId, req.params.docId);
+            if (!document)
+                return res.status(404).json({ message: 'Document not found' });
+            res.json({ document });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    // Its title or content (a new version, made on `baseVersion`), and where it is in the tree
+    // or whether it's exportable (not a version).
+    router.patch('/projects/:projectId/documents/:docId', async (req, res) => {
+        try {
+            const found = await projectFor(req, res, true);
+            if (!found)
+                return;
+            const { project, auth, projectId } = found;
+            const { docId } = req.params;
+            const body = req.body ?? {};
+            const store = (0, documents_1.documentStore)();
+            const current = await store.get(projectId, docId);
+            if (!current)
+                return res.status(404).json({ message: 'Document not found' });
+            const changesText = body.title !== undefined || body.content !== undefined;
+            const changesPlace = body.parentId !== undefined || body.position !== undefined || body.exportable !== undefined;
+            if (!changesText && !changesPlace)
+                return res.status(400).json({ message: 'Nothing to change: title, content, parentId, position or exportable' });
+            // Everything is checked before anything changes.
+            let text;
+            if (changesText) {
+                if (!isVersion(body.baseVersion))
+                    return res.status(400).json({ message: 'baseVersion is required: the version the change was made on' });
+                const title = body.title === undefined ? current.title : checkTitle(body.title);
+                if (failed(title))
+                    return res.status(400).json({ message: title.error });
+                if (current.kind === 'folder' && body.content)
+                    return res.status(400).json({ message: 'A folder has no content' });
+                const content = body.content === undefined ? current.content : checkContent(body.content);
+                if (failed(content))
+                    return res.status(400).json({ message: content.error });
+                text = { title, content };
+            }
+            const place = {};
+            if (body.parentId !== undefined) {
+                const parentId = checkParent(body.parentId, await store.list(projectId), docId);
+                if (failed(parentId))
+                    return res.status(400).json({ message: parentId.error });
+                place.parentId = parentId;
+            }
+            if (body.position !== undefined) {
+                if (!Number.isInteger(body.position))
+                    return res.status(400).json({ message: 'position must be a whole number' });
+                place.position = body.position;
+            }
+            if (body.exportable !== undefined) {
+                // Whether its exports deliver it is publishing it: a token needs docs:publish.
+                if (auth.apiToken && !(0, auth_2.tokenAllows)(auth.apiToken, 'docs:publish')) {
+                    return res.status(403).json({ error: "This API token doesn't have the 'docs:publish' permission" });
+                }
+                if (typeof body.exportable !== 'boolean')
+                    return res.status(400).json({ message: 'exportable is true or false' });
+                if (current.kind === 'folder')
+                    return res.status(400).json({ message: 'A folder isn\'t exported: its documents are' });
+                place.exportable = body.exportable;
+            }
+            const author = (0, documents_1.authorOf)(auth);
+            let document = current;
+            if (text) {
+                document = await store.save(projectId, docId, body.baseVersion, text, author, new Date());
+                if (!document) {
+                    const now = await store.get(projectId, docId);
+                    return now ? conflict(res, now) : res.status(404).json({ message: 'Document not found' });
+                }
+            }
+            if (changesPlace)
+                document = await store.update(projectId, docId, place);
+            if (!document)
+                return res.status(404).json({ message: 'Document not found' });
+            broadcast(project, text
+                ? { action: 'saved', documentIds: [docId], version: document.version, title: document.title, author }
+                : { action: 'changed', documentIds: [docId], author });
+            res.json({ document });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    // What's under one of its headings, the rest untouched: a new version, made on `baseVersion`.
+    router.patch('/projects/:projectId/documents/:docId/sections', async (req, res) => {
+        try {
+            const found = await projectFor(req, res, true);
+            if (!found)
+                return;
+            const { project, auth, projectId } = found;
+            const { docId } = req.params;
+            const { baseVersion, heading, content } = req.body ?? {};
+            if (!isVersion(baseVersion))
+                return res.status(400).json({ message: 'baseVersion is required: the version the change was made on' });
+            if (typeof heading !== 'string' || !heading.trim())
+                return res.status(400).json({ message: 'heading is required: the section\'s heading, e.g. "## Architecture"' });
+            const body = checkContent(content);
+            if (failed(body))
+                return res.status(400).json({ message: body.error });
+            const store = (0, documents_1.documentStore)();
+            const current = await store.get(projectId, docId);
+            if (!current)
+                return res.status(404).json({ message: 'Document not found' });
+            if (current.kind === 'folder')
+                return res.status(400).json({ message: 'A folder has no content' });
+            // A section of another version than the one it was read on could be another text.
+            if (current.version !== baseVersion)
+                return conflict(res, current);
+            const replaced = (0, documents_1.replaceSection)(current.content, heading, body);
+            if ('error' in replaced) {
+                return replaced.error === 'not-found'
+                    ? res.status(404).json({ message: `No section "${heading.trim()}" in the document` })
+                    : res.status(400).json({ message: `More than one section is "${heading.trim()}": give the heading with its #s, or update the whole document` });
+            }
+            const author = (0, documents_1.authorOf)(auth);
+            const document = await store.save(projectId, docId, baseVersion, { title: current.title, content: replaced.content }, author, new Date());
+            if (!document) {
+                const now = await store.get(projectId, docId);
+                return now ? conflict(res, now) : res.status(404).json({ message: 'Document not found' });
+            }
+            broadcast(project, { action: 'saved', documentIds: [docId], version: document.version, title: document.title, author });
+            res.json({ document });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    router.get('/projects/:projectId/documents/:docId/versions', async (req, res) => {
+        try {
+            const found = await projectFor(req, res);
+            if (!found)
+                return;
+            const store = (0, documents_1.documentStore)();
+            if (!(await store.get(found.projectId, req.params.docId)))
+                return res.status(404).json({ message: 'Document not found' });
+            res.json({ versions: await store.versions(found.projectId, req.params.docId) });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    router.get('/projects/:projectId/documents/:docId/versions/:version', async (req, res) => {
+        try {
+            const found = await projectFor(req, res);
+            if (!found)
+                return;
+            const number = Number(req.params.version);
+            const version = isVersion(number) ? await (0, documents_1.documentStore)().version(found.projectId, req.params.docId, number) : null;
+            if (!version)
+                return res.status(404).json({ message: 'Version not found' });
+            res.json({ version });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    // The version its exports deliver (null: none, it's no longer published). Editing it later
+    // changes nothing exported until another version is published.
+    router.post('/projects/:projectId/documents/:docId/publish', async (req, res) => {
+        try {
+            const found = await projectFor(req, res, true);
+            if (!found)
+                return;
+            const { project, auth, projectId } = found;
+            const { docId } = req.params;
+            const version = req.body?.version;
+            if (version !== null && !isVersion(version))
+                return res.status(400).json({ message: 'version is the version to publish, or null to publish none' });
+            const store = (0, documents_1.documentStore)();
+            const current = await store.get(projectId, docId);
+            if (!current)
+                return res.status(404).json({ message: 'Document not found' });
+            if (current.kind === 'folder')
+                return res.status(400).json({ message: 'A folder isn\'t published: its documents are' });
+            if (version !== null && version > current.version)
+                return res.status(404).json({ message: 'Version not found' });
+            const document = await store.update(projectId, docId, { publishedVersion: version });
+            broadcast(project, { action: 'changed', documentIds: [docId], author: (0, documents_1.authorOf)(auth) });
+            res.json({ document });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    // A document, or a folder with everything in it.
+    router.delete('/projects/:projectId/documents/:docId', async (req, res) => {
+        try {
+            const found = await projectFor(req, res, true);
+            if (!found)
+                return;
+            const { project, auth, projectId } = found;
+            const store = (0, documents_1.documentStore)();
+            const documents = await store.list(projectId);
+            if (!documents.some(d => d.id === req.params.docId))
+                return res.status(404).json({ message: 'Document not found' });
+            const ids = (0, documents_1.withDescendants)(documents, req.params.docId);
+            await store.remove(projectId, ids);
+            broadcast(project, { action: 'deleted', documentIds: ids, author: (0, documents_1.authorOf)(auth) });
+            res.json({ deleted: ids });
+        }
+        catch (err) {
+            res.status(500).json({ message: err.message });
+        }
+    });
+    return router;
+}

package/dist/middleware/routes/mcp.js

@@ -5,11 +5,13 @@ const express_1 = require("express");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const server_1 = require("../../mcp/server");
 const rateLimit_1 = require("../../mcp/rateLimit");
+const oauthTokens_1 = require("../../services/oauthTokens");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { version } = require('../../../package.json');
 const jsonRpcError = (res, status, message) => res.status(status).json({ jsonrpc: '2.0', error: { code: -32000, message }, id: null });
 // StreamBy's MCP server (Streamable HTTP, stateless: one server per request), for agents
-// working with StreamBy through an API token. Each tool calls the REST API right here -- this
+// working with StreamBy through an API token, or an OAuth access token of an app the user
+// signed in to (e.g. claude.ai's connector). Each tool calls the REST API right here -- this
 // same process, under the same mount -- with the request's own Authorization header, so it
 // reaches what the token and its owner can and nothing more.
 function mcpRouter(config) {
@@ -17,12 +19,17 @@ function mcpRouter(config) {
     const limiter = (0, rateLimit_1.createRateLimiter)(config.mcp?.rateLimit ?? rateLimit_1.DEFAULT_MCP_RATE_LIMIT);
     router.post('/mcp', async (req, res) => {
         const auth = req.auth;
-        if (!auth.apiToken)
-            return jsonRpcError(res, 401, 'The MCP server takes an API token (Authorization: Bearer sbt_...)');
+        // A browser session isn't for agents: they come with a token.
+        if (!auth.apiToken) {
+            if (config.oauth)
+                res.setHeader('WWW-Authenticate', (0, oauthTokens_1.wwwAuthenticate)(config.oauth, false));
+            return jsonRpcError(res, 401, 'The MCP server takes an API token (Authorization: Bearer sbt_...) or an OAuth access token');
+        }
+        // Per token; an app is counted per user it acts for.
         const taken = limiter.take(auth.apiToken.tokenId);
         if (!taken.allowed) {
             res.setHeader('Retry-After', String(Math.ceil(taken.retryAfterMs / 1000)));
-            return jsonRpcError(res, 429, 'Too many requests for this API token; try again later');
+            return jsonRpcError(res, 429, 'Too many requests for this token; try again later');
         }
         const base = config.mcp?.apiBaseUrl ?? `http://127.0.0.1:${req.socket.localPort}${req.baseUrl}`;
         const api = async ({ method, path, body }) => {

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

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

package/dist/middleware/routes/oauthResource.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauthResourceRouter = oauthResourceRouter;
+const express_1 = require("express");
+const oauthTokens_1 = require("../../services/oauthTokens");
+// StreamBy's metadata as an OAuth protected resource (RFC 9728), open to anyone: an MCP client
+// that got a 401 reads it to know which authorization server to sign the user in with. The
+// host serves the same document at its root too, where RFC 9728 puts it.
+function oauthResourceRouter(config) {
+    const router = (0, express_1.Router)();
+    router.get('/.well-known/oauth-protected-resource', (_req, res) => {
+        if (!config.oauth)
+            return res.status(404).json({ error: 'Not an OAuth protected resource' });
+        res.set({ 'Access-Control-Allow-Origin': '*', 'Cache-Control': 'public, max-age=300' });
+        return res.json((0, oauthTokens_1.protectedResourceMetadata)(config.oauth));
+    });
+    return router;
+}

package/dist/middleware/routes/project.js

@@ -13,6 +13,7 @@ const apiTokens_1 = require("../../services/apiTokens");
 const nosqlDb_1 = require("../../utils/nosqlDb");
 const production_1 = require("../../services/production");
 const jobStore_1 = require("../../services/jobStore");
+const documents_1 = require("../../services/documents");
 function projectRouter(config) {
     const router = (0, express_1.Router)();
     const Project = (0, manager_1.getModel)('projects');
@@ -261,6 +262,8 @@ function projectRouter(config) {
             await (0, production_1.deleteProductionData)(String(projectId));
             if (projectId)
                 await (0, jobStore_1.jobStore)().deleteProject(String(projectId));
+            if (projectId)
+                await (0, documents_1.documentStore)().deleteProject(String(projectId));
             const allProjects = await Project.find({});
             const projects = allProjects
                 .filter(project => {

package/dist/services/apiTokenPermissions.d.ts

@@ -1,5 +1,5 @@
 /** Permissions on a project, for the projects a token reaches. */
-export declare const PROJECT_PERMISSIONS: readonly ["project:read", "project:update", "project:delete", "members:read", "members:manage", "assets:read", "assets:write", "assets:delete", "production:read", "production:write", "production:delete", "workflow:read", "workflow:write", "exports:read", "exports:write", "rights:read", "rights:write", "jobs:read", "jobs:run"];
+export declare const PROJECT_PERMISSIONS: readonly ["project:read", "project:update", "project:delete", "members:read", "members:manage", "assets:read", "assets:write", "assets:delete", "production:read", "production:write", "production:delete", "workflow:read", "workflow:write", "exports:read", "exports:write", "rights:read", "rights:write", "jobs:read", "jobs:run", "docs:read", "docs:write", "docs:publish", "docs:delete"];
 /** Permissions on the account: only a user's token has them. */
 export declare const ACCOUNT_PERMISSIONS: readonly ["projects:create"];
 export type ProjectPermission = typeof PROJECT_PERMISSIONS[number];

package/dist/services/apiTokenPermissions.js

@@ -15,6 +15,7 @@ exports.PROJECT_PERMISSIONS = [
     'exports:read', 'exports:write',
     'rights:read', 'rights:write',
     'jobs:read', 'jobs:run',
+    'docs:read', 'docs:write', 'docs:publish', 'docs:delete',
 ];
 /** Permissions on the account: only a user's token has them. */
 exports.ACCOUNT_PERMISSIONS = ['projects:create'];
@@ -94,6 +95,13 @@ const RULES = [
     // Jobs: transcoding, rendering, AI, publishing a deliverable.
     rule('read', `${P}/jobs`, 'jobs:read'),
     rule(['POST'], `${P}/(jobs/[^/]+(/retry)?|pipeline-suggest|deliverables/[^/]+/publish)`, 'jobs:run'),
+    // Documents: writing them is saving a version or moving them; publishing one (choosing what
+    // the exports deliver, or whether they deliver it at all) is apart. A PATCH that changes
+    // `exportable` needs docs:publish too (see routes/document).
+    rule('read', `${P}/documents(/.+)?`, 'docs:read'),
+    rule(['POST'], `${P}/documents/[^/]+/publish`, 'docs:publish'),
+    rule('write', `${P}/documents(/[^/]+(/sections)?)?`, 'docs:write'),
+    rule('delete', `${P}/documents/[^/]+`, 'docs:delete'),
 ];
 /** The rule for a request made with an API token, or undefined: not reachable with one. */
 function routeRuleFor(method, path) {

package/dist/services/auth.d.ts

@@ -6,5 +6,9 @@ export declare const isPublicRoute: (method: string, path: string) => boolean;
 export declare const scopeReachesProject: (scope: Auth["apiToken"], projectId: string) => boolean;
 /** Whether a token has a permission (a request without a token: always). */
 export declare const tokenAllows: (scope: Auth["apiToken"], permission: ApiTokenPermission) => boolean;
+/** Whether an app (an OAuth request) may make this request's method on its path. */
+export declare const oauthMayDelete: (method: string, path: string) => boolean;
+/** Whether a request publishes a document (its version, or whether it's exported). */
+export declare const publishesDocument: (method: string, path: string, body: unknown) => boolean;
 export declare const enforceApiTokenScope: (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
 export declare const authenticate: (config: StreamByConfig) => (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;

package/dist/services/auth.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authenticate = exports.enforceApiTokenScope = exports.tokenAllows = exports.scopeReachesProject = exports.isPublicRoute = void 0;
+exports.authenticate = exports.enforceApiTokenScope = exports.publishesDocument = exports.oauthMayDelete = exports.tokenAllows = exports.scopeReachesProject = exports.isPublicRoute = void 0;
 const auth_1 = require("../utils/auth");
 const apiTokenPermissions_1 = require("./apiTokenPermissions");
+const oauthTokens_1 = require("./oauthTokens");
 // The one route open without a session: a project's public export, read
 // (GET /:projectId/export/:exportName, see routes/export). Exactly that path -- not any path
 // that has an "export" segment somewhere.
@@ -33,13 +34,45 @@ exports.scopeReachesProject = scopeReachesProject;
 /** Whether a token has a permission (a request without a token: always). */
 const tokenAllows = (scope, permission) => !scope || scope.permissions.includes(permission);
 exports.tokenAllows = tokenAllows;
+// ── OAuth apps ──
+// An app the user signed in to was approved to make and change things, never to delete them:
+// its permissions come from its scopes, and some of those (project:update, workflow:write,
+// exports:write) also reach routes that delete (a connection, a worker, an integration, a
+// pipeline, an export). So an app's DELETE is refused, whatever its route's permission.
+// The one DELETE it may make is taking a deliverable's mark off: that forgets the mark only
+// (the asset, its versions and its files stay, and it can be marked again), and it's the
+// counterpart of marking one, which assets:write already allows.
+const OAUTH_DELETE_ALLOWED = new RegExp(`^/projects/[^/]+/deliverables/[^/]+/?$`);
+/** Whether an app (an OAuth request) may make this request's method on its path. */
+const oauthMayDelete = (method, path) => method.toUpperCase() !== 'DELETE' || OAUTH_DELETE_ALLOWED.test(path);
+exports.oauthMayDelete = oauthMayDelete;
+// Nor does an app publish: what it edits stays a draft until someone publishes it. Publishing
+// is choosing a document's version for its exports (POST .../publish) or whether they deliver
+// it (`exportable`). Refused whatever its scopes grant, as deleting is.
+const DOCUMENT_PUBLISH = /^\/projects\/[^/]+\/documents\/[^/]+\/publish\/?$/;
+const DOCUMENT = /^\/projects\/[^/]+\/documents\/[^/]+\/?$/;
+/** Whether a request publishes a document (its version, or whether it's exported). */
+const publishesDocument = (method, path, body) => {
+    const upper = method.toUpperCase();
+    if (upper === 'POST' && DOCUMENT_PUBLISH.test(path))
+        return true;
+    return upper === 'PATCH' && DOCUMENT.test(path) && typeof body === 'object' && body !== null && 'exportable' in body;
+};
+exports.publishesDocument = publishesDocument;
 const enforceApiTokenScope = (req, res, next) => {
-    const scope = req.auth?.apiToken;
+    const auth = req.auth;
+    const scope = auth?.apiToken;
     if (!scope)
         return next();
     // The MCP server handles a token itself: its tools call the routes here, each one checked.
     if (req.path === '/mcp')
         return next();
+    if (auth?.oauth && !(0, exports.oauthMayDelete)(req.method, req.path)) {
+        return res.status(403).json({ error: 'An app connected with OAuth can\'t delete' });
+    }
+    if (auth?.oauth && (0, exports.publishesDocument)(req.method, req.path, req.body)) {
+        return res.status(403).json({ error: 'An app connected with OAuth can\'t publish: what it edits stays a draft' });
+    }
     const rule = (0, apiTokenPermissions_1.routeRuleFor)(req.method, req.path);
     if (!rule || (rule.userTokenOnly && scope.kind !== 'user')) {
         return res.status(403).json({ error: 'Not available with an API token' });
@@ -53,25 +86,34 @@ const enforceApiTokenScope = (req, res, next) => {
     next();
 };
 exports.enforceApiTokenScope = enforceApiTokenScope;
+const hasBearer = (req) => /^Bearer\s+\S/i.test(req.headers.authorization ?? '');
 const authenticate = (config) => async (req, res, next) => {
     if ((0, exports.isPublicRoute)(req.method, req.path)) {
         return next();
     }
+    // A client without a valid token is told where to sign in (RFC 9728), when StreamBy is set
+    // up as an OAuth resource.
+    const unauthorized = () => {
+        if (config.oauth)
+            res.setHeader('WWW-Authenticate', (0, oauthTokens_1.wwwAuthenticate)(config.oauth, hasBearer(req)));
+        return res.status(401).json({ error: 'Unauthorized' });
+    };
     try {
         const auth = await config.authProvider(req);
-        if (!auth || !auth.userId || !auth.role) {
-            return res.status(401).json({ error: 'Unauthorized' });
-        }
+        if (!auth || !auth.userId || !auth.role)
+            return unauthorized();
         // A project token's principal is only ever a project's token (see utils/auth).
-        if ((0, auth_1.isProjectTokenPrincipal)(auth.userId) && auth.apiToken?.kind !== 'project') {
-            return res.status(401).json({ error: 'Unauthorized' });
-        }
+        if ((0, auth_1.isProjectTokenPrincipal)(auth.userId) && auth.apiToken?.kind !== 'project')
+            return unauthorized();
+        // An app acting for the user reaches only what its scopes grant: never without them.
+        if (auth.oauth && auth.apiToken?.kind !== 'user')
+            return unauthorized();
         req.auth = auth;
         next();
     }
     catch (error) {
-        console.error('Authentication failed:', error);
-        return res.status(401).json({ error: 'Unauthorized' });
+        console.error('Authentication failed:', error instanceof Error ? error.message : error);
+        return unauthorized();
     }
 };
 exports.authenticate = authenticate;

package/dist/services/documents.d.ts

@@ -0,0 +1,66 @@
+import { Auth, DocumentAuthor, DocumentVersion, ProjectDocument, StreamByConfig } from '../types';
+/** A document as the tree lists it: all but its content. */
+export type DocumentSummary = Omit<ProjectDocument, 'content'>;
+/** A version as the history lists it: all but its content. */
+export type VersionSummary = Omit<DocumentVersion, 'content'>;
+type Structure = Partial<Pick<ProjectDocument, 'parentId' | 'position' | 'exportable' | 'publishedVersion'>>;
+export interface DocumentStore {
+    list(projectId: string): Promise<DocumentSummary[]>;
+    get(projectId: string, id: string): Promise<ProjectDocument | null>;
+    /** A new document, and its first version. */
+    create(document: ProjectDocument): Promise<ProjectDocument>;
+    /**
+     * A new version, only if the document is still at `baseVersion`: null if it isn't (someone
+     * saved in between) or there's no such document.
+     */
+    save(projectId: string, id: string, baseVersion: number, change: {
+        title: string;
+        content: string;
+    }, author: DocumentAuthor, at: Date): Promise<ProjectDocument | null>;
+    /** Where it is in the tree, and what's published of it: not a version. */
+    update(projectId: string, id: string, patch: Structure): Promise<ProjectDocument | null>;
+    /** Its versions, the latest first. */
+    versions(projectId: string, id: string): Promise<VersionSummary[]>;
+    version(projectId: string, id: string, version: number): Promise<DocumentVersion | null>;
+    /** Documents and their versions. */
+    remove(projectId: string, ids: string[]): Promise<void>;
+    /** A deleted project's documents. */
+    deleteProject(projectId: string): Promise<void>;
+}
+/** The router's main database, where documents are kept. */
+export declare const setDocumentStoreDatabase: (config: StreamByConfig) => void;
+export declare function documentStore(): DocumentStore;
+/** Who's saving: the user, through the UI, an API token, or an app acting for them. */
+export declare function authorOf(auth: Auth): DocumentAuthor;
+/** A document and everything inside it (a folder's documents, at any depth). */
+export declare function withDescendants(documents: DocumentSummary[], id: string): string[];
+export type SectionResult = {
+    content: string;
+} | {
+    error: 'not-found' | 'ambiguous';
+};
+/**
+ * The markdown with what's under `heading` replaced by `body`, the rest untouched. `heading` is
+ * its title, with or without its #s ("## Architecture", "Architecture"): with them, only a
+ * heading of that level matches.
+ */
+export declare function replaceSection(markdown: string, heading: string, body: string): SectionResult;
+/** A document as an export delivers it: its published version, never a draft. */
+export interface PublishedDocument {
+    id: string;
+    title: string;
+    parentId: string | null;
+    position: number;
+    version: number;
+    content: string;
+    publishedAt: Date;
+}
+/**
+ * The project's exportable documents that have a published version (in one folder, at any
+ * depth, or only those given), as that version was saved.
+ */
+export declare function publishedDocuments(projectId: string, scope?: {
+    folderId?: string;
+    documentIds?: string[];
+}): Promise<PublishedDocument[]>;
+export {};