@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,164 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { and, 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
+// 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.
+const TOKEN_BYTES = 32;
+const MAX_LABEL_LEN = 200;
+export class ExternalApiKeyService {
+    db;
+    keyPrefix;
+    /**
+     * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
+     *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+     */
+    constructor(db, keyPrefix) {
+        this.db = db;
+        this.keyPrefix = keyPrefix;
+    }
+    /** True if a bearer string carries this tenant's external-API-key prefix. */
+    looksLikeExternalApiKey(token) {
+        return typeof token === 'string' && token.startsWith(this.keyPrefix);
+    }
+    async mint(userId, label) {
+        const trimmed = (label ?? '').trim();
+        if (trimmed.length === 0) {
+            throw new InvalidTokenLabelError('Label cannot be empty');
+        }
+        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 tokenHash = hashToken(plaintext);
+        const [row] = await this.db
+            .insert(externalApiKeys)
+            .values({ userId, tokenHash, label: trimmed })
+            .returning();
+        return {
+            plaintext,
+            summary: toSummary(row),
+        };
+    }
+    async verifyAndLoadUser(plaintext) {
+        const resolved = await this.verifyAndLoadToken(plaintext);
+        return resolved ? resolved.user : null;
+    }
+    async verifyAndLoadToken(plaintext) {
+        if (!this.looksLikeExternalApiKey(plaintext)) {
+            return null;
+        }
+        const tokenHash = hashToken(plaintext);
+        // Join users so a single round-trip resolves both "token is valid" and
+        // "load the user it belongs to". The unique index on token_hash makes
+        // this a point-lookup. `isNull(revokedAt)` is what enforces revocation
+        // — the row remains for audit.
+        const [row] = await this.db
+            .select({
+            tokenId: externalApiKeys.id,
+            userId: users.id,
+            email: users.email,
+            name: users.name,
+            avatarUrl: users.avatarUrl,
+        })
+            .from(externalApiKeys)
+            .innerJoin(users, eq(externalApiKeys.userId, users.id))
+            .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt)))
+            .limit(1);
+        if (!row)
+            return null;
+        // Fire-and-forget so verification latency is bounded by the SELECT, not
+        // the UPDATE. A failed touch is logged but never blocks the caller —
+        // 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);
+        });
+        return {
+            tokenId: row.tokenId,
+            user: {
+                id: row.userId,
+                email: row.email,
+                name: row.name,
+                avatarUrl: row.avatarUrl ?? undefined,
+            },
+        };
+    }
+    async listForUser(userId) {
+        const rows = await this.db
+            .select()
+            .from(externalApiKeys)
+            .where(eq(externalApiKeys.userId, userId))
+            .orderBy(desc(externalApiKeys.createdAt));
+        return rows.map(toSummary);
+    }
+    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.
+        const result = await this.db
+            .update(externalApiKeys)
+            .set({ revokedAt: new Date() })
+            .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNull(externalApiKeys.revokedAt)))
+            .returning({ id: externalApiKeys.id });
+        if (result.length === 0) {
+            // Distinguish "doesn't exist / not yours" 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)))
+                .limit(1);
+            if (!existing) {
+                throw new TokenNotFoundError();
+            }
+        }
+    }
+    async remove(id, userId) {
+        // Only revoked rows may be hard-deleted — deleting an active key would
+        // silently cut off a live agent. Scope by userId so a user can only
+        // delete their own tokens. Validate first (so we can return a precise
+        // not-found vs still-active error), then delete inside a transaction.
+        const [existing] = await this.db
+            .select({ revokedAt: externalApiKeys.revokedAt })
+            .from(externalApiKeys)
+            .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+            .limit(1);
+        if (!existing) {
+            throw new TokenNotFoundError();
+        }
+        if (existing.revokedAt === null) {
+            // Exists and is yours, but wasn't revoked — refuse rather than delete.
+            throw new TokenStillActiveError();
+        }
+        // Dependents (e.g. the enterprise LLM-usage metering rows) hang off this
+        // row via ON DELETE CASCADE foreign keys, so a bare delete takes any audit
+        // trail with it — this service doesn't have to know those tables exist.
+        await this.db
+            .delete(externalApiKeys)
+            .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNotNull(externalApiKeys.revokedAt)));
+    }
+    async touchLastUsed(tokenId) {
+        await this.db
+            .update(externalApiKeys)
+            .set({ lastUsedAt: new Date() })
+            .where(eq(externalApiKeys.id, tokenId));
+    }
+}
+function hashToken(plaintext) {
+    return createHash('sha256').update(plaintext).digest('hex');
+}
+function toSummary(row) {
+    return {
+        id: row.id,
+        label: row.label,
+        createdAt: row.createdAt.getTime(),
+        lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
+        revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
+    };
+}
+//# sourceMappingURL=external-api-key.service.js.map

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

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

package/dist/modules/tool-auth/internal-token.service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What an internal token authorizes: a user identity, nothing more. Minted when
+ * an agent's code-mode client is built and seeded into that client's UTCP config.
+ * Deliberately identity-only — the SAME shape a `bevel_…` connection key resolves
+ * to: the workspace is chosen per call from the tool's `branch` argument, and the
+ * scope is always write (the middleware sets it, exactly as for connection keys).
+ */
+export interface InternalTokenClaim {
+    userId: string;
+    /**
+     * The agent run / conversation id (the Mastra thread id) this token is scoped
+     * to, when minted per-run. Surfaced as `ToolContext.sessionId` so the
+     * ontology-session boundary can scope to one run for the in-process agent
+     * (the external/MCP path carries `sessionId` on the tool body instead).
+     * Absent for identity-only tokens.
+     */
+    sessionId?: string;
+    /**
+     * True when this token is the LOOPBACK identity of an external caller — the
+     * MCP proxy mints one per OAuth/JWT MCP session (which has no `bevel_…`
+     * connection key to pass through). The verifier resolves such tokens to
+     * `source: 'external'`: the caller IS an external agent, and must be treated
+     * like one everywhere — admitted to external-only surfaces (`start_session`,
+     * `ask`), refused from internal-only ones (`execute_command`, …), and
+     * expected to carry `sessionId` on the tool body, not in the token.
+     */
+    externalProxy?: boolean;
+}
+/**
+ * Mints + verifies stateless HMAC internal tokens. No DB: the token is
+ * self-contained `(claim, exp)` signed with a process secret, so it is
+ * multi-replica safe for verification within a deploy and costs nothing to
+ * issue. Tokens carry only `userId` and are short-lived; the agent factory
+ * mints one per code-mode client (per user).
+ *
+ * Distinct from connection keys (`bevel_…`, long-lived, user-wide): internal
+ * tokens are the least-privilege credential for the in-process loopback surface
+ * and are rejected by the external endpoints, and vice-versa.
+ */
+export declare class InternalTokenService {
+    private readonly secret;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly prefix;
+    constructor(opts?: {
+        secret?: string;
+        ttlMs?: number;
+        now?: () => number;
+        prefix?: string;
+    });
+    /** Token lifetime in ms — so callers caching a minted token can refresh it before expiry. */
+    get tokenTtlMs(): number;
+    /** @param ttlMs Override the default lifetime — e.g. the MCP proxy mints
+     *   session-loopback tokens that must outlive its 4h session idle TTL. */
+    mint(claim: InternalTokenClaim, ttlMs?: number): string;
+    /** Returns the claim for a valid, unexpired token; null otherwise. */
+    verify(token: string): InternalTokenClaim | null;
+    /** True if the bearer string looks like an internal token (vs an external API key). */
+    looksLikeInternalToken(token: string): boolean;
+    private sign;
+}
+//# sourceMappingURL=internal-token.service.d.ts.map

package/dist/modules/tool-auth/internal-token.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-token.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/internal-token.service.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAaD;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAG9B,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAarF,6FAA6F;IAC7F,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;8EAC0E;IAC1E,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAOvD,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IA2BhD,uFAAuF;IACvF,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI9C,OAAO,CAAC,IAAI;CAGb"}

package/dist/modules/tool-auth/internal-token.service.js

@@ -0,0 +1,85 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+const DEFAULT_PREFIX = 'bevel-int_';
+function b64url(buf) {
+    return buf.toString('base64url');
+}
+/**
+ * Mints + verifies stateless HMAC internal tokens. No DB: the token is
+ * self-contained `(claim, exp)` signed with a process secret, so it is
+ * multi-replica safe for verification within a deploy and costs nothing to
+ * issue. Tokens carry only `userId` and are short-lived; the agent factory
+ * mints one per code-mode client (per user).
+ *
+ * Distinct from connection keys (`bevel_…`, long-lived, user-wide): internal
+ * tokens are the least-privilege credential for the in-process loopback surface
+ * and are rejected by the external endpoints, and vice-versa.
+ */
+export class InternalTokenService {
+    secret;
+    ttlMs;
+    now;
+    prefix;
+    constructor(opts = {}) {
+        // A per-boot random secret is fine: tokens are minted per turn-ish and
+        // re-minted after a restart. A caller may inject a stable secret (tests, or
+        // a future multi-replica deploy) instead.
+        this.secret = opts.secret ? Buffer.from(opts.secret, 'utf8') : randomBytes(32);
+        this.ttlMs = opts.ttlMs ?? 60 * 60 * 1000; // 1h
+        this.now = opts.now ?? Date.now;
+        // Tenant-derived prefix (default `bevel-int_`), injected from
+        // AppConfig.internalTokenPrefix so internal tokens brand with the deploy's tenant.
+        this.prefix = opts.prefix ?? DEFAULT_PREFIX;
+    }
+    /** Token lifetime in ms — so callers caching a minted token can refresh it before expiry. */
+    get tokenTtlMs() {
+        return this.ttlMs;
+    }
+    /** @param ttlMs Override the default lifetime — e.g. the MCP proxy mints
+     *   session-loopback tokens that must outlive its 4h session idle TTL. */
+    mint(claim, ttlMs) {
+        const payload = { ...claim, exp: this.now() + (ttlMs ?? this.ttlMs) };
+        const body = b64url(Buffer.from(JSON.stringify(payload), 'utf8'));
+        const sig = b64url(this.sign(body));
+        return `${this.prefix}${body}.${sig}`;
+    }
+    /** Returns the claim for a valid, unexpired token; null otherwise. */
+    verify(token) {
+        if (!this.looksLikeInternalToken(token))
+            return null;
+        const rest = token.slice(this.prefix.length);
+        const dot = rest.indexOf('.');
+        if (dot < 0)
+            return null;
+        const body = rest.slice(0, dot);
+        const sig = rest.slice(dot + 1);
+        const expected = b64url(this.sign(body));
+        if (sig.length !== expected.length)
+            return null;
+        if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
+            return null;
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        }
+        catch {
+            return null;
+        }
+        if (typeof payload.exp !== 'number' || payload.exp < this.now())
+            return null;
+        if (typeof payload.userId !== 'string')
+            return null;
+        return {
+            userId: payload.userId,
+            ...(typeof payload.sessionId === 'string' ? { sessionId: payload.sessionId } : {}),
+            ...(payload.externalProxy === true ? { externalProxy: true } : {}),
+        };
+    }
+    /** True if the bearer string looks like an internal token (vs an external API key). */
+    looksLikeInternalToken(token) {
+        return token.startsWith(this.prefix);
+    }
+    sign(body) {
+        return createHmac('sha256', this.secret).update(body).digest();
+    }
+}
+//# sourceMappingURL=internal-token.service.js.map

package/dist/modules/tool-auth/internal-token.service.js.map

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

package/dist/modules/tool-auth/llm-usage-meter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Metering view over connection-key LLM usage, consumed by the connection-key
+ * management routes (mcp) to show each key's spend against the daily budget.
+ * The enterprise LLM proxy's `LlmUsageService` satisfies this structurally; a
+ * core-only deployment (no LLM proxy, nothing to meter) passes
+ * {@link unmeteredLlmUsage}.
+ */
+export interface ILlmUsageMeter {
+    /** Daily per-key token cap shown in the UI, or null when unmetered. */
+    readonly dailyCap: number | null;
+    /** Today's usage per key id, as `{ [tokenId]: tokens }` — missing keys mean 0. */
+    usageForTokens(tokenIds: string[]): Promise<Record<string, number>>;
+}
+/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
+export declare const unmeteredLlmUsage: ILlmUsageMeter;
+//# sourceMappingURL=llm-usage-meter.d.ts.map

package/dist/modules/tool-auth/llm-usage-meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-usage-meter.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/llm-usage-meter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kFAAkF;IAClF,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrE;AAED,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,EAAE,cAG/B,CAAC"}

package/dist/modules/tool-auth/llm-usage-meter.js

@@ -0,0 +1,6 @@
+/** Core default: no proxy, no metering — every key reads as unused/uncapped. */
+export const unmeteredLlmUsage = {
+    dailyCap: null,
+    usageForTokens: async () => ({}),
+};
+//# sourceMappingURL=llm-usage-meter.js.map

package/dist/modules/tool-auth/llm-usage-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-usage-meter.js","sourceRoot":"","sources":["../../../src/modules/tool-auth/llm-usage-meter.ts"],"names":[],"mappings":"AAcA,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,QAAQ,EAAE,IAAI;IACd,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;CACjC,CAAC"}

package/dist/modules/tool-auth/tool-auth.middleware.d.ts

@@ -0,0 +1,101 @@
+import type { RequestHandler } from 'express';
+import type { IExternalApiKeyService } from './external-api-key.interface.js';
+import type { AuthService } from '../auth/auth.service.js';
+import { InternalTokenService } from './internal-token.service.js';
+/**
+ * What the `toolAuth` middleware resolves a bearer to, before the per-call
+ * `ToolContext` is built. Internal and external are now the SAME shape — a user
+ * identity at write scope — resolving through one path; `source` only records
+ * which credential authenticated (so internal-only routes can be gated):
+ *  - `external`: a `bevel_…` connection key → user.
+ *  - `internal`: an identity-only HMAC token minted for an agent's code-mode client.
+ *  - `session`: a browser JWT — admitted ONLY on the read-only manual endpoint
+ *    (`createManualAuthMiddleware`), never on a tool-execution route, so it can
+ *    browse the catalog but cannot invoke tools.
+ * The workspace is chosen per call from the tool's `branch` argument (downstream
+ * ACL / protected-branch checks gate writes).
+ */
+export interface ToolAuth {
+    source: 'internal' | 'external' | 'session';
+    userId: string;
+    tokenId?: string;
+    /** The agent run id carried by a per-run internal token (in-process agent). The external path supplies `sessionId` on the tool body instead. */
+    sessionId?: string;
+    /** Always `'write'` now (the middleware sets it for both internal + external — neither credential carries scope). The read path is dormant until consumer agents are removed. */
+    scope: 'read' | 'write';
+}
+declare global {
+    namespace Express {
+        interface Request {
+            toolAuth?: ToolAuth;
+        }
+    }
+}
+/**
+ * Gate that admits ONLY in-process callers (those bearing an internal HMAC
+ * token). Mount it AFTER `toolAuth` on every internal-only surface — the
+ * internal tool catalog and the routes of tools registered with
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
+ * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * an external connection key authenticates successfully, so without this gate it
+ * could invoke an internal-only route directly by guessing its name. The route
+ * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so
+ * the restriction has to be enforced here at request time, not by hiding the
+ * route. 403 (authenticated, but not authorized for this surface).
+ */
+export declare const requireInternalSource: RequestHandler;
+/**
+ * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
+ * callers. `start_session` mints a fresh chat thread as the caller's
+ * ontology-session id; an internal (in-process agent) token already carries
+ * its run's `sessionId`, so letting it mint a new thread mid-run would
+ * silently reset the one-ontology-per-conversation boundary.
+ *
+ * "External" is decided by the VERIFIER, not by which credential shape
+ * authenticated: a `bevel_…` connection key resolves external, and so does an
+ * `externalProxy` internal token — the loopback identity the MCP proxy mints
+ * for an OAuth/JWT MCP session, whose caller IS an external agent. (Gating on
+ * the raw credential shape used to 403 those sessions here, deadlocking them:
+ * they couldn't mint a sessionId, and every session-gated tool demands one.)
+ * Mount AFTER `toolAuth`. 403 (authenticated, but not authorized).
+ */
+export declare const requireExternalSource: RequestHandler;
+/** Outcome of verifying a bearer token — either a normalized identity or a status+message to surface. */
+export type VerifyResult = {
+    ok: true;
+    auth: ToolAuth;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+/**
+ * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
+ * normalized `ToolAuth`, accepting EITHER a `bevel_…` connection key (external —
+ * pipeline-agent, MCP) OR an internal HMAC token (our own agent's loopback). A
+ * bare JWT / unknown scheme is refused. Throws only if the connection-key store
+ * itself errors (backend down); the caller maps that to 500. This is the shared
+ * primitive both `createToolAuthMiddleware` (our Express hosting) and
+ * `validateToken` (the tool-author SDK) are built on, so there is ONE auth path.
+ */
+export declare function createTokenVerifier(externalApiKeyService: IExternalApiKeyService, internalTokenService: InternalTokenService): (token: string | undefined) => Promise<VerifyResult>;
+/**
+ * The one auth gate every tool endpoint applies — a THIN Express adapter over
+ * `createTokenVerifier`: parse the bearer header, run the shared verify core,
+ * normalize the result to `req.toolAuth` (or the matching status). All auth logic
+ * lives in the verifier; this only does header parsing + HTTP mapping.
+ */
+export declare function createToolAuthMiddleware(externalApiKeyService: IExternalApiKeyService, internalTokenService: InternalTokenService): RequestHandler;
+/**
+ * Auth gate for the READ-ONLY discovery manuals (`GET /agent/utcp` +
+ * `/agent/internal/utcp`) ONLY. Superset of `createToolAuthMiddleware`: it
+ * accepts a `bevel_…` connection key, an internal token, OR a browser JWT —
+ * the last resolving to `source: 'session'`. This is what lets a logged-in user
+ * browse the catalog with their existing session (the manual is just a spec, no
+ * secrets, and may become per-user — hence one user-aware endpoint rather than a
+ * parallel route). It is deliberately NOT used on tool-execution routes, so a
+ * JWT can read the manual but can never invoke a tool. The internal manual stays
+ * `requireInternalSource`-gated downstream, so a session/key is 403'd there.
+ */
+export declare function createManualAuthMiddleware(externalApiKeyService: IExternalApiKeyService, internalTokenService: InternalTokenService, authService: AuthService): RequestHandler;
+//# sourceMappingURL=tool-auth.middleware.d.ts.map

package/dist/modules/tool-auth/tool-auth.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-auth.middleware.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-auth/tool-auth.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gJAAgJ;IAChJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iLAAiL;IACjL,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;SACrB;KACF;CACF;AAID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAMnC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAMnC,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,qBAAqB,EAAE,sBAAsB,EAC7C,oBAAoB,EAAE,oBAAoB,GACzC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,YAAY,CAAC,CA6BtD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,qBAAqB,EAAE,sBAAsB,EAC7C,oBAAoB,EAAE,oBAAoB,GACzC,cAAc,CAwBhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,qBAAqB,EAAE,sBAAsB,EAC7C,oBAAoB,EAAE,oBAAoB,EAC1C,WAAW,EAAE,WAAW,GACvB,cAAc,CAuChB"}

package/dist/modules/tool-auth/tool-auth.middleware.js

@@ -0,0 +1,166 @@
+const WWW_AUTH = 'Bearer realm="bevel-tools"';
+/**
+ * Gate that admits ONLY in-process callers (those bearing an internal HMAC
+ * token). Mount it AFTER `toolAuth` on every internal-only surface — the
+ * internal tool catalog and the routes of tools registered with
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
+ * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * an external connection key authenticates successfully, so without this gate it
+ * could invoke an internal-only route directly by guessing its name. The route
+ * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so
+ * the restriction has to be enforced here at request time, not by hiding the
+ * route. 403 (authenticated, but not authorized for this surface).
+ */
+export const requireInternalSource = (req, res, next) => {
+    if (req.toolAuth?.source !== 'internal') {
+        res.status(403).json({ error: 'This tool is internal-only.' });
+        return;
+    }
+    next();
+};
+/**
+ * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
+ * callers. `start_session` mints a fresh chat thread as the caller's
+ * ontology-session id; an internal (in-process agent) token already carries
+ * its run's `sessionId`, so letting it mint a new thread mid-run would
+ * silently reset the one-ontology-per-conversation boundary.
+ *
+ * "External" is decided by the VERIFIER, not by which credential shape
+ * authenticated: a `bevel_…` connection key resolves external, and so does an
+ * `externalProxy` internal token — the loopback identity the MCP proxy mints
+ * for an OAuth/JWT MCP session, whose caller IS an external agent. (Gating on
+ * the raw credential shape used to 403 those sessions here, deadlocking them:
+ * they couldn't mint a sessionId, and every session-gated tool demands one.)
+ * Mount AFTER `toolAuth`. 403 (authenticated, but not authorized).
+ */
+export const requireExternalSource = (req, res, next) => {
+    if (req.toolAuth?.source !== 'external') {
+        res.status(403).json({ error: 'This tool is external-only.' });
+        return;
+    }
+    next();
+};
+/**
+ * The framework-agnostic verify core: bearer token (the value AFTER `Bearer `) →
+ * normalized `ToolAuth`, accepting EITHER a `bevel_…` connection key (external —
+ * pipeline-agent, MCP) OR an internal HMAC token (our own agent's loopback). A
+ * bare JWT / unknown scheme is refused. Throws only if the connection-key store
+ * itself errors (backend down); the caller maps that to 500. This is the shared
+ * primitive both `createToolAuthMiddleware` (our Express hosting) and
+ * `validateToken` (the tool-author SDK) are built on, so there is ONE auth path.
+ */
+export function createTokenVerifier(externalApiKeyService, internalTokenService) {
+    const missing = { ok: false, status: 401, message: 'A connection key or internal token is required' };
+    return async (token) => {
+        if (!token)
+            return missing;
+        // Internal token → in-process loopback caller. Usually our own agent
+        // (source 'internal'), EXCEPT the `externalProxy` tokens the MCP proxy
+        // mints as the loopback identity of an OAuth/JWT MCP session — that
+        // caller is an external agent and resolves as one, so external-only
+        // surfaces admit it and internal-only surfaces refuse it, exactly like a
+        // connection key (it just has no tokenId to meter on).
+        if (internalTokenService.looksLikeInternalToken(token)) {
+            const claim = internalTokenService.verify(token);
+            if (!claim)
+                return { ok: false, status: 401, message: 'Invalid or expired internal token' };
+            return claim.externalProxy
+                ? { ok: true, auth: { source: 'external', userId: claim.userId, scope: 'write' } }
+                : { ok: true, auth: { source: 'internal', userId: claim.userId, sessionId: claim.sessionId, scope: 'write' } };
+        }
+        // External API key → external caller. (verifyAndLoadToken may throw → propagates → caller maps to 500.)
+        if (externalApiKeyService.looksLikeExternalApiKey(token)) {
+            const resolved = await externalApiKeyService.verifyAndLoadToken(token);
+            return resolved
+                ? { ok: true, auth: { source: 'external', userId: resolved.user.id, tokenId: resolved.tokenId, scope: 'write' } }
+                : { ok: false, status: 401, message: 'Invalid or revoked connection key' };
+        }
+        return missing;
+    };
+}
+/**
+ * The one auth gate every tool endpoint applies — a THIN Express adapter over
+ * `createTokenVerifier`: parse the bearer header, run the shared verify core,
+ * normalize the result to `req.toolAuth` (or the matching status). All auth logic
+ * lives in the verifier; this only does header parsing + HTTP mapping.
+ */
+export function createToolAuthMiddleware(externalApiKeyService, internalTokenService) {
+    const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+    return async (req, res, next) => {
+        const header = req.headers.authorization;
+        if (!header || !header.toLowerCase().startsWith('bearer ')) {
+            res.setHeader('WWW-Authenticate', WWW_AUTH);
+            res.status(401).json({ error: 'Missing or invalid Authorization header' });
+            return;
+        }
+        const token = header.slice(header.indexOf(' ') + 1).trim();
+        try {
+            const result = await verify(token);
+            if (!result.ok) {
+                if (result.status === 401)
+                    res.setHeader('WWW-Authenticate', WWW_AUTH);
+                res.status(result.status).json({ error: result.message });
+                return;
+            }
+            req.toolAuth = result.auth;
+            next();
+        }
+        catch (err) {
+            console.error('[tools] connection-key verification failed:', err);
+            res.status(500).json({ error: 'Authentication backend unavailable' });
+        }
+    };
+}
+/**
+ * Auth gate for the READ-ONLY discovery manuals (`GET /agent/utcp` +
+ * `/agent/internal/utcp`) ONLY. Superset of `createToolAuthMiddleware`: it
+ * accepts a `bevel_…` connection key, an internal token, OR a browser JWT —
+ * the last resolving to `source: 'session'`. This is what lets a logged-in user
+ * browse the catalog with their existing session (the manual is just a spec, no
+ * secrets, and may become per-user — hence one user-aware endpoint rather than a
+ * parallel route). It is deliberately NOT used on tool-execution routes, so a
+ * JWT can read the manual but can never invoke a tool. The internal manual stays
+ * `requireInternalSource`-gated downstream, so a session/key is 403'd there.
+ */
+export function createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService) {
+    const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+    return async (req, res, next) => {
+        const header = req.headers.authorization;
+        if (!header || !header.toLowerCase().startsWith('bearer ')) {
+            res.setHeader('WWW-Authenticate', WWW_AUTH);
+            res.status(401).json({ error: 'Missing or invalid Authorization header' });
+            return;
+        }
+        const token = header.slice(header.indexOf(' ') + 1).trim();
+        // An external API key / internal token goes through the shared verify core.
+        if (internalTokenService.looksLikeInternalToken(token) || externalApiKeyService.looksLikeExternalApiKey(token)) {
+            try {
+                const result = await verify(token);
+                if (!result.ok) {
+                    if (result.status === 401)
+                        res.setHeader('WWW-Authenticate', WWW_AUTH);
+                    res.status(result.status).json({ error: result.message });
+                    return;
+                }
+                req.toolAuth = result.auth;
+                next();
+            }
+            catch (err) {
+                console.error('[tools] connection-key verification failed:', err);
+                res.status(500).json({ error: 'Authentication backend unavailable' });
+            }
+            return;
+        }
+        // Otherwise treat the bearer as a browser session JWT.
+        try {
+            const { userId } = authService.verifyToken(token);
+            req.toolAuth = { source: 'session', userId, scope: 'write' };
+            next();
+        }
+        catch {
+            res.setHeader('WWW-Authenticate', WWW_AUTH);
+            res.status(401).json({ error: 'Invalid or expired token' });
+        }
+    };
+}
+//# sourceMappingURL=tool-auth.middleware.js.map