@hotmeshio/long-tail 0.1.0

package/build/services/iam/activity.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Identity and credential access for proxy activities.
+ *
+ * Activities call `getActivityIdentity()` to read the principal
+ * injected by the activity interceptor and to resolve provider
+ * credentials (OAuth tokens, API keys) via the credential cascade.
+ *
+ * @example Single-identity — activity runs as the invoking user or bot
+ * ```typescript
+ * import { getActivityIdentity } from '../services/iam/activity';
+ *
+ * export async function sendEmail(input: { to: string; body: string }) {
+ *   const identity = getActivityIdentity();
+ *   const gmailToken = await identity.getCredential('google');
+ *   // identity.principal has id, type, roles, displayName
+ * }
+ * ```
+ *
+ * @example Dual-identity — bot executes but needs the invoking user's credential
+ * ```typescript
+ * export async function readUserMail(input: { query: string }) {
+ *   const identity = getActivityIdentity();
+ *   // getCredential checks the bot first, then falls back to the
+ *   // human invoker's stored token (e.g., their Gmail OAuth)
+ *   const gmailToken = await identity.getCredential('google');
+ *   // identity.initiatingPrincipal has the human's profile
+ * }
+ * ```
+ */
+import type { ToolContext, ToolPrincipal } from '../../types/tool-context';
+/** Identity and credential access returned by `getActivityIdentity()`. */
+export interface ActivityIdentity {
+    /** The executing principal (user or bot). */
+    principal: ToolPrincipal;
+    /** The original human invoker when proxy invocation is used (undefined if no proxy). */
+    initiatingPrincipal?: ToolPrincipal;
+    /** Scopes granted for this invocation (e.g., 'workflow:invoke'). */
+    scopes: string[];
+    /**
+     * Resolve a provider credential via the credential cascade.
+     * Tries: executing principal → initiating principal → system env var.
+     * Throws MissingCredentialError if none found.
+     */
+    getCredential(provider: string, label?: string): Promise<string>;
+    /** Full ToolContext (trace IDs, delegation token, etc.). */
+    toolContext: ToolContext;
+}
+/**
+ * Returns the identity context for the current proxy activity.
+ * @throws Error if called outside an interceptor-wrapped activity.
+ */
+export declare function getActivityIdentity(): ActivityIdentity;

package/build/services/iam/activity.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Identity and credential access for proxy activities.
+ *
+ * Activities call `getActivityIdentity()` to read the principal
+ * injected by the activity interceptor and to resolve provider
+ * credentials (OAuth tokens, API keys) via the credential cascade.
+ *
+ * @example Single-identity — activity runs as the invoking user or bot
+ * ```typescript
+ * import { getActivityIdentity } from '../services/iam/activity';
+ *
+ * export async function sendEmail(input: { to: string; body: string }) {
+ *   const identity = getActivityIdentity();
+ *   const gmailToken = await identity.getCredential('google');
+ *   // identity.principal has id, type, roles, displayName
+ * }
+ * ```
+ *
+ * @example Dual-identity — bot executes but needs the invoking user's credential
+ * ```typescript
+ * export async function readUserMail(input: { query: string }) {
+ *   const identity = getActivityIdentity();
+ *   // getCredential checks the bot first, then falls back to the
+ *   // human invoker's stored token (e.g., their Gmail OAuth)
+ *   const gmailToken = await identity.getCredential('google');
+ *   // identity.initiatingPrincipal has the human's profile
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActivityIdentity = getActivityIdentity;
+const context_1 = require("./context");
+const credentials_1 = require("./credentials");
+/**
+ * Returns the identity context for the current proxy activity.
+ * @throws Error if called outside an interceptor-wrapped activity.
+ */
+function getActivityIdentity() {
+    const ctx = (0, context_1.getToolContext)();
+    if (!ctx) {
+        throw new Error('No IAM context available. Is this running inside a proxy activity with the LT interceptor?');
+    }
+    return {
+        principal: ctx.principal,
+        initiatingPrincipal: ctx.initiatingPrincipal,
+        scopes: ctx.credentials.scopes,
+        toolContext: ctx,
+        async getCredential(provider, label) {
+            const resolved = await (0, credentials_1.resolveCredential)(ctx.principal, provider, label, {
+                fallbackPrincipal: ctx.initiatingPrincipal,
+            });
+            if (!resolved) {
+                throw new credentials_1.MissingCredentialError(provider);
+            }
+            return resolved.value;
+        },
+    };
+}

package/build/services/iam/bots.d.ts

@@ -0,0 +1,83 @@
+import { addUserRole, removeUserRole, getUserRoles } from '../user';
+import type { LTUserRecord, LTRoleType } from '../../types';
+import { listBotApiKeys, revokeBotApiKey } from '../auth/bot-api-key';
+import type { BotApiKeyRecord } from '../auth/bot-api-key';
+export type { BotApiKeyRecord };
+export interface CreateBotInput {
+    /** Unique identifier (used as external_id). */
+    name: string;
+    /** Human-readable description of the bot's purpose. */
+    description?: string;
+    /** Display name shown in audit logs. */
+    display_name?: string;
+    /** Initial roles to assign. */
+    roles?: Array<{
+        role: string;
+        type: LTRoleType;
+    }>;
+    /** ID of the user creating this bot (for audit). */
+    created_by?: string;
+}
+export interface BotAccountRecord extends LTUserRecord {
+    /** Always 'bot' for bot accounts. */
+    account_type: 'bot';
+    /** Description from metadata. */
+    description?: string;
+    /** Who created this bot. */
+    created_by?: string;
+}
+/**
+ * Create a new bot account.
+ */
+export declare function createBot(input: CreateBotInput): Promise<BotAccountRecord>;
+/**
+ * Get a single bot account by ID.
+ */
+export declare function getBot(id: string): Promise<BotAccountRecord | null>;
+/**
+ * List all bot accounts with pagination.
+ */
+export declare function listBots(limit?: number, offset?: number): Promise<{
+    bots: BotAccountRecord[];
+    total: number;
+}>;
+/**
+ * Update a bot account.
+ */
+export declare function updateBot(id: string, input: {
+    display_name?: string;
+    description?: string;
+    status?: string;
+}): Promise<BotAccountRecord | null>;
+/**
+ * Deactivate a bot account (sets status to 'inactive').
+ */
+export declare function deactivateBot(id: string): Promise<boolean>;
+/**
+ * Delete a bot account and all its API keys (cascaded).
+ */
+export declare function deleteBot(id: string): Promise<boolean>;
+/**
+ * Generate a new API key for a bot.
+ */
+export declare function createBotKey(botId: string, name: string, scopes?: string[], expiresAt?: Date): Promise<{
+    id: string;
+    rawKey: string;
+}>;
+/**
+ * List API keys for a bot (without hashes).
+ */
+export { listBotApiKeys as listBotKeys };
+/**
+ * Revoke a bot API key.
+ */
+export { revokeBotApiKey as revokeBotKey };
+export { addUserRole as addBotRole };
+export { removeUserRole as removeBotRole };
+export { getUserRoles as getBotRoles };
+/**
+ * Ensure the system bot account exists.
+ * Called at startup so cron and system-initiated workflows
+ * always have a principal (the `lt-system` bot).
+ */
+export declare function ensureSystemBot(): Promise<string>;

package/build/services/iam/bots.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBotRoles = exports.removeBotRole = exports.addBotRole = exports.revokeBotKey = exports.listBotKeys = void 0;
+exports.createBot = createBot;
+exports.getBot = getBot;
+exports.listBots = listBots;
+exports.updateBot = updateBot;
+exports.deactivateBot = deactivateBot;
+exports.deleteBot = deleteBot;
+exports.createBotKey = createBotKey;
+exports.ensureSystemBot = ensureSystemBot;
+/**
+ * Bot account management.
+ *
+ * Bot accounts are rows in lt_users with account_type = 'bot'.
+ * They share the same RBAC, OAuth credentials, and delegation tokens
+ * as human users — no separate infrastructure needed.
+ */
+const db_1 = require("../db");
+const user_1 = require("../user");
+const user_2 = require("../user");
+Object.defineProperty(exports, "addBotRole", { enumerable: true, get: function () { return user_2.addUserRole; } });
+Object.defineProperty(exports, "removeBotRole", { enumerable: true, get: function () { return user_2.removeUserRole; } });
+Object.defineProperty(exports, "getBotRoles", { enumerable: true, get: function () { return user_2.getUserRoles; } });
+const bot_api_key_1 = require("../auth/bot-api-key");
+Object.defineProperty(exports, "listBotKeys", { enumerable: true, get: function () { return bot_api_key_1.listBotApiKeys; } });
+Object.defineProperty(exports, "revokeBotKey", { enumerable: true, get: function () { return bot_api_key_1.revokeBotApiKey; } });
+const LIST_BOTS = `
+  SELECT * FROM lt_users
+  WHERE account_type = 'bot'
+  ORDER BY created_at DESC
+  LIMIT $1 OFFSET $2`;
+const COUNT_BOTS = `
+  SELECT COUNT(*)::int AS total FROM lt_users WHERE account_type = 'bot'`;
+/**
+ * Create a new bot account.
+ */
+async function createBot(input) {
+    const userInput = {
+        external_id: input.name,
+        display_name: input.display_name ?? input.name,
+        roles: input.roles,
+        metadata: {
+            account_type: 'bot',
+            description: input.description,
+            created_by: input.created_by,
+        },
+    };
+    // Create the user row, then set account_type column
+    const user = await (0, user_1.createUser)(userInput);
+    const pool = await (0, db_1.getPool)();
+    await pool.query('UPDATE lt_users SET account_type = $1 WHERE id = $2', ['bot', user.id]);
+    return toBotRecord(user, input.description, input.created_by);
+}
+/**
+ * Get a single bot account by ID.
+ */
+async function getBot(id) {
+    const user = await (0, user_1.getUser)(id);
+    if (!user || user.metadata?.account_type !== 'bot')
+        return null;
+    return toBotRecord(user);
+}
+/**
+ * List all bot accounts with pagination.
+ */
+async function listBots(limit = 50, offset = 0) {
+    const pool = await (0, db_1.getPool)();
+    const [{ rows }, countResult] = await Promise.all([
+        pool.query(LIST_BOTS, [limit, offset]),
+        pool.query(COUNT_BOTS),
+    ]);
+    // Attach roles to each bot
+    const bots = await Promise.all(rows.map(async (row) => {
+        const roles = await (0, user_2.getUserRoles)(row.id);
+        return toBotRecord({ ...row, roles });
+    }));
+    return { bots, total: countResult.rows[0].total };
+}
+/**
+ * Update a bot account.
+ */
+async function updateBot(id, input) {
+    const existing = await getBot(id);
+    if (!existing)
+        return null;
+    const metadata = {
+        ...(existing.metadata || {}),
+        ...(input.description !== undefined ? { description: input.description } : {}),
+    };
+    const user = await (0, user_1.updateUser)(id, {
+        display_name: input.display_name,
+        status: input.status,
+        metadata,
+    });
+    if (!user)
+        return null;
+    return toBotRecord(user);
+}
+/**
+ * Deactivate a bot account (sets status to 'inactive').
+ */
+async function deactivateBot(id) {
+    const bot = await getBot(id);
+    if (!bot)
+        return false;
+    const updated = await (0, user_1.updateUser)(id, { status: 'inactive' });
+    return !!updated;
+}
+/**
+ * Delete a bot account and all its API keys (cascaded).
+ */
+async function deleteBot(id) {
+    const bot = await getBot(id);
+    if (!bot)
+        return false;
+    return (0, user_1.deleteUser)(id);
+}
+// ── Bot API key management ─────────────────────────────────────────────────
+/**
+ * Generate a new API key for a bot.
+ */
+async function createBotKey(botId, name, scopes = [], expiresAt) {
+    const bot = await getBot(botId);
+    if (!bot)
+        throw new Error('Bot not found');
+    return (0, bot_api_key_1.generateBotApiKey)(name, botId, scopes, expiresAt);
+}
+// ── System bot ─────────────────────────────────────────────────────────────
+const SYSTEM_BOT_NAME = 'lt-system';
+/**
+ * Ensure the system bot account exists.
+ * Called at startup so cron and system-initiated workflows
+ * always have a principal (the `lt-system` bot).
+ */
+async function ensureSystemBot() {
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query('SELECT id FROM lt_users WHERE external_id = $1', [SYSTEM_BOT_NAME]);
+    if (rows.length > 0)
+        return rows[0].id;
+    const bot = await createBot({
+        name: SYSTEM_BOT_NAME,
+        display_name: 'System',
+        description: 'System bot for cron and system-initiated workflows',
+        roles: [{ role: 'system', type: 'superadmin' }],
+    });
+    return bot.id;
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function toBotRecord(user, description, createdBy) {
+    return {
+        ...user,
+        account_type: 'bot',
+        description: description ?? user.metadata?.description,
+        created_by: createdBy ?? user.metadata?.created_by,
+    };
+}

package/build/services/iam/context.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from '../../types/tool-context';
+/**
+ * Run a function with ToolContext available via `getToolContext()`.
+ * Called by the interceptor to wrap workflow execution.
+ */
+export declare function runWithToolContext<T>(ctx: ToolContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Retrieve the ToolContext for the current execution scope.
+ *
+ * Activities: reads from argumentMetadata (injected by activity interceptor).
+ * Workflow scope: reads from AsyncLocalStorage (set by workflow interceptor).
+ * Returns undefined when no identity is available.
+ */
+export declare function getToolContext(): ToolContext | undefined;

package/build/services/iam/context.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithToolContext = runWithToolContext;
+exports.getToolContext = getToolContext;
+/**
+ * ToolContext access for activities and workflow-scoped code.
+ *
+ * Two paths, checked in order:
+ *
+ * 1. **argumentMetadata** (production-safe, distributed):
+ *    The activity interceptor injects `principal` + `scopes` into
+ *    `argumentMetadata`, which HotMesh delivers to the activity worker
+ *    via `Durable.activity.getContext()`. Works across process boundaries.
+ *
+ * 2. **AsyncLocalStorage** (workflow-local, single-process):
+ *    The workflow interceptor wraps `next()` with `runWithToolContext()`
+ *    for code running in the workflow's own async scope (e.g., MCP server
+ *    tools called directly, not via proxy activities).
+ */
+const async_hooks_1 = require("async_hooks");
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const store = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Run a function with ToolContext available via `getToolContext()`.
+ * Called by the interceptor to wrap workflow execution.
+ */
+function runWithToolContext(ctx, fn) {
+    return store.run(ctx, fn);
+}
+/**
+ * Retrieve the ToolContext for the current execution scope.
+ *
+ * Activities: reads from argumentMetadata (injected by activity interceptor).
+ * Workflow scope: reads from AsyncLocalStorage (set by workflow interceptor).
+ * Returns undefined when no identity is available.
+ */
+function getToolContext() {
+    // 1. Try argumentMetadata (activity worker — works distributed)
+    try {
+        const actCtx = hotmesh_1.Durable.activity.getContext();
+        const meta = actCtx?.argumentMetadata;
+        if (meta?.principal) {
+            const principal = meta.principal;
+            return {
+                principal,
+                ...(meta.initiatingPrincipal
+                    ? { initiatingPrincipal: meta.initiatingPrincipal }
+                    : {}),
+                credentials: {
+                    scopes: meta.scopes ?? [],
+                },
+                trace: {},
+            };
+        }
+    }
+    catch {
+        // Not inside an activity execution — fall through
+    }
+    // 2. Fallback: AsyncLocalStorage (workflow-local scope)
+    return store.getStore();
+}

package/build/services/iam/credentials.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Universal credential resolution cascade.
+ *
+ * Given a principal and provider, resolves the best available credential:
+ * 1. Principal's own stored OAuth token / API key
+ * 2. System-level environment variable fallback
+ */
+import type { ToolPrincipal } from '../../types/tool-context';
+/**
+ * Thrown when credential resolution finds no credential for a provider.
+ * Caught by route handlers to return structured 422 responses.
+ */
+export declare class MissingCredentialError extends Error {
+    provider: string;
+    constructor(provider: string);
+}
+export interface ResolvedCredential {
+    value: string;
+    source: 'user' | 'bot' | 'system';
+    type: 'oauth_token' | 'api_key';
+}
+export interface ResolveCredentialOptions {
+    /** Fallback principal for dual-identity workflows (e.g., human invoker when bot executes). */
+    fallbackPrincipal?: ToolPrincipal;
+}
+/**
+ * Resolve the best credential for a principal + provider.
+ *
+ * Four-tier cascade:
+ * 1. Primary principal's stored OAuth token / API key
+ * 2. Fallback principal's stored credential (when provided — e.g., the human
+ *    invoker in a bot-executed workflow)
+ * 3. System env var (e.g., ANTHROPIC_API_KEY)
+ * 4. null (caller typically throws MissingCredentialError)
+ *
+ * @param principal - The authenticated principal (user or bot)
+ * @param provider - OAuth provider name (e.g., 'anthropic', 'openai')
+ * @param label - Optional credential label for multi-credential accounts
+ * @param options - Optional fallback principal for dual-identity resolution
+ * @returns Resolved credential or null if none available
+ */
+export declare function resolveCredential(principal: ToolPrincipal, provider: string, label?: string, options?: ResolveCredentialOptions): Promise<ResolvedCredential | null>;

package/build/services/iam/credentials.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingCredentialError = void 0;
+exports.resolveCredential = resolveCredential;
+const oauth_1 = require("../oauth");
+const logger_1 = require("../logger");
+/**
+ * Thrown when credential resolution finds no credential for a provider.
+ * Caught by route handlers to return structured 422 responses.
+ */
+class MissingCredentialError extends Error {
+    constructor(provider) {
+        super(`No credential found for provider "${provider}". Register one at Credentials.`);
+        this.name = 'MissingCredentialError';
+        this.provider = provider;
+    }
+}
+exports.MissingCredentialError = MissingCredentialError;
+/** Well-known provider → env var mappings. */
+const SYSTEM_ENV_VARS = {
+    anthropic: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'],
+    openai: ['OPENAI_API_KEY'],
+};
+/**
+ * Resolve the best credential for a principal + provider.
+ *
+ * Four-tier cascade:
+ * 1. Primary principal's stored OAuth token / API key
+ * 2. Fallback principal's stored credential (when provided — e.g., the human
+ *    invoker in a bot-executed workflow)
+ * 3. System env var (e.g., ANTHROPIC_API_KEY)
+ * 4. null (caller typically throws MissingCredentialError)
+ *
+ * @param principal - The authenticated principal (user or bot)
+ * @param provider - OAuth provider name (e.g., 'anthropic', 'openai')
+ * @param label - Optional credential label for multi-credential accounts
+ * @param options - Optional fallback principal for dual-identity resolution
+ * @returns Resolved credential or null if none available
+ */
+async function resolveCredential(principal, provider, label, options) {
+    // 1. Try primary principal's stored credential
+    try {
+        const decrypted = await (0, oauth_1.getFreshAccessToken)(principal.id, provider, label);
+        if (decrypted) {
+            return {
+                value: decrypted.accessToken,
+                source: principal.type,
+                type: 'oauth_token',
+            };
+        }
+    }
+    catch (err) {
+        logger_1.loggerRegistry.debug(`No stored credential for principal=${principal.id} provider=${provider}: ${err}`);
+    }
+    // 2. Try fallback principal's credential (dual-identity: bot runs, user's token needed)
+    if (options?.fallbackPrincipal) {
+        try {
+            const decrypted = await (0, oauth_1.getFreshAccessToken)(options.fallbackPrincipal.id, provider, label);
+            if (decrypted) {
+                return {
+                    value: decrypted.accessToken,
+                    source: options.fallbackPrincipal.type,
+                    type: 'oauth_token',
+                };
+            }
+        }
+        catch (err) {
+            logger_1.loggerRegistry.debug(`No stored credential for fallback principal=${options.fallbackPrincipal.id} provider=${provider}: ${err}`);
+        }
+    }
+    // 3. System env var fallback
+    const envVars = SYSTEM_ENV_VARS[provider];
+    if (envVars) {
+        for (const varName of envVars) {
+            const value = process.env[varName];
+            if (value) {
+                return {
+                    value,
+                    source: 'system',
+                    type: 'api_key',
+                };
+            }
+        }
+    }
+    return null;
+}

package/build/services/iam/envelope.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build a ToolContext from the envelope's pre-resolved principal.
+ *
+ * Pure data transformation — no DB calls. The principal was resolved
+ * at the front door (API route, cron, escalation re-run) and travels
+ * with the envelope.
+ */
+import type { LTEnvelope } from '../../types/envelope';
+import type { ToolContext } from '../../types/tool-context';
+export declare function buildToolContextFromEnvelope(envelope: LTEnvelope | undefined, workflowId?: string, traceId?: string, spanId?: string): ToolContext | null;

package/build/services/iam/envelope.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Build a ToolContext from the envelope's pre-resolved principal.
+ *
+ * Pure data transformation — no DB calls. The principal was resolved
+ * at the front door (API route, cron, escalation re-run) and travels
+ * with the envelope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolContextFromEnvelope = buildToolContextFromEnvelope;
+const delegation_1 = require("../auth/delegation");
+function buildToolContextFromEnvelope(envelope, workflowId, traceId, spanId) {
+    const principal = envelope?.lt?.principal;
+    if (!principal)
+        return null;
+    const scopes = envelope.lt?.scopes ?? ['mcp:tool:call'];
+    const delegationToken = (0, delegation_1.createDelegationToken)(principal.id, scopes, 300, { workflowId });
+    return {
+        principal,
+        ...(envelope.lt?.initiatingPrincipal
+            ? { initiatingPrincipal: envelope.lt.initiatingPrincipal }
+            : {}),
+        credentials: { delegationToken, scopes },
+        trace: {
+            originId: envelope.lt?.originId,
+            parentId: envelope.lt?.parentId,
+            workflowId,
+            traceId,
+            spanId,
+        },
+    };
+}

package/build/services/iam/ephemeral.d.ts

@@ -0,0 +1,50 @@
+export declare function formatEphemeralToken(uuid: string, label: string): string;
+export declare function isEphemeralToken(value: string): boolean;
+export declare function parseEphemeralToken(value: string): {
+    label: string;
+    uuid: string;
+} | null;
+/**
+ * Parse a token string and exchange the UUID for the decrypted value.
+ * Returns null if the token format is invalid, expired, or uses exhausted.
+ */
+export declare function exchangeEphemeralToken(tokenString: string): Promise<string | null>;
+/**
+ * Deep-traverse a JSON value, replacing any string matching the eph:v1: format
+ * with the exchanged plaintext. Non-matching values pass through unchanged.
+ */
+export declare function exchangeTokensInArgs(obj: any): Promise<any>;
+export interface StoreEphemeralOptions {
+    /** Max number of exchanges. 0 = unlimited. Default: 0 */
+    maxUses?: number;
+    /** TTL in seconds. Null/0 = no expiry. Default: null */
+    ttlSeconds?: number;
+    /** Human-readable label for debugging. */
+    label?: string;
+}
+/**
+ * Store a sensitive value. Returns the raw token UUID.
+ * The value is encrypted at rest using AES-256-GCM.
+ *
+ * - maxUses: 0 (default) = unlimited exchanges until expired/revoked
+ * - ttlSeconds: null (default) = no time-based expiry
+ * - Both can be combined: e.g., maxUses=10, ttlSeconds=900
+ */
+export declare function storeEphemeral(value: string, opts?: StoreEphemeralOptions): Promise<string>;
+/**
+ * Exchange a raw UUID token for the decrypted value.
+ *
+ * - If max_uses > 0: increments use_count, returns null when exhausted
+ * - If max_uses = 0: unlimited (never blocked by count)
+ * - If expires_at is set: returns null after expiry
+ * - Row is deleted when use_count reaches max_uses (if max_uses > 0)
+ */
+export declare function exchangeEphemeral(token: string): Promise<string | null>;
+/**
+ * Explicitly revoke a token before expiry/exhaustion.
+ */
+export declare function revokeEphemeral(token: string): Promise<boolean>;
+/**
+ * Clean up expired tokens. Returns the number of rows deleted.
+ */
+export declare function cleanupExpired(): Promise<number>;