@bevel-software/platform-core-backend 0.1.0

package/dist/modules/skills/skills.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/skills.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAuB9E"}

package/dist/modules/skills/skills.routes.js

@@ -0,0 +1,34 @@
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+/**
+ * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
+ * `authMiddleware`. Backed by the SAME `SkillService` as the agent tool surface,
+ * so discovery, default-branch pinning, and per-user `canRead` filtering live
+ * ONCE — the frontend never re-implements skill discovery or bypasses access.
+ *
+ *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills/:name      → GetSkillResult               (body + files)
+ *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
+ */
+export function createSkillsRoutes(skillService) {
+    const router = express.Router();
+    router.get('/skills', async (req, res) => {
+        const email = req.userEmail;
+        if (!email) {
+            res.status(401).json({ error: 'Unauthenticated' });
+            return;
+        }
+        res.json({ skills: await skillService.listSkills(email) });
+    });
+    router.get('/skills/:name', async (req, res) => {
+        const email = req.userEmail;
+        if (!email) {
+            res.status(401).json({ error: 'Unauthenticated' });
+            return;
+        }
+        const file = typeof req.query.file === 'string' ? req.query.file : undefined;
+        res.json(await skillService.getSkill(email, req.params.name, file));
+    });
+    return router;
+}
+//# sourceMappingURL=skills.routes.js.map

package/dist/modules/skills/skills.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.routes.js","sourceRoot":"","sources":["../../../src/modules/skills/skills.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,4BAA4B,CAAC,CAAC,kDAAkD;AAGvF;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAA2B;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACvC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7E,GAAG,CAAC,IAAI,CAAC,MAAM,YAAY,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modules/skills/skills.service.d.ts

@@ -0,0 +1,21 @@
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import type { ISkillService, GetSkillResult, SkillSummary } from './skills.contract.js';
+/**
+ * Reads skills from the DEFAULT-branch workspace (never the caller's branch), so
+ * the catalog is one global, released set. Results are cached briefly and on a
+ * merge to default the cache should be dropped via `invalidate()`.
+ */
+export declare class SkillService implements ISkillService {
+    private readonly workspaceService;
+    private readonly accessControl;
+    private readonly kbDirName;
+    private readonly cache;
+    constructor(workspaceService: WorkspaceService, accessControl: IAccessControl, kbDirName: string, now?: () => number);
+    invalidate(): void;
+    listSkills(userEmail?: string): Promise<SkillSummary[]>;
+    getSkill(userEmail: string, name: string, file?: string): Promise<GetSkillResult>;
+    private scan;
+    private scanDisk;
+}
+//# sourceMappingURL=skills.service.d.ts.map

package/dist/modules/skills/skills.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.service.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/skills.service.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAI5E,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAEd,YAAY,EACb,MAAM,sBAAsB,CAAC;AAW9B;;;;GAIG;AACH,qBAAa,YAAa,YAAW,aAAa;IAI9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;gBAG7B,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,MAAM,EAClC,GAAG,GAAE,MAAM,MAAiB;IAK9B,UAAU,IAAI,IAAI;IAIZ,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBvD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;YAgCzE,IAAI;YAQJ,QAAQ;CA2EvB"}

package/dist/modules/skills/skills.service.js

@@ -0,0 +1,202 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseDocument } from 'yaml';
+import { DEFAULT_BRANCH, SKILLS_DIR } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
+import { walkFiles } from '../../shared/fs-walk.js';
+import { TtlCache } from '../../shared/ttl-cache.js';
+const CACHE_TTL_MS = 60_000;
+/**
+ * Reads skills from the DEFAULT-branch workspace (never the caller's branch), so
+ * the catalog is one global, released set. Results are cached briefly and on a
+ * merge to default the cache should be dropped via `invalidate()`.
+ */
+export class SkillService {
+    workspaceService;
+    accessControl;
+    kbDirName;
+    cache;
+    constructor(workspaceService, accessControl, kbDirName, now = Date.now) {
+        this.workspaceService = workspaceService;
+        this.accessControl = accessControl;
+        this.kbDirName = kbDirName;
+        this.cache = new TtlCache(CACHE_TTL_MS, now);
+    }
+    invalidate() {
+        this.cache.invalidate();
+    }
+    async listSkills(userEmail) {
+        const skills = await this.scan();
+        const summaries = skills.map((s) => s.summary);
+        if (!userEmail)
+            return summaries;
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        const allowed = await this.accessControl.canReadBatch(wsId, userEmail, summaries.map((s) => `${s.path}/SKILL.md`));
+        // Fail closed: keep a skill only on an explicit `true` verdict — a missing
+        // entry counts as denied, matching the KB's default-deny read model (and the
+        // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
+        // the checker skips a path.
+        return summaries.filter((s) => allowed.get(`${s.path}/SKILL.md`) === true);
+    }
+    async getSkill(userEmail, name, file) {
+        if (!isSafeName(name))
+            return { ok: false, error: 'not_found' };
+        const found = (await this.scan()).find((s) => s.summary.name === name);
+        if (!found)
+            return { ok: false, error: 'not_found' };
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        if (!(await this.accessControl.canRead(wsId, userEmail, `${found.summary.path}/SKILL.md`))) {
+            return { ok: false, error: 'forbidden' };
+        }
+        if (file !== undefined) {
+            if (!isSafeRelFile(file))
+                return { ok: false, error: 'invalid_file' };
+            const repoPath = `${found.summary.path}/${file}`;
+            try {
+                const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
+                return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
+            }
+            catch {
+                return { ok: false, error: 'not_found' };
+            }
+        }
+        const skill = {
+            ...found.summary,
+            body: found.body,
+            allowedTools: found.allowedTools,
+            files: found.files,
+        };
+        return { ok: true, kind: 'skill', skill };
+    }
+    // --- internal ---------------------------------------------------------------
+    async scan() {
+        const cached = this.cache.get();
+        if (cached)
+            return cached;
+        const skills = await this.scanDisk();
+        this.cache.set(skills);
+        return skills;
+    }
+    async scanDisk() {
+        // Ensure the default-branch clone exists, then scan its Skills/ dir. Any
+        // failure (no workspace, no Skills/ dir) degrades to an empty catalog — the
+        // manual/tools must never break because skills can't be read.
+        let wsId;
+        try {
+            wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+        }
+        catch {
+            return [];
+        }
+        const root = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName, SKILLS_DIR);
+        // Skills may be grouped in category subfolders (each carrying its own
+        // access.md), so a SKILL.md can live at any depth under Skills/. Walk the
+        // tree and treat every folder that directly contains a SKILL.md as a skill;
+        // don't descend past it — its inner files are bundled assets, not nested
+        // skills. The skill name is the leaf folder name; its path is the full
+        // Skills-relative folder (e.g. `Skills/Development/coding-guidelines`).
+        const out = [];
+        const walk = async (dir, relFolder) => {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+                let raw;
+                try {
+                    raw = await fs.readFile(path.join(dir, 'SKILL.md'), 'utf-8');
+                }
+                catch {
+                    return;
+                }
+                const fm = parseSkillFrontmatter(raw);
+                // Identity via the shared rule: frontmatter `id` → `name` → folder name.
+                // `getSkill()` refuses unsafe names (path separators, `.`/`..`), so a
+                // declared id that fails the same check would list but never fetch —
+                // fall back to the folder name (a readdir entry, safe by construction)
+                // to keep listing and lookup consistent.
+                const declared = resolveDeclaredId(fm.frontmatter, path.basename(dir));
+                const name = isSafeName(declared) ? declared : path.basename(dir);
+                out.push({
+                    summary: { name, description: fm.description, version: fm.version, path: relFolder },
+                    body: fm.body,
+                    allowedTools: fm.allowedTools,
+                    files: await listBundledFiles(dir, relFolder),
+                });
+                return; // a skill folder is a leaf — its subfolders hold assets, not skills
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith('.'))
+                    continue;
+                await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
+            }
+        };
+        await walk(root, SKILLS_DIR);
+        // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
+        // resolves it, so it must be unique. Sort by (name, path) for a deterministic
+        // winner, then REFUSE later duplicates via the shared dedup — the same rule
+        // tools use (no silent auto-suffix that would rebind an id under the caller).
+        out.sort((a, b) => a.summary.name.localeCompare(b.summary.name) ||
+            a.summary.path.localeCompare(b.summary.path));
+        return dedupeById(out, (s) => s.summary.name, (s, id) => console.warn(`[skills] skipping "${s.summary.path}": id "${id}" is already used by another skill — ` +
+            'give it a unique `id`/`name` in its SKILL.md frontmatter.'));
+    }
+}
+// --- helpers ------------------------------------------------------------------
+/** Skill names are folder names; reject anything that could escape the folder. */
+function isSafeName(name) {
+    return name.length > 0 && !name.includes('/') && !name.includes('\\') && name !== '.' && name !== '..';
+}
+/** A bundled-file path must stay inside the skill folder. */
+function isSafeRelFile(file) {
+    if (!file || file.includes('\\') || path.isAbsolute(file))
+        return false;
+    return file.split('/').every((seg) => seg.length > 0 && seg !== '..');
+}
+function scalarToString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function parseSkillFrontmatter(raw) {
+    const fm = extractFrontmatter(raw);
+    if (!fm)
+        return { description: '', body: raw.trimStart(), frontmatter: {} };
+    const body = fm.body.trimStart();
+    let data = {};
+    try {
+        // Resilient: `toJS` returns the best-effort value even if some entry is
+        // malformed, so one bad field never drops the rest.
+        const parsed = parseDocument(fm.frontmatter).toJS();
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            data = parsed;
+        }
+    }
+    catch {
+        /* keep empty metadata */
+    }
+    const description = typeof data.description === 'string' ? data.description.trim() : '';
+    const metadata = (data.metadata ?? {});
+    const version = scalarToString(data.version) ?? scalarToString(metadata.version);
+    // `allowed-tools` is a space-separated string (agentskills) or a YAML list.
+    const at = data['allowed-tools'];
+    const allowedTools = Array.isArray(at)
+        ? at.map((t) => String(t))
+        : typeof at === 'string'
+            ? at.split(/\s+/).filter(Boolean)
+            : undefined;
+    return { description, version, allowedTools, body, frontmatter: data };
+}
+/** Repo-root-relative paths of every bundled file under a skill folder (excludes SKILL.md). */
+async function listBundledFiles(dir, relFolder) {
+    return (await walkFiles(dir, () => true))
+        .filter((rel) => rel !== 'SKILL.md')
+        .map((rel) => `${relFolder}/${rel}`);
+}
+//# sourceMappingURL=skills.service.js.map

package/dist/modules/skills/skills.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.service.js","sourceRoot":"","sources":["../../../src/modules/skills/skills.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/skills/skills.tools.d.ts

@@ -0,0 +1,15 @@
+import type { Router, RequestHandler } from 'express';
+import type { IToolRegistry } from '../tool-registry/tool.contract.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { ISkillService } from './skills.contract.js';
+/**
+ * Registers the two skill tools (both surfaces) and hosts their endpoints.
+ *
+ * The defs are registered as PROVIDERS (resolved at manual-build time) so each
+ * tool's description can name the currently-available skills — the agent sees
+ * what exists right in the tool catalog, no `list_skills` round-trip needed, and
+ * it auto-updates as the default-branch catalog changes. The hosted routes are
+ * static; only the description text is dynamic.
+ */
+export declare function registerSkillsTools(registry: IToolRegistry, router: Router, toolAuth: RequestHandler, toolHandler: ToolHandlerFactory, skillService: ISkillService): void;
+//# sourceMappingURL=skills.tools.d.ts.map

package/dist/modules/skills/skills.tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.tools.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/skills.tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AAGjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,aAAa,GAC1B,IAAI,CAwBN"}

package/dist/modules/skills/skills.tools.js

@@ -0,0 +1,96 @@
+import { toolDef } from '../tool-helpers/tool-def.js';
+/**
+ * Registers the two skill tools (both surfaces) and hosts their endpoints.
+ *
+ * The defs are registered as PROVIDERS (resolved at manual-build time) so each
+ * tool's description can name the currently-available skills — the agent sees
+ * what exists right in the tool catalog, no `list_skills` round-trip needed, and
+ * it auto-updates as the default-branch catalog changes. The hosted routes are
+ * static; only the description text is dynamic.
+ */
+export function registerSkillsTools(registry, router, toolAuth, toolHandler, skillService) {
+    registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+    registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
+    registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+    registry.registerInternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
+    router.post('/agent/tools/list_skills', toolAuth, toolHandler(async (_args, ctx) => ({
+        skills: await skillService.listSkills(ctx.user.email),
+    })));
+    router.post('/agent/tools/get_skill', toolAuth, toolHandler(async (args, ctx) => {
+        const name = typeof args.name === 'string' ? args.name : '';
+        const file = typeof args.file === 'string' ? args.file : undefined;
+        if (!name)
+            return { error: 'missing_name' };
+        return skillService.getSkill(ctx.user.email, name, file);
+    }));
+}
+/** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
+async function availableSkillsLine(skillService, userEmail) {
+    const skills = await skillService.listSkills(userEmail);
+    if (skills.length === 0)
+        return 'No skills are currently available.';
+    return `Currently available skills: ${skills.map((s) => `\`${s.name}\``).join(', ')}.`;
+}
+async function buildListSkillsDef(skillService, userEmail) {
+    return toolDef({
+        name: 'list_skills',
+        description: 'List the available skills (reusable specialist instructions) with their names and descriptions. ' +
+            'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
+            (await availableSkillsLine(skillService, userEmail)),
+        path: '/api/agent/tools/list_skills',
+        inputs: { type: 'object', properties: {}, additionalProperties: false },
+        outputs: {
+            type: 'object',
+            properties: {
+                skills: {
+                    type: 'array',
+                    description: 'Available skills.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' },
+                            description: { type: 'string' },
+                            version: { type: 'string' },
+                            path: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        },
+        tags: ['skills'],
+    });
+}
+async function buildGetSkillDef(skillService, userEmail) {
+    return toolDef({
+        name: 'get_skill',
+        description: 'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
+            'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
+            '(e.g. a script) instead of the body. ' +
+            (await availableSkillsLine(skillService, userEmail)),
+        path: '/api/agent/tools/get_skill',
+        inputs: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+                file: {
+                    type: 'string',
+                    description: 'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
+                        'fetch its content instead of the body.',
+                },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+        outputs: {
+            type: 'object',
+            description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',
+            properties: {
+                skill: { type: 'object', description: 'The loaded skill: name, description, body, files, ….' },
+                file: { type: 'object', description: 'A bundled file: name, file, path, content.' },
+                error: { type: 'string', description: 'Error code: `not_found`, `forbidden`, `invalid_file`, `missing_name`.' },
+            },
+        },
+        tags: ['skills'],
+    });
+}
+//# sourceMappingURL=skills.tools.js.map

package/dist/modules/skills/skills.tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.tools.js","sourceRoot":"","sources":["../../../src/modules/skills/skills.tools.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-auth/external-api-key.errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Domain errors for the API token service. Distinct classes so callers can
+ * map each to an HTTP status and a user-facing message without string-matching.
+ */
+export declare class InvalidTokenLabelError extends Error {
+    constructor(message: string);
+}
+export declare class TokenNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class TokenStillActiveError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=external-api-key.errors.d.ts.map

package/dist/modules/tool-auth/external-api-key.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-key.errors.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,SAAoB;CAIxC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,SAA2C;CAI/D"}

package/dist/modules/tool-auth/external-api-key.errors.js

@@ -0,0 +1,23 @@
+/**
+ * Domain errors for the API token service. Distinct classes so callers can
+ * map each to an HTTP status and a user-facing message without string-matching.
+ */
+export class InvalidTokenLabelError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidTokenLabelError';
+    }
+}
+export class TokenNotFoundError extends Error {
+    constructor(message = 'Token not found') {
+        super(message);
+        this.name = 'TokenNotFoundError';
+    }
+}
+export class TokenStillActiveError extends Error {
+    constructor(message = 'Disconnect this key before deleting it') {
+        super(message);
+        this.name = 'TokenStillActiveError';
+    }
+}
+//# sourceMappingURL=external-api-key.errors.js.map

package/dist/modules/tool-auth/external-api-key.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-key.errors.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAO,GAAG,iBAAiB;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,GAAG,wCAAwC;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/modules/tool-auth/external-api-key.interface.d.ts

@@ -0,0 +1,90 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * Connection-key id bound by whichever auth middleware resolved a
+             * `<tenant>_…` key (MCP auth, LLM-proxy auth) — consumers use it for
+             * per-key attribution/metering. Declared beside the key contract so
+             * every key-resolving surface shares one augmentation.
+             */
+            externalApiKeyId?: string;
+        }
+    }
+}
+/**
+ * Summary row shown in the user's "Connection keys" settings panel. Never
+ * carries the plaintext — that is returned exactly once from `mint`.
+ */
+export interface ExternalApiKeySummary {
+    id: string;
+    label: string;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+}
+/**
+ * Result of minting a new connection key. `plaintext` is shown to the user
+ * once (with a "you won't see this again" warning); the stored DB row only
+ * carries the hash.
+ */
+export interface MintedExternalApiKey {
+    plaintext: string;
+    summary: ExternalApiKeySummary;
+}
+/**
+ * Contract for connection-key (API token) lifecycle. Used by the MCP auth
+ * middleware to resolve a Bearer token to a Bevel user, and by the settings
+ * UI to mint, list, and revoke keys.
+ *
+ * Verification is a hash lookup on a unique index, so it stays O(1) even
+ * with many tokens per user. Revoked tokens are kept (not deleted) so an
+ * operator can audit `last_used_at` after a leak.
+ */
+export interface IExternalApiKeyService {
+    /**
+     * True if a bearer string carries this tenant's external-API-key prefix
+     * (`<tenant>_…`). Lets auth middlewares route a key vs a JWT / internal token
+     * without a DB round-trip, using the tenant prefix the service was built with.
+     */
+    looksLikeExternalApiKey(token: string): boolean;
+    /**
+     * Generate a new token, persist its hash, and return the plaintext. The
+     * plaintext is **only** returned here — there is no read path that can
+     * surface it again.
+     */
+    mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+    /**
+     * Resolve a plaintext token to the owning user. Returns null when the
+     * token is unknown, revoked, or malformed. Bumps `last_used_at`
+     * fire-and-forget — verification latency stays bounded by the hash
+     * lookup, not the update.
+     */
+    verifyAndLoadUser(plaintext: string): Promise<AuthUser | null>;
+    /**
+     * Like `verifyAndLoadUser`, but also returns the matching token's id. The
+     * LLM proxy needs the token id (not just the user) to meter per-key usage
+     * against the daily cap. Returns null on unknown/revoked/malformed tokens.
+     */
+    verifyAndLoadToken(plaintext: string): Promise<{
+        tokenId: string;
+        user: AuthUser;
+    } | null>;
+    /** Active + revoked tokens for the user, newest-first. */
+    listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
+    /**
+     * Mark a token revoked. Idempotent — revoking an already-revoked token
+     * is a no-op (the row's `revokedAt` is not overwritten). Throws
+     * TokenNotFoundError if the token doesn't belong to the user.
+     */
+    revoke(id: string, userId: string): Promise<void>;
+    /**
+     * Permanently delete a token row, dropping its audit trail. Only permitted
+     * on an already-revoked token — an active key must be disconnected first,
+     * so a live agent's access is never yanked by a single click. Throws
+     * TokenNotFoundError if the token doesn't belong to the user, and
+     * TokenStillActiveError if it hasn't been revoked yet.
+     */
+    remove(id: string, userId: string): Promise<void>;
+}
+//# sourceMappingURL=external-api-key.interface.d.ts.map

package/dist/modules/tool-auth/external-api-key.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-key.interface.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf;;;;;eAKG;YACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;SAC3B;KACF;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAEhD;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEnE;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE/D;;;;OAIG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAEvD,0DAA0D;IAC1D,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAE9D;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/modules/tool-auth/external-api-key.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=external-api-key.interface.js.map

package/dist/modules/tool-auth/external-api-key.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-key.interface.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.interface.ts"],"names":[],"mappings":""}

package/dist/modules/tool-auth/external-api-key.service.d.ts

@@ -0,0 +1,25 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../database/connection.js';
+import type { ExternalApiKeySummary, IExternalApiKeyService, MintedExternalApiKey } from './external-api-key.interface.js';
+export declare class ExternalApiKeyService implements IExternalApiKeyService {
+    private readonly db;
+    private readonly keyPrefix;
+    /**
+     * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
+     *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+     */
+    constructor(db: Database, keyPrefix: string);
+    /** True if a bearer string carries this tenant's external-API-key prefix. */
+    looksLikeExternalApiKey(token: string): boolean;
+    mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+    verifyAndLoadUser(plaintext: string): Promise<AuthUser | null>;
+    verifyAndLoadToken(plaintext: string): Promise<{
+        tokenId: string;
+        user: AuthUser;
+    } | null>;
+    listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
+    revoke(id: string, userId: string): Promise<void>;
+    remove(id: string, userId: string): Promise<void>;
+    private touchLastUsed;
+}
+//# sourceMappingURL=external-api-key.service.d.ts.map

package/dist/modules/tool-auth/external-api-key.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-key.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAO1D,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AAUzC,qBAAa,qBAAsB,YAAW,sBAAsB;IAMhE,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B;;;OAGG;gBAEgB,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM;IAGpC,6EAA6E;IAC7E,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIzC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyBlE,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAK9D,kBAAkB,CACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC;IA4ChD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAS7D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCjD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAgCzC,aAAa;CAM5B"}