streamby-core 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 0.38.0
+
+### Added
+
+- **Uploading and downloading files from the MCP server**, so an agent can bring files from and
+  to the tools it works with (Blender's or Godot's own MCP, a script). The file never goes
+  through the conversation: the tools give signed URLs, and the tool that has the file uploads
+  or downloads it directly. See the README for an example with Blender.
+  - `request_asset_upload` (`assets:write`): a new asset, or a new version of one, and the URL
+    to upload its file to.
+  - `get_asset_download_url` (`assets:read`): a URL to download an asset's file, its latest
+    version or an earlier one. `list_asset_versions` lists them.
+- **Asset versions are kept, and an asset's URL doesn't change when it's replaced.** A new
+  version (`replace-url`, from the UI too) is still uploaded to the asset's own key, so a site
+  that links to the asset shows the new one. Before that, the current version is copied to a
+  key of its own, `<key>.v<n>.<ext>`, and recorded in `asset_versions` (an asset's first
+  version is recorded on upload; an older asset gets it when it's first replaced). If it can't
+  be copied, nothing is replaced and no upload URL is given. The `replace-url` routes answer
+  the new version's `versionId` and `version`. Deleting an asset deletes every key of it.
+  - New `StorageAdapter.copyFile`, implemented by the S3 adapter. With an adapter without it,
+    asking for a new version answers 501.
+  - StreamBy doesn't set `Cache-Control` on uploads, so a browser or a CDN may serve a replaced
+    asset's earlier version for a while: set it where the files are served (see the README).
+- `GET /projects/:projectId/assets/:fileId/download-url` (`?versionId=` for an earlier version):
+  a signed URL that downloads the file with its name, wherever it's stored.
+- **Deliverables**: an asset, or one of its versions, delivered for a production shot or for an
+  export, kept in the NoSQL database's `deliverables` collection. `GET`, `POST` and
+  `DELETE /projects/:projectId/deliverables` list (by `shotId` or `exportId`), mark and remove
+  them; `list_deliverables`, `mark_deliverable` and `remove_deliverable` in the MCP server.
+  Deleting a shot, a sequence, an export or an asset removes its deliverables.
+- **`mcp.signedUrlTtl`**: how long the signed URLs given to an API token work, also when it
+  lists files. Default: 15 minutes to upload, 5 to download. A session's are as before.
+- `StorageAdapter.getPresignedUploadUrl` and `getPresignedGetUrl` take how long the URL works
+  (and `getPresignedGetUrl` the name to download it with).
+
+- `GET /projects/:id` answers `hasProductionData`: whether the project has production
+  sequences, so a client can show them even without a production node in its workflow.
+
+### Changed
+
+- **Production data is checked before it's saved.** Sequences, shots and tasks need a name
+  that isn't blank; a status must be `todo`, `in_progress`, `review` or `done`, and a task's
+  priority `low`, `medium` or `high`; a shot's `assignedTo` must list active members of the
+  project, and a task's be one of them (or null); a due date must be a date. Otherwise they
+  answer 400. A shot is made only in a sequence of the project, and a task only in a shot of
+  it (404 otherwise).
+- The MCP tools for shots take `assignedTo` as a list of user ids, as the API does, and their
+  statuses and priorities are listed in their schema.
+- **The MCP tools take the path a user does.** `create_sequence`, `create_shot` and
+  `create_task` first add a production node (a Shot node) to the project's workflow when it
+  has none, as dropping one on the canvas does, and make nothing if it can't be added. So they
+  need `workflow:write` as well as `production:write`. Each tool's description says where its
+  result shows in the UI.
+
+### Fixed
+
+- **Deleting production data leaves nothing behind.** Deleting a sequence deletes its shots'
+  tasks too (they were left), and deleting a project deletes its sequences, shots, tasks and
+  deliverables. Deleting a sequence that doesn't exist answers 404.
+- **Only editors and admins upload a new version of an asset.** The `replace-url` routes let
+  any member of the project, a viewer included, replace an asset's file.
+- The ingest job no longer records a second version of the file an upload already recorded.
+
+## 0.37.0
+
+### ⚠️ Breaking changes
+
+- **API tokens have permissions, not an access level.** The tokens made before this version no
+  longer work, and aren't listed: make new ones. There's no migration. The `api_tokens` table
+  gets its new columns at startup (`kind`, `permissions`, `createdByName`), and its old
+  `access` column becomes optional; nothing else is changed.
+- **`ApiTokenScope` changed.** It has `kind` (`'user'` or `'project'`) and `permissions`,
+  instead of `access`. `ApiTokenAccess` is gone.
+- **`createApiToken`** takes who makes the token (`{ kind, userId, username, projectId }`), and
+  `permissions` instead of `access`. `listApiTokens` and `revokeApiToken` are now
+  `listUserApiTokens` and `revokeUserApiToken`.
+- **The host's `authProvider` must handle a project's token** (see the README): it isn't a
+  user, so it must not be looked up as one. `resolveApiToken` returns its `name` to go by.
+
+### Added
+
+- **Permissions** for tokens, by resource and action: `project`, `members`, `assets`,
+  `production`, `workflow`, `exports`, `rights` and `jobs`, each with `read` and its writes
+  (`update`, `write`, `manage`, `delete` or `run`), and `projects:create` for the account.
+  Every route a token reaches needs its own permission; a route no permission covers isn't
+  reachable with a token. A user's token is still limited by its user's role in each project.
+  `PROJECT_PERMISSIONS` and `ACCOUNT_PERMISSIONS` are exported.
+- **Projects' tokens**, at `GET`, `POST` and `DELETE /projects/:id/api-tokens`, managed by the
+  project's admins only. They act on their project alone, with their permissions, and keep
+  working after whoever made them leaves it; the project's admins are notified when that
+  happens (`api_token_creator_left`). Deleting a project ends its tokens.
+- **`projects:create`**: a user's token with it creates projects, and reaches the ones it
+  creates.
+- **MCP tools** `create_project`, `delete_project`, `delete_asset`, `delete_sequence`,
+  `delete_shot` and `delete_task`. Each tool needs its permissions and is listed only for a
+  token that has them; the ones that delete are marked as destructive.
+
 ## 0.36.0
 
 ### Added

package/README.md

@@ -102,20 +102,49 @@ createStreamByRouter({
 
 ## 🎫 API tokens
 
-Agents and services work with StreamBy as a user through API tokens, without the user's
-browser session. A user manages their own tokens (`GET`, `POST` and
-`DELETE /streamby/user/api-tokens`, only with a session). Each token has:
-
-- **an access level**: `read` (only reads) or `write` (reads and writes);
-- **the projects it reaches**: a list of project ids, or `'*'` for every project the user is a
-  member of, including ones they join later;
-- **an expiry**: 7, 30, 90 or 365 days, or none.
-
-A token is `sbt_` followed by 32 random bytes. It's shown once, when it's made. Only its
-SHA-256 hash is stored, with a short prefix to tell it apart.
+Agents and services work with StreamBy through API tokens, without a browser session. There
+are two kinds:
+
+- **A user's token** acts as its user. The user manages their own (`GET`, `POST` and
+  `DELETE /streamby/user/api-tokens`). It reaches a list of the user's projects, or `'*'` for
+  every project they're a member of, including ones they join later. It never does more than
+  its user can: their role in each project still applies.
+- **A project's token** acts on its project alone, as the project's, not as whoever made it:
+  it keeps working after they leave the project, for permanent integrations (CI, services, the
+  project's agents). Only the project's admins list, make and revoke them (`GET`, `POST` and
+  `DELETE /streamby/projects/:id/api-tokens`), and each one records who made it. When they
+  leave, the project's admins are notified that it still works. Deleting the project ends
+  its tokens.
+
+Tokens are managed only with a session: a token can't manage tokens.
+
+Each token has a name, **its permissions**, and **an expiry** (7, 30, 90 or 365 days, or
+none). It's `sbt_` followed by 32 random bytes, shown once, when it's made. Only its SHA-256
+hash is stored, with a short prefix to tell it apart.
+
+**Permissions**
+
+| Resource | Permissions | Covers |
+|---|---|---|
+| Project | `project:read`, `project:update`, `project:delete` | The project, its settings and its connections (API, database, storage, distribution, render farm), integrations and allowed origins. |
+| Members | `members:read`, `members:manage` | Listing members; inviting, changing and removing them, and searching users. |
+| Assets | `assets:read`, `assets:write`, `assets:delete` | Files and folders, upload URLs, metadata, versions, reviews and annotations, QC reports. |
+| Production | `production:read`, `production:write`, `production:delete` | Sequences, shots and tasks. |
+| Workflow | `workflow:read`, `workflow:write` | The workflow and its pipelines. |
+| 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). |
+| 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
+(the user's notifications, integrations and tokens, Explore, accepting an invitation) isn't
+reachable with a token.
+
+**Resolving a token**
 
 Requests send it as `Authorization: Bearer sbt_...`. Your `authProvider` resolves it with
-`resolveApiToken` and returns its owner, with the token's scope in `apiToken`:
+`resolveApiToken`, and returns its `userId` with the token's scope in `apiToken`. A project's
+token isn't a user: its `userId` is the token's own (on its project), and it goes by its name.
 
 ```ts
 import { createStreamByRouter, resolveApiToken, API_TOKEN_PREFIX } from 'streamby-core';
@@ -127,6 +156,9 @@ createStreamByRouter({
     if (bearer?.startsWith(API_TOKEN_PREFIX)) {
       const resolved = await resolveApiToken(bearer); // null once revoked or expired
       if (!resolved) throw new Error('Invalid API token');
+      if (resolved.scope.kind === 'project') {
+        return { userId: resolved.userId, username: resolved.name, role: 'viewer', apiToken: resolved.scope };
+      }
       const user = await findUser(resolved.userId);   // your own user lookup
       return { userId: user.id, username: user.username, role: user.role, apiToken: resolved.scope };
     }
@@ -135,17 +167,9 @@ createStreamByRouter({
 });
 ```
 
-A request made with a token reaches only what the token's scope allows:
-
-- a `read` token can't write;
-- a project outside the token's projects answers 404, and the project list shows only the
-  token's projects;
-- a token can't manage tokens;
-- outside a project, a token can only make a few reads (`/auth`, `/projects`, `/jobs/:jobId`,
-  `/user/subscription`, `/users/search`).
-
-The owner's role in each project still applies on top of that. A token never does more than
-its owner can, and it stops reaching a project as soon as its owner leaves it.
+A request made with a token goes through only when its route's permission is among the
+token's (otherwise 403), and a project outside the token's projects answers 404; the project
+list shows only the token's projects.
 
 ---
 
@@ -156,24 +180,94 @@ StreamBy serves an [MCP](https://modelcontextprotocol.io) server at `POST /strea
 projects with an API token (see above). It takes only an API token; 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's scope and its owner's role in each project allow, and a write is saved just like one
-made from the UI, which shows it when it loads the project.
+token allows (and, for a user's token, what its 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**
 
-- **Reading**, with any token:
-  - `list_projects`, `get_project`;
-  - `list_assets` (by category, optionally in one storage connection, and filtered by name),
-    `get_asset_metadata`, `get_asset_rights`;
-  - `get_workflow`, `list_pipelines`, `get_pipeline`, `list_exports`, `get_export`;
-  - `get_job`;
-  - `list_sequences`, `list_shots`, `list_tasks`.
-- **Writing**, listed only for a `write` token, and allowed only where its owner is an editor or
-  an admin:
-  - `update_asset_metadata`, `set_asset_rights`;
-  - `create_pipeline`, `update_pipeline`;
-  - `create_sequence`, `update_sequence`, `create_shot`, `update_shot`, `create_task`,
-    `update_task`.
+A token sees only the tools whose permissions it has.
+
+| Tools | Permissions |
+|---|---|
+| `list_projects` | any token |
+| `get_project` | `project:read` |
+| `create_project` | `projects:create` |
+| `delete_project` | `project:delete` |
+| `list_assets` (by category, optionally in one storage connection, and filtered by name), `get_asset_metadata` | `assets:read` |
+| `update_asset_metadata` | `assets:write` |
+| `delete_asset` | `assets:delete` |
+| `get_asset_rights` / `set_asset_rights` | `rights:read` / `rights:write` |
+| `get_workflow`, `list_pipelines`, `get_pipeline` | `workflow:read` |
+| `create_pipeline`, `update_pipeline` | `workflow:write` |
+| `list_exports` | `project:read` and `exports:read` |
+| `get_export` | `exports:read` |
+| `get_job` | `jobs:read` |
+| `list_sequences`, `list_shots`, `list_tasks` | `production:read` |
+| `update_sequence`, `update_shot`, `update_task` | `production:write` |
+| `create_sequence`, `create_shot`, `create_task` | `production:write` and `workflow:write` |
+| `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` |
+
+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:
+if the workflow has none yet, `create_sequence`, `create_shot` and `create_task` first add a
+Shot node to it, as dropping one on the canvas does (so they need `workflow:write`), and make
+nothing if it can't be added.
+
+The tools that delete are marked as destructive (`destructiveHint`), so a client can ask before
+running them.
+
+**Files**
+
+A file never goes through the conversation. `request_asset_upload` makes a new asset (or a new
+version of one) and gives a signed URL to `PUT` its bytes to; `get_asset_download_url` gives a
+signed URL to `GET` an asset's file, its latest version or any earlier one. The tool that has
+the file uploads or downloads it directly, for example Blender's or Godot's own MCP server,
+which can run code. Each URL is for that one file, and given to an API token it works only
+briefly: 15 minutes to upload, 5 to download (`mcp.signedUrlTtl`).
+
+**Versions.** Replacing an asset doesn't change its URL: the new version is uploaded to the
+asset's own key, so a site that links to the asset shows the new one with no deploy. Before
+that, the current version is copied to a key of its own (`<key>.v<n>.<ext>`) and recorded, so
+every earlier version can still be downloaded by its id; if it can't be copied, nothing is
+replaced. A storage adapter keeps versions only if it can copy (`copyFile`; the S3 one does);
+otherwise asking for a new version answers 501. Deleting the asset deletes every key of it.
+
+Since the URL stays the same, a browser or a CDN may keep serving the earlier version for a
+while. StreamBy doesn't set `Cache-Control` on uploads (a signed URL that did would require
+every client to send the same header): set it where the files are served, for example a short
+`max-age` or `no-cache` on the CDN in front of the bucket, or invalidate the path when an asset
+is replaced.
+
+A **deliverable** is an asset, or one of its versions, delivered for a
+production shot or for an export; a shot or an export can have several, and the shot's panel
+in the UI shows them.
+
+For example, with Claude connected to StreamBy and to Blender's MCP server, asking *"export the
+scene as glTF and deliver it for shot SH010 of Portfolio"* goes:
+
+1. `list_projects`, `list_sequences`, `list_shots`: the project and the shot's id.
+2. `request_asset_upload` with `category: '3d-models'`, `fileName: 'SH010_layout.glb'` and
+   `contentType: 'model/gltf-binary'`: the new asset's id, and where to upload it.
+3. In Blender, code that exports the scene and uploads it:
+
+   ```python
+   import bpy, urllib.request
+   path = bpy.app.tempdir + "SH010_layout.glb"
+   bpy.ops.export_scene.gltf(filepath=path, export_format="GLB")
+   with open(path, "rb") as f:
+       req = urllib.request.Request(UPLOAD_URL, data=f.read(), method="PUT",
+                                    headers={"Content-Type": "model/gltf-binary"})
+   urllib.request.urlopen(req)
+   ```
+
+4. `mark_deliverable` with the asset's id and `shotId`: it shows in the shot's panel.
+
+Bringing an asset into Blender or Godot is the other way around: `get_asset_download_url`, and
+code there that downloads the URL and imports the file (in Blender,
+`bpy.ops.import_scene.gltf(filepath=...)`). A new version of the same asset is
+`request_asset_upload` with its `assetId`.
 
 **Limits and audit**
 
@@ -181,14 +275,16 @@ made from the UI, which shows it when it loads the project.
   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, 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, 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({
   // ...
   mcp: {
     rateLimit: { requests: 120, windowMs: 60_000 }, // the default
+    signedUrlTtl: { upload: 900, download: 300 },   // the default, in seconds
     // apiBaseUrl: 'http://127.0.0.1:3000/streamby', // where tools reach the REST API;
     //   by default this same process, at the request's local port and mount path
   },
@@ -197,8 +293,9 @@ createStreamByRouter({
 
 ### Connecting from Claude Code
 
-Make an API token in StreamBy (Settings → Security → Personal API tokens), and keep it in an
-environment variable, never in a file:
+Make an API token in StreamBy, with only the permissions the agent needs: your own
+(Settings → Security → Personal API tokens), or a project's (in the project, Settings → API
+Tokens). Keep it in an environment variable, never in a file:
 
 ```bash
 export STREAMBY_TOKEN=sbt_...
@@ -223,8 +320,8 @@ environment:
 
 Claude Desktop runs local (stdio) servers from `claude_desktop_config.json`. Reach StreamBy
 through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), passing the token in its
-`env`. This file holds it in plain text, so use a token with only the scope you need, and
-an expiry:
+`env`. This file holds it in plain text, so use a token with only the permissions you need,
+and an expiry:
 
 ```json
 {

package/dist/adapters/database/connectionManager.js

@@ -149,21 +149,34 @@ const ensureTablesExist = async (pool) => {
     `);
         console.log('✅ "user_integrations" table ensured to exist.');
         // API tokens: only their hash is kept (see services/apiTokens). Main db only, like
-        // user_integrations above.
+        // user_integrations above. A table from before tokens had a kind and permissions gets the
+        // new columns; its old tokens no longer work (they have no kind) and aren't listed.
         await pool.query(`
       CREATE TABLE IF NOT EXISTS streamby.api_tokens (
-        id            TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        "userId"      VARCHAR(255) NOT NULL,
-        name          VARCHAR(255) NOT NULL,
-        prefix        VARCHAR(32) NOT NULL,
-        hash          CHAR(64) NOT NULL UNIQUE,
-        access        VARCHAR(10) NOT NULL,
-        "projectIds"  JSONB NOT NULL,
-        "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "expiresAt"   TIMESTAMP WITH TIME ZONE,
-        "lastUsedAt"  TIMESTAMP WITH TIME ZONE
+        id                TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        kind              VARCHAR(10),
+        "userId"          VARCHAR(255) NOT NULL,
+        "createdByName"   VARCHAR(255),
+        name              VARCHAR(255) NOT NULL,
+        prefix            VARCHAR(32) NOT NULL,
+        hash              CHAR(64) NOT NULL UNIQUE,
+        permissions       JSONB NOT NULL DEFAULT '[]',
+        "projectIds"      JSONB NOT NULL,
+        "createdAt"       TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "expiresAt"       TIMESTAMP WITH TIME ZONE,
+        "lastUsedAt"      TIMESTAMP WITH TIME ZONE
       );
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS kind VARCHAR(10);
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS "createdByName" VARCHAR(255);
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS permissions JSONB NOT NULL DEFAULT '[]';
+      DO $$ BEGIN
+        IF EXISTS (SELECT 1 FROM information_schema.columns
+                   WHERE table_schema = 'streamby' AND table_name = 'api_tokens' AND column_name = 'access') THEN
+          ALTER TABLE streamby.api_tokens ALTER COLUMN access DROP NOT NULL;
+        END IF;
+      END $$;
       CREATE INDEX IF NOT EXISTS api_tokens_userid_idx ON streamby.api_tokens ("userId");
+      CREATE INDEX IF NOT EXISTS api_tokens_kind_idx ON streamby.api_tokens (kind);
     `);
         console.log('✅ "api_tokens" table ensured to exist.');
         // The MCP server's audit log: every tool call (see mcp/audit). Main db only.

package/dist/adapters/storage/s3.d.ts

@@ -8,8 +8,9 @@ export declare class S3Adapter implements StorageAdapter {
     deleteProjectDirectory(projectId: string): Promise<any>;
     getPresignedUrl(contentType: string, projectId: string): Promise<any>;
     getPresignedProjectImageUrl(projectId: string): Promise<any>;
-    getPresignedGetUrl(key: string): Promise<string>;
-    getPresignedUploadUrl(key: string, contentType: string): Promise<string>;
+    getPresignedGetUrl(key: string, expiresIn?: number, downloadName?: string): Promise<string>;
+    getPresignedUploadUrl(key: string, contentType: string, expiresIn?: number): Promise<string>;
+    copyFile(from: string, to: string): Promise<void>;
     deleteFile(key: string): Promise<void>;
     listFilesByCategory(projectId: string, category: string): Promise<StorageFileInfo[]>;
     private inferMimeType;

package/dist/adapters/storage/s3.js

@@ -64,13 +64,21 @@ class S3Adapter {
         const publicUrl = `https://${this.bucket}.s3.amazonaws.com/${key}`;
         return { url, publicUrl };
     }
-    async getPresignedGetUrl(key) {
-        const command = new client_s3_1.GetObjectCommand({ Bucket: this.bucket, Key: key });
-        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn: 86400 });
+    async getPresignedGetUrl(key, expiresIn = 86400, downloadName) {
+        const command = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            ...(downloadName ? { ResponseContentDisposition: contentDisposition(downloadName) } : {}),
+        });
+        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn });
     }
-    async getPresignedUploadUrl(key, contentType) {
+    async getPresignedUploadUrl(key, contentType, expiresIn = 3600) {
         const command = new client_s3_1.PutObjectCommand({ Bucket: this.bucket, Key: key, ContentType: contentType });
-        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn: 3600 });
+        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn });
+    }
+    async copyFile(from, to) {
+        const source = `${this.bucket}/${from.split('/').map(encodeURIComponent).join('/')}`;
+        await this.s3.send(new client_s3_1.CopyObjectCommand({ Bucket: this.bucket, CopySource: source, Key: to }));
     }
     async deleteFile(key) {
         const command = new client_s3_1.DeleteObjectCommand({ Bucket: this.bucket, Key: key });
@@ -114,3 +122,8 @@ class S3Adapter {
     }
 }
 exports.S3Adapter = S3Adapter;
+// An attachment with its name: ASCII in `filename`, the full name in `filename*` (RFC 6266).
+const contentDisposition = (name) => {
+    const ascii = name.replace(/[^\x20-\x7e]|["\\]/g, '_');
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { createStreamByRouter } from './middleware/createRouter';
 export { emitToUser } from './services/wsHub';
 export { createNotification } from './services/notification';
-export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenAccess } from './types';
+export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenKind, ApiTokenPermission, ProjectPermission, AccountPermission } from './types';
 export { resolveApiToken, API_TOKEN_PREFIX } from './services/apiTokens';
+export { PROJECT_PERMISSIONS, ACCOUNT_PERMISSIONS } from './services/apiTokenPermissions';
 export type { ResolvedApiToken } from './services/apiTokens';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
+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");
@@ -10,3 +10,6 @@ Object.defineProperty(exports, "createNotification", { enumerable: true, get: fu
 var apiTokens_1 = require("./services/apiTokens");
 Object.defineProperty(exports, "resolveApiToken", { enumerable: true, get: function () { return apiTokens_1.resolveApiToken; } });
 Object.defineProperty(exports, "API_TOKEN_PREFIX", { enumerable: true, get: function () { return apiTokens_1.API_TOKEN_PREFIX; } });
+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; } });

package/dist/mcp/server.d.ts

@@ -6,9 +6,10 @@ export type ApiCaller = (call: ToolCall) => Promise<{
     status: number;
     body: unknown;
 }>;
+/** The tools an API token may use: those whose every permission it has. */
+export declare const toolsFor: (scope: Auth["apiToken"]) => import("./tools").ToolDefinition<any>[];
 /**
- * An MCP server for one request of `auth` (an API token's owner): its tools, the writing ones
- * only for a token with write access. Each tool call goes to the REST API through `api`, and is
- * recorded in the audit log.
+ * An MCP server for one request made with an API token (`auth`): only the tools its permissions
+ * allow. Each tool call goes to the REST API through `api`, and is recorded in the audit log.
  */
 export declare function createMcpServer(auth: Auth, api: ApiCaller, config: StreamByConfig, version: string): McpServer;

package/dist/mcp/server.js

@@ -1,36 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCP_SERVER_NAME = void 0;
+exports.toolsFor = exports.MCP_SERVER_NAME = void 0;
 exports.createMcpServer = createMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const tools_1 = require("./tools");
 const audit_1 = require("./audit");
+const workflowNodes_1 = require("./workflowNodes");
 exports.MCP_SERVER_NAME = 'streamby';
 const errorText = (body, status) => {
     const message = body?.message ?? body?.error;
     return typeof message === 'string' ? message : `StreamBy answered ${status}`;
 };
+/** The tools an API token may use: those whose every permission it has. */
+const toolsFor = (scope) => tools_1.TOOLS.filter(tool => tool.permissions.every(p => !!scope?.permissions.includes(p)));
+exports.toolsFor = toolsFor;
 /**
- * An MCP server for one request of `auth` (an API token's owner): its tools, the writing ones
- * only for a token with write access. Each tool call goes to the REST API through `api`, and is
- * recorded in the audit log.
+ * An MCP server for one request made with an API token (`auth`): only the tools its permissions
+ * allow. Each tool call goes to the REST API through `api`, and is recorded in the audit log.
  */
 function createMcpServer(auth, api, config, version) {
     const server = new mcp_js_1.McpServer({ name: exports.MCP_SERVER_NAME, version });
-    const canWrite = auth.apiToken?.access === 'write';
-    for (const tool of tools_1.TOOLS) {
-        if (tool.write && !canWrite)
-            continue;
+    // A project's token acts on its project: what it does there is the project's.
+    const tokenProject = auth.apiToken?.kind === 'project' && Array.isArray(auth.apiToken.projectIds)
+        ? auth.apiToken.projectIds[0] ?? null
+        : null;
+    for (const tool of (0, exports.toolsFor)(auth.apiToken)) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.input,
-            annotations: { readOnlyHint: !tool.write, destructiveHint: false, openWorldHint: false },
+            annotations: { readOnlyHint: !tool.write, destructiveHint: !!tool.destructive, openWorldHint: false },
         }, async (args) => {
             const started = Date.now();
-            const projectId = tool.projectOf?.(args) ?? null;
+            const projectId = tool.projectOf?.(args) ?? tokenProject;
             let status = null;
             try {
+                // What the workflow needs first, as a user would add it.
+                if (tool.workflowNode) {
+                    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,
+                            ok: false, status: null, error: refused, durationMs: Date.now() - started,
+                        }, config);
+                        return { isError: true, content: [{ type: 'text', text: refused }] };
+                    }
+                }
                 const answer = await api(tool.call(args));
                 status = answer.status;
                 const ok = status >= 200 && status < 300;

package/dist/mcp/tools.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
+import { ApiTokenPermission } from '../services/apiTokenPermissions';
+import type { WorkflowNodeRequirement } from './workflowNodes';
 export interface ToolCall {
-    method: 'GET' | 'POST' | 'PATCH' | 'PUT';
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
     path: string;
     body?: unknown;
 }
@@ -8,7 +10,10 @@ export interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
     name: string;
     title: string;
     description: string;
-    write: boolean;
+    permissions: ApiTokenPermission[];
+    write?: boolean;
+    destructive?: boolean;
+    workflowNode?: WorkflowNodeRequirement;
     input: S;
     projectOf?: (args: z.infer<z.ZodObject<S>>) => string | undefined;
     call: (args: z.infer<z.ZodObject<S>>) => ToolCall;