streamby-core 0.40.0 → 0.42.0

package/dist/services/documents.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDocumentStoreDatabase = void 0;
+exports.documentStore = documentStore;
+exports.authorOf = authorOf;
+exports.withDescendants = withDescendants;
+exports.replaceSection = replaceSection;
+exports.publishedDocuments = publishedDocuments;
+const connectionManager_1 = require("../adapters/database/connectionManager");
+const withoutContent = ({ content: _content, ...rest }) => rest;
+const byPlace = (a, b) => a.position - b.position || new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+// ── PostgreSQL ──
+const sqlStore = (pool) => {
+    const DOCS = 'streamby.documents';
+    const VERSIONS = 'streamby.document_versions';
+    const SUMMARY = `id, "projectId", kind, title, "parentId", position, version, exportable, "publishedVersion", "createdAt", "createdBy", "updatedAt", "updatedBy"`;
+    const insertVersion = (client, v) => client.query(`INSERT INTO ${VERSIONS} ("documentId", "projectId", version, title, content, author, "createdAt") VALUES ($1, $2, $3, $4, $5, $6, $7)`, [v.documentId, v.projectId, v.version, v.title, v.content, JSON.stringify(v.author), v.createdAt]);
+    // A save changes two tables: both, or neither.
+    const transaction = async (work) => {
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            const result = await work(client);
+            await client.query(result === null ? 'ROLLBACK' : 'COMMIT');
+            return result;
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => { });
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    };
+    return {
+        async list(projectId) {
+            const { rows } = await pool.query(`SELECT ${SUMMARY} FROM ${DOCS} WHERE "projectId" = $1 ORDER BY position, "createdAt"`, [projectId]);
+            return rows;
+        },
+        async get(projectId, id) {
+            const { rows } = await pool.query(`SELECT * FROM ${DOCS} WHERE "projectId" = $1 AND id = $2`, [projectId, id]);
+            return rows[0] ?? null;
+        },
+        async create(d) {
+            return (await transaction(async (client) => {
+                const { rows } = await client.query(`INSERT INTO ${DOCS} (id, "projectId", kind, title, "parentId", position, content, version, exportable, "publishedVersion", "createdAt", "createdBy", "updatedAt", "updatedBy")
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14) RETURNING *`, [d.id, d.projectId, d.kind, d.title, d.parentId, d.position, d.content, d.version, d.exportable, d.publishedVersion,
+                    d.createdAt, JSON.stringify(d.createdBy), d.updatedAt, JSON.stringify(d.updatedBy)]);
+                await insertVersion(client, { documentId: d.id, projectId: d.projectId, version: d.version, title: d.title, content: d.content, author: d.createdBy, createdAt: d.createdAt });
+                return rows[0];
+            }));
+        },
+        async save(projectId, id, baseVersion, change, author, at) {
+            return transaction(async (client) => {
+                const { rows } = await client.query(`UPDATE ${DOCS} SET title = $4, content = $5, version = version + 1, "updatedAt" = $6, "updatedBy" = $7
+            WHERE "projectId" = $1 AND id = $2 AND version = $3 RETURNING *`, [projectId, id, baseVersion, change.title, change.content, at, JSON.stringify(author)]);
+                const saved = rows[0];
+                if (!saved)
+                    return null;
+                await insertVersion(client, { documentId: id, projectId, version: saved.version, title: saved.title, content: saved.content, author, createdAt: at });
+                return saved;
+            });
+        },
+        async update(projectId, id, patch) {
+            const entries = Object.entries(patch).filter(([, value]) => value !== undefined);
+            if (!entries.length)
+                return this.get(projectId, id);
+            const sets = entries.map(([key], i) => `"${key}" = $${i + 3}`).join(', ');
+            const { rows } = await pool.query(`UPDATE ${DOCS} SET ${sets} WHERE "projectId" = $1 AND id = $2 RETURNING *`, [projectId, id, ...entries.map(([, value]) => value)]);
+            return rows[0] ?? null;
+        },
+        async versions(projectId, id) {
+            const { rows } = await pool.query(`SELECT "documentId", "projectId", version, title, author, "createdAt" FROM ${VERSIONS}
+          WHERE "projectId" = $1 AND "documentId" = $2 ORDER BY version DESC`, [projectId, id]);
+            return rows;
+        },
+        async version(projectId, id, version) {
+            const { rows } = await pool.query(`SELECT * FROM ${VERSIONS} WHERE "projectId" = $1 AND "documentId" = $2 AND version = $3`, [projectId, id, version]);
+            return rows[0] ?? null;
+        },
+        async remove(projectId, ids) {
+            if (!ids.length)
+                return;
+            await transaction(async (client) => {
+                await client.query(`DELETE FROM ${VERSIONS} WHERE "projectId" = $1 AND "documentId" = ANY($2)`, [projectId, ids]);
+                await client.query(`DELETE FROM ${DOCS} WHERE "projectId" = $1 AND id = ANY($2)`, [projectId, ids]);
+                return true;
+            });
+        },
+        async deleteProject(projectId) {
+            await pool.query(`DELETE FROM ${VERSIONS} WHERE "projectId" = $1`, [projectId]);
+            await pool.query(`DELETE FROM ${DOCS} WHERE "projectId" = $1`, [projectId]);
+        },
+    };
+};
+// ── MongoDB ──
+// A save writes the document and then its version: in a transaction, both or neither, when
+// the server supports them (a replica set or a sharded cluster, as Atlas is). A standalone
+// server doesn't: there they're two writes, and if the version's failed after the document's,
+// the document would be at a version its history lacks.
+let mongoTransactions;
+const noTransactions = (err) => {
+    const { code, message } = (err ?? {});
+    return code === 20 || /Transaction numbers are only allowed|replica set/i.test(message ?? '');
+};
+const mongoStore = (client) => {
+    const docs = () => client.db().collection('documents');
+    const versions = () => client.db().collection('document_versions');
+    const strip = (doc) => {
+        if (!doc)
+            return null;
+        const { _id, ...rest } = doc;
+        return rest;
+    };
+    const together = async (work) => {
+        if (mongoTransactions !== false && typeof client.startSession === 'function') {
+            const session = client.startSession();
+            try {
+                let result;
+                await session.withTransaction(async () => { result = await work(session); });
+                mongoTransactions = true;
+                return result;
+            }
+            catch (err) {
+                if (!noTransactions(err))
+                    throw err;
+                mongoTransactions = false;
+            }
+            finally {
+                await session.endSession();
+            }
+        }
+        return work();
+    };
+    return {
+        async list(projectId) {
+            const found = await docs().find({ projectId }, { projection: { content: 0 } }).toArray();
+            return found.map(d => strip(d)).sort(byPlace);
+        },
+        async get(projectId, id) {
+            return strip(await docs().findOne({ projectId, id }));
+        },
+        async create(d) {
+            return together(async (session) => {
+                await docs().insertOne({ ...d }, { session });
+                await versions().insertOne({ documentId: d.id, projectId: d.projectId, version: d.version, title: d.title, content: d.content, author: d.createdBy, createdAt: d.createdAt }, { session });
+                return d;
+            });
+        },
+        async save(projectId, id, baseVersion, change, author, at) {
+            return together(async (session) => {
+                // Conditional on the version: of two saves made on the same one, only the first goes through.
+                const saved = strip(await docs().findOneAndUpdate({ projectId, id, version: baseVersion }, { $set: { ...change, version: baseVersion + 1, updatedAt: at, updatedBy: author } }, { returnDocument: 'after', session }));
+                if (!saved)
+                    return null;
+                await versions().insertOne({ documentId: id, projectId, version: saved.version, ...change, author, createdAt: at }, { session });
+                return saved;
+            });
+        },
+        async update(projectId, id, patch) {
+            const $set = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+            if (!Object.keys($set).length)
+                return this.get(projectId, id);
+            return strip(await docs().findOneAndUpdate({ projectId, id }, { $set }, { returnDocument: 'after' }));
+        },
+        async versions(projectId, id) {
+            const found = await versions().find({ projectId, documentId: id }, { projection: { content: 0 } }).toArray();
+            return found.map(v => strip(v)).sort((a, b) => b.version - a.version);
+        },
+        async version(projectId, id, version) {
+            return strip(await versions().findOne({ projectId, documentId: id, version }));
+        },
+        async remove(projectId, ids) {
+            if (!ids.length)
+                return;
+            await together(async (session) => {
+                await versions().deleteMany({ projectId, documentId: { $in: ids } }, { session });
+                await docs().deleteMany({ projectId, id: { $in: ids } }, { session });
+            });
+        },
+        async deleteProject(projectId) {
+            await versions().deleteMany({ projectId });
+            await docs().deleteMany({ projectId });
+        },
+    };
+};
+// ── In memory (no main database) ──
+const memoryStore = () => {
+    const docs = new Map();
+    const versions = [];
+    const own = (projectId, id) => {
+        const d = docs.get(id);
+        return d && d.projectId === projectId ? d : undefined;
+    };
+    return {
+        async list(projectId) {
+            return [...docs.values()].filter(d => d.projectId === projectId).map(withoutContent).sort(byPlace);
+        },
+        async get(projectId, id) {
+            const d = own(projectId, id);
+            return d ? { ...d } : null;
+        },
+        async create(d) {
+            docs.set(d.id, { ...d });
+            versions.push({ documentId: d.id, projectId: d.projectId, version: d.version, title: d.title, content: d.content, author: d.createdBy, createdAt: d.createdAt });
+            return { ...d };
+        },
+        async save(projectId, id, baseVersion, change, author, at) {
+            const d = own(projectId, id);
+            if (!d || d.version !== baseVersion)
+                return null;
+            Object.assign(d, change, { version: baseVersion + 1, updatedAt: at, updatedBy: author });
+            versions.push({ documentId: id, projectId, version: d.version, ...change, author, createdAt: at });
+            return { ...d };
+        },
+        async update(projectId, id, patch) {
+            const d = own(projectId, id);
+            if (!d)
+                return null;
+            Object.assign(d, Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)));
+            return { ...d };
+        },
+        async versions(projectId, id) {
+            return versions.filter(v => v.projectId === projectId && v.documentId === id).map(withoutContent).sort((a, b) => b.version - a.version);
+        },
+        async version(projectId, id, version) {
+            const v = versions.find(x => x.projectId === projectId && x.documentId === id && x.version === version);
+            return v ? { ...v } : null;
+        },
+        async remove(projectId, ids) {
+            for (const id of ids)
+                if (own(projectId, id))
+                    docs.delete(id);
+            for (let i = versions.length - 1; i >= 0; i--)
+                if (versions[i].projectId === projectId && ids.includes(versions[i].documentId))
+                    versions.splice(i, 1);
+        },
+        async deleteProject(projectId) {
+            for (const [id, d] of docs)
+                if (d.projectId === projectId)
+                    docs.delete(id);
+            for (let i = versions.length - 1; i >= 0; i--)
+                if (versions[i].projectId === projectId)
+                    versions.splice(i, 1);
+        },
+    };
+};
+let mainDbId;
+let memory;
+/** The router's main database, where documents are kept. */
+const setDocumentStoreDatabase = (config) => {
+    mainDbId = config.databases?.find(db => db.main)?.id;
+};
+exports.setDocumentStoreDatabase = setDocumentStoreDatabase;
+function documentStore() {
+    if (mainDbId && (0, connectionManager_1.getConnectedIds)().includes(mainDbId)) {
+        const entry = (0, connectionManager_1.getConnection)(mainDbId);
+        return entry.type === 'sql' ? sqlStore(entry.client) : mongoStore(entry.client);
+    }
+    return (memory ?? (memory = memoryStore()));
+}
+// ── Who saved it ──
+/** Who's saving: the user, through the UI, an API token, or an app acting for them. */
+function authorOf(auth) {
+    if (auth.oauth)
+        return { userId: auth.userId, username: auth.username, via: 'oauth', clientId: auth.oauth.clientId, clientName: auth.oauth.clientName };
+    if (auth.apiToken)
+        return { userId: auth.userId, username: auth.username, via: 'apiToken', tokenId: auth.apiToken.tokenId };
+    return { userId: auth.userId, username: auth.username, via: 'session' };
+}
+// ── The tree ──
+/** A document and everything inside it (a folder's documents, at any depth). */
+function withDescendants(documents, id) {
+    const ids = [id];
+    for (let i = 0; i < ids.length; i++) {
+        for (const d of documents)
+            if (d.parentId === ids[i])
+                ids.push(d.id);
+    }
+    return ids;
+}
+// ── Sections ──
+// A section is what's under a markdown heading ("## Architecture"), up to the next heading of
+// the same level or above. Headings inside a fenced code block aren't headings.
+const HEADING = /^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$/;
+const FENCE = /^[ \t]*(```|~~~)/;
+const headingOf = (text) => {
+    const match = text.trim().match(/^(#{1,6})[ \t]+(.*?)[ \t]*#*$/);
+    return match ? { level: match[1].length, title: match[2].trim() } : { level: null, title: text.trim() };
+};
+/**
+ * The markdown with what's under `heading` replaced by `body`, the rest untouched. `heading` is
+ * its title, with or without its #s ("## Architecture", "Architecture"): with them, only a
+ * heading of that level matches.
+ */
+function replaceSection(markdown, heading, body) {
+    const wanted = headingOf(heading);
+    const lines = markdown.split('\n');
+    const headings = [];
+    let fenced = false;
+    lines.forEach((line, i) => {
+        if (FENCE.test(line))
+            fenced = !fenced;
+        const match = !fenced && line.match(HEADING);
+        if (match)
+            headings.push({ line: i, level: match[1].length, title: match[2].trim() });
+    });
+    const matches = headings.filter(h => h.title === wanted.title && (wanted.level === null || h.level === wanted.level));
+    if (!matches.length)
+        return { error: 'not-found' };
+    if (matches.length > 1)
+        return { error: 'ambiguous' };
+    const [target] = matches;
+    const next = headings.find(h => h.line > target.line && h.level <= target.level);
+    const end = next ? next.line : lines.length;
+    const text = body.replace(/^(\s*\n)+/, '').replace(/\s+$/, '');
+    const replaced = [
+        ...lines.slice(0, target.line + 1),
+        ...(text ? ['', ...text.split('\n')] : []),
+        ...(next ? [''] : []),
+        ...lines.slice(end),
+    ];
+    // A document's last line ends it, as it did.
+    if (!next && markdown.endsWith('\n'))
+        replaced.push('');
+    return { content: replaced.join('\n') };
+}
+/**
+ * The project's exportable documents that have a published version (in one folder, at any
+ * depth, or only those given), as that version was saved.
+ */
+async function publishedDocuments(projectId, scope = {}) {
+    const store = documentStore();
+    const documents = await store.list(projectId);
+    const within = scope.folderId ? new Set(withDescendants(documents, scope.folderId)) : null;
+    const chosen = documents.filter(d => d.kind === 'document' && d.exportable && d.publishedVersion !== null
+        && (!within || within.has(d.id))
+        && (!scope.documentIds?.length || scope.documentIds.includes(d.id)));
+    const published = await Promise.all(chosen.map(async (d) => {
+        const version = await store.version(projectId, d.id, d.publishedVersion);
+        return version && {
+            id: d.id, title: version.title, parentId: d.parentId, position: d.position,
+            version: version.version, content: version.content, publishedAt: version.createdAt,
+        };
+    }));
+    return published.filter((d) => !!d);
+}

package/dist/services/executor.js

@@ -8,6 +8,7 @@ const connectionResolver_1 = require("./connectionResolver");
 const userIntegration_1 = require("./userIntegration");
 const oauthClient_1 = require("./oauthClient");
 const jobQueue_1 = require("./jobQueue");
+const documents_1 = require("./documents");
 const mediaProcessor_1 = require("./mediaProcessor");
 const vfxProcessor_1 = require("./vfxProcessor");
 const aiProcessor_1 = require("./aiProcessor");
@@ -143,6 +144,13 @@ async function executeExport(nodeSchema, project, config, { public: isPublic = t
                 await (0, connectionResolver_1.releaseDbClient)(resolved);
             }
         }
+        else if (node.type === 'documentsNode') {
+            // The project's own documents, as published: an edit is a draft, delivered only once a
+            // version of it is published. Its own data, so public exports read it too.
+            const documentIds = Array.isArray(node.data?.documentIds) ? node.data.documentIds : undefined;
+            const folderId = node.data?.folderId || undefined;
+            dataResults.push(await (0, documents_1.publishedDocuments)(project._id?.toString() ?? project.id, { folderId, documentIds }));
+        }
         else if (node.type === 'connectionNode') {
             const connection = project.connections?.find((c) => c.id === node.data?.connectionId);
             if (!connection)

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', 'docs: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', 'docs:write',
+];
+/** 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';
@@ -517,3 +529,43 @@ export interface AssetVersionRecord {
     changeNote?: string;
     createdAt: Date;
 }
+/**
+ * Who saved a document's version: a user in the UI, an API token, or an app the user let act
+ * for them (OAuth, e.g. Claude in claude.ai).
+ */
+export interface DocumentAuthor {
+    userId: string;
+    username: string;
+    via: 'session' | 'apiToken' | 'oauth';
+    tokenId?: string;
+    clientId?: string;
+    clientName?: string;
+}
+export type DocumentKind = 'document' | 'folder';
+/** A project's document as it is now (a folder only groups others: it has no content). */
+export interface ProjectDocument {
+    id: string;
+    projectId: string;
+    kind: DocumentKind;
+    title: string;
+    parentId: string | null;
+    position: number;
+    content: string;
+    version: number;
+    exportable: boolean;
+    publishedVersion: number | null;
+    createdAt: Date;
+    createdBy: DocumentAuthor;
+    updatedAt: Date;
+    updatedBy: DocumentAuthor;
+}
+/** One save of a document: its title and content then, who saved it and when. */
+export interface DocumentVersion {
+    documentId: string;
+    projectId: string;
+    version: number;
+    title: string;
+    content: string;
+    author: DocumentAuthor;
+    createdAt: Date;
+}

package/package.json

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