@hotmeshio/long-tail 0.23.2 → 0.24.1

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

@@ -0,0 +1,88 @@
+import type { LTGrantPolicy, LTGrantSnapshot, LTGrantSummary, LTOAuthClient } from '../../../types/oauth-server';
+/** A refresh token reused within this many seconds is treated as a client retry. */
+export declare const REFRESH_REUSE_GRACE_SECONDS = 10;
+export interface RevokedGrant {
+    grant_id: string;
+    user_id: string;
+}
+/** A new random secret: 32 bytes, base64url. */
+export declare function createSecret(): string;
+/** SHA-256 of a secret. Codes and refresh tokens are stored only as hashes. */
+export declare function hashSecret(secret: string): string;
+/** The PKCE S256 challenge for a code verifier (RFC 7636). */
+export declare function pkceChallenge(verifier: string): string;
+export declare function registerClient(input: {
+    clientName?: string;
+    redirectUris: string[];
+}): Promise<LTOAuthClient>;
+export declare const isClientId: (value: string) => boolean;
+export declare function getClient(clientId: string): Promise<LTOAuthClient | null>;
+/** Record the person's consent as a grant and return a one-time code for it. */
+export declare function issueAuthorizationCode(input: {
+    userId: string;
+    clientId: string;
+    policy: LTGrantPolicy;
+    scope: string;
+    redirectUri: string;
+    codeChallenge: string;
+    resource?: string;
+    ttlSeconds: number;
+}): Promise<{
+    code: string;
+    grantId: string;
+}>;
+/**
+ * Exchange a code for the grant and its first refresh token. Null when the
+ * code is unknown, used, expired, for another client or redirect URI, fails
+ * PKCE, or its grant or owner is no longer active. A code presented again
+ * after its exchange revokes its grant.
+ */
+export declare function exchangeAuthorizationCode(input: {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+    refreshTtlSeconds: number;
+}): Promise<{
+    snapshot: LTGrantSnapshot;
+    resource: string | null;
+    refreshToken: string;
+} | null>;
+/**
+ * Rotate a refresh token for the client that holds it. Null when it is
+ * unknown, used, expired, another client's, or its grant or owner is no
+ * longer active. A used token presented again outside the
+ * grace window revokes its grant, and `revoked` reports it.
+ */
+export declare function rotateRefreshToken(input: {
+    refreshToken: string;
+    clientId: string;
+    refreshTtlSeconds: number;
+}): Promise<{
+    snapshot: LTGrantSnapshot;
+    refreshToken: string;
+} | {
+    snapshot: null;
+    revoked: RevokedGrant | null;
+}>;
+/** The live grant an access token names; null when it is revoked, its owner inactive, or it is another user's. */
+export declare function getLiveGrant(grantId: string, userId: string): Promise<LTGrantSnapshot | null>;
+/** Revoke the grant behind a refresh token presented by its own client (RFC 7009). */
+export declare function revokeByRefreshToken(refreshToken: string, clientId: string): Promise<RevokedGrant | null>;
+/** Revoke a grant; with `userId`, only when it belongs to that user. */
+export declare function revokeGrant(grantId: string, userId?: string): Promise<RevokedGrant | null>;
+/** The person's live grants that a client has put to use. */
+export declare function listGrants(userId: string): Promise<LTGrantSummary[]>;
+export interface OAuthPruneCounts {
+    refreshTokens: number;
+    codes: number;
+    grants: number;
+    clients: number;
+}
+/**
+ * Delete what the authorization server no longer needs, older than the
+ * window (a Postgres interval): spent and expired refresh tokens and codes,
+ * then grants with neither left or revoked, then clients with no live grant.
+ * Each step reads what the one before it left.
+ */
+export declare function pruneOAuthServer(olderThan: string): Promise<OAuthPruneCounts>;

package/build/services/auth/oauth-server/store.js

@@ -0,0 +1,171 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isClientId = exports.REFRESH_REUSE_GRACE_SECONDS = void 0;
+exports.createSecret = createSecret;
+exports.hashSecret = hashSecret;
+exports.pkceChallenge = pkceChallenge;
+exports.registerClient = registerClient;
+exports.getClient = getClient;
+exports.issueAuthorizationCode = issueAuthorizationCode;
+exports.exchangeAuthorizationCode = exchangeAuthorizationCode;
+exports.rotateRefreshToken = rotateRefreshToken;
+exports.getLiveGrant = getLiveGrant;
+exports.revokeByRefreshToken = revokeByRefreshToken;
+exports.revokeGrant = revokeGrant;
+exports.listGrants = listGrants;
+exports.pruneOAuthServer = pruneOAuthServer;
+const crypto = __importStar(require("crypto"));
+const db_1 = require("../../../lib/db");
+const uuid_1 = require("../../../lib/uuid");
+const sql_1 = require("./sql");
+/** A refresh token reused within this many seconds is treated as a client retry. */
+exports.REFRESH_REUSE_GRACE_SECONDS = 10;
+/** A new random secret: 32 bytes, base64url. */
+function createSecret() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+/** SHA-256 of a secret. Codes and refresh tokens are stored only as hashes. */
+function hashSecret(secret) {
+    return crypto.createHash('sha256').update(secret).digest('hex');
+}
+/** The PKCE S256 challenge for a code verifier (RFC 7636). */
+function pkceChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+async function registerClient(input) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.INSERT_CLIENT, [
+        `ltc_${createSecret()}`, input.clientName ?? null, input.redirectUris,
+    ]);
+    return rows[0];
+}
+/** A client id as registerClient issues it; anything else names no client and never reaches SQL. */
+const CLIENT_ID = /^ltc_[A-Za-z0-9_-]{43}$/;
+const isClientId = (value) => CLIENT_ID.test(value);
+exports.isClientId = isClientId;
+async function getClient(clientId) {
+    if (!(0, exports.isClientId)(clientId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_CLIENT, [clientId]);
+    return rows[0] ?? null;
+}
+/** Record the person's consent as a grant and return a one-time code for it. */
+async function issueAuthorizationCode(input) {
+    if (!(0, uuid_1.isUuid)(input.userId))
+        throw new Error('issueAuthorizationCode: userId must be a UUID');
+    const code = createSecret();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.ISSUE_CODE, [
+        input.userId, input.clientId, input.policy, input.scope,
+        hashSecret(code), input.redirectUri, input.codeChallenge, input.resource ?? null, input.ttlSeconds,
+    ]);
+    return { code, grantId: rows[0].grant_id };
+}
+/**
+ * Exchange a code for the grant and its first refresh token. Null when the
+ * code is unknown, used, expired, for another client or redirect URI, fails
+ * PKCE, or its grant or owner is no longer active. A code presented again
+ * after its exchange revokes its grant.
+ */
+async function exchangeAuthorizationCode(input) {
+    const pool = (0, db_1.getPool)();
+    const refreshToken = createSecret();
+    const codeHash = hashSecret(input.code);
+    const { rows } = await pool.query(sql_1.EXCHANGE_CODE, [
+        codeHash, input.clientId, input.redirectUri, pkceChallenge(input.codeVerifier),
+        hashSecret(refreshToken), input.refreshTtlSeconds,
+    ]);
+    if (!rows[0]) {
+        await pool.query(sql_1.REVOKE_ON_CODE_REUSE, [codeHash]);
+        return null;
+    }
+    const { resource, ...snapshot } = rows[0];
+    return { snapshot, resource, refreshToken };
+}
+/**
+ * Rotate a refresh token for the client that holds it. Null when it is
+ * unknown, used, expired, another client's, or its grant or owner is no
+ * longer active. A used token presented again outside the
+ * grace window revokes its grant, and `revoked` reports it.
+ */
+async function rotateRefreshToken(input) {
+    const pool = (0, db_1.getPool)();
+    const next = createSecret();
+    const oldHash = hashSecret(input.refreshToken);
+    const { rows } = await pool.query(sql_1.ROTATE_REFRESH_TOKEN, [oldHash, hashSecret(next), input.refreshTtlSeconds, input.clientId]);
+    if (rows[0])
+        return { snapshot: rows[0], refreshToken: next };
+    const reuse = await pool.query(sql_1.REVOKE_ON_REFRESH_REUSE, [oldHash, exports.REFRESH_REUSE_GRACE_SECONDS]);
+    return { snapshot: null, revoked: reuse.rows[0] ?? null };
+}
+/** The live grant an access token names; null when it is revoked, its owner inactive, or it is another user's. */
+async function getLiveGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || !(0, uuid_1.isUuid)(userId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_LIVE_GRANT, [grantId, userId]);
+    return rows[0] ?? null;
+}
+/** Revoke the grant behind a refresh token presented by its own client (RFC 7009). */
+async function revokeByRefreshToken(refreshToken, clientId) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_BY_REFRESH_TOKEN, [hashSecret(refreshToken), clientId]);
+    return rows[0] ?? null;
+}
+/** Revoke a grant; with `userId`, only when it belongs to that user. */
+async function revokeGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || (userId !== undefined && !(0, uuid_1.isUuid)(userId)))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_GRANT, [grantId, userId ?? null]);
+    return rows[0] ?? null;
+}
+/** The person's live grants that a client has put to use. */
+async function listGrants(userId) {
+    if (!(0, uuid_1.isUuid)(userId))
+        return [];
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_GRANTS, [userId]);
+    return rows;
+}
+/**
+ * Delete what the authorization server no longer needs, older than the
+ * window (a Postgres interval): spent and expired refresh tokens and codes,
+ * then grants with neither left or revoked, then clients with no live grant.
+ * Each step reads what the one before it left.
+ */
+async function pruneOAuthServer(olderThan) {
+    const pool = (0, db_1.getPool)();
+    const refreshTokens = (await pool.query(sql_1.PRUNE_REFRESH_TOKENS, [olderThan])).rowCount ?? 0;
+    const codes = (await pool.query(sql_1.PRUNE_CODES, [olderThan])).rowCount ?? 0;
+    const grants = (await pool.query(sql_1.PRUNE_GRANTS, [olderThan])).rowCount ?? 0;
+    const clients = (await pool.query(sql_1.PRUNE_CLIENTS, [olderThan])).rowCount ?? 0;
+    return { refreshTokens, codes, grants, clients };
+}

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

@@ -3,6 +3,7 @@ export declare const GET_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, key_h
 export declare const GET_ALL_ACTIVE_BOT_KEYS = "\n  SELECT id, name, user_id, key_hash, scopes\n  FROM lt_bot_api_keys\n  WHERE (expires_at IS NULL OR expires_at > NOW())";
 export declare const UPDATE_BOT_KEY_LAST_USED = "\n  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1";
 export declare const DELETE_BOT_KEY = "\n  DELETE FROM lt_bot_api_keys WHERE id = $1";
+export declare const GET_BOT_KEY_OWNER = "\n  SELECT user_id FROM lt_bot_api_keys WHERE id = $1";
 export declare const LIST_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at\n  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at";
 export declare const INSERT_SERVICE_TOKEN = "\n  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)\n  VALUES ($1, $2, $3, $4, $5) RETURNING id";
 export declare const GET_ALL_ACTIVE_SERVICE_TOKENS = "\n  SELECT id, name, token_hash FROM lt_service_tokens\n  WHERE (expires_at IS NULL OR expires_at > NOW())";

package/build/services/auth/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ── Bot API key queries ─────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
+exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.GET_BOT_KEY_OWNER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
 exports.INSERT_BOT_KEY = `
   INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
   VALUES ($1, $2, $3, $4, $5) RETURNING id`;
@@ -18,6 +18,8 @@ exports.UPDATE_BOT_KEY_LAST_USED = `
   UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
 exports.DELETE_BOT_KEY = `
   DELETE FROM lt_bot_api_keys WHERE id = $1`;
+exports.GET_BOT_KEY_OWNER = `
+  SELECT user_id FROM lt_bot_api_keys WHERE id = $1`;
 exports.LIST_BOT_KEYS_BY_USER = `
   SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
   FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;

package/build/services/cron/index.js

@@ -65,6 +65,7 @@ function validateCronSchedule(expr) {
 const CRON_TOPIC_PREFIX = 'lt.cron';
 const CRON_ID_PREFIX = 'lt-cron';
 const YAML_CRON_TOPIC_PREFIX = 'lt.cron.yaml';
+const CRON_SOURCE = 'cron';
 const YAML_CRON_ID_PREFIX = 'lt-cron-yaml';
 /**
  * Singleton registry for workflow cron schedules.
@@ -241,9 +242,10 @@ class LTCronRegistry {
                 try {
                     cronCallCount++;
                     logger_1.loggerRegistry.info(`[lt-cron] tick #${cronCallCount} at ${new Date().toISOString()} — pub(${appId}/${graphTopic})`);
-                    const { getEngine } = await Promise.resolve().then(() => __importStar(require('../yaml-workflow/deployer')));
-                    const engine = await getEngine(appId);
-                    await engine.pub(graphTopic, cronEnvelope, undefined, { entity: graphTopic });
+                    // Through the invoke service, so the run carries only the scope the
+                    // server resolves for execute_as, never one written in the envelope.
+                    const { invokeYamlWorkflow } = await Promise.resolve().then(() => __importStar(require('../yaml-workflow/invoke')));
+                    await invokeYamlWorkflow(wf, { data: cronEnvelope, execute_as: wf.execute_as ?? undefined, source: CRON_SOURCE });
                     logger_1.loggerRegistry.info(`[lt-cron] tick #${cronCallCount} published successfully`);
                 }
                 catch (err) {

package/build/services/escalation/queries.js

@@ -278,8 +278,13 @@ async function listDistinctTypes() {
  * and an out-of-scope role yields an empty result, not someone else's rows.
  */
 function narrowRoleWithinScope(role, visibleRoles) {
-    if (!role || !visibleRoles)
-        return { role, roles: visibleRoles, empty: false };
+    if (!visibleRoles)
+        return { role, roles: undefined, empty: false };
+    // An empty scope sees nothing; the SDK would read an empty list as no filter.
+    if (visibleRoles.length === 0)
+        return { empty: true };
+    if (!role)
+        return { roles: visibleRoles, empty: false };
     if (!visibleRoles.includes(role))
         return { empty: true };
     return { role, roles: undefined, empty: false };

package/build/services/export/index.d.ts

@@ -48,6 +48,16 @@ export interface WorkflowEnvelopes {
  * so, making this the natural polling body.
  */
 export declare function getWorkflowEnvelopes(workflowId: string, taskQueue: string, workflowName: string): Promise<WorkflowEnvelopes>;
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+export declare function getWorkflowStartIdentity(workflowId: string): Promise<{
+    userId?: string;
+    initiatedBy?: string;
+} | null>;
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/export/index.js

@@ -4,11 +4,13 @@ exports.exportWorkflow = exportWorkflow;
 exports.getWorkflowStatus = getWorkflowStatus;
 exports.exportWorkflowExecution = exportWorkflowExecution;
 exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
+exports.getWorkflowStartIdentity = getWorkflowStartIdentity;
 exports.getWorkflowState = getWorkflowState;
 exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const client_1 = require("./client");
+const resolve_1 = require("../task/resolve");
 const post_process_1 = require("./post-process");
 const workflow_state_1 = require("../workflow-state");
 /** Error thrown when a workflow job is not found (expired or never existed). */
@@ -123,6 +125,31 @@ async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
     const output = await handle.output().catch(() => null);
     return { workflow_id: workflowId, status: reading.state, input, output: output ?? null };
 }
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+async function getWorkflowStartIdentity(workflowId) {
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveWorkflowHandle)(workflowId);
+    }
+    catch {
+        return null;
+    }
+    const handle = await (0, client_1.getHandle)(resolved.taskQueue, resolved.workflowName, workflowId);
+    const args = await handle.input().catch(() => undefined);
+    const envelope = Array.isArray(args) && args.length >= 1 ? args[0] : null;
+    const lt = (envelope && typeof envelope === 'object' ? envelope.lt : null) ?? null;
+    if (!lt)
+        return {};
+    return {
+        ...(typeof lt.userId === 'string' ? { userId: lt.userId } : {}),
+        ...(typeof lt.initiatedBy === 'string' ? { initiatedBy: lt.initiatedBy } : {}),
+    };
+}
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/invocation-access.d.ts

@@ -8,11 +8,32 @@ export declare const INVOCATION_ROLE_TYPES: {
     readonly ADMIN: "admin";
 };
 export declare const ADMIN_ROLE = "admin";
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+/** The workflow that calls a named MCP tool with lt-system authority. */
+export declare const CAPABILITY_INVOKE_WORKFLOW = "capabilityInvoke";
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+export declare const SYSTEM_AUTHORITY_WORKFLOWS: ReadonlySet<string>;
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+export declare function mayActAs(caller: readonly InvocationRoleGrant[], target: readonly InvocationRoleGrant[]): boolean;
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[]): boolean;
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'>, roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'> & {
+    workflow_type?: string;
+}, roles: readonly InvocationRoleGrant[]): boolean;

package/build/services/invocation-access.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.SYSTEM_AUTHORITY_WORKFLOWS = exports.CAPABILITY_INVOKE_WORKFLOW = exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.mayActAs = mayActAs;
 exports.hasGlobalInvocationAccess = hasGlobalInvocationAccess;
 exports.canInvokeWorkflow = canInvokeWorkflow;
 exports.INVOCATION_ROLE_TYPES = {
@@ -8,24 +9,55 @@ exports.INVOCATION_ROLE_TYPES = {
     ADMIN: 'admin',
 };
 exports.ADMIN_ROLE = 'admin';
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-function hasGlobalInvocationAccess(roles, authRole) {
-    if (authRole === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
+/** The workflow that calls a named MCP tool with lt-system authority. */
+exports.CAPABILITY_INVOKE_WORKFLOW = 'capabilityInvoke';
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+exports.SYSTEM_AUTHORITY_WORKFLOWS = new Set([exports.CAPABILITY_INVOKE_WORKFLOW]);
+const ROLE_TYPE_RANK = { member: 1, admin: 2, superadmin: 3 };
+function holdsSuperadmin(roles) {
+    return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN);
+}
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+function mayActAs(caller, target) {
+    if (holdsSuperadmin(caller))
         return true;
+    if (!caller.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.ADMIN))
+        return false;
+    if (holdsSuperadmin(target))
+        return false;
+    return target.every((t) => caller.some((c) => c.role === t.role && (ROLE_TYPE_RANK[c.type] ?? 0) >= (ROLE_TYPE_RANK[t.type] ?? 0)));
+}
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+function hasGlobalInvocationAccess(roles) {
     return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
         || roles.some((r) => r.role === exports.ADMIN_ROLE && r.type === exports.INVOCATION_ROLE_TYPES.ADMIN);
 }
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-function canInvokeWorkflow(config, roles, authRole) {
+function canInvokeWorkflow(config, roles) {
     if (!config.invocable)
         return false;
+    if (config.workflow_type && exports.SYSTEM_AUTHORITY_WORKFLOWS.has(config.workflow_type))
+        return holdsSuperadmin(roles);
     if (config.invocation_roles.length === 0)
         return true;
-    if (hasGlobalInvocationAccess(roles, authRole))
+    if (hasGlobalInvocationAccess(roles))
         return true;
     const held = new Set(roles.map((r) => r.role));
     return config.invocation_roles.some((r) => held.has(r));

package/build/services/maintenance/index.js

@@ -106,6 +106,14 @@ async function executeRule(appId, rule) {
             }
             break;
         }
+        // Drop the authorization server's dead rows: spent or expired tokens and
+        // codes, grants with neither left or long revoked, clients with no live grant.
+        case rule.target === 'oauth' && rule.action === 'delete': {
+            const { pruneOAuthServer } = await Promise.resolve().then(() => __importStar(require('../auth/oauth-server')));
+            const counts = await pruneOAuthServer(rule.olderThan);
+            logger_1.loggerRegistry.info(`[lt-maintenance] oauth pruned: ${JSON.stringify(counts)} (olderThan: ${rule.olderThan})`);
+            break;
+        }
         default:
             logger_1.loggerRegistry.warn(`[lt-maintenance] unknown rule, skipping: ${JSON.stringify(rule)}`);
     }

package/build/services/mcp/client/connection-dispatch.d.ts

@@ -8,7 +8,12 @@ import type { LTMcpToolManifest } from '../../../types';
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>): Promise<{
+export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>, extra?: {
+    authInfo?: {
+        userId: string;
+        role?: string;
+    };
+}): Promise<{
     dispatched: true;
     result: any;
 } | null>;

package/build/services/mcp/client/connection-dispatch.js

@@ -13,7 +13,7 @@ const connection_lifecycle_1 = require("./connection-lifecycle");
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-async function dispatchBuiltinTool(serverId, toolName, args) {
+async function dispatchBuiltinTool(serverId, toolName, args, extra) {
     const builtinFactories = (0, connection_lifecycle_1.getBuiltinFactories)();
     const builtinServers = (0, connection_lifecycle_1.getBuiltinServers)();
     // Normalize and match against builtin factories
@@ -43,7 +43,8 @@ async function dispatchBuiltinTool(serverId, toolName, args) {
     // Call the handler directly — no transport, no JSON-RPC.
     // Tool handlers return MCP-shaped responses: { content: [{ type: 'text', text: '...' }] }
     // Parse the text content the same way callServerTool does.
-    const mcpResponse = await tool.handler(args);
+    // With `extra`, the handler sees an external caller and acts as them.
+    const mcpResponse = extra ? await tool.handler(args, extra) : await tool.handler(args);
     let parsed = mcpResponse;
     if (mcpResponse && Array.isArray(mcpResponse.content)) {
         const textContent = mcpResponse.content.find((c) => c.type === 'text');

package/build/services/mcp/client/connection-lifecycle.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { LTMcpServerRecord } from '../../../types';
+import type { LTMcpServerRecord, LTToolManifestEntry } from '../../../types';
 /** Read-only access to the clients map for sibling modules. */
 export declare function getClients(): Map<string, Client>;
 /** Read-only access to the builtin factories map for sibling modules. */
@@ -10,7 +10,9 @@ export declare function getBuiltinServers(): Map<string, any>;
  * Register a built-in server factory so it can be auto-connected
  * when callServerTool is invoked with its name.
  */
-export declare function registerBuiltinServer(name: string, factory: () => Promise<any>): void;
+export declare function registerBuiltinServer(name: string, factory: () => Promise<any>, toolManifest?: LTToolManifestEntry[]): void;
+/** The tool manifest a built-in server was registered with, if any. */
+export declare function getBuiltinToolManifest(name: string): LTToolManifestEntry[] | undefined;
 /**
  * Connect to a registered MCP server.
  * Creates the appropriate transport based on transport_type,
@@ -29,6 +31,12 @@ export declare function disconnectFromServer(serverId: string): Promise<void>;
  * Alias lookups (e.g. 'translation' matching 'long-tail-translation') reuse
  * the same client instance to avoid double-connecting the singleton server.
  */
+/**
+ * The built-in server a server id or name resolves to, by the same rules
+ * resolveClient follows: an exact or fuzzy factory name, else a registered
+ * server whose name matches a factory. Null for an external server.
+ */
+export declare function resolveBuiltinServerName(serverId: string): Promise<string | null>;
 export declare function resolveClient(serverId: string): Promise<Client | null>;
 /**
  * Connect to all auto-connect servers.