eve/dist/src/execution/tool-auth.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

/**
 * Tool-hosted authorization wiring for authored tools that declare
 * `auth` on {@link defineTool}.
 *
 * Mirrors the connection authorization flow (see
 * `runtime/framework-tools/connection-search-dynamic.ts`) but scopes the
 * per-step token cache and framework-owned callback URL by the tool's
 * path-derived name instead of a connection name. All the shared
 * machinery — principal resolution, cache reads/writes, the park/resume
 * webhook dance, and the loop guard — lives in
 * `runtime/connections/scoped-authorization.ts`; this module is the thin
 * execution-layer adapter that wraps one tool's `execute`.
 */
import type { ToolContext } from "#public/definitions/tool.js";
import { type AuthorizationDefinition } from "#runtime/connections/types.js";
/**
 * Wraps one authored tool's `execute` with the tool-hosted
 * authorization flow.
 *
 * Each invocation:
 * 1. Completes an authorization whose OAuth callback arrived this turn,
 *    caching the freshly minted token (the loop-guard flag).
 * 2. Runs the authored `execute` with a {@link ToolContext} whose
 *    `getToken()` / `requireAuth()` are bound to this tool's scope.
 * 3. On a thrown `ConnectionAuthorizationRequiredError` — implicit from
 *    `getToken()` or explicit via `requireAuth()` — either fails
 *    terminally (token rejected immediately after sign-in) or evicts the
 *    rejected token from the per-step cache and starts the interactive
 *    flow, returning an `AuthorizationSignal` to park the turn. An
 *    interactive strategy never rethrows the raw `Required` into the
 *    model: if no callback URL can be minted it fails with a classified
 *    {@link ConnectionAuthorizationFailedError} instead. Only
 *    non-interactive strategies rethrow the original error, since they
 *    have no consent flow to park on.
 */
export declare function createAuthorizedToolExecute(input: {
    readonly scope: string;
    readonly auth: AuthorizationDefinition;
    readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
}): (toolInput: unknown) => Promise<unknown>;
/**
 * Wraps one authored tool's `execute` with a context that supports both
 * top-level tool auth (`ctx.getToken()`) and inline provider auth
 * (`ctx.getToken(connect("..."))`).
 */
export declare function createToolExecuteWithAuth(input: {
    readonly scope: string;
    readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
    readonly topLevelAuth?: AuthorizationDefinition;
}): (toolInput: unknown) => Promise<unknown>;
/**
 * Builds the {@link ToolContext} for an authored tool without top-level
 * `auth`. No-arg token accessors throw, but provider-scoped accessors
 * still work.
 */
export declare function buildUnauthorizedToolContext(scope: string): ToolContext;