streamby-core 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.41.0
+
+### Added
+
+- **OAuth access tokens**: apps the user signs in to with their account (claude.ai's
+  connector) work with StreamBy and its MCP server, as a protected resource (RFC 9728). The
+  README documents the setup, and how to add the connector in claude.ai.
+  - `createOAuthTokenVerifier({ issuer, audiences, jwks })` checks a token with the
+    authorization server's keys (RS256, from its JWKS URL or a function), its issuer, its
+    audience (one of StreamBy's resources, RFC 8707) and its expiry. The host's `authProvider`
+    returns its user with `apiToken: verified.scope` and `oauth: { clientId, clientName? }`.
+  - Scopes map to permissions: `streamby:read` to every `:read` one, `streamby:write` to those
+    and making and changing; none to deleting nor managing members (`OAUTH_SCOPE_PERMISSIONS`,
+    `permissionsForOAuthScopes`). The user's role in each project still applies.
+  - An app deletes nothing: its `DELETE` requests answer 403 whatever their route's permission
+    (`project:update`, `workflow:write` and `exports:write` reach some that delete), but taking
+    a deliverable's mark off. API tokens are unchanged.
+  - The router's `oauth` config (`{ issuer, resource, resourceMetadataUrl?, resourceName? }`)
+    makes a request without a valid token answer 401 with
+    `WWW-Authenticate: Bearer resource_metadata="..."`, and serves the metadata at
+    `GET /.well-known/oauth-protected-resource`; `protectedResourceMetadata` builds it for the
+    host to serve at its root too.
+  - `looksLikeOAuthAccessToken` tells an access token from a host's session tokens.
+- `Auth.oauth`: the app a request comes from. A request with it and without `apiToken` is
+  refused (an app never gets all of its user's access).
+
+### Changed
+
+- The MCP server takes an OAuth access token too. An app's requests are limited per user it acts
+  for, and its tool calls are recorded in `mcp_audit` by its client (`oauthClientId`, a new
+  column added at startup) with no `tokenId` (now nullable).
+
 ## 0.40.0
 
 ### ⚠️ Breaking changes

package/README.md

@@ -173,19 +173,106 @@ list shows only the token's projects.
 
 ---
 
+## 🔐 OAuth: apps the user signs in to
+
+An app the user signs in to with their account, such as claude.ai's connector, works with
+StreamBy through an **OAuth access token**, not an API token. StreamBy is the protected resource
+(RFC 9728); the tokens are issued by the host's authorization server (for Nhexa, Nhexa-API).
+
+A token is a JWT the server signs with RS256 for one resource (its audience, RFC 8707), checked
+with the server's published keys (JWKS) alone: no secret is shared. It reaches what the user
+approved, and never more than the user can: their role in each project still applies.
+
+| Scope | Permissions |
+|---|---|
+| `streamby:read` | Every `:read` permission: `project:read`, `members:read`, `assets:read`, `production:read`, `workflow:read`, `exports:read`, `rights:read`, `jobs:read`. |
+| `streamby:write` | Those, and making and changing: `project:update`, `assets:write`, `production:write`, `workflow:write`, `exports:write`, `rights:write`, `jobs:run`, `projects:create`. |
+
+No scope grants deleting (`*:delete`, `project:delete`) nor managing members. And since some
+write permissions also reach routes that delete (`project:update` a connection, a worker or an
+integration; `workflow:write` a pipeline; `exports:write` an export), **an app's `DELETE` is
+refused (403) whatever its route**, but taking a deliverable's mark off, which only forgets the
+mark (the asset stays). API tokens aren't affected. Other scopes (`profile`, `email`) grant
+nothing in StreamBy. `OAUTH_SCOPE_PERMISSIONS` is exported.
+
+**Telling clients where to sign in**
+
+Set `oauth` in the router's config. A request without a valid token then gets a 401 with
+`WWW-Authenticate: Bearer resource_metadata="..."`, and the metadata says which authorization
+server to use. The router serves it at `GET /streamby/.well-known/oauth-protected-resource`;
+serve it at your root too, where RFC 9728 puts it (`resourceMetadataUrl` defaults to that):
+
+```ts
+import express from 'express';
+import { createStreamByRouter, protectedResourceMetadata } from 'streamby-core';
+
+const oauth = { issuer: 'https://api.example.com', resource: 'https://api.example.com/streamby/mcp' };
+app.get('/.well-known/oauth-protected-resource/streamby/mcp', (_req, res) => res.json(protectedResourceMetadata(oauth)));
+app.use('/streamby', createStreamByRouter({ /* ... */ oauth }));
+```
+
+**Validating a token (your `authProvider`)**
+
+Your `authProvider` checks the token with `createOAuthTokenVerifier` and returns the user, with
+the token's scope in `apiToken` and the app in `oauth`. A request with `oauth` but no `apiToken`
+is refused, so an app never gets all of its user's access. `looksLikeOAuthAccessToken` tells the
+token from your own session tokens.
+
+```ts
+import { createOAuthTokenVerifier, looksLikeOAuthAccessToken, API_TOKEN_PREFIX } from 'streamby-core';
+
+const verifyOAuthToken = createOAuthTokenVerifier({
+  issuer: 'https://api.example.com',
+  // What a token may be for: StreamBy's resources.
+  audiences: ['https://api.example.com/streamby', 'https://api.example.com/streamby/mcp'],
+  // The server's JWKS URL, or a function giving its keys (when the host is the server itself).
+  jwks: 'https://api.example.com/.well-known/jwks.json',
+});
+
+createStreamByRouter({
+  // ...
+  authProvider: async (req) => {
+    const bearer = req.headers.authorization?.replace(/^Bearer /, '');
+    if (bearer?.startsWith(API_TOKEN_PREFIX)) { /* an API token, as above */ }
+    if (looksLikeOAuthAccessToken(bearer)) {
+      const verified = await verifyOAuthToken(bearer); // null: forged, expired, or for another resource
+      if (!verified) throw new Error('Invalid OAuth access token');
+      // Optional but recommended: has the user taken the app's access away? (your own records)
+      if (!(await stillConnected(verified.userId, verified.clientId))) throw new Error('Access revoked');
+      const user = await findUser(verified.userId);
+      return {
+        userId: user.id, username: user.username, role: user.role,
+        apiToken: verified.scope,
+        oauth: { clientId: verified.clientId, clientName: 'Claude' }, // the name, if you know it
+      };
+    }
+    // ...your session-based authentication
+  },
+});
+```
+
+The verifier keeps the keys for 5 minutes (`jwksCacheMs`) and fetches them again for a key id it
+doesn't know (a rotation), at most once a minute. It doesn't know whether the user has since
+taken the app's access away: without that check, a revoked app keeps its access until its access
+token expires (Nhexa's last an hour). Nhexa-API checks the user's consent on every request, so
+taking the access away in accounts.nhexa.cl ends it at once.
+
+---
+
 ## 🤖 MCP server
 
 StreamBy serves an [MCP](https://modelcontextprotocol.io) server at `POST /streamby/mcp`
 (Streamable HTTP, stateless). Agents such as Claude Code use it to read and work on StreamBy
-projects with an API token (see above). It takes only an API token; a browser session gets 401.
+projects with an API token, and apps the user signed in to (claude.ai's connector) with an OAuth
+access token (see above). A browser session gets 401.
 
 Each tool calls StreamBy's own REST API with the caller's token. So it reaches exactly what the
-token allows (and, for a user's token, what its user's role in each project allows), and a
+token allows (and, for a user's token or an app, what the user's role in each project allows), and a
 change is saved just like one made from the UI, which shows it when it loads the project.
 
 **Tools**
 
-A token sees only the tools whose permissions it has.
+A token sees only the tools whose permissions it has (an app: those its scopes grant).
 
 | Tools | Permissions |
 |---|---|
@@ -273,13 +360,14 @@ code there that downloads the URL and imports the file (in Blender,
 
 **Limits and audit**
 
-- Each token can make at most 120 requests a minute (a sliding window). Past that, StreamBy
-  answers 429 with `Retry-After`. Each instance counts its own requests. Change the limit with
-  `mcp.rateLimit`.
+- Each token can make at most 120 requests a minute (a sliding window); an app, per user it acts
+  for. Past that, StreamBy answers 429 with `Retry-After`. Each instance counts its own
+  requests. Change the limit with `mcp.rateLimit`.
 - Every tool call is recorded in the `mcp_audit` table, created at startup in the main database.
-  Each row has the user (a project's token: the token itself), the token's id, the project, the
-  tool, whether it went through, the status, the error and the duration. A row never includes
-  the arguments or the token.
+  Each row has the user (a project's token: the token itself), the token's id (an app's call:
+  its OAuth client, in `oauthClientId`, and no token), the project, the tool, whether it went
+  through, the status, the error and the duration. A row never includes the arguments or the
+  token.
 
 ```ts
 createStreamByRouter({
@@ -337,7 +425,24 @@ and an expiry:
 }
 ```
 
-The claude.ai connector needs OAuth, which isn't available yet: it's for API tokens only for now.
+### Connecting from claude.ai
+
+claude.ai connects through a custom connector, which signs in with OAuth (see above): nobody on
+the team sets up a token or a file. Each person signs in with their own account and approves what
+Claude may do, and Claude reaches only that, and only what their role in each project allows.
+
+- **For yourself**: in claude.ai, Settings → Connectors → Add custom connector. Give it a name
+  (StreamBy) and the server's URL, `https://your-host/streamby/mcp`, and add it. Then Connect:
+  claude.ai opens the sign-in page, and after you sign in, the consent screen, with what it asks
+  for (`streamby:read`, and `streamby:write` to make and change things). Approve it.
+- **For your organization** (Team and Enterprise plans): an owner adds it once in Organization
+  settings → Connectors, with the same URL; each member then connects it with their own account
+  from their Settings → Connectors.
+
+claude.ai registers itself with the authorization server (dynamic client registration or a
+client ID metadata document), so there's nothing to set up there. To take its access away, the
+person removes it in their account's connected apps (in Nhexa, accounts.nhexa.cl → Aplicaciones
+→ Quitar acceso), or disconnects it in claude.ai.
 
 ---
 

package/dist/adapters/database/connectionManager.js

@@ -249,6 +249,9 @@ const createTables = async (pool) => {
         "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
       );
       CREATE INDEX IF NOT EXISTS mcp_audit_token_idx ON streamby.mcp_audit ("tokenId", "createdAt");
+      -- An app's calls (an OAuth access token) are recorded by its client, with no token.
+      ALTER TABLE streamby.mcp_audit ADD COLUMN IF NOT EXISTS "oauthClientId" VARCHAR(255);
+      ALTER TABLE streamby.mcp_audit ALTER COLUMN "tokenId" DROP NOT NULL;
     `);
         console.log('✅ "mcp_audit" table ensured to exist.');
     }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/mcp/audit.d.ts

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

package/dist/mcp/audit.js

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

package/dist/mcp/server.js

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

package/dist/middleware/createRouter.js

@@ -28,6 +28,7 @@ const dbConnection_1 = require("./routes/dbConnection");
 const storageConnection_1 = require("./routes/storageConnection");
 const userIntegration_1 = require("./routes/userIntegration");
 const oauth_1 = require("./routes/oauth");
+const oauthResource_1 = require("./routes/oauthResource");
 const notification_1 = require("./routes/notification");
 const subscription_1 = require("./routes/subscription");
 const media_1 = require("./routes/media");
@@ -112,6 +113,8 @@ function createStreamByRouter(config) {
     if (config.websocket?.server) {
         (0, wsHub_1.initWsHub)(config.websocket.server, config);
     }
+    // Where to sign in for a token (RFC 9728): open, before anything asks for one.
+    router.use((0, oauthResource_1.oauthResourceRouter)(config));
     // /auth answers whether there's a session (it reads it itself); everything after needs one,
     // but for the public export route (see authenticate).
     router.use((0, auth_2.authRouter)(config));

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/services/auth.d.ts

@@ -6,5 +6,7 @@ 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;
 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.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,29 @@ 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;
 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' });
+    }
     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 +70,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/oauthTokens.d.ts

@@ -0,0 +1,60 @@
+import { ApiTokenScope, OAuthResourceConfig } from '../types';
+import { ApiTokenPermission } from './apiTokenPermissions';
+export declare const OAUTH_SCOPES: readonly ["streamby:read", "streamby:write"];
+export type OAuthScope = typeof OAUTH_SCOPES[number];
+/** The permissions each scope grants. */
+export declare const OAUTH_SCOPE_PERMISSIONS: Record<OAuthScope, ApiTokenPermission[]>;
+/** What a token's scopes let it do (scopes that aren't StreamBy's grant nothing here). */
+export declare const permissionsForOAuthScopes: (scopes: string[]) => ApiTokenPermission[];
+export interface Jwk {
+    kty: string;
+    kid?: string;
+    n?: string;
+    e?: string;
+    alg?: string;
+    use?: string;
+}
+export interface Jwks {
+    keys: Jwk[];
+}
+export interface OAuthTokenVerifierOptions {
+    issuer: string;
+    audiences: string[];
+    jwks: string | (() => Promise<Jwks>);
+    jwksCacheMs?: number;
+    fetcher?: (url: string, init: RequestInit) => Promise<Response>;
+    now?: () => number;
+}
+export interface VerifiedOAuthToken {
+    userId: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: Date;
+    scope: ApiTokenScope;
+}
+/**
+ * Whether a bearer is shaped as an OAuth access token (a JWT signed with RS256), not whether
+ * it's valid: for an authProvider to tell it from its own session tokens.
+ */
+export declare const looksLikeOAuthAccessToken: (token: unknown) => token is string;
+/** The grant an OAuth request counts as (its rate limit's key): one app, for one user. */
+export declare const oauthGrantId: (clientId: string, userId: string) => string;
+/**
+ * Checks OAuth access tokens: their signature with the issuer's keys, the issuer, that they're
+ * for StreamBy (their audience), and that they haven't expired. The verified token, or null.
+ * It doesn't know whether the user has since revoked the app: the host may check that too.
+ */
+export declare function createOAuthTokenVerifier(options: OAuthTokenVerifierOptions): (token: unknown) => Promise<VerifiedOAuthToken | null>;
+/** Where RFC 9728 puts a resource's metadata: at its origin, before its path. */
+export declare const defaultResourceMetadataUrl: (resource: string) => string;
+export declare const resourceMetadataUrlOf: (oauth: OAuthResourceConfig) => string;
+/** The metadata a client reads to know where to sign in, and what to ask for. */
+export declare const protectedResourceMetadata: (oauth: OAuthResourceConfig) => {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: ("streamby:read" | "streamby:write")[];
+    bearer_methods_supported: string[];
+    resource_name: string;
+};
+/** The WWW-Authenticate challenge of a 401: the metadata's URL, and why the token was refused. */
+export declare const wwwAuthenticate: (oauth: OAuthResourceConfig, invalidToken: boolean) => string;

package/dist/services/oauthTokens.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wwwAuthenticate = exports.protectedResourceMetadata = exports.resourceMetadataUrlOf = exports.defaultResourceMetadataUrl = exports.oauthGrantId = exports.looksLikeOAuthAccessToken = exports.permissionsForOAuthScopes = exports.OAUTH_SCOPE_PERMISSIONS = exports.OAUTH_SCOPES = void 0;
+exports.createOAuthTokenVerifier = createOAuthTokenVerifier;
+const crypto_1 = __importDefault(require("crypto"));
+// ── OAuth access tokens ──
+// An app the user signed in to with their account (e.g. claude.ai's connector) comes with an
+// OAuth access token: a JWT the authorization server signed (RS256) for one resource (its
+// audience, RFC 8707). It's checked with the server's published keys alone (JWKS): no secret
+// is shared. What it may do is what the user approved -- its scopes -- as permissions of the
+// API tokens' kind, so the same checks limit it; and, as a user's token, never more than the
+// user can (their role in each project still applies).
+exports.OAUTH_SCOPES = ['streamby:read', 'streamby:write'];
+const READ_PERMISSIONS = [
+    'project:read', 'members:read', 'assets:read', 'production:read', 'workflow:read',
+    'exports:read', 'rights:read', 'jobs:read',
+];
+// Making and changing, as the consent screen says: never deleting, nor managing members.
+const WRITE_PERMISSIONS = [
+    'project:update', 'assets:write', 'production:write', 'workflow:write', 'exports:write',
+    'rights:write', 'jobs:run', 'projects:create',
+];
+/** The permissions each scope grants. */
+exports.OAUTH_SCOPE_PERMISSIONS = {
+    'streamby:read': READ_PERMISSIONS,
+    'streamby:write': [...READ_PERMISSIONS, ...WRITE_PERMISSIONS],
+};
+/** What a token's scopes let it do (scopes that aren't StreamBy's grant nothing here). */
+const permissionsForOAuthScopes = (scopes) => [...new Set(scopes.flatMap(scope => exports.OAUTH_SCOPE_PERMISSIONS[scope] ?? []))];
+exports.permissionsForOAuthScopes = permissionsForOAuthScopes;
+const SKEW_SECONDS = 60;
+const REFETCH_MIN_MS = 60 * 1000;
+const decodePart = (part) => {
+    try {
+        const value = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Whether a bearer is shaped as an OAuth access token (a JWT signed with RS256), not whether
+ * it's valid: for an authProvider to tell it from its own session tokens.
+ */
+const looksLikeOAuthAccessToken = (token) => {
+    if (typeof token !== 'string')
+        return false;
+    const parts = token.split('.');
+    return parts.length === 3 && decodePart(parts[0])?.alg === 'RS256';
+};
+exports.looksLikeOAuthAccessToken = looksLikeOAuthAccessToken;
+/** The grant an OAuth request counts as (its rate limit's key): one app, for one user. */
+const oauthGrantId = (clientId, userId) => `oauth:${clientId}:${userId}`;
+exports.oauthGrantId = oauthGrantId;
+/**
+ * Checks OAuth access tokens: their signature with the issuer's keys, the issuer, that they're
+ * for StreamBy (their audience), and that they haven't expired. The verified token, or null.
+ * It doesn't know whether the user has since revoked the app: the host may check that too.
+ */
+function createOAuthTokenVerifier(options) {
+    const now = () => (options.now ? options.now() : Date.now());
+    const cacheMs = options.jwksCacheMs ?? 5 * 60 * 1000;
+    const fetcher = options.fetcher ?? fetch;
+    let keys = new Map();
+    let fetchedAt = -Infinity;
+    let inFlight = null;
+    const loadKeys = async () => {
+        const jwks = typeof options.jwks === 'function'
+            ? await options.jwks()
+            : await fetcher(options.jwks, { headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(5000) })
+                .then(res => (res.ok ? res.json() : Promise.reject(new Error(`JWKS answered ${res.status}`))));
+        const next = new Map();
+        for (const jwk of jwks?.keys ?? []) {
+            if (jwk.kty !== 'RSA' || !jwk.kid || (jwk.alg && jwk.alg !== 'RS256') || (jwk.use && jwk.use !== 'sig'))
+                continue;
+            try {
+                next.set(jwk.kid, crypto_1.default.createPublicKey({ key: jwk, format: 'jwk' }));
+            }
+            catch { /* not a usable key */ }
+        }
+        keys = next;
+        fetchedAt = now();
+    };
+    const refresh = async () => {
+        inFlight ?? (inFlight = loadKeys().catch(err => {
+            fetchedAt = now(); // don't hammer a failing JWKS
+            console.error('❌ StreamBy OAuth: could not load the issuer\'s keys:', err instanceof Error ? err.message : err);
+        }).finally(() => { inFlight = null; }));
+        await inFlight;
+    };
+    const keyFor = async (kid) => {
+        if (now() - fetchedAt > cacheMs)
+            await refresh();
+        if (!keys.has(kid) && now() - fetchedAt > REFETCH_MIN_MS)
+            await refresh();
+        return keys.get(kid);
+    };
+    return async function verify(token) {
+        if (!(0, exports.looksLikeOAuthAccessToken)(token))
+            return null;
+        const [headerPart, payloadPart, signaturePart] = token.split('.');
+        const header = decodePart(headerPart);
+        const claims = decodePart(payloadPart);
+        if (!header || !claims || typeof header.kid !== 'string')
+            return null;
+        const key = await keyFor(header.kid);
+        if (!key)
+            return null;
+        const signed = crypto_1.default.verify('RSA-SHA256', Buffer.from(`${headerPart}.${payloadPart}`), key, Buffer.from(signaturePart, 'base64url'));
+        if (!signed)
+            return null;
+        const seconds = Math.floor(now() / 1000);
+        const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+        if (claims.iss !== options.issuer)
+            return null;
+        if (!audiences.some(aud => typeof aud === 'string' && options.audiences.includes(aud)))
+            return null;
+        if (typeof claims.exp !== 'number' || claims.exp + SKEW_SECONDS <= seconds)
+            return null;
+        if (typeof claims.nbf === 'number' && claims.nbf - SKEW_SECONDS > seconds)
+            return null;
+        if (typeof claims.sub !== 'string' || !claims.sub || typeof claims.client_id !== 'string' || !claims.client_id)
+            return null;
+        const scopes = typeof claims.scope === 'string' ? claims.scope.split(' ').filter(Boolean) : [];
+        return {
+            userId: claims.sub,
+            clientId: claims.client_id,
+            scopes,
+            expiresAt: new Date(claims.exp * 1000),
+            scope: {
+                tokenId: (0, exports.oauthGrantId)(claims.client_id, claims.sub),
+                kind: 'user',
+                permissions: (0, exports.permissionsForOAuthScopes)(scopes),
+                projectIds: '*',
+            },
+        };
+    };
+}
+// ── The protected resource's metadata (RFC 9728) ──
+/** Where RFC 9728 puts a resource's metadata: at its origin, before its path. */
+const defaultResourceMetadataUrl = (resource) => {
+    const url = new URL(resource);
+    const path = url.pathname === '/' ? '' : url.pathname.replace(/\/$/, '');
+    return `${url.origin}/.well-known/oauth-protected-resource${path}`;
+};
+exports.defaultResourceMetadataUrl = defaultResourceMetadataUrl;
+const resourceMetadataUrlOf = (oauth) => oauth.resourceMetadataUrl ?? (0, exports.defaultResourceMetadataUrl)(oauth.resource);
+exports.resourceMetadataUrlOf = resourceMetadataUrlOf;
+/** The metadata a client reads to know where to sign in, and what to ask for. */
+const protectedResourceMetadata = (oauth) => ({
+    resource: oauth.resource,
+    authorization_servers: [oauth.issuer],
+    scopes_supported: [...exports.OAUTH_SCOPES],
+    bearer_methods_supported: ['header'],
+    resource_name: oauth.resourceName ?? 'StreamBy',
+});
+exports.protectedResourceMetadata = protectedResourceMetadata;
+/** The WWW-Authenticate challenge of a 401: the metadata's URL, and why the token was refused. */
+const wwwAuthenticate = (oauth, invalidToken) => `Bearer resource_metadata="${(0, exports.resourceMetadataUrlOf)(oauth)}"${invalidToken ? ', error="invalid_token"' : ''}`;
+exports.wwwAuthenticate = wwwAuthenticate;

package/dist/types/index.d.ts

@@ -146,6 +146,7 @@ export interface StreamByConfig {
             download?: number;
         };
     };
+    oauth?: OAuthResourceConfig;
     websocket?: {
         server: WebSocketServer;
     };
@@ -179,6 +180,17 @@ export interface Auth {
     username: string;
     role: 'viewer' | 'editor' | 'admin';
     apiToken?: ApiTokenScope;
+    oauth?: OAuthClientInfo;
+}
+export interface OAuthClientInfo {
+    clientId: string;
+    clientName?: string;
+}
+export interface OAuthResourceConfig {
+    issuer: string;
+    resource: string;
+    resourceMetadataUrl?: string;
+    resourceName?: string;
 }
 export type { ApiTokenPermission, ProjectPermission, AccountPermission };
 export type ApiTokenKind = 'user' | 'project';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamby-core",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "StreamBy middleware framework for media storage management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",