streamby-core 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 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,34 @@ 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` |
+| `create_sequence`, `update_sequence`, `create_shot`, `update_shot`, `create_task`, `update_task` | `production:write` |
+| `delete_sequence`, `delete_shot`, `delete_task` | `production:delete` |
+
+The tools that delete are marked as destructive (`destructiveHint`), so a client can ask before
+running them.
 
 **Limits and audit**
 
@@ -181,8 +215,9 @@ 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({
@@ -197,8 +232,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 +259,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/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,6 +1,6 @@
 "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");
@@ -10,25 +10,28 @@ 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 {
                 const answer = await api(tool.call(args));

package/dist/mcp/tools.d.ts

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

package/dist/mcp/tools.js

@@ -38,21 +38,21 @@ const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([,
 exports.TOOLS = [
     // ── Reading ──
     tool({
-        name: 'list_projects', title: 'List projects', write: false,
+        name: 'list_projects', title: 'List projects', permissions: [],
         description: 'The StreamBy projects this token reaches.',
         input: {},
         call: () => ({ method: 'GET', path: '/projects' }),
         pick: (data) => data.projects,
     }),
     tool({
-        name: 'get_project', title: 'Get a project', write: false,
+        name: 'get_project', title: 'Get a project', permissions: ['project:read'],
         description: "A project's details: its name, description, members, exports and connections.",
         input: { projectId },
         projectOf: byProject,
         call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}` }),
     }),
     tool({
-        name: 'list_assets', title: 'List assets', write: false,
+        name: 'list_assets', title: 'List assets', permissions: ['assets:read'],
         description: "A project's assets of a category (images, audios, videos, 3d-models), optionally in one storage connection, and optionally only those whose name contains `query`.",
         input: {
             projectId,
@@ -77,42 +77,42 @@ exports.TOOLS = [
         },
     }),
     tool({
-        name: 'get_asset_metadata', title: "Get an asset's metadata", write: false,
+        name: 'get_asset_metadata', title: "Get an asset's metadata", permissions: ['assets:read'],
         description: "An asset's metadata (technical data and custom tags).",
         input: { projectId, fileId: id('asset') },
         projectOf: byProject,
         call: ({ projectId, fileId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(fileId)}/metadata` }),
     }),
     tool({
-        name: 'get_asset_rights', title: "Get an asset's rights", write: false,
+        name: 'get_asset_rights', title: "Get an asset's rights", permissions: ['rights:read'],
         description: "An asset's rights: holder, license, territory, expiry and restrictions.",
         input: { projectId, assetId: id('asset') },
         projectOf: byProject,
         call: ({ projectId, assetId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights` }),
     }),
     tool({
-        name: 'get_workflow', title: "Get a project's workflow", write: false,
+        name: 'get_workflow', title: "Get a project's workflow", permissions: ['workflow:read'],
         description: "A project's workflow (its node graph).",
         input: { projectId },
         projectOf: byProject,
         call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/workflow` }),
     }),
     tool({
-        name: 'list_pipelines', title: 'List pipelines', write: false,
+        name: 'list_pipelines', title: 'List pipelines', permissions: ['workflow:read'],
         description: "A project's pipelines.",
         input: { projectId },
         projectOf: byProject,
         call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/pipelines` }),
     }),
     tool({
-        name: 'get_pipeline', title: 'Get a pipeline', write: false,
+        name: 'get_pipeline', title: 'Get a pipeline', permissions: ['workflow:read'],
         description: 'A pipeline, with its node schema.',
         input: { projectId, pipelineId: id('pipeline') },
         projectOf: byProject,
         call: ({ projectId, pipelineId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/pipelines/${enc(pipelineId)}` }),
     }),
     tool({
-        name: 'list_exports', title: 'List exports', write: false,
+        name: 'list_exports', title: 'List exports', permissions: ['project:read', 'exports:read'],
         description: "A project's exports (its published endpoints).",
         input: { projectId },
         projectOf: byProject,
@@ -120,34 +120,34 @@ exports.TOOLS = [
         pick: (data) => data?.project?.exports ?? data?.exports ?? [],
     }),
     tool({
-        name: 'get_export', title: 'Get an export', write: false,
+        name: 'get_export', title: 'Get an export', permissions: ['exports:read'],
         description: 'An export, with its node schema.',
         input: { projectId, exportId: id('export') },
         projectOf: byProject,
         call: ({ projectId, exportId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/exports/${enc(exportId)}` }),
     }),
     tool({
-        name: 'get_job', title: 'Get a job', write: false,
+        name: 'get_job', title: 'Get a job', permissions: ['jobs:read'],
         description: "A job's status and progress (transcoding, rendering, ingesting...).",
         input: { jobId: id('job') },
         call: ({ jobId }) => ({ method: 'GET', path: `/jobs/${enc(jobId)}` }),
     }),
     tool({
-        name: 'list_sequences', title: 'List production sequences', write: false,
+        name: 'list_sequences', title: 'List production sequences', permissions: ['production:read'],
         description: "A project's production sequences.",
         input: { projectId },
         projectOf: byProject,
         call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/production/sequences` }),
     }),
     tool({
-        name: 'list_shots', title: 'List shots', write: false,
+        name: 'list_shots', title: 'List shots', permissions: ['production:read'],
         description: "A production sequence's shots.",
         input: { projectId, sequenceId: id('sequence') },
         projectOf: byProject,
         call: ({ projectId, sequenceId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}/shots` }),
     }),
     tool({
-        name: 'list_tasks', title: 'List shot tasks', write: false,
+        name: 'list_tasks', title: 'List shot tasks', permissions: ['production:read'],
         description: "A shot's tasks.",
         input: { projectId, shotId: id('shot') },
         projectOf: byProject,
@@ -155,73 +155,132 @@ exports.TOOLS = [
     }),
     // ── Writing ──
     tool({
-        name: 'update_asset_metadata', title: "Update an asset's custom tags", write: true,
+        name: 'update_asset_metadata', title: "Update an asset's custom tags", permissions: ['assets:write'], write: true,
         description: "Sets an asset's custom tags (key/value pairs), replacing the ones it had.",
         input: { projectId, fileId: id('asset'), customTags: zod_1.z.record(zod_1.z.string(), zod_1.z.string()) },
         projectOf: byProject,
         call: ({ projectId, fileId, customTags }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/assets/${enc(fileId)}/metadata`, body: { customTags } }),
     }),
     tool({
-        name: 'set_asset_rights', title: "Set an asset's rights", write: true,
+        name: 'set_asset_rights', title: "Set an asset's rights", permissions: ['rights:write'], write: true,
         description: "Sets an asset's rights: holder, license, territory, expiry, restrictions and notes.",
         input: { projectId, assetId: id('asset'), ...rightsFields },
         projectOf: byProject,
         call: ({ projectId, assetId, ...rights }) => ({ method: 'PUT', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights`, body: defined(rights) }),
     }),
     tool({
-        name: 'create_pipeline', title: 'Create a pipeline', write: true,
+        name: 'create_pipeline', title: 'Create a pipeline', permissions: ['workflow:write'], write: true,
         description: 'Creates a pipeline in a project.',
         input: { projectId, name: zod_1.z.string().min(1), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/pipelines`, body: defined(fields) }),
     }),
     tool({
-        name: 'update_pipeline', title: 'Update a pipeline', write: true,
+        name: 'update_pipeline', title: 'Update a pipeline', permissions: ['workflow:write'], write: true,
         description: "Changes a pipeline's name, description or order.",
         input: { projectId, pipelineId: id('pipeline'), name: zod_1.z.string().min(1).optional(), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, pipelineId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/pipelines/${enc(pipelineId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_sequence', title: 'Create a production sequence', write: true,
+        name: 'create_sequence', title: 'Create a production sequence', permissions: ['production:write'], write: true,
         description: 'Creates a production sequence in a project.',
         input: { projectId, name: zod_1.z.string().min(1), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/sequences`, body: defined(fields) }),
     }),
     tool({
-        name: 'update_sequence', title: 'Update a production sequence', write: true,
+        name: 'update_sequence', title: 'Update a production sequence', permissions: ['production:write'], write: true,
         description: "Changes a sequence's name, description or order.",
         input: { projectId, sequenceId: id('sequence'), name: zod_1.z.string().min(1).optional(), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, sequenceId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_shot', title: 'Create a shot', write: true,
+        name: 'create_shot', title: 'Create a shot', permissions: ['production:write'], write: true,
         description: 'Creates a shot in a production sequence.',
         input: { projectId, sequenceId: id('sequence'), name: zod_1.z.string().min(1), ...shotFields },
         projectOf: byProject,
         call: ({ projectId, sequenceId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}/shots`, body: defined(fields) }),
     }),
     tool({
-        name: 'update_shot', title: 'Update a shot', write: true,
+        name: 'update_shot', title: 'Update a shot', permissions: ['production:write'], write: true,
         description: 'Changes a shot (its name, status, assignee, due date...).',
         input: { projectId, shotId: id('shot'), name: zod_1.z.string().min(1).optional(), ...shotFields },
         projectOf: byProject,
         call: ({ projectId, shotId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_task', title: 'Create a shot task', write: true,
+        name: 'create_task', title: 'Create a shot task', permissions: ['production:write'], write: true,
         description: 'Creates a task in a shot.',
         input: { projectId, shotId: id('shot'), name: zod_1.z.string().min(1), ...taskFields },
         projectOf: byProject,
         call: ({ projectId, shotId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks`, body: defined(fields) }),
     }),
     tool({
-        name: 'update_task', title: 'Update a shot task', write: true,
+        name: 'update_task', title: 'Update a shot task', permissions: ['production:write'], write: true,
         description: 'Changes a task (its name, status, priority, assignee, due date, notes).',
         input: { projectId, shotId: id('shot'), taskId: id('task'), name: zod_1.z.string().min(1).optional(), ...taskFields },
         projectOf: byProject,
         call: ({ projectId, shotId, taskId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks/${enc(taskId)}`, body: defined(fields) }),
     }),
+    // ── Projects ──
+    tool({
+        name: 'create_project', title: 'Create a project', permissions: ['projects:create'], write: true,
+        description: 'Creates a StreamBy project, its maker being its admin, as from "New project" in the UI. The token reaches it from then on.',
+        input: {
+            name: zod_1.z.string().min(1),
+            description: zod_1.z.string().optional(),
+            public: zod_1.z.boolean().optional().describe('Whether it shows in Explore (true if not given; a private one needs a subscriber plan)'),
+            category: zod_1.z.string().optional(),
+        },
+        call: (fields) => ({ method: 'POST', path: '/projects/create', body: defined(fields) }),
+        pick: (data) => ({ projectId: data?.projectId, message: data?.message }),
+    }),
+    tool({
+        name: 'delete_project', title: 'Delete a project', permissions: ['project:delete'], write: true, destructive: true,
+        description: 'Deletes a project, with everything in it, for every member. It cannot be undone.',
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'DELETE', path: `/projects/${enc(projectId)}` }),
+        pick: (data) => ({ message: data?.message }),
+    }),
+    // ── Deleting ──
+    tool({
+        name: 'delete_asset', title: 'Delete an asset', permissions: ['assets:delete'], write: true, destructive: true,
+        description: "Deletes an asset's file, from the project's built-in storage or from one of its storage connections. It cannot be undone.",
+        input: {
+            projectId,
+            fileId: id('asset'),
+            connectionId: zod_1.z.string().optional().describe("The storage connection it's in; the project's built-in storage if not given"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, fileId, connectionId }) => ({
+            method: 'DELETE',
+            path: connectionId
+                ? `/projects/${enc(projectId)}/connections/storage/${enc(connectionId)}/files/${enc(fileId)}`
+                : `/projects/${enc(projectId)}/storage/files/${enc(fileId)}`,
+        }),
+    }),
+    tool({
+        name: 'delete_sequence', title: 'Delete a production sequence', permissions: ['production:delete'], write: true, destructive: true,
+        description: 'Deletes a production sequence, with its shots. It cannot be undone.',
+        input: { projectId, sequenceId: id('sequence') },
+        projectOf: byProject,
+        call: ({ projectId, sequenceId }) => ({ method: 'DELETE', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}` }),
+    }),
+    tool({
+        name: 'delete_shot', title: 'Delete a shot', permissions: ['production:delete'], write: true, destructive: true,
+        description: 'Deletes a shot, with its tasks. It cannot be undone.',
+        input: { projectId, shotId: id('shot') },
+        projectOf: byProject,
+        call: ({ projectId, shotId }) => ({ method: 'DELETE', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}` }),
+    }),
+    tool({
+        name: 'delete_task', title: 'Delete a shot task', permissions: ['production:delete'], write: true, destructive: true,
+        description: "Deletes a shot's task. It cannot be undone.",
+        input: { projectId, shotId: id('shot'), taskId: id('task') },
+        projectOf: byProject,
+        call: ({ projectId, shotId, taskId }) => ({ method: 'DELETE', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks/${enc(taskId)}` }),
+    }),
 ];