eve/dist/src/harness/authorization.d.ts

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

import { ContextKey } from "#context/key.js";
import type { ConnectionAuthorizationChallenge } from "#connections/errors.js";
import type { AuthorizationCallback, ConnectionPrincipal } from "#shared/connection-types.js";
import type { JsonValue } from "#shared/json.js";
declare const AUTHORIZATION_BRAND: "__eveAuthorization";
declare const AUTHORIZATION_PENDING_BRAND: "__eveAuthorizationPending";
export interface AuthorizationChallenge {
    /** Opaque identity of this exact authorization attempt. */
    readonly attemptId?: string;
    readonly candidateId?: string;
    /** Opaque resolved connection identity; omitted for tool-hosted authorization. */
    readonly instanceId?: string;
    readonly name: string;
    readonly challenge: ConnectionAuthorizationChallenge;
    readonly hookUrl: string;
    /** Principal passed to `startAuthorization`; omitted from model-facing copies. */
    readonly principal?: ConnectionPrincipal;
    /**
     * Opaque resume value from the strategy's `startAuthorization`,
     * journaled across the park. Absent for provider-owned flows.
     */
    readonly resume?: JsonValue;
}
export interface AuthorizationSignal {
    readonly [AUTHORIZATION_BRAND]: true;
    readonly challenges: readonly AuthorizationChallenge[];
}
/**
 * Opaque tool output the model sees while authorization is pending.
 * Contains connection names only — no OAuth URLs, user codes, or hook URLs.
 */
export interface AuthorizationPendingModelOutput {
    readonly [AUTHORIZATION_PENDING_BRAND]: true;
    readonly connections: readonly string[];
}
export interface AuthorizationResult {
    readonly attemptId?: string;
    readonly instanceId?: string;
    readonly resume?: JsonValue;
    readonly callback: AuthorizationCallback;
    readonly hookUrl: string;
    readonly principal?: ConnectionPrincipal;
}
/**
 * Creates an authorization signal. Return this from a tool's execute
 * to suspend the session for OAuth or other external authorization.
 *
 * The harness emits `authorization.required` events for each challenge
 * and parks the session. Channels render sign-in buttons.
 */
export declare function requestAuthorization(challenges: readonly AuthorizationChallenge[]): AuthorizationSignal;
/**
 * Returns a model-safe copy of `signal` with runtime-only challenge state stripped.
 *
 * Used for the copy the AI SDK records as a tool output. The shape stays a
 * valid {@link AuthorizationSignal} so every `isAuthorizationSignal` consumer
 * still detects it; the park detector reads the full resume, principal, and
 * resolved-instance state from the harness's out-of-band stash.
 */
export declare function redactSignalResume(signal: AuthorizationSignal): AuthorizationSignal;
/**
 * Reads the authorization callback on resume. Returns `undefined` if
 * not resuming from an authorization request.
 *
 * When `name` is omitted, returns the first result (convenience for
 * single-challenge tools).
 */
export declare function getAuthorizationResult(name?: string): AuthorizationResult | undefined;
/** Returns every callback result available to the active step. */
export declare function getAuthorizationResults(): readonly NamedAuthorizationResult[];
/**
 * Removes and returns one authorization callback result.
 *
 * Callback results are one-shot inputs to `completeAuthorization`. Consuming
 * before completion prevents a failed or replayed callback from poisoning
 * every later tool call in the same step.
 */
export declare function consumeAuthorizationResult(name: string, instanceId?: string): AuthorizationResult | undefined;
/**
 * Builds a callback URL for external systems. `name` and `attemptId` identify
 * the exact challenge in the URL path.
 *
 * By default the URL embeds the session's stable inbox token.
 * A runtime with its own continuation supplies that hook through AuthorizationHookKey.
 * It is independent of the continuation token, so channel aliasing mid-turn
 * does not invalidate the callback URL.
 *
 * Returns `undefined` if no callback address is available.
 */
export declare function getHookUrl(name: string, attemptId: string): string | undefined;
/** Mints the identity and callback URL for one interactive authorization attempt. */
export declare function createAuthorizationAttempt(name: string): {
    readonly attemptId: string;
    readonly hookUrl: string;
} | undefined;
export declare function isAuthorizationSignal(value: unknown): value is AuthorizationSignal;
export declare function isAuthorizationPendingModelOutput(value: unknown): value is AuthorizationPendingModelOutput;
/**
 * JSON-safe pending authorization output for model-facing tool results and
 * wire surfaces (`action.result`, telemetry). Omits OAuth URLs and user
 * codes — connection names only.
 */
export declare function authorizationPendingAsJsonObject(input: {
    readonly connections: readonly string[];
}): AuthorizationPendingModelOutput;
/**
 * Projects a full {@link AuthorizationSignal} to the opaque shape recorded
 * in model-facing tool results and session history.
 */
export declare function modelFacingAuthorizationOutput(signal: AuthorizationSignal): AuthorizationPendingModelOutput;
/** Human-readable tool output for {@link modelFacingAuthorizationOutput}. */
export declare function authorizationPendingModelText(connections: readonly string[]): string;
export declare function isPendingAuthorizationToolOutput(value: unknown): boolean;
/**
 * Physical hook token embedded in a session's authorization callback URLs.
 * The callback route resumes exactly this hook, so it is the stable inbox's
 * physical address rather than its logical session token.
 */
export declare function authHookToken(sessionId: string): string;
interface NamedAuthorizationResult extends AuthorizationResult {
    readonly name: string;
}
export declare const PendingAuthorizationResultKey: ContextKey<readonly NamedAuthorizationResult[]>;
/**
 * Deployment base URL for building callback URLs. Set by the
 * framework (turnStep) at the start of each step from workflow
 * metadata.
 */
export declare const CallbackBaseUrlKey: ContextKey<string>;
/** Hook token of a runtime that owns its callback instead of using the session hook. */
export declare const AuthorizationHookKey: ContextKey<string>;
export interface PendingAuthorizationState {
    readonly activityRootTurnIds?: Readonly<Record<string, string>>;
    readonly challenges: readonly AuthorizationChallenge[];
}
export declare function setPendingAuthorization(sessionState: Record<string, unknown> | undefined, value: PendingAuthorizationState): Record<string, unknown>;
/** Keeps the last challenge for each authorization name and principal scope. */
export declare function resolveActiveAuthorizationChallenges(challenges: readonly AuthorizationChallenge[]): readonly AuthorizationChallenge[];
/** Existing same-scope attempts replaced by newer attempts for the same principal. */
export declare function getSupersededAuthorizationChallenges(sessionState: Record<string, unknown> | undefined, replacements: readonly AuthorizationChallenge[]): readonly AuthorizationChallenge[];
export declare function clearPendingAuthorization(sessionState: Record<string, unknown> | undefined, attemptIds?: readonly string[]): Record<string, unknown> | undefined;
export declare function getPendingAuthorization(sessionState: Record<string, unknown> | undefined): PendingAuthorizationState | undefined;
export declare function hasPendingAuthorization(sessionState: Record<string, unknown> | undefined): boolean;
export {};