streamby-core 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.35.0
+
+### Added
+
+- **API tokens**, so agents and services can work with StreamBy as a user without the user's
+  browser session. The README has the details.
+  - `GET`, `POST` and `DELETE /user/api-tokens` let a user list, make and revoke their own
+    tokens. These routes need a session: a token can't manage tokens.
+  - A token is `sbt_` followed by 32 random bytes. It's shown once, when it's made.
+  - **Scope:** each token is `read` (only reads) or `write` (reads and writes). It reaches a
+    list of projects, or `'*'` for every project its owner is a member of, including ones they
+    join later. It expires in 7, 30, 90 or 365 days, or never.
+  - A request made with a token reaches only its scope:
+    - a `read` token can't write;
+    - a project outside its scope answers 404, and the project list and jobs show only its
+      projects;
+    - outside a project, it can only make a few reads.
+
+    The owner's role in each project still applies on top, so a token never does more than
+    its owner can, and it stops reaching a project once its owner leaves it.
+  - **`resolveApiToken`** (exported, with `API_TOKEN_PREFIX`) is for the host's
+    `authProvider`. It turns `Authorization: Bearer sbt_...` into the token's owner and scope,
+    or `null` once the token is revoked or expired. The `authProvider` returns the scope as
+    `Auth.apiToken`. Without it, a token would have all of its owner's access.
+  - **New table: `api_tokens`.** It's created at startup in the main database, and it keeps
+    only each token's SHA-256 hash, never the token itself.
+
+### Security
+
+- A connection authenticated with an API token can't open the WebSocket. It's closed with
+  code 1008. The WebSocket belongs to the browser session and receives every event of its
+  user, from any project.
+
 ## 0.34.0
 
 ### ⚠️ Migration and deploy

package/README.md

@@ -1,4 +1,4 @@
-# @streamby/core
+# streamby-core
 
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
@@ -9,7 +9,7 @@ Part of the [StreamBy](https://streamby.nhexa.cl) ecosystem by TerminalCore Labs
 
 ## 🚀 What is it?
 
-`@streamby/core` is a plug-and-play middleware for Express (or compatible frameworks) that enables file uploads, listings and **multi-project access** over services like:
+`streamby-core` is a plug-and-play middleware for Express (or compatible frameworks) that enables file uploads, listings and **multi-project access** over services like:
 
 - ✅ AWS S3
 - ✅ Google Cloud Storage (soon)
@@ -23,7 +23,7 @@ It's designed to be installed inside your existing API as a library — **no nee
 ## 📦 Installation
 
 ```bash
-npm install @streamby/core ws
+npm install streamby-core ws
 npm install -D @types/ws
 ```
 
@@ -35,7 +35,7 @@ npm install -D @types/ws
 import http from 'http';
 import express from 'express';
 import { WebSocketServer } from 'ws';
-import { createStreamByRouter } from '@streamby/core';
+import { createStreamByRouter } from 'streamby-core';
 
 const app = express();
 const server = http.createServer(app);
@@ -100,6 +100,55 @@ 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.
+
+Requests send it as `Authorization: Bearer sbt_...`. Your `authProvider` resolves it with
+`resolveApiToken` and returns its owner, with the token's scope in `apiToken`:
+
+```ts
+import { createStreamByRouter, resolveApiToken, API_TOKEN_PREFIX } from 'streamby-core';
+
+createStreamByRouter({
+  // ...
+  authProvider: async (req) => {
+    const bearer = req.headers.authorization?.replace(/^Bearer /, '');
+    if (bearer?.startsWith(API_TOKEN_PREFIX)) {
+      const resolved = await resolveApiToken(bearer); // null once revoked or expired
+      if (!resolved) throw new Error('Invalid API token');
+      const user = await findUser(resolved.userId);   // your own user lookup
+      return { userId: user.id, username: user.username, role: user.role, apiToken: resolved.scope };
+    }
+    // ...your session-based authentication
+  },
+});
+```
+
+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.
+
+---
+
 ## 👥 Project roles
 
 What a user can do in a project depends on their role in that project, as an active member
@@ -120,7 +169,7 @@ nor one that starts a job.
 
 ## 🗄️ Database Schema Setup
 
-`@streamby/core` requires a pre-configured database schema for its internal operations. It does not manage database connections directly; instead, it expects the host application to provide initialized connection instances. This ensures full control and flexibility for the host environment.
+`streamby-core` requires a pre-configured database schema for its internal operations. It does not manage database connections directly; instead, it expects the host application to provide initialized connection instances. This ensures full control and flexibility for the host environment.
 
 The library will only interact with the specified schema and will not touch other schemas in your database. The `reset` option is opt-in and will only drop and recreate the specified `streamby` schema if explicitly set to `true`.
 
@@ -128,7 +177,7 @@ The library will only interact with the specified schema and will not touch othe
 
 ```ts
 import { Pool } from "pg";
-import { setupStreambyPg } from "@streamby/core/pg/setup"; // Adjust path as per your package structure
+import { setupStreambyPg } from "streamby-core/pg/setup"; // Adjust path as per your package structure
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
@@ -141,7 +190,7 @@ await setupStreambyPg({ pool, schema: "streamby", reset: false });
 
 ```ts
 import { MongoClient } from "mongodb";
-import { setupStreambyMongo } from "@streamby/core/mongo/setup"; // Adjust path as per your package structure
+import { setupStreambyMongo } from "streamby-core/mongo/setup"; // Adjust path as per your package structure
 
 const client = new MongoClient(process.env.MONGO_URL!);
 
@@ -154,7 +203,7 @@ await setupStreambyMongo({ client, dbName: "streamby" });
 
 ```ts
 import express from 'express';
-import { createStreamByRouter } from '@streamby/core';
+import { createStreamByRouter } from 'streamby-core';
 
 const app = express();
 
@@ -215,7 +264,7 @@ Unit tests use [Vitest](https://vitest.dev) and [Supertest](https://www.npmjs.co
 
 ## 🗺️ API Endpoints
 
-Here's a summary of the key API endpoints provided by `@streamby/core`:
+Here's a summary of the key API endpoints provided by `streamby-core`:
 
 ### `GET /streamby/projects`
 
@@ -330,5 +379,5 @@ Copyright (C) 2026 TerminalCore Labs
 
 Licensed under the [GNU Affero General Public License v3.0](./LICENSE) (AGPL-3.0-only).
 
-> **Note for consumers:** unlike most installable packages, this one is intentionally AGPL rather than MIT. AGPL's copyleft applies to any project that depends on it -- if you install `@streamby/core`, your own project must also be licensed under AGPL-3.0 (or a compatible copyleft license). Confirm this is acceptable for your use case before adding this dependency.
+> **Note for consumers:** unlike most installable packages, this one is intentionally AGPL rather than MIT. AGPL's copyleft applies to any project that depends on it -- if you install `streamby-core`, your own project must also be licensed under AGPL-3.0 (or a compatible copyleft license). Confirm this is acceptable for your use case before adding this dependency.
 

package/dist/adapters/database/connectionManager.js

@@ -147,6 +147,24 @@ const ensureTablesExist = async (pool) => {
       CREATE INDEX IF NOT EXISTS user_integrations_userid_idx ON streamby.user_integrations ("userId");
     `);
         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.
+        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
+      );
+      CREATE INDEX IF NOT EXISTS api_tokens_userid_idx ON streamby.api_tokens ("userId");
+    `);
+        console.log('✅ "api_tokens" table ensured to exist.');
     }
     catch (error) {
         console.error('❌ Error ensuring tables exist:', error);

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { createStreamByRouter } from './middleware/createRouter';
 export { emitToUser } from './services/wsHub';
 export { createNotification } from './services/notification';
-export type { UserPlan, UserSubscription } from './types';
+export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenAccess } from './types';
+export { resolveApiToken, API_TOKEN_PREFIX } from './services/apiTokens';
+export type { ResolvedApiToken } from './services/apiTokens';

package/dist/index.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
+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");
 Object.defineProperty(exports, "emitToUser", { enumerable: true, get: function () { return wsHub_1.emitToUser; } });
 var notification_1 = require("./services/notification");
 Object.defineProperty(exports, "createNotification", { enumerable: true, get: function () { return notification_1.createNotification; } });
+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; } });

package/dist/middleware/createRouter.js

@@ -12,6 +12,7 @@ const backfillBuiltinConnections_1 = require("../services/backfillBuiltinConnect
 const reencryptCredentials_1 = require("../services/reencryptCredentials");
 const wsHub_1 = require("../services/wsHub");
 const auth_1 = require("../services/auth");
+const apiToken_1 = require("./routes/apiToken");
 const encryption_1 = require("../utils/encryption");
 const auth_2 = require("./routes/auth");
 const user_1 = require("./routes/user");
@@ -95,6 +96,7 @@ function createStreamByRouter(config) {
             (0, manager_1.registerModel)('users', [mainDb.id], 'users', 'accounts');
             (0, manager_1.registerModel)('user_subscriptions', [mainDb.id], 'user_subscriptions', 'streamby');
             (0, manager_1.registerModel)('user_integrations', [mainDb.id], 'user_integrations', streambySchema);
+            (0, manager_1.registerModel)('api_tokens', [mainDb.id], 'api_tokens', streambySchema);
         }
     }
     if (config.websocket?.server) {
@@ -104,8 +106,10 @@ function createStreamByRouter(config) {
     // but for the public export route (see authenticate).
     router.use((0, auth_2.authRouter)(config));
     router.use((0, auth_1.authenticate)(config));
+    router.use(auth_1.enforceApiTokenScope);
     router.use(subscription_1.ensureSubscription);
     router.use((0, user_1.userRouter)(config));
+    router.use((0, apiToken_1.apiTokenRouter)(config));
     router.use((0, export_1.exportRouter)(config));
     router.use((0, member_1.memberRouter)(config));
     router.use((0, storage_2.storageRouter)(config));

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

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

package/dist/middleware/routes/apiToken.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiTokenRouter = apiTokenRouter;
+const express_1 = require("express");
+const manager_1 = require("../../models/manager");
+const auth_1 = require("../../utils/auth");
+const apiTokens_1 = require("../../services/apiTokens");
+// The signed-in user's own API tokens (see services/apiTokens): listed, made, revoked. Only
+// with a session: a token can't manage tokens (see enforceApiTokenScope).
+function apiTokenRouter(config) {
+    const router = (0, express_1.Router)();
+    const Project = (0, manager_1.getModel)('projects');
+    router.get('/user/api-tokens', async (req, res) => {
+        try {
+            const auth = req.auth;
+            res.json({ apiTokens: await (0, apiTokens_1.listApiTokens)(auth.userId) });
+        }
+        catch (err) {
+            res.status(500).json({ message: 'Failed to list API tokens', details: err.message });
+        }
+    });
+    // The token itself is in this response only: it's never stored, nor shown again.
+    router.post('/user/api-tokens', async (req, res) => {
+        try {
+            const auth = req.auth;
+            const { name, access, projectIds, expiresInDays } = req.body ?? {};
+            // A token reaches only projects its owner is in.
+            if (Array.isArray(projectIds)) {
+                for (const id of projectIds) {
+                    const project = typeof id === 'string' ? await Project.findOne({ _id: id }) : null;
+                    if (!(0, auth_1.isProjectMember)(project, auth.userId)) {
+                        return res.status(400).json({ message: `You are not a member of project '${id}'` });
+                    }
+                }
+            }
+            const { token, info } = await (0, apiTokens_1.createApiToken)(auth.userId, { name, access, projectIds, expiresInDays: expiresInDays ?? null }, config);
+            res.status(201).json({ token, apiToken: info, message: 'Copy the token now: it will not be shown again' });
+        }
+        catch (err) {
+            if (err instanceof apiTokens_1.ApiTokenError)
+                return res.status(err.status).json({ message: err.message });
+            res.status(500).json({ message: 'Failed to create API token', details: err.message });
+        }
+    });
+    router.delete('/user/api-tokens/:tokenId', async (req, res) => {
+        try {
+            const auth = req.auth;
+            const revoked = await (0, apiTokens_1.revokeApiToken)(auth.userId, req.params.tokenId);
+            if (!revoked)
+                return res.status(404).json({ message: 'API token not found' });
+            res.status(204).end();
+        }
+        catch (err) {
+            res.status(500).json({ message: 'Failed to revoke API token', details: err.message });
+        }
+    });
+    return router;
+}

package/dist/middleware/routes/media.js

@@ -8,6 +8,7 @@ const jobQueue_1 = require("../../services/jobQueue");
 const mediaProcessor_1 = require("../../services/mediaProcessor");
 const storage_1 = require("../../providers/storage");
 const connectionManager_1 = require("../../adapters/database/connectionManager");
+const auth_2 = require("../../services/auth");
 function getMetadataCollection() {
     const ids = (0, connectionManager_1.getConnectedIds)().filter(id => (0, connectionManager_1.getConnection)(id).type === 'nosql');
     if (!ids.length)
@@ -33,6 +34,9 @@ function mediaRouter(config) {
             const job = (0, jobQueue_1.getJob)(req.params.jobId);
             if (!job)
                 return res.status(404).json({ message: 'Job not found' });
+            // With an API token, only a job of a project it reaches.
+            if (!(0, auth_2.scopeReachesProject)(auth.apiToken, job.projectId))
+                return res.status(404).json({ message: 'Job not found' });
             if (job.userId !== auth.userId) {
                 const project = await Project.findOne({ _id: job.projectId });
                 if (!(0, auth_1.isProjectMember)(project, auth.userId))

package/dist/middleware/routes/project.js

@@ -8,6 +8,7 @@ const connectionManager_1 = require("../../adapters/database/connectionManager")
 const sql_1 = require("../../adapters/database/sql");
 const sanitize_1 = require("../../utils/sanitize");
 const projectIntegration_1 = require("../../services/projectIntegration");
+const auth_2 = require("../../services/auth");
 function projectRouter(config) {
     const router = (0, express_1.Router)();
     const Project = (0, manager_1.getModel)('projects');
@@ -32,6 +33,9 @@ function projectRouter(config) {
                 const currentUserMember = project.members?.find((m) => m.userId?.toString() === auth.userId?.toString());
                 if (!currentUserMember || currentUserMember.status !== 'active')
                     return false;
+                // With an API token, only the projects it reaches.
+                if (!(0, auth_2.scopeReachesProject)(auth.apiToken, (project._id ?? project.id)?.toString()))
+                    return false;
                 if (filterArchived !== undefined) {
                     return (currentUserMember.archived || false) === filterArchived;
                 }

package/dist/services/apiTokens.d.ts

@@ -0,0 +1,47 @@
+import { ApiTokenAccess, ApiTokenScope, StreamByConfig } from '../types';
+export declare const API_TOKEN_PREFIX = "sbt_";
+export declare const API_TOKEN_EXPIRY_DAYS: readonly [7, 30, 90, 365];
+export interface ApiTokenRecord {
+    id: string;
+    userId: string;
+    name: string;
+    prefix: string;
+    hash: string;
+    access: ApiTokenAccess;
+    projectIds: string[];
+    createdAt: Date;
+    expiresAt: Date | null;
+    lastUsedAt: Date | null;
+}
+/** What a token's owner sees of it. */
+export type ApiTokenInfo = Omit<ApiTokenRecord, 'hash' | 'userId' | 'projectIds'> & {
+    projectIds: string[] | '*';
+};
+export declare class ApiTokenError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+export interface CreateApiTokenInput {
+    name: string;
+    access: ApiTokenAccess;
+    projectIds: string[] | '*';
+    expiresInDays: number | null;
+}
+/** A new token for `userId`: the token itself, shown only now, and what's kept of it. */
+export declare function createApiToken(userId: string, input: CreateApiTokenInput, config: StreamByConfig): Promise<{
+    token: string;
+    info: ApiTokenInfo;
+}>;
+/** The tokens `userId` has. */
+export declare function listApiTokens(userId: string): Promise<ApiTokenInfo[]>;
+/** Revokes one of `userId`'s tokens: it stops working at once. Whether there was one. */
+export declare function revokeApiToken(userId: string, tokenId: string): Promise<boolean>;
+export interface ResolvedApiToken {
+    userId: string;
+    scope: ApiTokenScope;
+}
+/**
+ * The token's owner and scope, for the host's authProvider; null when it isn't a token, isn't
+ * known (revoked), or has expired. Marks when it was last used.
+ */
+export declare function resolveApiToken(token: unknown): Promise<ResolvedApiToken | null>;

package/dist/services/apiTokens.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiTokenError = exports.API_TOKEN_EXPIRY_DAYS = exports.API_TOKEN_PREFIX = void 0;
+exports.createApiToken = createApiToken;
+exports.listApiTokens = listApiTokens;
+exports.revokeApiToken = revokeApiToken;
+exports.resolveApiToken = resolveApiToken;
+const crypto_1 = __importDefault(require("crypto"));
+const manager_1 = require("../models/manager");
+// API tokens: how an agent or a service works with StreamBy as a user, without their browser
+// session. A token is "sbt_" and 32 random bytes; only its hash is stored, with a prefix to
+// tell it apart in a list. It's sent as `Authorization: Bearer sbt_...` and the host's
+// authProvider resolves it (resolveApiToken), so the request is its owner's -- limited by the
+// token's scope (read or write, which projects), and never more than its owner can do: the
+// owner's role in each project still decides.
+exports.API_TOKEN_PREFIX = 'sbt_';
+const PREFIX_SHOWN = exports.API_TOKEN_PREFIX.length + 8;
+exports.API_TOKEN_EXPIRY_DAYS = [7, 30, 90, 365];
+const ALL_PROJECTS = '*';
+class ApiTokenError extends Error {
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+exports.ApiTokenError = ApiTokenError;
+const hashOf = (token) => crypto_1.default.createHash('sha256').update(token).digest('hex');
+const infoOf = ({ hash: _hash, userId: _userId, ...info }) => ({
+    ...info,
+    projectIds: parseProjectIds(info.projectIds),
+});
+// As stored (a list, read back from SQL JSON as a list or its text): ['*'] is every project.
+const parseProjectIds = (value) => {
+    if (typeof value === 'string') {
+        try {
+            return parseProjectIds(JSON.parse(value));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(value))
+        return [];
+    const ids = value.map(String);
+    return ids.includes(ALL_PROJECTS) ? '*' : ids;
+};
+const mainDbType = (config) => config.databases?.find(db => db.main)?.type ?? 'nosql';
+/** A new token for `userId`: the token itself, shown only now, and what's kept of it. */
+async function createApiToken(userId, input, config) {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    if (!name)
+        throw new ApiTokenError('A token needs a name.');
+    if (input.access !== 'read' && input.access !== 'write')
+        throw new ApiTokenError("access must be 'read' or 'write'.");
+    if (input.projectIds !== '*' && (!Array.isArray(input.projectIds) || !input.projectIds.length || !input.projectIds.every(id => typeof id === 'string' && id && id !== ALL_PROJECTS))) {
+        throw new ApiTokenError("projectIds must be '*' or a list of project ids.");
+    }
+    if (input.expiresInDays !== null && !exports.API_TOKEN_EXPIRY_DAYS.includes(input.expiresInDays)) {
+        throw new ApiTokenError(`expiresInDays must be one of ${exports.API_TOKEN_EXPIRY_DAYS.join(', ')}, or null.`);
+    }
+    const token = exports.API_TOKEN_PREFIX + crypto_1.default.randomBytes(32).toString('base64url');
+    const now = new Date();
+    const record = {
+        id: crypto_1.default.randomUUID(),
+        userId,
+        name,
+        prefix: token.slice(0, PREFIX_SHOWN),
+        hash: hashOf(token),
+        access: input.access,
+        projectIds: input.projectIds === '*' ? [ALL_PROJECTS] : [...new Set(input.projectIds)],
+        createdAt: now,
+        expiresAt: input.expiresInDays === null ? null : new Date(now.getTime() + input.expiresInDays * 86400000),
+        lastUsedAt: null,
+    };
+    await (0, manager_1.getModel)('api_tokens').create({ ...record, dbType: mainDbType(config) });
+    return { token, info: infoOf(record) };
+}
+/** The tokens `userId` has. */
+async function listApiTokens(userId) {
+    const records = (await (0, manager_1.getModel)('api_tokens').find({ userId }));
+    return records
+        .map(infoOf)
+        .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+}
+/** Revokes one of `userId`'s tokens: it stops working at once. Whether there was one. */
+async function revokeApiToken(userId, tokenId) {
+    return (await (0, manager_1.getModel)('api_tokens').delete({ id: tokenId, userId })) > 0;
+}
+/**
+ * The token's owner and scope, for the host's authProvider; null when it isn't a token, isn't
+ * known (revoked), or has expired. Marks when it was last used.
+ */
+async function resolveApiToken(token) {
+    if (typeof token !== 'string' || !token.startsWith(exports.API_TOKEN_PREFIX))
+        return null;
+    const ApiTokens = (0, manager_1.getModel)('api_tokens');
+    const record = (await ApiTokens.findOne({ hash: hashOf(token) }));
+    if (!record)
+        return null;
+    if (record.expiresAt && new Date(record.expiresAt).getTime() <= Date.now())
+        return null;
+    ApiTokens.update({ id: record.id }, { lastUsedAt: new Date() }).catch(() => { });
+    return {
+        userId: record.userId,
+        scope: { tokenId: record.id, access: record.access, projectIds: parseProjectIds(record.projectIds) },
+    };
+}

package/dist/services/auth.d.ts

@@ -1,4 +1,7 @@
 import { Request, Response, NextFunction } from 'express';
-import { StreamByConfig } from '../types';
+import { Auth, StreamByConfig } from '../types';
 export declare const isPublicRoute: (method: string, path: string) => boolean;
+/** Whether a token's scope reaches a project. */
+export declare const scopeReachesProject: (scope: Auth["apiToken"], projectId: 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,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authenticate = exports.isPublicRoute = void 0;
+exports.authenticate = exports.enforceApiTokenScope = exports.scopeReachesProject = exports.isPublicRoute = void 0;
 // 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.
@@ -8,6 +8,46 @@ const PUBLIC_EXPORT = /^\/[^/]+\/export\/[^/]+\/?$/;
 const READ_METHODS = ['GET', 'HEAD', 'OPTIONS'];
 const isPublicRoute = (method, path) => READ_METHODS.includes(method.toUpperCase()) && PUBLIC_EXPORT.test(path);
 exports.isPublicRoute = isPublicRoute;
+// ── API tokens ──
+// A request made with an API token reaches only what the token's scope does: no writes with a
+// read token, no project outside its projects (as if it didn't exist), no managing tokens, and
+// of the routes outside a project only the few below. Its owner's role in each project still
+// decides on top (the routes' own checks).
+// The project a route acts on, by its path.
+const PROJECT_PATHS = [/^\/projects\/([^/]+)/, /^\/(?:upload|delete)-project-image-url\/([^/]+)/];
+const NOT_A_PROJECT = new Set(['create', 'explore']);
+const projectIdOf = (path) => {
+    for (const pattern of PROJECT_PATHS) {
+        const id = pattern.exec(path)?.[1];
+        if (id && !NOT_A_PROJECT.has(id))
+            return decodeURIComponent(id);
+    }
+    return undefined;
+};
+// Outside a project, a token reaches only these reads (each limited to its scope there).
+const OUTSIDE_A_PROJECT = [/^\/auth\/?$/, /^\/projects\/?$/, /^\/jobs\/[^/]+\/?$/, /^\/user\/subscription\/?$/, /^\/users\/search\/?$/];
+/** Whether a token's scope reaches a project. */
+const scopeReachesProject = (scope, projectId) => !scope || scope.projectIds === '*' || scope.projectIds.includes(projectId);
+exports.scopeReachesProject = scopeReachesProject;
+const enforceApiTokenScope = (req, res, next) => {
+    const scope = req.auth?.apiToken;
+    if (!scope)
+        return next();
+    if (/^\/user\/api-tokens(\/|$)/.test(req.path)) {
+        return res.status(403).json({ error: 'API tokens are managed with a session, not with a token' });
+    }
+    if (!READ_METHODS.includes(req.method.toUpperCase()) && scope.access !== 'write') {
+        return res.status(403).json({ error: 'This API token can only read' });
+    }
+    const projectId = projectIdOf(req.path);
+    if (projectId) {
+        return (0, exports.scopeReachesProject)(scope, projectId) ? next() : res.status(404).json({ message: 'Project not found' });
+    }
+    if (READ_METHODS.includes(req.method.toUpperCase()) && OUTSIDE_A_PROJECT.some(route => route.test(req.path)))
+        return next();
+    return res.status(403).json({ error: 'Not available with an API token' });
+};
+exports.enforceApiTokenScope = enforceApiTokenScope;
 const authenticate = (config) => async (req, res, next) => {
     if ((0, exports.isPublicRoute)(req.method, req.path)) {
         return next();

package/dist/services/wsHub.js

@@ -15,6 +15,12 @@ function initWsHub(wss, config) {
                 ws.close(1008, 'Unauthorized');
                 return;
             }
+            // The WebSocket is the browser session's: it gets every event of its user, whatever the
+            // project, so an API token (scoped to some projects, maybe read-only) never opens it.
+            if (auth.apiToken) {
+                ws.close(1008, "API tokens can't open the WebSocket");
+                return;
+            }
             userId = auth.userId;
         }
         catch (err) {

package/dist/types/index.d.ts

@@ -158,6 +158,13 @@ export interface Auth {
     userId: string;
     username: string;
     role: 'viewer' | 'editor' | 'admin';
+    apiToken?: ApiTokenScope;
+}
+export type ApiTokenAccess = 'read' | 'write';
+export interface ApiTokenScope {
+    tokenId: string;
+    access: ApiTokenAccess;
+    projectIds: string[] | '*';
 }
 export type AuthProvider = (req: Request) => Promise<Auth>;
 export type UserPlan = 'freemium' | 'subscriber' | 'admin';

package/package.json

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