@hotmeshio/long-tail 0.1.0

package/build/scripts/process-helpers.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Shared helpers for the end-to-end process runner.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setBase = setBase;
+exports.getBase = getBase;
+exports.log = log;
+exports.header = header;
+exports.api = api;
+exports.login = login;
+exports.sleep = sleep;
+exports.poll = poll;
+let _base = 'http://localhost:3000';
+function setBase(url) {
+    _base = url;
+}
+function getBase() {
+    return _base;
+}
+function log(role, msg) {
+    const label = role.padEnd(10);
+    console.log(`  ${label} │ ${msg}`);
+}
+function header(text) {
+    console.log(`\n  ─── ${text} ${'─'.repeat(Math.max(0, 58 - text.length))}\n`);
+}
+async function api(method, path, token, body) {
+    const res = await fetch(`${_base}/api${path}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json();
+    if (!res.ok) {
+        throw new Error(`${method} ${path} → ${res.status}: ${JSON.stringify(json)}`);
+    }
+    return json;
+}
+async function login(username, password) {
+    const { token } = await api('POST', '/auth/login', '', { username, password });
+    return token;
+}
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function poll(label, fn, timeoutMs = 30_000, intervalMs = 1_000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const result = await fn();
+        if (result)
+            return result;
+        await sleep(intervalMs);
+    }
+    throw new Error(`Timed out waiting for: ${label}`);
+}

package/build/scripts/process.d.ts

@@ -0,0 +1,18 @@
+/**
+ * End-to-end process runner for Long Tail examples.
+ *
+ * Walks Process 3 ("Wrong Language → Durable MCP") through the full
+ * escalation chain and MCP triage cycle:
+ *
+ *   1. Wait for server + seeded escalation
+ *   2. Reviewer claims → escalates to admin
+ *   3. Admin claims → escalates to engineer
+ *   4. Engineer claims → resolves with needsTriage, describes: "Content is in Spanish"
+ *   5. LLM-driven MCP triage diagnoses, translates, re-runs workflow, notifies engineering
+ *   6. Verify: original workflow completed, engineering escalation created
+ *
+ * Usage:
+ *   npx tsx scripts/process.ts
+ *   npx tsx scripts/process.ts --base http://localhost:3000
+ */
+export {};

package/build/scripts/process.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * End-to-end process runner for Long Tail examples.
+ *
+ * Walks Process 3 ("Wrong Language → Durable MCP") through the full
+ * escalation chain and MCP triage cycle:
+ *
+ *   1. Wait for server + seeded escalation
+ *   2. Reviewer claims → escalates to admin
+ *   3. Admin claims → escalates to engineer
+ *   4. Engineer claims → resolves with needsTriage, describes: "Content is in Spanish"
+ *   5. LLM-driven MCP triage diagnoses, translates, re-runs workflow, notifies engineering
+ *   6. Verify: original workflow completed, engineering escalation created
+ *
+ * Usage:
+ *   npx tsx scripts/process.ts
+ *   npx tsx scripts/process.ts --base http://localhost:3000
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const process_helpers_1 = require("./process-helpers");
+if (process.argv.includes('--base')) {
+    (0, process_helpers_1.setBase)(process.argv[process.argv.indexOf('--base') + 1]);
+}
+// ── Main ────────────────────────────────────────────────────────────────────
+async function run() {
+    const BASE = (0, process_helpers_1.getBase)();
+    console.log('\n  Long Tail — Process Runner');
+    console.log('  ═════════════════════════════════════════════════════════════\n');
+    console.log(`  Server: ${BASE}`);
+    // ── 0. Wait for server ──────────────────────────────────────────────────
+    (0, process_helpers_1.header)('Waiting for server');
+    await (0, process_helpers_1.poll)('server ready', async () => {
+        try {
+            const res = await fetch(`${BASE}/health`);
+            return res.ok ? true : null;
+        }
+        catch {
+            return null;
+        }
+    }, 60_000, 2_000);
+    (0, process_helpers_1.log)('system', 'Server is up');
+    // ── 1. Login as all users ───────────────────────────────────────────────
+    (0, process_helpers_1.header)('Authentication');
+    const reviewerToken = await (0, process_helpers_1.login)('reviewer', 'l0ngt@1l');
+    (0, process_helpers_1.log)('reviewer', 'Logged in');
+    const adminToken = await (0, process_helpers_1.login)('admin', 'l0ngt@1l');
+    (0, process_helpers_1.log)('admin', 'Logged in');
+    const engineerToken = await (0, process_helpers_1.login)('engineer', 'l0ngt@1l');
+    (0, process_helpers_1.log)('engineer', 'Logged in');
+    // ── 2. Wait for Process 3 escalation to appear ──────────────────────────
+    (0, process_helpers_1.header)('Process 3 — Wrong Language');
+    (0, process_helpers_1.log)('system', 'Waiting for escalation (wrong_language content) ...');
+    const escalation = await (0, process_helpers_1.poll)('process-3 escalation', async () => {
+        const { escalations } = await (0, process_helpers_1.api)('GET', '/escalations/available?role=reviewer&limit=50', reviewerToken);
+        // Find the one with wrong_language flag in the escalation payload
+        return escalations.find((e) => {
+            if (!e.escalation_payload)
+                return false;
+            try {
+                const payload = typeof e.escalation_payload === 'string'
+                    ? JSON.parse(e.escalation_payload)
+                    : e.escalation_payload;
+                return payload?.analysis?.flags?.includes('wrong_language');
+            }
+            catch {
+                return false;
+            }
+        }) ?? null;
+    }, 30_000);
+    const originId = escalation.origin_id;
+    (0, process_helpers_1.log)('system', `Found escalation ${escalation.id.slice(0, 8)}... (origin: ${originId?.slice(0, 30)}...)`);
+    // ── 3. Reviewer: claim → escalate to admin ──────────────────────────────
+    (0, process_helpers_1.header)('Step 1 — Reviewer');
+    await (0, process_helpers_1.api)('POST', `/escalations/${escalation.id}/claim`, reviewerToken);
+    (0, process_helpers_1.log)('reviewer', 'Claimed escalation');
+    // Read the escalation details
+    const detail = await (0, process_helpers_1.api)('GET', `/escalations/${escalation.id}`, reviewerToken);
+    const payloadData = detail.escalation_payload
+        ? (typeof detail.escalation_payload === 'string' ? JSON.parse(detail.escalation_payload) : detail.escalation_payload)
+        : {};
+    (0, process_helpers_1.log)('reviewer', `Content: "${(payloadData.content || '').slice(0, 50)}..."`);
+    (0, process_helpers_1.log)('reviewer', `Flags: ${payloadData.analysis?.flags?.join(', ') || 'none'}`);
+    (0, process_helpers_1.log)('reviewer', 'This is a language issue — outside my role. Escalating to admin.');
+    await (0, process_helpers_1.api)('PATCH', `/escalations/${escalation.id}/escalate`, reviewerToken, {
+        targetRole: 'admin',
+    });
+    (0, process_helpers_1.log)('reviewer', 'Escalated → admin');
+    // ── 4. Admin: claim → escalate to engineer ──────────────────────────────
+    (0, process_helpers_1.header)('Step 2 — Admin');
+    // Poll for the escalation to appear in admin's queue
+    const adminEsc = await (0, process_helpers_1.poll)('admin escalation', async () => {
+        const { escalations } = await (0, process_helpers_1.api)('GET', '/escalations/available?role=admin&limit=50', adminToken);
+        return escalations.find((e) => e.id === escalation.id) ?? null;
+    });
+    await (0, process_helpers_1.api)('POST', `/escalations/${adminEsc.id}/claim`, adminToken);
+    (0, process_helpers_1.log)('admin', 'Claimed escalation');
+    (0, process_helpers_1.log)('admin', 'Content is in Spanish — needs technical fix. Escalating to engineer.');
+    await (0, process_helpers_1.api)('PATCH', `/escalations/${adminEsc.id}/escalate`, adminToken, {
+        targetRole: 'engineer',
+    });
+    (0, process_helpers_1.log)('admin', 'Escalated → engineer');
+    // ── 5. Engineer: claim → resolve with needsTriage ───────────────────────
+    (0, process_helpers_1.header)('Step 3 — Engineer (MCP Triage)');
+    const engEsc = await (0, process_helpers_1.poll)('engineer escalation', async () => {
+        const { escalations } = await (0, process_helpers_1.api)('GET', '/escalations/available?role=engineer&limit=50', engineerToken);
+        return escalations.find((e) => e.id === escalation.id) ?? null;
+    });
+    await (0, process_helpers_1.api)('POST', `/escalations/${engEsc.id}/claim`, engineerToken);
+    (0, process_helpers_1.log)('engineer', 'Claimed escalation');
+    (0, process_helpers_1.log)('engineer', 'Content is in the wrong language. Requesting AI triage.');
+    const resolveResult = await (0, process_helpers_1.api)('POST', `/escalations/${engEsc.id}/resolve`, engineerToken, {
+        resolverPayload: {
+            approved: false,
+            reason: 'Content is in Spanish — needs translation before review',
+            _lt: {
+                needsTriage: true,
+            },
+            notes: 'Content arrived in Spanish. Needs translation to English before it can be reviewed.',
+        },
+    });
+    (0, process_helpers_1.log)('engineer', `Triage started: ${resolveResult.triage ? 'yes' : 'no'} (workflow: ${resolveResult.workflowId?.slice(0, 20)}...)`);
+    // ── 6. Wait for triage to complete ──────────────────────────────────────
+    (0, process_helpers_1.header)('MCP Triage — Remediation');
+    (0, process_helpers_1.log)('system', 'Waiting for triage workflow to translate and re-run ...');
+    // Poll the process to see new tasks appear (triage + re-run)
+    const processResult = await (0, process_helpers_1.poll)('triage completion', async () => {
+        const detail = await (0, process_helpers_1.api)('GET', `/tasks/processes/${encodeURIComponent(originId)}`, engineerToken);
+        const tasks = detail.tasks || [];
+        // Look for a completed reviewContent re-run (from triage)
+        const triageTask = tasks.find((t) => t.workflow_type === 'mcpTriage' && t.status === 'completed');
+        const rerunTask = tasks.find((t) => t.workflow_type === 'reviewContent' &&
+            t.status === 'completed' &&
+            t.created_at > escalation.created_at);
+        if (triageTask || rerunTask)
+            return detail;
+        return null;
+    }, 45_000, 2_000);
+    const tasks = processResult.tasks || [];
+    const triageTask = tasks.find((t) => t.workflow_type?.includes('mcpTriage'));
+    const rerunTask = tasks.find((t) => t.workflow_type === 'reviewContent' &&
+        t.status === 'completed' &&
+        t.created_at > escalation.created_at);
+    if (triageTask) {
+        (0, process_helpers_1.log)('mcp', `Triage workflow: ${triageTask.status}`);
+    }
+    if (rerunTask) {
+        (0, process_helpers_1.log)('mcp', `Re-run workflow: ${rerunTask.status} (translated content auto-approved)`);
+    }
+    // ── 7. Check for engineering escalation ─────────────────────────────────
+    (0, process_helpers_1.header)('Verification');
+    // Check engineering escalation created by triage
+    const engEscalation = await (0, process_helpers_1.poll)('engineering recommendation', async () => {
+        const { escalations } = await (0, process_helpers_1.api)('GET', '/escalations/available?role=engineer&limit=50', engineerToken);
+        return escalations.find((e) => e.type === 'triage_recommendation' &&
+            e.origin_id === originId) ?? null;
+    }, 30_000, 2_000);
+    if (engEscalation) {
+        (0, process_helpers_1.log)('verify', 'Engineering escalation created by triage');
+        (0, process_helpers_1.log)('verify', `Description: ${engEscalation.description?.slice(0, 80)}...`);
+        // Claim and acknowledge the notification escalation
+        await (0, process_helpers_1.api)('POST', `/escalations/${engEscalation.id}/claim`, engineerToken);
+        await (0, process_helpers_1.api)('POST', `/escalations/${engEscalation.id}/resolve`, engineerToken, {
+            resolverPayload: { acknowledged: true, note: 'Will add language detection to pipeline' },
+        });
+        (0, process_helpers_1.log)('engineer', 'Acknowledged recommendation — will add language detection to pipeline');
+    }
+    // Summary
+    const allTasks = tasks;
+    const escalations = processResult.escalations || [];
+    (0, process_helpers_1.log)('verify', `Process tasks: ${allTasks.length}`);
+    (0, process_helpers_1.log)('verify', `Process escalations: ${escalations.length}`);
+    (0, process_helpers_1.header)('Process Complete');
+    console.log('  The full Durable MCP cycle:');
+    console.log('');
+    console.log('    Content arrived in Spanish');
+    console.log('    → AI flagged (confidence: 0.15, wrong_language)');
+    console.log('    → Escalated to reviewer');
+    console.log('    → Reviewer escalated to admin (language issue)');
+    console.log('    → Admin escalated to engineer (needs technical fix)');
+    console.log('    → Engineer requested AI triage (LLM will diagnose and fix)');
+    console.log('    → MCP orchestrator: translate_content() → re-invoke workflow');
+    console.log('    → Translated content auto-approved');
+    console.log('    → Engineering notified: add language detection to pipeline');
+    console.log('    → Engineer acknowledged recommendation');
+    console.log('');
+    console.log('  ═════════════════════════════════════════════════════════════\n');
+}
+run().catch((err) => {
+    console.error(`\n  ✗ ${err.message}\n`);
+    process.exit(1);
+});

package/build/scripts/token.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate a JWT token for the Long Tail dashboard.
+ *
+ * Usage:
+ *   npx ts-node scripts/token.ts
+ *   npx ts-node scripts/token.ts --userId admin --role superadmin
+ *   npx ts-node scripts/token.ts --userId reviewer1 --roles reviewer,compliance
+ *
+ * Or via npm script:
+ *   npm run token
+ *   npm run token -- --userId admin --role superadmin
+ */
+export {};

package/build/scripts/token.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Generate a JWT token for the Long Tail dashboard.
+ *
+ * Usage:
+ *   npx ts-node scripts/token.ts
+ *   npx ts-node scripts/token.ts --userId admin --role superadmin
+ *   npx ts-node scripts/token.ts --userId reviewer1 --roles reviewer,compliance
+ *
+ * Or via npm script:
+ *   npm run token
+ *   npm run token -- --userId admin --role superadmin
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const args = process.argv.slice(2);
+function getArg(name, fallback) {
+    const idx = args.indexOf(`--${name}`);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+const userId = getArg('userId', 'admin');
+const role = getArg('role', 'superadmin');
+const rolesArg = getArg('roles', '');
+const secret = process.env.JWT_SECRET || 'lt-dev-secret';
+const expiresIn = getArg('expires', '7d');
+// Build roles array for the dashboard auth context
+const roleNames = rolesArg ? rolesArg.split(',') : [role];
+const roles = roleNames.map((r) => ({
+    role: r.trim(),
+    type: r.trim() === 'superadmin' ? 'superadmin' : 'member',
+}));
+const payload = { userId, role, roles };
+const token = jsonwebtoken_1.default.sign(payload, secret, { expiresIn });
+console.log('\n  HotMesh Long Tail — Token Generator\n');
+console.log('  Payload:', JSON.stringify(payload, null, 2));
+console.log('  Expires:', expiresIn);
+console.log('  Secret:', secret === 'lt-dev-secret' ? 'lt-dev-secret (default)' : '***');
+console.log('\n  Token:\n');
+console.log(`  ${token}\n`);

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

@@ -0,0 +1,32 @@
+/** Record returned from bot API key queries (never includes key_hash). */
+export interface BotApiKeyRecord {
+    id: string;
+    name: string;
+    user_id: string;
+    scopes: string[];
+    expires_at: Date | null;
+    last_used_at: Date | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Generate a new API key for a bot account.
+ * Returns the raw key once — it is never stored in plaintext.
+ */
+export declare function generateBotApiKey(name: string, userId: string, scopes?: string[], expiresAt?: Date): Promise<{
+    id: string;
+    rawKey: string;
+}>;
+/**
+ * Validate a raw bot API key.
+ * Returns the key record (with user_id) if valid, null otherwise.
+ */
+export declare function validateBotApiKey(rawKey: string): Promise<BotApiKeyRecord | null>;
+/**
+ * Revoke (delete) a bot API key by ID.
+ */
+export declare function revokeBotApiKey(id: string): Promise<boolean>;
+/**
+ * List API keys for a bot account (without hashes).
+ */
+export declare function listBotApiKeys(userId: string): Promise<BotApiKeyRecord[]>;

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

@@ -0,0 +1,112 @@
+"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.generateBotApiKey = generateBotApiKey;
+exports.validateBotApiKey = validateBotApiKey;
+exports.revokeBotApiKey = revokeBotApiKey;
+exports.listBotApiKeys = listBotApiKeys;
+const crypto = __importStar(require("crypto"));
+const bcryptjs_1 = __importDefault(require("bcryptjs"));
+const db_1 = require("../db");
+const TOKEN_PREFIX = 'lt_bot_';
+const INSERT_KEY = `
+  INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
+  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
+const GET_KEYS_BY_USER = `
+  SELECT id, name, user_id, key_hash, scopes
+  FROM lt_bot_api_keys
+  WHERE user_id = $1
+    AND (expires_at IS NULL OR expires_at > NOW())`;
+const GET_ALL_ACTIVE_KEYS = `
+  SELECT id, name, user_id, key_hash, scopes
+  FROM lt_bot_api_keys
+  WHERE (expires_at IS NULL OR expires_at > NOW())`;
+const UPDATE_LAST_USED = `
+  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
+const DELETE_KEY = `
+  DELETE FROM lt_bot_api_keys WHERE id = $1`;
+const LIST_BY_USER = `
+  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
+  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;
+/**
+ * Generate a new API key for a bot account.
+ * Returns the raw key once — it is never stored in plaintext.
+ */
+async function generateBotApiKey(name, userId, scopes = [], expiresAt) {
+    const rawKey = `${TOKEN_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
+    const keyHash = await bcryptjs_1.default.hash(rawKey, 10);
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(INSERT_KEY, [
+        name, userId, keyHash, scopes, expiresAt || null,
+    ]);
+    return { id: rows[0].id, rawKey };
+}
+/**
+ * Validate a raw bot API key.
+ * Returns the key record (with user_id) if valid, null otherwise.
+ */
+async function validateBotApiKey(rawKey) {
+    if (!rawKey.startsWith(TOKEN_PREFIX))
+        return null;
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(GET_ALL_ACTIVE_KEYS);
+    for (const row of rows) {
+        if (await bcryptjs_1.default.compare(rawKey, row.key_hash)) {
+            await pool.query(UPDATE_LAST_USED, [row.id]);
+            const { key_hash, ...record } = row;
+            return record;
+        }
+    }
+    return null;
+}
+/**
+ * Revoke (delete) a bot API key by ID.
+ */
+async function revokeBotApiKey(id) {
+    const pool = await (0, db_1.getPool)();
+    const result = await pool.query(DELETE_KEY, [id]);
+    return (result.rowCount ?? 0) > 0;
+}
+/**
+ * List API keys for a bot account (without hashes).
+ */
+async function listBotApiKeys(userId) {
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(LIST_BY_USER, [userId]);
+    return rows;
+}

package/build/services/auth/delegation.d.ts

@@ -0,0 +1,20 @@
+import type { DelegationTokenPayload } from '../../types/delegation';
+/**
+ * Create a scoped, short-lived delegation token.
+ *
+ * Delegation tokens authorize MCP tools to act on behalf of a user
+ * with only the specified scopes.
+ */
+export declare function createDelegationToken(userId: string, scopes: string[], ttlSeconds?: number, options?: {
+    workflowId?: string;
+    serverId?: string;
+}): string;
+/**
+ * Validate a delegation token. Returns the decoded payload or throws.
+ */
+export declare function validateDelegationToken(token: string): DelegationTokenPayload;
+/**
+ * Check that a delegation token has the required scope.
+ * Throws if the scope is missing.
+ */
+export declare function requireScope(payload: DelegationTokenPayload, requiredScope: string): void;

package/build/services/auth/delegation.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDelegationToken = createDelegationToken;
+exports.validateDelegationToken = validateDelegationToken;
+exports.requireScope = requireScope;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const config_1 = require("../../modules/config");
+const MAX_TTL_SECONDS = 3600; // 1 hour
+const DEFAULT_TTL_SECONDS = 300; // 5 minutes
+/**
+ * Create a scoped, short-lived delegation token.
+ *
+ * Delegation tokens authorize MCP tools to act on behalf of a user
+ * with only the specified scopes.
+ */
+function createDelegationToken(userId, scopes, ttlSeconds = DEFAULT_TTL_SECONDS, options) {
+    const ttl = Math.min(Math.max(ttlSeconds, 1), MAX_TTL_SECONDS);
+    const payload = {
+        type: 'delegation',
+        sub: userId,
+        scopes,
+        workflowId: options?.workflowId,
+        serverId: options?.serverId,
+    };
+    return jsonwebtoken_1.default.sign(payload, config_1.config.JWT_SECRET, {
+        expiresIn: ttl,
+        issuer: 'long-tail',
+    });
+}
+/**
+ * Validate a delegation token. Returns the decoded payload or throws.
+ */
+function validateDelegationToken(token) {
+    const decoded = jsonwebtoken_1.default.verify(token, config_1.config.JWT_SECRET, {
+        issuer: 'long-tail',
+    });
+    if (decoded.type !== 'delegation') {
+        throw new Error('Token is not a delegation token');
+    }
+    return decoded;
+}
+/**
+ * Check that a delegation token has the required scope.
+ * Throws if the scope is missing.
+ */
+function requireScope(payload, requiredScope) {
+    if (!payload.scopes.includes(requiredScope)) {
+        throw new Error(`Delegation token missing required scope: ${requiredScope}`);
+    }
+}

package/build/services/auth/service-token.d.ts

@@ -0,0 +1,23 @@
+import type { ServiceTokenRecord } from '../../types/delegation';
+/**
+ * Generate a new service token for an external MCP server.
+ * Returns the raw token once — it is never stored in plaintext.
+ */
+export declare function generateServiceToken(name: string, serverId: string | null, scopes: string[], expiresAt?: Date): Promise<{
+    id: string;
+    rawToken: string;
+}>;
+/**
+ * Validate a raw service token. Returns the record if valid, null otherwise.
+ */
+export declare function validateServiceToken(rawToken: string): Promise<(ServiceTokenRecord & {
+    token_hash?: undefined;
+}) | null>;
+/**
+ * Revoke (delete) a service token by ID.
+ */
+export declare function revokeServiceToken(id: string): Promise<boolean>;
+/**
+ * List service tokens for an MCP server (without hashes).
+ */
+export declare function listServiceTokens(serverId: string): Promise<ServiceTokenRecord[]>;