@hotmeshio/long-tail 0.23.1 → 0.24.0

package/build/lib/events/nats-ws-server-filter.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * The server's half of a browser's NATS connection, as the WebSocket proxy
+ * forwards it. Message payloads (MSG and HMSG) pass through `rewrite`, which
+ * returns the payload to deliver or null to withhold the message; protocol
+ * lines (INFO, PING, PONG, +OK, -ERR) pass unchanged.
+ *
+ * Operations can span WebSocket frames, so the filter keeps whatever it has
+ * not yet seen whole.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsServerFilter = void 0;
+const CRLF = Buffer.from('\r\n');
+class NatsServerFilter {
+    constructor(rewrite) {
+        this.rewrite = rewrite;
+        this.pending = Buffer.alloc(0);
+    }
+    /** The bytes to forward to the browser for one chunk from the server. */
+    feed(chunk) {
+        this.pending = this.pending.length ? Buffer.concat([this.pending, chunk]) : chunk;
+        const out = [];
+        for (;;) {
+            const end = this.pending.indexOf(CRLF);
+            if (end === -1)
+                break;
+            const line = this.pending.subarray(0, end).toString('utf8');
+            const space = line.indexOf(' ');
+            const op = (space === -1 ? line : line.slice(0, space)).toUpperCase();
+            if (op !== 'MSG' && op !== 'HMSG') {
+                out.push(this.pending.subarray(0, end + CRLF.length));
+                this.pending = this.pending.subarray(end + CRLF.length);
+                continue;
+            }
+            // MSG <subject> <sid> [reply] <size>
+            // HMSG <subject> <sid> [reply] <header size> <total size>
+            const args = line.slice(space + 1).trim().split(/\s+/);
+            const total = Number(args[args.length - 1]);
+            const headerSize = op === 'HMSG' ? Number(args[args.length - 2]) : 0;
+            const start = end + CRLF.length;
+            const need = start + total + CRLF.length;
+            if (this.pending.length < need)
+                break;
+            const headers = this.pending.subarray(start, start + headerSize);
+            const body = this.rewrite(this.pending.subarray(start + headerSize, start + total));
+            this.pending = this.pending.subarray(need);
+            if (body === null)
+                continue;
+            const prefix = args.slice(0, op === 'HMSG' ? -2 : -1).join(' ');
+            const sizes = op === 'HMSG' ? `${headerSize} ${headerSize + body.length}` : `${body.length}`;
+            out.push(Buffer.from(`${op} ${prefix} ${sizes}\r\n`, 'utf8'), headers, body, CRLF);
+        }
+        return Buffer.concat(out);
+    }
+}
+exports.NatsServerFilter = NatsServerFilter;

package/build/lib/events/nats-ws-ticket.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A browser's pass to the NATS WebSocket proxy, in place of the NATS server
+ * credential. It names the person in `sub` and carries no `userId`, so it
+ * authenticates nothing but the proxy upgrade.
+ */
+export declare const NATS_WS_TICKET_TYPE = "nats-ws+jwt";
+export declare const NATS_WS_TICKET_PARAM = "ticket";
+export declare function signNatsWsTicket(userId: string): string | null;
+/** The person a valid ticket names; null for anything else. */
+export declare function verifyNatsWsTicket(ticket: string | null | undefined): string | null;

package/build/lib/events/nats-ws-ticket.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NATS_WS_TICKET_PARAM = exports.NATS_WS_TICKET_TYPE = void 0;
+exports.signNatsWsTicket = signNatsWsTicket;
+exports.verifyNatsWsTicket = verifyNatsWsTicket;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const config_1 = require("../../modules/config");
+/**
+ * A browser's pass to the NATS WebSocket proxy, in place of the NATS server
+ * credential. It names the person in `sub` and carries no `userId`, so it
+ * authenticates nothing but the proxy upgrade.
+ */
+exports.NATS_WS_TICKET_TYPE = 'nats-ws+jwt';
+exports.NATS_WS_TICKET_PARAM = 'ticket';
+function signNatsWsTicket(userId) {
+    if (!config_1.config.JWT_SECRET)
+        return null;
+    return jsonwebtoken_1.default.sign({}, config_1.config.JWT_SECRET, {
+        algorithm: 'HS256',
+        header: { alg: 'HS256', typ: exports.NATS_WS_TICKET_TYPE },
+        subject: userId,
+        expiresIn: config_1.config.NATS_WS_TICKET_TTL_SECONDS,
+    });
+}
+/** The person a valid ticket names; null for anything else. */
+function verifyNatsWsTicket(ticket) {
+    if (!ticket || !config_1.config.JWT_SECRET)
+        return null;
+    try {
+        const decoded = jsonwebtoken_1.default.verify(ticket, config_1.config.JWT_SECRET, { algorithms: ['HS256'], complete: true });
+        if (decoded.header.typ !== exports.NATS_WS_TICKET_TYPE)
+            return null;
+        const payload = decoded.payload;
+        return typeof payload.sub === 'string' && typeof payload.exp === 'number' ? payload.sub : null;
+    }
+    catch {
+        return null;
+    }
+}

package/build/lib/events/socketio.d.ts

@@ -4,7 +4,16 @@ import type { LTEvent, LTEventAdapter } from '../../types';
  * Callback to verify a Socket.IO handshake token.
  * Return `true` to allow the connection, `false` to reject.
  */
-export type SocketIOAuthenticator = (token: string) => boolean | Promise<boolean>;
+/**
+ * Verifies a socket's token. Returning the person (`{ userId }`) lets delivery
+ * follow their capabilities; `true` admits the socket with the browser view
+ * (lib/events/browser-view.ts).
+ */
+export type SocketIOAuthenticator = (token: string) => boolean | {
+    userId: string;
+} | Promise<boolean | {
+    userId: string;
+}>;
 /**
  * Socket.IO event adapter for browser clients.
  *

package/build/lib/events/socketio.js

@@ -4,6 +4,7 @@ exports.SocketIOEventAdapter = void 0;
 const socket_io_1 = require("socket.io");
 const logger_1 = require("../logger");
 const matching_1 = require("./matching");
+const browser_view_1 = require("./browser-view");
 /**
  * Socket.IO event adapter for browser clients.
  *
@@ -73,6 +74,8 @@ class SocketIOEventAdapter {
                     if (!valid) {
                         return next(new Error('Authentication failed'));
                     }
+                    if (typeof valid === 'object')
+                        socket.data.ltUserId = valid.userId;
                     next();
                 }
                 catch {
@@ -86,6 +89,9 @@ class SocketIOEventAdapter {
             // switches the socket from broadcast to scoped delivery.
             const patterns = new Set();
             socket.data.ltPatterns = patterns;
+            // Until the lookup answers, the socket receives the browser view.
+            socket.data.ltViewer = { builder: false };
+            (0, browser_view_1.viewerFor)(socket.data.ltUserId).then((viewer) => { socket.data.ltViewer = viewer; });
             socket.on('lt.subscribe', (pattern) => {
                 if (typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 256) {
                     patterns.add(pattern);
@@ -107,14 +113,15 @@ class SocketIOEventAdapter {
         const channel = `lt.events.${event.type}`;
         for (const socket of this.io.of('/').sockets.values()) {
             const patterns = socket.data.ltPatterns;
+            const delivered = (0, browser_view_1.eventForViewer)(event, socket.data.ltViewer ?? { builder: false });
             if (!patterns || patterns.size === 0) {
-                // Legacy scope: a socket with no registered patterns gets everything.
-                socket.emit(channel, event);
+                // Legacy scope: a socket with no registered patterns gets every subject.
+                socket.emit(channel, delivered);
                 continue;
             }
             for (const pattern of patterns) {
                 if ((0, matching_1.subjectMatchesPattern)(channel, pattern)) {
-                    socket.emit(channel, event);
+                    socket.emit(channel, delivered);
                     break;
                 }
             }

package/build/lib/http/index.d.ts

@@ -0,0 +1,27 @@
+import express from 'express';
+/**
+ * The single module that imports the HTTP framework.
+ *
+ * Routes, middleware, adapters and the standalone server take routers,
+ * handler types and body/static middleware from here. Long Tail runs both
+ * as its own server and as a guest on a host's Express instance (NestJS,
+ * Express), so the framework dependency has exactly one owner.
+ */
+export { Router } from 'express';
+export type { Application, ErrorRequestHandler, NextFunction, Request, RequestHandler, Response, } from 'express';
+type JsonBodyOptions = Parameters<typeof express.json>[0];
+type StaticFilesOptions = Parameters<typeof express.static>[1];
+/** A new application. Only the standalone server owns one; embedded mode uses the host's. */
+export declare function createApp(): express.Application;
+/** JSON body parsing. A body the host already parsed is left as is. */
+export declare function jsonBody(options?: JsonBodyOptions): express.RequestHandler;
+/** Static file serving from `root`. */
+export declare function serveStatic(root: string, options?: StaticFilesOptions): express.RequestHandler;
+/**
+ * Non-credentialed CORS for public endpoints: any origin may call them, and
+ * preflight requests are answered here.
+ */
+export declare function allowAnyOrigin(methods?: string[]): express.RequestHandler;
+type FormBodyOptions = Parameters<typeof express.urlencoded>[0];
+/** URL-encoded form body parsing. A body the host already parsed is left as is. */
+export declare function formBody(options?: FormBodyOptions): express.RequestHandler;

package/build/lib/http/index.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Router = void 0;
+exports.createApp = createApp;
+exports.jsonBody = jsonBody;
+exports.serveStatic = serveStatic;
+exports.allowAnyOrigin = allowAnyOrigin;
+exports.formBody = formBody;
+const express_1 = __importDefault(require("express"));
+/**
+ * The single module that imports the HTTP framework.
+ *
+ * Routes, middleware, adapters and the standalone server take routers,
+ * handler types and body/static middleware from here. Long Tail runs both
+ * as its own server and as a guest on a host's Express instance (NestJS,
+ * Express), so the framework dependency has exactly one owner.
+ */
+var express_2 = require("express");
+Object.defineProperty(exports, "Router", { enumerable: true, get: function () { return express_2.Router; } });
+/** A new application. Only the standalone server owns one; embedded mode uses the host's. */
+function createApp() {
+    return (0, express_1.default)();
+}
+/** JSON body parsing. A body the host already parsed is left as is. */
+function jsonBody(options) {
+    return express_1.default.json(options);
+}
+/** Static file serving from `root`. */
+function serveStatic(root, options) {
+    return express_1.default.static(root, options);
+}
+/**
+ * Non-credentialed CORS for public endpoints: any origin may call them, and
+ * preflight requests are answered here.
+ */
+function allowAnyOrigin(methods = ['GET', 'POST']) {
+    const allowMethods = [...methods, 'OPTIONS'].join(', ');
+    return (req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', allowMethods);
+        res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, MCP-Protocol-Version');
+        if (req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}
+/** URL-encoded form body parsing. A body the host already parsed is left as is. */
+function formBody(options = { extended: false }) {
+    return express_1.default.urlencoded(options);
+}

package/build/modules/auth.d.ts

@@ -1,4 +1,4 @@
-import { Request, RequestHandler } from 'express';
+import { Request, RequestHandler } from '../lib/http';
 import type { AuthPayload, LTAuthAdapter } from '../types';
 export type { AuthPayload, LTAuthAdapter };
 declare global {
@@ -40,34 +40,25 @@ export declare class JwtAuthAdapter implements LTAuthAdapter {
  */
 export declare function createAuthMiddleware(adapter: LTAuthAdapter): RequestHandler;
 export declare const requireAuth: RequestHandler;
+/**
+ * `requireAuth` without the SSO fallback: only a credential the request
+ * carries itself (the configured adapter, else a Bearer JWT or bot key).
+ * For endpoints a cross-site page must not reach through the host's cookie.
+ */
+export declare const requireCredentialAuth: RequestHandler;
 /**
  * Replace the auth adapter used by `requireAuth`.
  * Call before starting the server.
  */
 export declare function setAuthAdapter(adapter: LTAuthAdapter): void;
-/**
- * Middleware that requires admin access. Must be placed AFTER requireAuth.
- *
- * Checks isSuperAdmin() via the database first, then falls back to the
- * JWT `role` claim for stateless admin checks. Returns 403 otherwise.
- */
-export declare const requireAdmin: RequestHandler;
-/**
- * Middleware that requires builder access. Must be placed AFTER requireAuth.
- *
- * Builders are superadmin or users with the 'engineer' role.
- * This is the backend equivalent of the dashboard's `isBuilder` check.
- */
-export declare const requireBuilder: RequestHandler;
-/**
- * Middleware that requires role-management access. Must be placed AFTER requireAuth.
- *
- * Grants access to superadmins, admin-type users, and engineers — the backend
- * equivalent of the dashboard's `isBuilder || isOps`. Ops (admin type) manage
- * users and roles; builders (superadmin, engineer) are a superset. This is the
- * gate for reading and writing role definitions.
- */
-export declare const requireRoleManager: RequestHandler;
+/** Admin access: admin or superadmin claim, or a superadmin in the database. */
+export declare const requireAdmin: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+/** Builder access: superadmin or the 'engineer' role. Backend twin of the dashboard's `isBuilder`. */
+export declare const requireBuilder: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+/** Role-management access: admin access or the 'engineer' role. Backend twin of `isBuilder || isOps`. */
+export declare const requireRoleManager: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+/** Reads of one workflow run (`:workflowId`): builder access, or the person who started it or it runs as. */
+export declare const requireWorkflowReader: RequestHandler;
 /**
  * Generate a JWT token. Utility for tests and token provisioning.
  */

package/build/modules/auth.js

@@ -1,42 +1,9 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireRoleManager = exports.requireBuilder = exports.requireAdmin = exports.requireAuth = exports.JwtAuthAdapter = void 0;
+exports.requireWorkflowReader = exports.requireRoleManager = exports.requireBuilder = exports.requireAdmin = exports.requireCredentialAuth = exports.requireAuth = exports.JwtAuthAdapter = void 0;
 exports.createAuthMiddleware = createAuthMiddleware;
 exports.setAuthAdapter = setAuthAdapter;
 exports.signToken = signToken;
@@ -44,7 +11,7 @@ const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const config_1 = require("./config");
 const sso_1 = require("./sso");
 const logger_1 = require("../lib/logger");
-const user_1 = require("../services/user");
+const capabilities_1 = require("./capabilities");
 const sso_provision_1 = require("../services/user/sso-provision");
 const bot_api_key_1 = require("../services/auth/bot-api-key");
 const principal_1 = require("../services/iam/principal");
@@ -192,6 +159,16 @@ const requireAuth = async (req, res, next) => {
     mw(req, res, next);
 };
 exports.requireAuth = requireAuth;
+/**
+ * `requireAuth` without the SSO fallback: only a credential the request
+ * carries itself (the configured adapter, else a Bearer JWT or bot key).
+ * For endpoints a cross-site page must not reach through the host's cookie.
+ */
+const requireCredentialAuth = (req, res, next) => {
+    const mw = _authMiddleware || createAuthMiddleware(new JwtAuthAdapter());
+    return mw(req, res, next);
+};
+exports.requireCredentialAuth = requireCredentialAuth;
 /**
  * Replace the auth adapter used by `requireAuth`.
  * Call before starting the server.
@@ -199,107 +176,47 @@ exports.requireAuth = requireAuth;
 function setAuthAdapter(adapter) {
     _authMiddleware = createAuthMiddleware(adapter);
 }
-/**
- * Middleware that requires admin access. Must be placed AFTER requireAuth.
- *
- * Checks isSuperAdmin() via the database first, then falls back to the
- * JWT `role` claim for stateless admin checks. Returns 403 otherwise.
- */
-const requireAdmin = async (req, res, next) => {
-    try {
-        if (!req.auth?.userId) {
-            res.status(403).json({ error: 'Forbidden' });
-            return;
-        }
-        // Fast path: trust the JWT role claim for admin/superadmin
-        if (req.auth.role === 'admin' || req.auth.role === 'superadmin') {
-            next();
-            return;
-        }
-        // Slow path: check database for superadmin role type
-        if (await (0, user_1.isSuperAdmin)(req.auth.userId)) {
-            next();
-            return;
+/** Express gate over a capability predicate. Must be placed AFTER requireAuth. */
+function requireCapability(check, denial) {
+    return async (req, res, next) => {
+        try {
+            if (!req.auth?.userId) {
+                res.status(403).json({ error: 'Forbidden' });
+                return;
+            }
+            if (await check(req.auth)) {
+                next();
+                return;
+            }
+            res.status(403).json({ error: denial });
         }
-        res.status(403).json({ error: 'Forbidden: admin access required' });
-    }
-    catch {
-        res.status(403).json({ error: 'Forbidden' });
-    }
-};
-exports.requireAdmin = requireAdmin;
-/**
- * Middleware that requires builder access. Must be placed AFTER requireAuth.
- *
- * Builders are superadmin or users with the 'engineer' role.
- * This is the backend equivalent of the dashboard's `isBuilder` check.
- */
-const requireBuilder = async (req, res, next) => {
-    try {
-        if (!req.auth?.userId) {
+        catch {
             res.status(403).json({ error: 'Forbidden' });
-            return;
         }
-        // Fast path: trust the JWT role claim for superadmin
-        if (req.auth.role === 'superadmin') {
-            next();
-            return;
-        }
-        // Check database for superadmin role type
-        if (await (0, user_1.isSuperAdmin)(req.auth.userId)) {
-            next();
-            return;
-        }
-        // Check database for engineer role (builder)
-        const { hasRole } = await Promise.resolve().then(() => __importStar(require('../services/user/roles')));
-        if (await hasRole(req.auth.userId, 'engineer')) {
-            next();
-            return;
-        }
-        res.status(403).json({ error: 'Forbidden: builder access required' });
-    }
-    catch {
-        res.status(403).json({ error: 'Forbidden' });
-    }
-};
-exports.requireBuilder = requireBuilder;
-/**
- * Middleware that requires role-management access. Must be placed AFTER requireAuth.
- *
- * Grants access to superadmins, admin-type users, and engineers — the backend
- * equivalent of the dashboard's `isBuilder || isOps`. Ops (admin type) manage
- * users and roles; builders (superadmin, engineer) are a superset. This is the
- * gate for reading and writing role definitions.
- */
-const requireRoleManager = async (req, res, next) => {
+    };
+}
+/** Admin access: admin or superadmin claim, or a superadmin in the database. */
+exports.requireAdmin = requireCapability(capabilities_1.mayAdminister, 'Forbidden: admin access required');
+/** Builder access: superadmin or the 'engineer' role. Backend twin of the dashboard's `isBuilder`. */
+exports.requireBuilder = requireCapability(capabilities_1.mayBuild, 'Forbidden: builder access required');
+/** Role-management access: admin access or the 'engineer' role. Backend twin of `isBuilder || isOps`. */
+exports.requireRoleManager = requireCapability(capabilities_1.mayManageRoles, 'Forbidden: role-management access required');
+/** Reads of one workflow run (`:workflowId`): builder access, or the person who started it or it runs as. */
+const requireWorkflowReader = async (req, res, next) => {
     try {
-        if (!req.auth?.userId) {
-            res.status(403).json({ error: 'Forbidden' });
-            return;
-        }
-        // Fast path: trust the JWT role claim for admin/superadmin
-        if (req.auth.role === 'admin' || req.auth.role === 'superadmin') {
-            next();
-            return;
-        }
-        // Slow path: check database for superadmin role type
-        if (await (0, user_1.isSuperAdmin)(req.auth.userId)) {
-            next();
-            return;
-        }
-        // Check database for engineer role (builder)
-        const { hasRole } = await Promise.resolve().then(() => __importStar(require('../services/user/roles')));
-        if (await hasRole(req.auth.userId, 'engineer')) {
+        if (req.auth?.userId && await (0, capabilities_1.mayReadWorkflowRun)(req.auth, String(req.params.workflowId))) {
             next();
             return;
         }
-        res.status(403).json({ error: 'Forbidden: role-management access required' });
+        res.status(403).json({ error: 'Forbidden: workflow read access required' });
     }
-    catch {
-        res.status(403).json({ error: 'Forbidden' });
+    catch (err) {
+        // A failed lookup is not an access decision: report it, and serve nothing.
+        logger_1.loggerRegistry.error(`[long-tail] workflow read check failed: ${err?.message}`);
+        res.status(500).json({ error: 'Workflow read check failed' });
     }
 };
-exports.requireRoleManager = requireRoleManager;
+exports.requireWorkflowReader = requireWorkflowReader;
 /**
  * Generate a JWT token. Utility for tests and token provisioning.
  */

package/build/modules/capabilities.d.ts

@@ -0,0 +1,62 @@
+import type { AuthPayload, CapabilityAccess, CapabilitySet, LTGrantRole } from '../types';
+/**
+ * Capability predicates shared by every entry point that faces people.
+ *
+ * Each predicate trusts the principal's `role` claim first and only then
+ * consults the database. Lookup errors propagate so callers can deny.
+ */
+export type CapabilityPrincipal = Pick<AuthPayload, 'userId' | 'role'> & {
+    /** Present for OAuth callers: the memberships the access token carries. */
+    grantRoles?: LTGrantRole[];
+};
+export interface RoleGrant {
+    role: string;
+    type?: string;
+}
+export type GrantDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    error: string;
+};
+/** Admin or superadmin claim, or a superadmin in the database. */
+export declare function mayAdminister(principal: CapabilityPrincipal | undefined): Promise<boolean>;
+/** Superadmin (claim or database), or holder of the engineer role. */
+export declare function mayBuild(principal: CapabilityPrincipal | undefined): Promise<boolean>;
+/**
+ * Builder access, or the person a workflow run was started by or runs as,
+ * read from the run's own start envelope.
+ */
+export declare function mayReadWorkflowRun(principal: CapabilityPrincipal | undefined, workflowId: string): Promise<boolean>;
+/** Anyone who may administer, plus holders of the engineer role. */
+export declare function mayManageRoles(principal: CapabilityPrincipal | undefined): Promise<boolean>;
+/**
+ * Whether `granterId` may assign `grant` to a user.
+ *
+ * - superadmin: any role and type
+ * - engineer: any role, never the superadmin type
+ * - anyone else: only roles they hold, never the superadmin type
+ */
+export declare function mayGrantRole(granterId: string, grant: RoleGrant): Promise<GrantDecision>;
+/** Whether `granterId` may assign every grant in a new account's role list. */
+export declare function mayGrantRoles(granterId: string, grants: RoleGrant[] | undefined): Promise<GrantDecision>;
+/**
+ * Whether `callerId` may change, remove, or mint keys for an account. An
+ * account holding superadmin is a superadmin's to manage; any other account
+ * is left to the route's own gate.
+ */
+export declare function mayManageAccount(callerId: string, targetId: string): Promise<GrantDecision>;
+/** Removing a role follows the grant rule for the role as the account holds it. */
+export declare function mayRevokeRole(callerId: string, targetId: string, role: string): Promise<GrantDecision>;
+/**
+ * Every capability the principal holds, with the same outcomes as the
+ * predicates above. A superadmin claim costs no lookup; anyone else costs
+ * at most one superadmin lookup and one engineer-role lookup.
+ */
+export declare function resolveCapabilities(principal: CapabilityPrincipal | undefined): Promise<CapabilitySet>;
+/**
+ * Capability checks for one request. `caller` needs only an authenticated
+ * principal; any other gate resolves the principal's capabilities once, on
+ * first need, so a request that checks only `caller` gates makes no lookup.
+ */
+export declare function capabilityAccess(principal: CapabilityPrincipal | undefined): CapabilityAccess;