@hotmeshio/long-tail 0.23.1 → 0.24.0

package/build/routes/yaml-workflows/crud.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-const express_1 = require("express");
+const http_1 = require("../../lib/http");
 const api = __importStar(require("../../api/yaml-workflows"));
-const router = (0, express_1.Router)();
+const auth_1 = require("../../modules/auth");
+const router = (0, http_1.Router)();
 /**
  * GET /api/yaml-workflows
  * List YAML workflows with optional status filter.
@@ -58,7 +59,7 @@ router.get('/', async (req, res) => {
  * Generate a YAML workflow from a completed execution.
  * Body: { workflow_id, task_queue, workflow_name, name, description? }
  */
-router.post('/', async (req, res) => {
+router.post('/', auth_1.requireBuilder, async (req, res) => {
     const result = await api.createYamlWorkflow(req.body);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -76,7 +77,7 @@ router.get('/app-ids', async (_req, res) => {
  * Unlike POST /, this does not require a source execution — the YAML is provided directly.
  * Body: { name, description?, yaml_content, input_schema?, activity_manifest?, tags?, app_id? }
  */
-router.post('/direct', async (req, res) => {
+router.post('/direct', auth_1.requireBuilder, async (req, res) => {
     const result = await api.createYamlWorkflowDirect(req.body);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -85,7 +86,7 @@ router.post('/direct', async (req, res) => {
  * Compile a durable TypeScript workflow into a YAML DAG.
  * Body: { source, is_file_path?, workflow_name, name, description?, app_id?, subscribes?, tags? }
  */
-router.post('/from-durable', async (req, res) => {
+router.post('/from-durable', auth_1.requireBuilder, async (req, res) => {
     const result = await api.createYamlWorkflowFromDurable(req.body);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -95,15 +96,15 @@ router.post('/from-durable', async (req, res) => {
  * Get a single YAML workflow.
  */
 router.get('/:id', async (req, res) => {
-    const result = await api.getYamlWorkflow({ id: req.params.id });
+    const result = await api.getYamlWorkflow({ id: String(req.params.id) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
  * PUT /api/yaml-workflows/:id
  * Update a YAML workflow's metadata.
  */
-router.put('/:id', async (req, res) => {
-    const result = await api.updateYamlWorkflow({ id: req.params.id, ...req.body });
+router.put('/:id', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.updateYamlWorkflow({ ...req.body, id: String(req.params.id) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
@@ -111,9 +112,9 @@ router.put('/:id', async (req, res) => {
  * Re-generate the YAML from the original source execution.
  * Only allowed for non-archived workflows.
  */
-router.post('/:id/regenerate', async (req, res) => {
+router.post('/:id/regenerate', auth_1.requireBuilder, async (req, res) => {
     const result = await api.regenerateYamlWorkflow({
-        id: req.params.id,
+        id: String(req.params.id),
         task_queue: req.body.task_queue,
         compilation_feedback: req.body.compilation_feedback,
     });
@@ -123,8 +124,8 @@ router.post('/:id/regenerate', async (req, res) => {
  * DELETE /api/yaml-workflows/:id
  * Delete a YAML workflow (must be draft or archived).
  */
-router.delete('/:id', async (req, res) => {
-    const result = await api.deleteYamlWorkflow({ id: req.params.id });
+router.delete('/:id', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.deleteYamlWorkflow({ id: String(req.params.id) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 exports.default = router;

package/build/routes/yaml-workflows/deployment.js

@@ -33,24 +33,25 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-const express_1 = require("express");
+const http_1 = require("../../lib/http");
 const api = __importStar(require("../../api/yaml-workflows"));
-const router = (0, express_1.Router)();
+const auth_1 = require("../../modules/auth");
+const router = (0, http_1.Router)();
 /**
  * POST /api/yaml-workflows/:id/deploy
  * Deploy all YAML workflows sharing this workflow's app_id as a merged version.
  * Bumps the version and deploys all graphs together.
  */
-router.post('/:id/deploy', async (req, res) => {
-    const result = await api.deployYamlWorkflow({ id: req.params.id });
+router.post('/:id/deploy', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.deployYamlWorkflow({ id: String(req.params.id) }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
  * POST /api/yaml-workflows/:id/activate
  * Activate the deployed version for this workflow's app_id and register all workers.
  */
-router.post('/:id/activate', async (req, res) => {
-    const result = await api.activateYamlWorkflow({ id: req.params.id });
+router.post('/:id/activate', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.activateYamlWorkflow({ id: String(req.params.id) }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
@@ -72,16 +73,16 @@ router.post('/:id/invoke', async (req, res) => {
  * POST /api/yaml-workflows/:id/archive
  * Archive a YAML workflow (stops accepting new invocations).
  */
-router.post('/:id/archive', async (req, res) => {
-    const result = await api.archiveYamlWorkflow({ id: req.params.id });
+router.post('/:id/archive', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.archiveYamlWorkflow({ id: String(req.params.id) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
  * POST /api/yaml-workflows/:id/restore
  * Restore an archived YAML workflow back to draft status for redeployment.
  */
-router.post('/:id/restore', async (req, res) => {
-    const result = await api.restoreYamlWorkflow({ id: req.params.id });
+router.post('/:id/restore', auth_1.requireBuilder, async (req, res) => {
+    const result = await api.restoreYamlWorkflow({ id: String(req.params.id) });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 exports.default = router;

package/build/routes/yaml-workflows/index.js

@@ -3,12 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const express_1 = require("express");
+const http_1 = require("../../lib/http");
 const cron_1 = __importDefault(require("./cron"));
 const crud_1 = __importDefault(require("./crud"));
 const deployment_1 = __importDefault(require("./deployment"));
 const versions_1 = __importDefault(require("./versions"));
-const router = (0, express_1.Router)();
+const router = (0, http_1.Router)();
 // cron.ts handles: GET /cron/status, PUT /:id/cron, DELETE /:id/cron
 // Mount before crud so /cron/status doesn't match /:id
 router.use(cron_1.default);

package/build/routes/yaml-workflows/versions.js

@@ -33,9 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-const express_1 = require("express");
+const http_1 = require("../../lib/http");
 const api = __importStar(require("../../api/yaml-workflows"));
-const router = (0, express_1.Router)();
+const router = (0, http_1.Router)();
 /**
  * GET /api/yaml-workflows/:id/versions
  * Return version history for a YAML workflow.

package/build/scripts/consolidation-sim.d.ts

@@ -0,0 +1,25 @@
+/**
+ * consolidation-sim: drive the consolidation example over HTTP so the
+ * Consolidate list shows a floor in motion.
+ *
+ * Opens a tub per destination (the first tub split into a standard and an
+ * express lane), starts orders with a mix of service levels, then walks
+ * them through the stations (prep, check) and places each in its
+ * destination's bin. With KEEP=1 it stops partway, leaving orders at every
+ * station and some bins partly filled, so the list's Holds and Coming
+ * columns and each row's expansion have something to show.
+ *
+ * Usage:
+ *   npm run consolidation:sim
+ *   DESTINATIONS=3 ORDERS=12 EXPRESS_PCT=30 KEEP=1 npm run consolidation:sim
+ *
+ * Env vars:
+ *   BASE_URL       long-tail API (default http://localhost:3000)
+ *   DESTINATIONS   destinations, one tub each (default 2)
+ *   ORDERS         orders to start (default 8)
+ *   EXPRESS_PCT    percent of orders on the express service (default 25)
+ *   STEP_MS        pause between floor moves (default 600)
+ *   KEEP           1 = stop partway and leave the floor mid-flight (default 0)
+ *   LT_USERNAME / LT_PASSWORD   the dev login (defaults: the seeded admin)
+ */
+export {};

package/build/scripts/consolidation-sim.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * consolidation-sim: drive the consolidation example over HTTP so the
+ * Consolidate list shows a floor in motion.
+ *
+ * Opens a tub per destination (the first tub split into a standard and an
+ * express lane), starts orders with a mix of service levels, then walks
+ * them through the stations (prep, check) and places each in its
+ * destination's bin. With KEEP=1 it stops partway, leaving orders at every
+ * station and some bins partly filled, so the list's Holds and Coming
+ * columns and each row's expansion have something to show.
+ *
+ * Usage:
+ *   npm run consolidation:sim
+ *   DESTINATIONS=3 ORDERS=12 EXPRESS_PCT=30 KEEP=1 npm run consolidation:sim
+ *
+ * Env vars:
+ *   BASE_URL       long-tail API (default http://localhost:3000)
+ *   DESTINATIONS   destinations, one tub each (default 2)
+ *   ORDERS         orders to start (default 8)
+ *   EXPRESS_PCT    percent of orders on the express service (default 25)
+ *   STEP_MS        pause between floor moves (default 600)
+ *   KEEP           1 = stop partway and leave the floor mid-flight (default 0)
+ *   LT_USERNAME / LT_PASSWORD   the dev login (defaults: the seeded admin)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const DESTINATIONS = Number(process.env.DESTINATIONS || 2);
+const ORDERS = Number(process.env.ORDERS || 8);
+const EXPRESS_PCT = Number(process.env.EXPRESS_PCT || 25);
+const STEP_MS = Number(process.env.STEP_MS || 600);
+const KEEP = process.env.KEEP === '1';
+const USERNAME = process.env.LT_USERNAME || 'superadmin';
+const PASSWORD = process.env.LT_PASSWORD || 'l0ngt@1l';
+const ROLES = { PREP: 'order-prep', CHECK: 'order-check', STAGE: 'order-stage', BIN: 'consolidate' };
+const RUN = Date.now().toString(36).slice(-4).toUpperCase();
+const DESTINATION_NAMES = ['north', 'south', 'east', 'west', 'central', 'harbor'];
+let token = '';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!res.ok)
+        throw new Error(`${method} ${path} → ${res.status}: ${data.error ?? text}`);
+    return data;
+}
+/** The pending row for one order at one role, polled until the workflow parks it. */
+async function rowFor(role, facets) {
+    const q = new URLSearchParams({ role, status: 'pending', limit: '1', facets: JSON.stringify(facets) });
+    for (let i = 0; i < 100; i++) {
+        const { escalations } = await api('GET', `/api/escalations?${q}`);
+        if (escalations[0])
+            return escalations[0];
+        await sleep(200);
+    }
+    throw new Error(`no pending ${role} row for ${JSON.stringify(facets)}`);
+}
+async function openBins(destinations) {
+    const bins = [];
+    for (const [i, destination] of destinations.entries()) {
+        const binKey = `T${i + 1}-${RUN}`;
+        const lanes = i === 0 ? ['standard', 'express'] : [undefined];
+        for (const lane of lanes) {
+            await api('POST', '/api/workflows/consolidationBin/invoke', { data: { binKey, destination, lane, max: 20, timeout: '8h' } });
+            const row = await rowFor(ROLES.BIN, { binKey, ...(lane ? { lane } : {}) });
+            bins.push({ id: row.id, destination, lane });
+            console.log(`[bin] ${binKey}${lane ? ` (${lane})` : ''} → ${destination}`);
+        }
+    }
+    return bins;
+}
+async function startOrders(destinations) {
+    const orders = [];
+    for (let i = 0; i < ORDERS; i++) {
+        const order = {
+            orderId: `O${RUN}-${String(i + 1).padStart(2, '0')}`,
+            destination: destinations[i % destinations.length],
+            serviceLevel: Math.random() * 100 < EXPRESS_PCT ? 'express' : 'standard',
+        };
+        await api('POST', '/api/workflows/consolidationOrder/invoke', { data: order });
+        orders.push(order);
+        console.log(`[order] ${order.orderId} → ${order.destination} (${order.serviceLevel})`);
+    }
+    return orders;
+}
+async function finish(role, order) {
+    const row = await rowFor(role, { orderId: order.orderId });
+    await api('POST', `/api/escalations/${row.id}/resolve`, { resolverPayload: { ok: true } });
+    console.log(`[${role}] ${order.orderId} done`);
+    await sleep(STEP_MS);
+}
+async function place(order, bins) {
+    const bin = bins.find((b) => b.destination === order.destination && (!b.lane || b.lane === order.serviceLevel));
+    const member = await rowFor(ROLES.STAGE, { orderId: order.orderId });
+    await api('POST', `/api/escalations/${bin.id}/accumulate`, {
+        itemKey: order.orderId, payload: { weight: 1 }, reciprocal: { id: member.id },
+    });
+    console.log(`[place] ${order.orderId} → ${bin.destination}${bin.lane ? ` (${bin.lane})` : ''}`);
+    await sleep(STEP_MS);
+}
+async function main() {
+    const auth = await api('POST', '/api/auth/login', { username: USERNAME, password: PASSWORD });
+    token = auth.token;
+    const destinations = DESTINATION_NAMES.slice(0, Math.max(1, Math.min(DESTINATIONS, DESTINATION_NAMES.length)))
+        .map((d) => `${d}-${RUN}`);
+    // 1. Open the tubs, then start the orders at the first station.
+    const bins = await openBins(destinations);
+    const orders = await startOrders(destinations);
+    // 2. Walk the orders. Mid-flight (KEEP=1): a quarter stays at prep, a
+    //    quarter at check, a quarter staged, the rest placed.
+    const quarter = Math.ceil(orders.length / 4);
+    for (const [i, order] of orders.entries()) {
+        if (KEEP && i < quarter)
+            continue;
+        await finish(ROLES.PREP, order);
+        if (KEEP && i < quarter * 2)
+            continue;
+        await finish(ROLES.CHECK, order);
+        if (KEEP && i < quarter * 3)
+            continue;
+        await place(order, bins);
+    }
+    // 3. A mis-placed order comes back out: the bin's count drops by one.
+    const placed = KEEP ? orders.slice(quarter * 3) : orders;
+    const last = placed[placed.length - 1];
+    if (last) {
+        const bin = bins.find((b) => b.destination === last.destination && (!b.lane || b.lane === last.serviceLevel));
+        await api('POST', `/api/escalations/${bin.id}/remove-item`, { itemKey: last.orderId });
+        console.log(`[remove] ${last.orderId} out of ${bin.destination}`);
+    }
+    console.log(`\nDone (run ${RUN}). Open the Consolidate list: ${BASE_URL}/escalations/available?role=${ROLES.BIN}`);
+}
+main().catch((err) => {
+    console.error(`[consolidation-sim] ${err.message}`);
+    process.exit(1);
+});

package/build/sdk/index.d.ts

@@ -291,6 +291,18 @@ export declare function createClient(options?: LTClientOptions): {
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         aggregateByFacets: (input: import("..").AggregateByFacetsInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         timelineByFacet: (input: import("..").TimelineByFacetInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getRelated: (input: {
+            role: string;
+            ids: string[];
+            version?: number;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getRelatedRows: (input: {
+            role: string;
+            id: string;
+            set: string;
+            version?: number;
+            limit?: number;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
     };
     workflows: {
         invoke: (input: {

package/build/sdk/index.js

@@ -162,6 +162,8 @@ function createClient(options = {}) {
             // Analytics surface (grouped membership/dwell + per-entity timeline), read_all-gated.
             aggregateByFacets: bindAuth(escalationsApi.aggregateByFacets, auth),
             timelineByFacet: bindAuth(escalationsApi.timelineByFacet, auth),
+            getRelated: bindAuth(escalationsApi.getRelatedAggregates, auth),
+            getRelatedRows: bindAuth(escalationsApi.getRelatedRows, auth),
         },
         // ── Workflows ──────────────────────────────────────────────────────────
         workflows: {

package/build/services/agent/authority.d.ts

@@ -0,0 +1,14 @@
+import type { AgentBehaviors } from '../../types/agent';
+/** Refuse an agent create or update whose schedules the caller could not run themselves. */
+export declare function assertMayConfigureAgent(callerId: string, input: {
+    id?: string;
+    user_id?: string | null;
+    behaviors?: AgentBehaviors;
+}): Promise<void>;
+/** Refuse a subscription create or update the caller could not run themselves. */
+export declare function assertMayConfigureSubscription(callerId: string, input: {
+    agentId: string;
+    subscriptionId?: string;
+    reaction_type?: string;
+    execute_as?: string | null;
+}): Promise<void>;

package/build/services/agent/authority.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMayConfigureAgent = assertMayConfigureAgent;
+exports.assertMayConfigureSubscription = assertMayConfigureSubscription;
+/**
+ * Who may configure automation. Agents run on their own, as the identity they
+ * name (an execute_as, else the agent's user_id) or, with none, as lt-system.
+ * Whoever configures one must be able to run as that identity: the same rule
+ * as an execute_as override. Automation that would run as lt-system, or a
+ * capability subscription (a tool called with lt-system authority), is a
+ * superadmin's to configure.
+ */
+const workflow_invocation_1 = require("../workflow-invocation");
+const user_1 = require("../user");
+const index_1 = require("./index");
+const subscriptions_1 = require("./subscriptions");
+const SYSTEM_AUTHORITY = 'runs as lt-system; only superadmin can configure it';
+async function assertIdentity(callerId, identity, what) {
+    if (!identity)
+        throw new workflow_invocation_1.InvocationError(`${what} has no identity, so it ${SYSTEM_AUTHORITY}`, 403);
+    await (0, workflow_invocation_1.assertMayActAs)(callerId, identity);
+}
+/** Refuse an agent create or update whose schedules the caller could not run themselves. */
+async function assertMayConfigureAgent(callerId, input) {
+    if (await (0, user_1.isSuperAdmin)(callerId))
+        return;
+    const existing = input.id ? await (0, index_1.getAgent)(input.id) : null;
+    const userId = input.user_id !== undefined ? input.user_id : existing?.user_id ?? null;
+    const behaviors = input.behaviors ?? existing?.behaviors;
+    if (userId)
+        await (0, workflow_invocation_1.assertMayActAs)(callerId, userId);
+    if (behaviors?.cron)
+        await assertIdentity(callerId, userId, 'the agent schedule');
+    for (const schedule of behaviors?.schedules ?? []) {
+        await assertIdentity(callerId, schedule.execute_as || userId, 'an agent schedule');
+    }
+}
+/** Refuse a subscription create or update the caller could not run themselves. */
+async function assertMayConfigureSubscription(callerId, input) {
+    if (await (0, user_1.isSuperAdmin)(callerId))
+        return;
+    const existing = input.subscriptionId ? await (0, subscriptions_1.getSubscription)(input.subscriptionId) : null;
+    if (input.subscriptionId && (!existing || existing.agent_id !== input.agentId)) {
+        throw new workflow_invocation_1.InvocationError('Subscription not found', 404);
+    }
+    const reaction = input.reaction_type ?? existing?.reaction_type;
+    if (reaction === 'capability') {
+        throw new workflow_invocation_1.InvocationError(`a capability subscription calls a tool directly, so it ${SYSTEM_AUTHORITY}`, 403);
+    }
+    const agent = await (0, index_1.getAgent)(input.agentId);
+    const executeAs = input.execute_as !== undefined ? input.execute_as : existing?.execute_as;
+    await assertIdentity(callerId, executeAs || agent?.user_id, 'the subscription');
+}

package/build/services/auth/bot-api-key.d.ts

@@ -29,4 +29,6 @@ export declare function revokeBotApiKey(id: string): Promise<boolean>;
 /**
  * List API keys for a bot account (without hashes).
  */
+/** The bot account a key belongs to, or null when there is no such key. */
+export declare function getBotApiKeyOwner(keyId: string): Promise<string | null>;
 export declare function listBotApiKeys(userId: string): Promise<BotApiKeyRecord[]>;

package/build/services/auth/bot-api-key.js

@@ -39,8 +39,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateBotApiKey = generateBotApiKey;
 exports.validateBotApiKey = validateBotApiKey;
 exports.revokeBotApiKey = revokeBotApiKey;
+exports.getBotApiKeyOwner = getBotApiKeyOwner;
 exports.listBotApiKeys = listBotApiKeys;
 const crypto = __importStar(require("crypto"));
+const uuid_1 = require("../../lib/uuid");
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
@@ -87,6 +89,14 @@ async function revokeBotApiKey(id) {
 /**
  * List API keys for a bot account (without hashes).
  */
+/** The bot account a key belongs to, or null when there is no such key. */
+async function getBotApiKeyOwner(keyId) {
+    if (!(0, uuid_1.isUuid)(keyId))
+        return null;
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_BOT_KEY_OWNER, [keyId]);
+    return rows[0]?.user_id ?? null;
+}
 async function listBotApiKeys(userId) {
     const pool = await (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.LIST_BOT_KEYS_BY_USER, [userId]);

package/build/services/auth/oauth-server/access-token.d.ts

@@ -0,0 +1,36 @@
+import type { AuthPayload, LTGrantPolicy, LTGrantRole, LTGrantSnapshot } from '../../../types';
+/**
+ * Access tokens are HS256 JWTs for one resource (`aud`, the `/mcp` URL). They
+ * name the grant (`gid`) and the person (`sub`) and carry no `userId` claim,
+ * so `requireAuth` refuses them on `/api`. A verified token is honored only
+ * while its grant is live: `/mcp` reads the grant on each request and acts on
+ * its current roles, policy and scope.
+ */
+export interface AccessTokenTarget {
+    issuer: string;
+    audience: string;
+}
+export interface LTAccessTokenClaims {
+    iss: string;
+    aud: string;
+    sub: string;
+    client_id: string;
+    gid: string;
+    scope: string;
+    policy: LTGrantPolicy;
+    roles: LTGrantRole[];
+    iat: number;
+    exp: number;
+}
+export declare function signAccessToken(snapshot: LTGrantSnapshot, target: AccessTokenTarget, ttlSeconds?: number): {
+    token: string;
+    expiresIn: number;
+};
+/** The claims of a valid access token for `target`; null for anything else. */
+export declare function verifyAccessToken(token: string, target: AccessTokenTarget): LTAccessTokenClaims | null;
+/**
+ * The request identity for a verified access token and its live grant, in the
+ * shape other credentials produce. Roles, policy and scope come from the grant
+ * as it stands now, not as the token recorded them.
+ */
+export declare function accessTokenPrincipal(claims: LTAccessTokenClaims, live: LTGrantSnapshot): AuthPayload;

package/build/services/auth/oauth-server/access-token.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signAccessToken = signAccessToken;
+exports.verifyAccessToken = verifyAccessToken;
+exports.accessTokenPrincipal = accessTokenPrincipal;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const config_1 = require("../../../modules/config");
+const defaults_1 = require("../../../modules/defaults");
+const constants_1 = require("./constants");
+function signAccessToken(snapshot, target, ttlSeconds = defaults_1.OAUTH_ACCESS_TOKEN_TTL_SECONDS) {
+    if (!config_1.config.JWT_SECRET)
+        throw new Error('signAccessToken: JWT_SECRET is not configured');
+    const token = jsonwebtoken_1.default.sign({
+        client_id: snapshot.client_id,
+        gid: snapshot.grant_id,
+        scope: snapshot.scope,
+        policy: snapshot.policy,
+        roles: snapshot.roles,
+    }, config_1.config.JWT_SECRET, {
+        algorithm: 'HS256',
+        header: { alg: 'HS256', typ: constants_1.ACCESS_TOKEN_TYPE },
+        issuer: target.issuer,
+        audience: target.audience,
+        subject: snapshot.user_id,
+        expiresIn: ttlSeconds,
+    });
+    return { token, expiresIn: ttlSeconds };
+}
+/** The claims of a valid access token for `target`; null for anything else. */
+function verifyAccessToken(token, target) {
+    if (!config_1.config.JWT_SECRET)
+        return null;
+    try {
+        const decoded = jsonwebtoken_1.default.verify(token, config_1.config.JWT_SECRET, {
+            algorithms: ['HS256'],
+            issuer: target.issuer,
+            audience: target.audience,
+            complete: true,
+        });
+        if (decoded.header.typ !== constants_1.ACCESS_TOKEN_TYPE)
+            return null;
+        const claims = decoded.payload;
+        if (typeof claims.exp !== 'number')
+            return null;
+        if (!claims.sub || !claims.gid || !claims.client_id || !Array.isArray(claims.roles))
+            return null;
+        return claims;
+    }
+    catch {
+        return null;
+    }
+}
+function highestRoleType(roles) {
+    if (roles.some((r) => r.type === 'superadmin'))
+        return 'superadmin';
+    if (roles.some((r) => r.type === 'admin'))
+        return 'admin';
+    return 'member';
+}
+/**
+ * The request identity for a verified access token and its live grant, in the
+ * shape other credentials produce. Roles, policy and scope come from the grant
+ * as it stands now, not as the token recorded them.
+ */
+function accessTokenPrincipal(claims, live) {
+    return {
+        userId: claims.sub,
+        role: highestRoleType(live.roles),
+        roles: live.roles.map((r) => ({ role: r.role, type: r.type })),
+        scopes: [live.scope],
+        principalType: constants_1.OAUTH_PRINCIPAL_TYPE,
+        clientId: live.client_id,
+        grantId: live.grant_id,
+        policy: live.policy,
+        grantRoles: live.roles,
+    };
+}

package/build/services/auth/oauth-server/authorization.d.ts

@@ -0,0 +1,47 @@
+import type { OAuthServerSettings } from '../../../modules/oauth-server';
+import type { LTGrantPreset, LTOAuthClient } from '../../../types/oauth-server';
+/**
+ * Validation of an authorization request (RFC 6749 §4.1.1 with PKCE, RFC 7636,
+ * and resource indicators, RFC 8707). Used by the authorize redirect and again
+ * when the person approves, so the consent page is never trusted.
+ */
+export interface AuthorizationRequest {
+    client: LTOAuthClient;
+    redirectUri: string;
+    codeChallenge: string;
+    state?: string;
+    scope?: string;
+    resource: string;
+}
+export type AuthorizationCheck = {
+    ok: true;
+    request: AuthorizationRequest;
+}
+/** The client or redirect URI can't be trusted: answer here, never redirect. */
+ | {
+    ok: false;
+    redirect: false;
+    error: string;
+    description: string;
+}
+/** The client and redirect URI are known: report the error to the client. */
+ | {
+    ok: false;
+    redirect: true;
+    redirectUri: string;
+    state?: string;
+    error: string;
+    description: string;
+};
+export declare function checkAuthorizationRequest(params: Record<string, unknown>, settings: OAuthServerSettings): Promise<AuthorizationCheck>;
+export declare function isGrantPreset(value: unknown): value is LTGrantPreset;
+/** `uri` with `params` added to its query, keeping any query it already has. */
+export declare function withQuery(uri: string, params: Record<string, string | undefined>): string;
+/**
+ * The presets the person may grant. Read-only always; Just be me only when it
+ * adds something: a membership that can write, or an admin tier.
+ */
+export declare function grantablePresets(roles: Array<{
+    type: string;
+    write_scope?: string | null;
+}>): LTGrantPreset[];