@bevel-software/platform-core-backend 0.14.0 → 0.19.0

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

@@ -1 +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"}
+{"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;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE;;;;;;;;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;AAC3B,2GAA2G;AAC3G,YAAY,CAAC,EAAE,oBAAoB,GAClC,IAAI,CA2BN"}

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

@@ -8,7 +8,9 @@ import { toolDef } from '../tool-helpers/tool-def.js';
  * 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) {
+export function registerSkillsTools(registry, router, toolAuth, toolHandler, skillService, 
+/** When given, a loaded skill carries `warnings` for `allowed-tools` entries that name no visible tool. */
+allowedTools) {
     registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
     registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
     registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
@@ -19,9 +21,13 @@ export function registerSkillsTools(registry, router, toolAuth, toolHandler, ski
     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;
+        const version = typeof args.version === 'string' ? args.version : undefined;
         if (!name)
             return { error: 'missing_name' };
-        return skillService.getSkill(ctx.user.email, name, file);
+        const result = await skillService.getSkill(ctx.user.email, name, file, { version });
+        if (!allowedTools || !result.ok || result.kind !== 'skill')
+            return result;
+        return { ...result, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
     }));
 }
 /** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
@@ -34,7 +40,9 @@ async function availableSkillsLine(skillService, userEmail) {
 async function buildListSkillsDef(skillService, userEmail) {
     return toolDef({
         name: 'list_skills',
-        description: 'List the available skills (reusable specialist instructions) with their names and descriptions. ' +
+        description: 'List the available skills (reusable specialist instructions) with their names, descriptions and, ' +
+            'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
+            'top-level `version`, else `lifecycle.version`). ' +
             'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
             (await availableSkillsLine(skillService, userEmail)),
         path: '/api/agent/tools/list_skills',
@@ -50,7 +58,11 @@ async function buildListSkillsDef(skillService, userEmail) {
                         properties: {
                             name: { type: 'string' },
                             description: { type: 'string' },
-                            version: { type: 'string' },
+                            version: {
+                                type: 'string',
+                                description: 'The version the skill currently declares (`metadata.version`, else top-level `version`, ' +
+                                    'else `lifecycle.version` in its SKILL.md); absent when it declares none.',
+                            },
                             path: { type: 'string' },
                         },
                     },
@@ -65,7 +77,8 @@ async function buildGetSkillDef(skillService, userEmail) {
         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. ' +
+            '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
+            'one the skill declared. ' +
             (await availableSkillsLine(skillService, userEmail)),
         path: '/api/agent/tools/get_skill',
         inputs: {
@@ -77,6 +90,14 @@ async function buildGetSkillDef(skillService, userEmail) {
                     description: 'Optional bundled file path relative to the skill folder (e.g. `scripts/build_xlsx.py`) — ' +
                         'fetch its content instead of the body.',
                 },
+                version: {
+                    type: 'string',
+                    description: 'Optional: the declared version to load (e.g. `1.4.0` — the `version` that `list_skills` ' +
+                        'reports: `metadata.version`, else `version`, else `lifecycle.version`). Omitted, the skill is loaded as it ' +
+                        'is now, which is the latest. Given, the skill — or the `file` — is served as it was at the most ' +
+                        'recent commit that declared that version; a version the skill never declared answers ' +
+                        '`version_not_found` with the versions it did declare.',
+                },
             },
             required: ['name'],
             additionalProperties: false,
@@ -87,7 +108,21 @@ async function buildGetSkillDef(skillService, userEmail) {
             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`.' },
+                warnings: {
+                    type: 'array',
+                    description: 'With `skill`: `allowed-tools` entries that look like platform tools but name none you can use — ' +
+                        'each `{ entry, message, suggestion? }`. Do not rely on such a tool.',
+                    items: { type: 'object' },
+                },
+                error: {
+                    type: 'string',
+                    description: 'Error code: `not_found`, `forbidden`, `invalid_file`, `missing_name`, `version_not_found`.',
+                },
+                versions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'With `version_not_found`: every version the skill has declared, newest first.',
+                },
             },
         },
         tags: ['skills'],

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

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

@@ -0,0 +1,18 @@
+import type { Response } from 'express';
+/**
+ * How every key-authenticated endpoint answers a bearer that LOOKS like a
+ * connection key but does not verify (unknown, revoked, mistyped).
+ *
+ * Deliberately no `resource_metadata`: that parameter (RFC 9728) invites an
+ * OAuth-capable client to discover our authorization server and start a
+ * browser sign-in, which is the wrong answer to someone who configured a key —
+ * signing in does not repair the key, and the invitation buries the one thing
+ * they need to hear. A missing bearer or a bad OAuth token keeps the discovery
+ * challenge; only this shape gets the plain sentence.
+ *
+ * The submitted key is never echoed, in the header, the body, or a log line.
+ */
+export declare const INVALID_CONNECTION_KEY_CHALLENGE = "Bearer error=\"invalid_token\", error_description=\"Invalid or revoked connection key\"";
+export declare const INVALID_CONNECTION_KEY_MESSAGE = "Invalid or revoked connection key. Mint a new one in External agent access.";
+export declare function rejectConnectionKey(res: Response): void;
+//# sourceMappingURL=connection-key-rejection.d.ts.map

package/dist/modules/tool-auth/connection-key-rejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-key-rejection.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/connection-key-rejection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gCAAgC,4FAC0C,CAAC;AAExF,eAAO,MAAM,8BAA8B,gFACoC,CAAC;AAEhF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAGvD"}

package/dist/modules/tool-auth/connection-key-rejection.js

@@ -0,0 +1,20 @@
+/**
+ * How every key-authenticated endpoint answers a bearer that LOOKS like a
+ * connection key but does not verify (unknown, revoked, mistyped).
+ *
+ * Deliberately no `resource_metadata`: that parameter (RFC 9728) invites an
+ * OAuth-capable client to discover our authorization server and start a
+ * browser sign-in, which is the wrong answer to someone who configured a key —
+ * signing in does not repair the key, and the invitation buries the one thing
+ * they need to hear. A missing bearer or a bad OAuth token keeps the discovery
+ * challenge; only this shape gets the plain sentence.
+ *
+ * The submitted key is never echoed, in the header, the body, or a log line.
+ */
+export const INVALID_CONNECTION_KEY_CHALLENGE = 'Bearer error="invalid_token", error_description="Invalid or revoked connection key"';
+export const INVALID_CONNECTION_KEY_MESSAGE = 'Invalid or revoked connection key. Mint a new one in External agent access.';
+export function rejectConnectionKey(res) {
+    res.setHeader('WWW-Authenticate', INVALID_CONNECTION_KEY_CHALLENGE);
+    res.status(401).json({ error: INVALID_CONNECTION_KEY_MESSAGE });
+}
+//# sourceMappingURL=connection-key-rejection.js.map

package/dist/modules/tool-auth/connection-key-rejection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-key-rejection.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/connection-key-rejection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAC3C,qFAAqF,CAAC;AAExF,MAAM,CAAC,MAAM,8BAA8B,GACzC,6EAA6E,CAAC;AAEhF,MAAM,UAAU,mBAAmB,CAAC,GAAa;IAC/C,GAAG,CAAC,SAAS,CAAC,kBAAkB,EAAE,gCAAgC,CAAC,CAAC;IACpE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/modules/tool-auth/connection-keys-admin.routes.d.ts

@@ -0,0 +1,14 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IExternalApiKeyService } from './external-api-key.interface.js';
+import '../auth/auth.middleware.js';
+/**
+ * Admin overview of connection keys across the deployment (the core
+ * "Connection keys" admin page): every key on every account — owner, label,
+ * created, last used, whether it is still live — and a revoke that is not
+ * scoped to the caller. The per-user surface stays in mcp.routes.ts; this
+ * router exists so an admin can cut off a leaked or forgotten key without
+ * signing in as its owner. Gated per request by {@link IAdminAccessService}.
+ */
+export declare function createConnectionKeysAdminRoutes(externalApiKeyService: Pick<IExternalApiKeyService, 'listForDeployment' | 'revokeAny'>, adminAccess: IAdminAccessService): express.Router;
+//# sourceMappingURL=connection-keys-admin.routes.d.ts.map

package/dist/modules/tool-auth/connection-keys-admin.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-keys-admin.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/connection-keys-admin.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAI9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,4BAA4B,CAAC;AAKpC;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,qBAAqB,EAAE,IAAI,CAAC,sBAAsB,EAAE,mBAAmB,GAAG,WAAW,CAAC,EACtF,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,MAAM,CAoDhB"}

package/dist/modules/tool-auth/connection-keys-admin.routes.js

@@ -0,0 +1,67 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+const log = logger('connection-keys');
+import { TokenNotFoundError } from './external-api-key.errors.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+/** Shape of the `api_tokens.id` column (any uuid version; case-insensitive). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Admin overview of connection keys across the deployment (the core
+ * "Connection keys" admin page): every key on every account — owner, label,
+ * created, last used, whether it is still live — and a revoke that is not
+ * scoped to the caller. The per-user surface stays in mcp.routes.ts; this
+ * router exists so an admin can cut off a leaked or forgotten key without
+ * signing in as its owner. Gated per request by {@link IAdminAccessService}.
+ */
+export function createConnectionKeysAdminRoutes(externalApiKeyService, adminAccess) {
+    const router = express.Router();
+    const requireAdmin = async (req, res, next) => {
+        if (!(await adminAccess.isAdmin(req.userEmail))) {
+            res.status(403).json({ error: 'Admins only' });
+            return;
+        }
+        next();
+    };
+    // GET /api/admin/connection-keys — every key with its owner, ordered by
+    // owner email then newest-first. Never carries a plaintext or a hash.
+    router.get('/admin/connection-keys', requireAdmin, async (_req, res) => {
+        try {
+            res.json({ keys: await externalApiKeyService.listForDeployment() });
+        }
+        catch (err) {
+            log.error('admin list failed:', { err });
+            res.status(500).json({ error: 'Failed to load connection keys' });
+        }
+    });
+    // DELETE /api/admin/connection-keys/:id — revoke (disconnect) a key
+    // belonging to ANY account. Idempotent on an already-revoked key; 404 when
+    // no such key exists. Revoked rows are kept so `last_used_at` stays
+    // auditable after a leak — there is deliberately no admin hard-delete.
+    router.delete('/admin/connection-keys/:id', requireAdmin, async (req, res) => {
+        const id = String(req.params.id);
+        // The id column is a uuid: anything else makes Postgres raise a cast
+        // error before the WHERE is even evaluated, which would surface as a 500.
+        // A malformed id names no key, so it is a not-found, same as an unknown one.
+        if (!UUID_RE.test(id)) {
+            res.status(404).json({ error: 'Token not found' });
+            return;
+        }
+        try {
+            await externalApiKeyService.revokeAny(id);
+            // Accountability record: WHO revoked WHICH key. Ids only — the key's
+            // label is the owner's free text and does not belong in logs.
+            log.info('revoke audit:', { action: 'admin-revoke-key', actorUserId: req.userId, tokenId: id });
+            res.json({ status: 'revoked' });
+        }
+        catch (err) {
+            if (err instanceof TokenNotFoundError) {
+                res.status(404).json({ error: err.message });
+                return;
+            }
+            log.error('admin revoke failed:', { err });
+            res.status(500).json({ error: 'Failed to revoke this key' });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=connection-keys-admin.routes.js.map

package/dist/modules/tool-auth/connection-keys-admin.routes.js.map

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

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

@@ -19,10 +19,24 @@ declare global {
 export interface ExternalApiKeySummary {
     id: string;
     label: string;
+    /**
+     * What the key was minted AS — `key` for one a person created by hand,
+     * another kind for one a flow minted on their behalf (a Claude link).
+     * Stored with the row; the label is the person's to edit and proves nothing.
+     */
+    kind: string;
     createdAt: number;
     lastUsedAt: number | null;
     revokedAt: number | null;
+    /**
+     * Who ended it, once `revokedAt` is set: the owner themselves, or an admin
+     * from the deployment overview. Null while live (and on rows revoked
+     * before this was recorded, which read as the owner's doing).
+     */
+    revokedBy: RevokedBy | null;
 }
+/** Who revoked a key: its owner, or an admin acting across the deployment. */
+export type RevokedBy = 'owner' | 'admin';
 /**
  * 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
@@ -32,6 +46,43 @@ export interface MintedExternalApiKey {
     plaintext: string;
     summary: ExternalApiKeySummary;
 }
+/**
+ * One row of the admin "Connection keys" overview: a key summary plus the
+ * account it belongs to. Deployment-wide, so unlike {@link ExternalApiKeySummary}
+ * the owner is not implied by the caller.
+ */
+export interface AdminExternalApiKeySummary extends ExternalApiKeySummary {
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+/** The kind of a key a person creates by hand. */
+export declare const DEFAULT_KEY_KIND = "key";
+/**
+ * How the plaintext of one kind of key is spelled: the prefix the outside
+ * world sees (and that routes the bearer back here), and the shape of the
+ * random part after it. `base64url` is the platform's own — 43 characters
+ * from a 32-byte draw. `github-token` is what a GitHub OAuth token looks
+ * like after its `gho_`: letters and digits only, 40 of them, so a consumer
+ * that validates the shape of a GitHub token (they are documented as
+ * alphanumeric) keeps it. Both hash the same way; the shape is only what a
+ * client is shown.
+ */
+export interface KeyKindSpec {
+    prefix: string;
+    shape?: 'base64url' | 'github-token';
+}
+/**
+ * How a key is minted. `kind` names one of the kinds the service was built
+ * with, each of which carries its own spelling (the tenant's prefix for the
+ * default kind, a GitHub-shaped token for a Claude link); an unknown kind is
+ * refused, since nothing would route its bearer back.
+ */
+export interface MintOptions {
+    kind?: string;
+}
 /**
  * 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
@@ -53,7 +104,7 @@ export interface IExternalApiKeyService {
      * plaintext is **only** returned here — there is no read path that can
      * surface it again.
      */
-    mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+    mint(userId: string, label: string, options?: MintOptions): Promise<MintedExternalApiKey>;
     /**
      * Resolve a plaintext token to the owning user. Returns null when the
      * token is unknown, revoked, or malformed. Bumps `last_used_at`
@@ -78,6 +129,20 @@ export interface IExternalApiKeyService {
      * TokenNotFoundError if the token doesn't belong to the user.
      */
     revoke(id: string, userId: string): Promise<void>;
+    /**
+     * Every token on the deployment, active and revoked, with its owner —
+     * the admin overview. Ordered by owner email, then newest-first, so the
+     * caller can group per account without re-sorting.
+     */
+    listForDeployment(): Promise<AdminExternalApiKeySummary[]>;
+    /**
+     * Admin revoke: mark a token revoked WITHOUT scoping by owner, recording
+     * `revokedBy: 'admin'` so the owner's page can say it was taken rather than
+     * disconnected. Same idempotency as {@link revoke}; throws
+     * TokenNotFoundError when no such token exists. Only reachable through an
+     * admin-gated route — the per-user route must keep using {@link revoke}.
+     */
+    revokeAny(id: 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,

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

@@ -1 +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"}
+{"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;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7B;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;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,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE1F;;;;;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;;;;OAIG;IACH,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;;;;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

@@ -1,2 +1,3 @@
-export {};
+/** The kind of a key a person creates by hand. */
+export const DEFAULT_KEY_KIND = 'key';
 //# sourceMappingURL=external-api-key.interface.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"external-api-key.interface.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.interface.ts"],"names":[],"mappings":""}
+{"version":3,"file":"external-api-key.interface.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.interface.ts"],"names":[],"mappings":"AAmEA,kDAAkD;AAClD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC"}

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

@@ -1,24 +1,43 @@
 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';
+import { type AdminExternalApiKeySummary, type ExternalApiKeySummary, type IExternalApiKeyService, type KeyKindSpec, type MintOptions, type MintedExternalApiKey } from './external-api-key.interface.js';
 export declare class ExternalApiKeyService implements IExternalApiKeyService {
     private readonly db;
     private readonly keyPrefix;
+    private readonly kinds;
+    private readonly prefixes;
     /**
      * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
      *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+     *   Every key of the default kind is minted with it.
+     * @param kinds Other kinds a key may be minted as, each with the spelling
+     *   that kind has — a Claude link's `gho_` and GitHub's alphabet, the
+     *   shape claude.ai expects from a GitHub host. Same key, same table, same
+     *   revocation; the KIND is stored on the row and is what tells such keys
+     *   apart (a label is the person's to edit), the spelling is only what the
+     *   outside world sees and what routes the bearer back here.
      */
-    constructor(db: Database, keyPrefix: string);
-    /** True if a bearer string carries this tenant's external-API-key prefix. */
+    constructor(db: Database, keyPrefix: string, kinds?: Readonly<Record<string, KeyKindSpec>>);
+    /** True if a bearer string carries one of this service's key prefixes. */
     looksLikeExternalApiKey(token: string): boolean;
-    mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+    mint(userId: string, label: string, options?: MintOptions): Promise<MintedExternalApiKey>;
     verifyAndLoadUser(plaintext: string): Promise<AuthUser | null>;
     verifyAndLoadToken(plaintext: string): Promise<{
         tokenId: string;
         user: AuthUser;
     } | null>;
     listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
+    listForDeployment(): Promise<AdminExternalApiKeySummary[]>;
     revoke(id: string, userId: string): Promise<void>;
+    revokeAny(id: string): Promise<void>;
+    /**
+     * Set `revokedAt` (and who did it) on the rows matching `scope`. Idempotent
+     * on already-revoked rows because we only write when `revokedAt` is
+     * currently null — re-revoking returns 0 rows changed but no error, and
+     * never rewrites who ended it first. Throws TokenNotFoundError when `scope`
+     * matches nothing at all.
+     */
+    private markRevoked;
     remove(id: string, userId: string): Promise<void>;
     private touchLastUsed;
 }

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

@@ -1 +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"}
+{"version":3,"file":"external-api-key.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/external-api-key.service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAO1D,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EAC1B,MAAM,iCAAiC,CAAC;AAazC,qBAAa,qBAAsB,YAAW,sBAAsB;IAehE,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhBxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAE7C;;;;;;;;;;OAUG;gBAEgB,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAM;IAKpE,0EAA0E;IAC1E,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIzC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgC7F,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,iBAAiB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC;IAoB1D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1C;;;;;;OAMG;YACW,WAAW;IAsBnB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAgCzC,aAAa;CAM5B"}

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

@@ -1,29 +1,50 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { and, desc, eq, isNotNull, isNull } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+const log = logger('external-api-key');
+import { and, asc, desc, eq, isNotNull, isNull } from 'drizzle-orm';
 import { externalApiKeys, users } from '../database/schema.js';
 import { InvalidTokenLabelError, TokenNotFoundError, TokenStillActiveError, } from './external-api-key.errors.js';
-// Plaintext format: `<tenant>_<43 base64url chars>`. 32 random bytes encoded
+import { DEFAULT_KEY_KIND, } from './external-api-key.interface.js';
+// Plaintext format: `<prefix><43 base64url chars>`. 32 random bytes encoded
 // base64url is 43 chars and gives 256 bits of entropy — overkill against
-// brute force, cheap to copy. The tenant prefix (default `bevel_`) lets the
-// auth middleware route key-vs-JWT requests without parsing both shapes.
+// brute force, cheap to copy. The prefix lets the auth middleware route
+// key-vs-JWT requests without parsing both shapes.
 const TOKEN_BYTES = 32;
+// A GitHub-shaped token: 20 random bytes as 40 hex digits — alphanumeric,
+// as GitHub's own are, and 160 bits, which a hash lookup never exhausts.
+const GITHUB_TOKEN_BYTES = 20;
 const MAX_LABEL_LEN = 200;
 export class ExternalApiKeyService {
     db;
     keyPrefix;
+    kinds;
+    prefixes;
     /**
      * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
      *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+     *   Every key of the default kind is minted with it.
+     * @param kinds Other kinds a key may be minted as, each with the spelling
+     *   that kind has — a Claude link's `gho_` and GitHub's alphabet, the
+     *   shape claude.ai expects from a GitHub host. Same key, same table, same
+     *   revocation; the KIND is stored on the row and is what tells such keys
+     *   apart (a label is the person's to edit), the spelling is only what the
+     *   outside world sees and what routes the bearer back here.
      */
-    constructor(db, keyPrefix) {
+    constructor(db, keyPrefix, kinds = {}) {
         this.db = db;
         this.keyPrefix = keyPrefix;
+        this.kinds = kinds;
+        this.prefixes = [keyPrefix, ...Object.values(kinds).map((k) => k.prefix)];
     }
-    /** True if a bearer string carries this tenant's external-API-key prefix. */
+    /** True if a bearer string carries one of this service's key prefixes. */
     looksLikeExternalApiKey(token) {
-        return typeof token === 'string' && token.startsWith(this.keyPrefix);
+        return typeof token === 'string' && this.prefixes.some((p) => token.startsWith(p));
     }
-    async mint(userId, label) {
+    async mint(userId, label, options = {}) {
+        const kind = options.kind ?? DEFAULT_KEY_KIND;
+        const spec = kind === DEFAULT_KEY_KIND ? { prefix: this.keyPrefix } : this.kinds[kind];
+        if (!spec)
+            throw new Error(`Unknown key kind "${kind}"`);
         const trimmed = (label ?? '').trim();
         if (trimmed.length === 0) {
             throw new InvalidTokenLabelError('Label cannot be empty');
@@ -31,11 +52,14 @@ export class ExternalApiKeyService {
         if (trimmed.length > MAX_LABEL_LEN) {
             throw new InvalidTokenLabelError(`Label cannot exceed ${MAX_LABEL_LEN} characters`);
         }
-        const plaintext = this.keyPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
+        const random = spec.shape === 'github-token'
+            ? randomBytes(GITHUB_TOKEN_BYTES).toString('hex')
+            : randomBytes(TOKEN_BYTES).toString('base64url');
+        const plaintext = spec.prefix + random;
         const tokenHash = hashToken(plaintext);
         const [row] = await this.db
             .insert(externalApiKeys)
-            .values({ userId, tokenHash, label: trimmed })
+            .values({ userId, tokenHash, label: trimmed, kind })
             .returning();
         return {
             plaintext,
@@ -74,7 +98,7 @@ export class ExternalApiKeyService {
         // the worst case is a slightly stale `last_used_at`, which is fine for
         // a "when was this key last used" audit view.
         this.touchLastUsed(row.tokenId).catch((err) => {
-            console.warn('[external-api-key] touchLastUsed failed:', err);
+            log.warn('touchLastUsed failed:', { err });
         });
         return {
             tokenId: row.tokenId,
@@ -94,24 +118,58 @@ export class ExternalApiKeyService {
             .orderBy(desc(externalApiKeys.createdAt));
         return rows.map(toSummary);
     }
+    async listForDeployment() {
+        // Owner joined in so the admin overview is one round-trip; ordered by
+        // owner email so per-account grouping is a linear pass, newest key
+        // first within an account (same order the owner sees on their own page).
+        const rows = await this.db
+            .select({
+            key: externalApiKeys,
+            userId: users.id,
+            email: users.email,
+            name: users.name,
+        })
+            .from(externalApiKeys)
+            .innerJoin(users, eq(externalApiKeys.userId, users.id))
+            .orderBy(asc(users.email), desc(externalApiKeys.createdAt));
+        return rows.map((row) => ({
+            ...toSummary(row.key),
+            user: { id: row.userId, email: row.email, name: row.name },
+        }));
+    }
     async revoke(id, userId) {
-        // Scope the WHERE by userId so a user can never revoke another user's
-        // token even if they learn the id. Idempotent on already-revoked rows
-        // because we only set `revokedAt` when it's currently null — re-revoking
-        // returns 0 rows changed but no error.
+        // Scope by userId so a user can never revoke another user's token even
+        // if they learn the id.
+        await this.markRevoked(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)), 'owner');
+    }
+    async revokeAny(id) {
+        // No owner scope: the caller is an admin acting across the deployment.
+        // The route that exposes this is admin-gated; nothing user-facing may
+        // reach it. Recorded as such so the owner is told it was taken, not
+        // that they disconnected it.
+        await this.markRevoked(eq(externalApiKeys.id, id), 'admin');
+    }
+    /**
+     * Set `revokedAt` (and who did it) on the rows matching `scope`. Idempotent
+     * on already-revoked rows because we only write when `revokedAt` is
+     * currently null — re-revoking returns 0 rows changed but no error, and
+     * never rewrites who ended it first. Throws TokenNotFoundError when `scope`
+     * matches nothing at all.
+     */
+    async markRevoked(scope, by) {
         const result = await this.db
             .update(externalApiKeys)
-            .set({ revokedAt: new Date() })
-            .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNull(externalApiKeys.revokedAt)))
+            .set({ revokedAt: new Date(), revokedBy: by })
+            .where(and(scope, isNull(externalApiKeys.revokedAt)))
             .returning({ id: externalApiKeys.id });
         if (result.length === 0) {
-            // Distinguish "doesn't exist / not yours" from "already revoked".
+            // Distinguish "doesn't exist / out of scope" from "already revoked".
             // The latter must stay idempotent (return success); only the former
             // throws.
             const [existing] = await this.db
                 .select({ id: externalApiKeys.id })
                 .from(externalApiKeys)
-                .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+                .where(scope)
                 .limit(1);
             if (!existing) {
                 throw new TokenNotFoundError();
@@ -156,9 +214,11 @@ function toSummary(row) {
     return {
         id: row.id,
         label: row.label,
+        kind: row.kind,
         createdAt: row.createdAt.getTime(),
         lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
         revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+        revokedBy: row.revokedBy ?? null,
     };
 }
 //# sourceMappingURL=external-api-key.service.js.map