eve 0.5.4 → 0.6.0-beta.3

package/dist/src/protocol/message.js

@@ -0,0 +1,2 @@
+const EVE_SESSION_ID_HEADER=`x-eve-session-id`,EVE_STREAM_FORMAT_HEADER=`x-eve-stream-format`,EVE_STREAM_VERSION_HEADER=`x-eve-stream-version`,EVE_MESSAGE_STREAM_CONTENT_TYPE=`application/x-ndjson; charset=utf-8`,EVE_MESSAGE_STREAM_FORMAT=`ndjson`,EVE_MESSAGE_STREAM_VERSION=`15`,textEncoder=new TextEncoder;function isCurrentTurnBoundaryEvent(e){return e.type===`session.completed`||e.type===`session.failed`||e.type===`session.waiting`}function createSessionStartedEvent(e){let t={};return e?.invocation!==void 0&&(t.invocation=e.invocation),e?.runtime!==void 0&&(t.runtime=e.runtime),{data:t,type:`session.started`}}function createTurnStartedEvent(e){return{data:{sequence:e.sequence,turnId:e.turnId},type:`turn.started`}}function createMessageReceivedEvent(e){return{data:{message:summarizeUserContent(e.message),sequence:e.sequence,turnId:e.turnId},type:`message.received`}}function summarizeUserContent(e){if(typeof e==`string`)return e;let t=[];for(let n of e)if(n.type===`text`)t.push(n.text);else if(n.type===`file`){let e=n.filename??n.mediaType;t.push(`[file: ${e} (${n.mediaType})]`)}else n.type===`image`&&t.push(`[image: ${n.mediaType??`image`}]`);return t.join(`
+`)}function createActionsRequestedEvent(e){return{data:{actions:e.actions,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`actions.requested`}}function createAuthorizationRequiredEvent(e){let t={description:e.description,name:e.name,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId};return e.authorization!==void 0&&(t.authorization=e.authorization),e.webhookUrl!==void 0&&(t.webhookUrl=e.webhookUrl),{data:t,type:`authorization.required`}}function createAuthorizationCompletedEvent(e){let t={name:e.name,outcome:e.outcome,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId};return e.reason!==void 0&&(t.reason=e.reason),{data:t,type:`authorization.completed`}}function createInputRequestedEvent(e){return{data:{requests:e.requests,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`input.requested`}}function createActionResultEvent(e){let t=normalizeActionResultOutcome(e.result);return{data:{error:t.error,result:e.result,sequence:e.sequence,stepIndex:e.stepIndex,status:t.status,turnId:e.turnId},type:`action.result`}}function createSubagentCalledEvent(e){return{data:{callId:e.callId,childSessionId:e.childSessionId,sessionId:e.sessionId,sequence:e.sequence,name:e.name,remote:e.remote,toolName:e.toolName,turnId:e.turnId,workflowId:e.workflowId},type:`subagent.called`}}function createMessageAppendedEvent(e){return{data:{messageDelta:e.messageDelta,messageSoFar:e.messageSoFar,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`message.appended`}}function createReasoningAppendedEvent(e){return{data:{reasoningDelta:e.reasoningDelta,reasoningSoFar:e.reasoningSoFar,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`reasoning.appended`}}function createMessageCompletedEvent(e){return{data:{finishReason:e.finishReason??`stop`,message:e.message,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`message.completed`}}function createReasoningCompletedEvent(e){return{data:{reasoning:e.reasoning,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`reasoning.completed`}}function createResultCompletedEvent(e){return{data:{result:e.result,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`result.completed`}}function createStepStartedEvent(e){return{data:{sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`step.started`}}function createStepCompletedEvent(e){let t={finishReason:e.finishReason,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId};return e.usage!==void 0&&(t.usage=e.usage),{data:t,type:`step.completed`}}function createStepFailedEvent(e){return{data:{code:e.code,details:e.details,message:e.message,sequence:e.sequence,stepIndex:e.stepIndex,turnId:e.turnId},type:`step.failed`}}function createTurnCompletedEvent(e){return{data:{sequence:e.sequence,turnId:e.turnId},type:`turn.completed`}}function createTurnFailedEvent(e){return{data:{code:e.code,details:e.details,message:e.message,sequence:e.sequence,turnId:e.turnId},type:`turn.failed`}}function createCompactionRequestedEvent(e){return{data:{modelId:e.modelId,sequence:e.sequence,sessionId:e.sessionId,turnId:e.turnId,usageInputTokens:e.usageInputTokens??null},type:`compaction.requested`}}function createCompactionCompletedEvent(e){return{data:{modelId:e.modelId,sequence:e.sequence,sessionId:e.sessionId,turnId:e.turnId},type:`compaction.completed`}}function createSessionWaitingEvent(){return{data:{wait:`next-user-message`},type:`session.waiting`}}function createSessionFailedEvent(e){return{data:{code:e.code,details:e.details,message:e.message,sessionId:e.sessionId},type:`session.failed`}}function createSessionCompletedEvent(){return{type:`session.completed`}}function timestampHandleMessageStreamEvent(e,t=new Date().toISOString()){return{...e,meta:{at:t}}}function encodeMessageStreamEvent(e){return textEncoder.encode(`${JSON.stringify(e)}\n`)}function normalizeActionResultOutcome(e){if(e.isError===!0)return{error:buildActionResultError(e),status:`failed`};let t=readActionResultOutputError(e.output);return t===void 0?{status:`completed`}:{error:t,status:`failed`}}function buildActionResultError(e){let t=readActionResultOutputError(e.output);return t===void 0?{code:`ACTION_RESULT_FAILED`,message:formatActionResultOutput(e.output)}:t}function readActionResultOutputError(e){let t=parseActionResultOutputRecord(e);if(t===void 0)return;let n=typeof t.code==`string`&&t.code.length>0?t.code:void 0,r=typeof t.message==`string`&&t.message.length>0?t.message:void 0;if(!(n===void 0||r===void 0))return{code:n,message:r}}function parseActionResultOutputRecord(e){if(typeof e==`object`&&e)return e;if(typeof e!=`string`)return;let t=e.trim();if(t.length!==0)try{let e=JSON.parse(t);if(typeof e==`object`&&e)return e}catch{return}}function formatActionResultOutput(e){if(typeof e==`string`)return e;let t=JSON.stringify(e);return typeof t==`string`&&t.length>0?t:`Action failed.`}export{EVE_MESSAGE_STREAM_CONTENT_TYPE,EVE_MESSAGE_STREAM_FORMAT,EVE_MESSAGE_STREAM_VERSION,EVE_SESSION_ID_HEADER,EVE_STREAM_FORMAT_HEADER,EVE_STREAM_VERSION_HEADER,createActionResultEvent,createActionsRequestedEvent,createAuthorizationCompletedEvent,createAuthorizationRequiredEvent,createCompactionCompletedEvent,createCompactionRequestedEvent,createInputRequestedEvent,createMessageAppendedEvent,createMessageCompletedEvent,createMessageReceivedEvent,createReasoningAppendedEvent,createReasoningCompletedEvent,createResultCompletedEvent,createSessionCompletedEvent,createSessionFailedEvent,createSessionStartedEvent,createSessionWaitingEvent,createStepCompletedEvent,createStepFailedEvent,createStepStartedEvent,createSubagentCalledEvent,createTurnCompletedEvent,createTurnFailedEvent,createTurnStartedEvent,encodeMessageStreamEvent,isCurrentTurnBoundaryEvent,timestampHandleMessageStreamEvent};

package/dist/src/protocol/routes.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Stable framework-owned route prefix reserved for Eve's runtime transport
+ * surfaces.
+ */
+export declare const EVE_ROUTE_PREFIX = "/eve/v1";
+/**
+ * Stable framework-owned health route.
+ */
+export declare const EVE_HEALTH_ROUTE_PATH = "/eve/v1/health";
+/**
+ * Stable framework-owned route exposing the JSON inspection payload for
+ * the current agent (model id, instructions preview, skills, schedules,
+ * subagents, tools, sandbox, and the runtime's own endpoint catalog).
+ *
+ * Default auth on this route is `[localDev(), vercelOidc()]` — the same
+ * chain the framework applies to the eve channel — so deployed Vercel
+ * targets require a valid OIDC bearer (with the same-project bypass for
+ * in-deployment callers) while local development accepts anonymously.
+ * See `routes/info.ts` for the handler.
+ */
+export declare const EVE_INFO_ROUTE_PATH = "/eve/v1/info";
+/**
+ * Stable framework-owned route for creating a new session.
+ */
+export declare const EVE_CREATE_SESSION_ROUTE_PATH = "/eve/v1/session";
+/**
+ * Stable framework-owned route pattern for sending a message to an existing
+ * session.
+ */
+export declare const EVE_CONTINUE_SESSION_ROUTE_PATTERN = "/eve/v1/session/:sessionId";
+/**
+ * Stable framework-owned message stream route pattern.
+ */
+export declare const EVE_MESSAGE_STREAM_ROUTE_PATTERN = "/eve/v1/session/:sessionId/stream";
+/**
+ * Framework-owned route pattern for dispatching one authored schedule
+ * exactly once from the dev server.
+ *
+ * Only registered when Nitro is running in dev mode — production builds
+ * never mount this route. Smoke tests and human developers use it to
+ * trigger a schedule out-of-band (without a cron firing) and recover the
+ * resulting `{ scheduleId, sessionIds }` payload as JSON so they can
+ * subscribe to {@link EVE_MESSAGE_STREAM_ROUTE_PATTERN} for each session.
+ *
+ * `:scheduleId` is the authored schedule's filesystem-derived name (e.g.
+ * `agent/schedules/heartbeat.ts` -> `"heartbeat"`).
+ */
+export declare const EVE_DEV_DISPATCH_SCHEDULE_ROUTE_PATTERN = "/eve/v1/dev/schedules/:scheduleId";
+/**
+ * Dev-only route exposing the current runtime artifact revision.
+ *
+ * Local development clients use this to decide when an HMR rebuild has
+ * published new runtime artifacts, so their next normal prompt can start a
+ * fresh server-side session while in-flight sessions keep their original
+ * snapshot.
+ */
+export declare const EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH = "/eve/v1/dev/runtime-artifacts";
+/**
+ * Builds the dev-only schedule dispatch URL for one named authored
+ * schedule. The path encodes the schedule id so reserved characters in
+ * authored filenames round-trip safely.
+ */
+export declare function createEveDevDispatchSchedulePath(scheduleId: string): string;
+/**
+ * Stable framework-owned route pattern for receiving inbound IdP redirects
+ * during in-turn interactive connection authorization.
+ *
+ * `:name` is the connection name; `:token` is the workflow hook token minted
+ * by the workflow body so the route handler can resume the suspended turn
+ * via `resumeHook(token, payload)`.
+ *
+ * The route is unauthenticated by design: an OAuth IdP follows this URL
+ * via a 3xx redirect from the user's browser with no Eve credentials
+ * attached. The token is the unguessable capability that authorizes the
+ * resume; anyone who has it can deliver the callback payload, which is
+ * exactly what the IdP needs to do.
+ */
+export declare const EVE_CONNECTION_CALLBACK_ROUTE_PATTERN = "/eve/v1/connections/:name/callback/:token";
+/**
+ * Stable framework-owned route pattern for terminal session callbacks.
+ *
+ * The `:token` segment is an unguessable workflow hook capability. The route
+ * is unauthenticated by design and resumes the matching parked runtime action.
+ */
+export declare const EVE_CALLBACK_ROUTE_PATTERN = "/eve/v1/callback/:token";
+/**
+ * Creates the stable framework-owned message stream route path for one session.
+ */
+export declare function createEveMessageStreamRoutePath(sessionId: string): string;
+/**
+ * Creates the stable framework-owned continue-session route path.
+ */
+export declare function createEveContinueSessionRoutePath(sessionId: string): string;
+/**
+ * Creates the stable framework-owned connection callback route path for
+ * one (`name`, `token`) pair.
+ *
+ * The workflow body builds this path against {@link EVE_ROUTE_PREFIX} when
+ * minting the redirect URL it hands to the IdP via `startAuthorization`.
+ * The runtime's framework callback route handler matches the same path
+ * pattern and forwards the projected request payload into
+ * `resumeHook(token, payload)`.
+ */
+export declare function createEveConnectionCallbackRoutePath(name: string, token: string): string;
+/**
+ * Creates the stable framework-owned terminal callback route path.
+ */
+export declare function createEveCallbackRoutePath(token: string): string;

package/dist/src/protocol/routes.js

@@ -0,0 +1 @@
+const EVE_ROUTE_PREFIX=`/eve/v1`,EVE_HEALTH_ROUTE_PATH=`${EVE_ROUTE_PREFIX}/health`,EVE_INFO_ROUTE_PATH=`${EVE_ROUTE_PREFIX}/info`,EVE_CREATE_SESSION_ROUTE_PATH=`${EVE_ROUTE_PREFIX}/session`,EVE_CONTINUE_SESSION_ROUTE_PATTERN=`${EVE_ROUTE_PREFIX}/session/:sessionId`,EVE_MESSAGE_STREAM_ROUTE_PATTERN=`${EVE_ROUTE_PREFIX}/session/:sessionId/stream`,EVE_DEV_DISPATCH_SCHEDULE_ROUTE_PATTERN=`${EVE_ROUTE_PREFIX}/dev/schedules/:scheduleId`,EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH=`${EVE_ROUTE_PREFIX}/dev/runtime-artifacts`;function createEveDevDispatchSchedulePath(e){return`${EVE_ROUTE_PREFIX}/dev/schedules/${encodeURIComponent(e)}`}const EVE_CONNECTION_CALLBACK_ROUTE_PATTERN=`${EVE_ROUTE_PREFIX}/connections/:name/callback/:token`,EVE_CALLBACK_ROUTE_PATTERN=`${EVE_ROUTE_PREFIX}/callback/:token`;function createEveMessageStreamRoutePath(e){return`${EVE_ROUTE_PREFIX}/session/${encodeURIComponent(e)}/stream`}function createEveContinueSessionRoutePath(e){return`${EVE_ROUTE_PREFIX}/session/${encodeURIComponent(e)}`}function createEveConnectionCallbackRoutePath(e,t){return`${EVE_ROUTE_PREFIX}/connections/${encodeURIComponent(e)}/callback/${encodeURIComponent(t)}`}function createEveCallbackRoutePath(e){return`${EVE_ROUTE_PREFIX}/callback/${encodeURIComponent(e)}`}export{EVE_CALLBACK_ROUTE_PATTERN,EVE_CONNECTION_CALLBACK_ROUTE_PATTERN,EVE_CONTINUE_SESSION_ROUTE_PATTERN,EVE_CREATE_SESSION_ROUTE_PATH,EVE_DEV_DISPATCH_SCHEDULE_ROUTE_PATTERN,EVE_DEV_RUNTIME_ARTIFACTS_ROUTE_PATH,EVE_HEALTH_ROUTE_PATH,EVE_INFO_ROUTE_PATH,EVE_MESSAGE_STREAM_ROUTE_PATTERN,EVE_ROUTE_PREFIX,createEveCallbackRoutePath,createEveConnectionCallbackRoutePath,createEveContinueSessionRoutePath,createEveDevDispatchSchedulePath,createEveMessageStreamRoutePath};

package/dist/src/public/agents/auth.d.ts

@@ -0,0 +1,46 @@
+import type { TokenValue } from "#client/types.js";
+/**
+ * Outbound request auth hook for remote agent dispatch. Runs once per
+ * outbound request; returns the headers (e.g. `authorization`) to merge onto
+ * that request. Use {@link vercelOidc}, {@link bearer}, or {@link basic} to
+ * construct one, or supply a custom function for other schemes.
+ */
+export type OutboundAuthFn = () => Promise<{
+    readonly headers: Readonly<Record<string, string>>;
+}>;
+/**
+ * Eve-owned mirror of the `@vercel/oidc` token lookup options forwarded to
+ * {@link vercelOidc}.
+ */
+export interface VercelOidcOptions {
+    /** Buffer in milliseconds before token expiry that triggers a refresh. */
+    readonly expirationBufferMs?: number;
+    /** Project ID (`prj_*`) or slug to use for token refresh. */
+    readonly project?: string;
+    /** Team ID (`team_*`) or slug to use for token refresh. */
+    readonly team?: string;
+}
+/**
+ * Returns an {@link OutboundAuthFn} that emits a `Bearer` Vercel OIDC token for
+ * outbound remote-agent requests. Reads the token from the request context or
+ * the `VERCEL_OIDC_TOKEN` environment variable (refreshed in development when
+ * expired). Pass {@link VercelOidcOptions} to scope the refresh to a team or
+ * project; defaults to `{}`.
+ */
+export declare function vercelOidc(options?: VercelOidcOptions): OutboundAuthFn;
+/**
+ * Returns an {@link OutboundAuthFn} that emits a `Bearer` `Authorization`
+ * header. `token` is a {@link TokenValue}: pass a string for a static token, or
+ * a function to resolve a fresh token on each outbound request.
+ */
+export declare function bearer(token: TokenValue): OutboundAuthFn;
+/**
+ * Returns an {@link OutboundAuthFn} that emits an HTTP Basic `Authorization`
+ * header. `username` is a literal string; `password` is a {@link TokenValue}
+ * (static string or per-request resolver). Base64-encodes the credentials per
+ * request.
+ */
+export declare function basic(input: {
+    readonly password: TokenValue;
+    readonly username: string;
+}): OutboundAuthFn;

package/dist/src/public/agents/auth.js

@@ -0,0 +1 @@
+import{getVercelOidcToken}from"#compiled/@vercel/oidc/index.js";function vercelOidc(t={}){return async()=>({headers:{authorization:`Bearer ${await getVercelOidcToken(t)}`}})}function bearer(e){return async()=>({headers:{authorization:`Bearer ${await resolveTokenValue(e)}`}})}function basic(e){return async()=>({headers:{authorization:`Basic ${btoa(`${e.username}:${await resolveTokenValue(e.password)}`)}`}})}async function resolveTokenValue(e){return typeof e==`function`?await e():e}export{basic,bearer,vercelOidc};

package/dist/src/public/channels/auth.d.ts

@@ -0,0 +1,416 @@
+/**
+ * Route-level HTTP authentication primitives.
+ *
+ * Strategy helpers return an {@link AuthFn} for route factories. Verifier
+ * helpers are lower-level pure functions for custom `fetch` handlers.
+ */
+import type { SessionAuthContext } from "#channel/types.js";
+import { type RuntimeIpAllowList } from "#runtime/governance/network/ip-allow-list.js";
+/**
+ * Result returned by the verifier helpers below. On success, `sessionAuth`
+ * is a fully-constructed {@link SessionAuthContext}; on failure no detail is
+ * returned so routes do not leak which credential check failed.
+ */
+export type VerifyResult = {
+    readonly ok: true;
+    readonly sessionAuth: SessionAuthContext;
+} | {
+    readonly ok: false;
+};
+/**
+ * Credentials accepted by {@link verifyHttpBasic}.
+ */
+export interface HttpBasicCredentials {
+    readonly username: string;
+    readonly password: string;
+}
+/**
+ * Verifies an HTTP Basic credential against the supplied username and
+ * password. Returns `{ ok: true, sessionAuth }` on success or `{ ok: false }`
+ * on a missing or mismatched credential. The password is compared with
+ * constant-time hash equality so a timing side channel cannot leak it; the
+ * username is compared directly.
+ */
+export declare function verifyHttpBasic(authorizationHeader: string | null, credentials: HttpBasicCredentials): VerifyResult;
+/**
+ * Configuration for {@link verifyJwtHmac}. Optional fields have defaults so
+ * adapters can omit unused matchers. `secret` is read by the adapter from its
+ * secret store (e.g. `process.env`) and passed in directly.
+ */
+export interface VerifyJwtHmacConfig {
+    readonly algorithm: "HS256" | "HS384" | "HS512";
+    readonly audiences: readonly string[];
+    readonly issuer: string;
+    readonly secret: string;
+    /**
+     * Tolerance in seconds for the `exp` and `nbf` claims. Defaults to 30.
+     */
+    readonly clockSkewSeconds?: number;
+    /**
+     * AWS IAM-style `*`-wildcard patterns matched against the token `sub`.
+     * When supplied, the token is rejected unless one matches.
+     */
+    readonly subjects?: readonly string[];
+    /**
+     * Per-claim membership matcher: each named claim must contain at least one
+     * of the listed values, or the token is rejected.
+     */
+    readonly claims?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Verifies a bearer JWT signed with an HMAC secret. Pass the token without
+ * the `Bearer ` prefix (see {@link extractBearerToken}). Returns
+ * `{ ok: true, sessionAuth }` on success or `{ ok: false }` when verification
+ * fails or the token's claims don't match the supplied matchers.
+ */
+export declare function verifyJwtHmac(token: string | null, config: VerifyJwtHmacConfig): Promise<VerifyResult>;
+/**
+ * Configuration for {@link verifyJwtEcdsa}.
+ */
+export interface VerifyJwtEcdsaConfig {
+    readonly algorithm: "ES256" | "ES384" | "ES512";
+    readonly audiences: readonly string[];
+    readonly issuer: string;
+    /**
+     * PEM-encoded ECDSA public key (`-----BEGIN PUBLIC KEY-----` ...).
+     */
+    readonly publicKey: string;
+    /**
+     * Tolerance in seconds for the `exp` and `nbf` claims. Defaults to 30.
+     */
+    readonly clockSkewSeconds?: number;
+    /**
+     * AWS IAM-style `*`-wildcard patterns matched against the token `sub`.
+     * When supplied, the token is rejected unless one matches.
+     */
+    readonly subjects?: readonly string[];
+    /**
+     * Per-claim membership matcher: each named claim must contain at least one
+     * of the listed values, or the token is rejected.
+     */
+    readonly claims?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Verifies a bearer JWT signed with an ECDSA private key against the supplied
+ * PEM public key. Pass the token without the `Bearer ` prefix (see
+ * {@link extractBearerToken}). Returns `{ ok: true, sessionAuth }` on success
+ * or `{ ok: false }` when verification fails or the token's claims do not
+ * match the configured `subjects`/`claims`.
+ */
+export declare function verifyJwtEcdsa(token: string | null, config: VerifyJwtEcdsaConfig): Promise<VerifyResult>;
+/**
+ * Configuration for {@link verifyOidc}.
+ */
+export interface VerifyOidcConfig {
+    readonly audiences: readonly string[];
+    readonly issuer: string;
+    /**
+     * OIDC discovery URL. Defaults to
+     * `${issuer}/.well-known/openid-configuration` (any trailing slash on
+     * `issuer` is stripped first).
+     */
+    readonly discoveryUrl?: string;
+    /**
+     * Tolerance in seconds for the `exp` and `nbf` claims. Defaults to 30.
+     */
+    readonly clockSkewSeconds?: number;
+    /**
+     * AWS IAM-style `*`-wildcard patterns matched against the token `sub`.
+     * When supplied, the token is rejected unless one matches.
+     */
+    readonly subjects?: readonly string[];
+    /**
+     * Per-claim membership matcher: each named claim must contain at least one
+     * of the listed values, or the token is rejected.
+     */
+    readonly claims?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Verifies a bearer OIDC token against an issuer's discovery URL. Pass the
+ * token without the `Bearer ` prefix (see {@link extractBearerToken}). The
+ * token must satisfy the configured `subjects`/`claims` matchers; on success
+ * the principal is tagged `principalType: "service"`. Unlike
+ * {@link verifyVercelOidc}, this never grants the Vercel current-project
+ * bypass. Returns `{ ok: false }` on failed verification or matchers.
+ */
+export declare function verifyOidc(token: string | null, config: VerifyOidcConfig): Promise<VerifyResult>;
+/**
+ * Extracts the bearer token from an `Authorization: Bearer <token>` header.
+ * Returns `null` if the header is missing, the scheme isn't `Bearer`, or the
+ * value after `Bearer ` is empty.
+ */
+export declare function extractBearerToken(authorizationHeader: string | null): string | null;
+/**
+ * Parsed IP allowlist for repeated checks. Construct once at module load,
+ * then call {@link isIpAllowed} per request.
+ */
+export type IpAllowList = RuntimeIpAllowList;
+/**
+ * Parses exact IP addresses or CIDR blocks into a reusable
+ * {@link IpAllowList}. Entries are trimmed; throws on an empty entry, a `*`
+ * wildcard (use exact IP/CIDR syntax), or an invalid address or CIDR prefix.
+ */
+export declare function createIpAllowList(entries: readonly string[]): IpAllowList;
+/**
+ * Returns whether `ip` is permitted by `allowList`. `null` always returns
+ * `false`. Adapters that need to allow unknown IPs should not call this.
+ */
+export declare function isIpAllowed(ip: string | null, allowList: IpAllowList): boolean;
+/**
+ * One challenge entry attached to the `www-authenticate` header on a failure
+ * response. For a Basic+Bearer prompt, pass both:
+ * `[{ scheme: "Basic", parameters: { realm: "agent" } }, { scheme: "Bearer" }]`
+ */
+export interface UnauthorizedChallenge {
+    readonly scheme: "Basic" | "Bearer";
+    readonly parameters?: Readonly<Record<string, string>>;
+}
+/**
+ * Options accepted by {@link createUnauthorizedResponse}.
+ */
+export interface UnauthorizedResponseOptions {
+    /**
+     * HTTP status code. Defaults to `401`. Use `403` for "authenticated but
+     * not allowed" outcomes.
+     */
+    readonly status?: 401 | 403;
+    /**
+     * Machine-readable error code returned in the JSON body. Defaults to
+     * `"unauthorized"` (401) or `"forbidden"` (403).
+     */
+    readonly code?: string;
+    /**
+     * Human-readable error message returned in the JSON body. Defaults to a
+     * generic prompt.
+     */
+    readonly message?: string;
+    /**
+     * Optional `www-authenticate` challenge entries.
+     */
+    readonly challenges?: readonly UnauthorizedChallenge[];
+}
+/**
+ * Builds a JSON failure response shaped like the framework's other auth
+ * failures: `cache-control: no-store`, one `www-authenticate` header per
+ * challenge, and a `{ ok: false, code, error }` body.
+ */
+export declare function createUnauthorizedResponse(opts?: UnauthorizedResponseOptions): Response;
+/**
+ * Options accepted by auth error classes. The class chooses the HTTP status.
+ */
+export type AuthErrorOptions = Omit<UnauthorizedResponseOptions, "status">;
+/**
+ * Error thrown by auth callbacks to reject a route with a structured 401
+ * response. `routeAuth` catches it and returns its response; other errors
+ * propagate through the normal channel failure path.
+ */
+export declare class UnauthenticatedError extends Error {
+    readonly response: Response;
+    constructor(opts?: AuthErrorOptions);
+}
+/**
+ * Error thrown by auth callbacks to reject a route with a structured 403
+ * response. `routeAuth` catches it and returns its response; other errors
+ * propagate through the normal channel failure path.
+ */
+export declare class ForbiddenError extends Error {
+    readonly response: Response;
+    constructor(opts?: AuthErrorOptions);
+}
+/**
+ * Route auth callback. Returned value semantics inside {@link routeAuth}:
+ *
+ * - A {@link SessionAuthContext} accepts the request and halts the walk.
+ * - `null` or `undefined` skips to the next entry.
+ *
+ * If every entry skips (including the empty `[]` case), the walker returns a
+ * 401. To reject with a specific response, throw an
+ * {@link UnauthenticatedError} or {@link ForbiddenError}. To accept anonymous
+ * traffic, include {@link none} as the final entry.
+ */
+export type AuthFn<TEvent = Request> = (event: TEvent) => SessionAuthContext | null | undefined | Promise<SessionAuthContext | null | undefined>;
+/**
+ * Walks an `AuthFn` (or array) in order against `request`. The first entry
+ * returning a {@link SessionAuthContext} wins; entries returning `null` or
+ * `undefined` are skipped. If the walk exhausts without a winner (including
+ * the empty-array case), returns a 401 {@link createUnauthorizedResponse}.
+ *
+ * Channel factories that share this resolution policy (e.g. `eveChannel`, or
+ * a custom `defineChannel` route handler) should call `routeAuth` rather than
+ * re-implement the walk.
+ */
+export declare function routeAuth(request: Request, auth: AuthFn<Request> | readonly AuthFn<Request>[]): Promise<SessionAuthContext | Response>;
+/**
+ * Returns an {@link AuthFn} for scaffolded apps that makes unfinished
+ * production auth fail as an intentional 401 rather than an internal route
+ * error. Replace it before serving real users:
+ *
+ * ```ts
+ * eveChannel({ auth: [localDev(), vercelOidc(), placeholderAuth()] });
+ * ```
+ *
+ * Outside production it returns `null`, so the auth walk keeps the same local
+ * development behavior as any other skipped entry.
+ */
+export declare function placeholderAuth(): AuthFn<Request>;
+/**
+ * Returns an {@link AuthFn} that accepts any request anonymously, producing
+ * a synthetic principal with `principalType: "anonymous"`. Use it as the
+ * final entry in an `auth` array to opt routes into unauthenticated access:
+ *
+ * ```ts
+ * eveChannel({ auth: [none()] }); // every request accepted anonymously
+ * ```
+ *
+ * The returned `SessionAuthContext` halts the {@link routeAuth} walk, so
+ * `none()` terminates whatever array it appears in. It ignores its event
+ * argument, so `TEvent` is inferred from the surrounding array (defaulting
+ * to `unknown`) and composes with `AuthFn<Request>` entries without a type
+ * argument.
+ */
+export declare function none<TEvent = unknown>(): AuthFn<TEvent>;
+/**
+ * Returns an {@link AuthFn} that authenticates requests during local
+ * development, keyed on the request URL's hostname (not the host process).
+ * A hostname is treated as loopback when it is `localhost` or any
+ * `*.localhost` subdomain (RFC 6761 routes the `.localhost` TLD to
+ * loopback), any IPv4 in `127.0.0.0/8`, or the IPv6 loopback `::1`.
+ *
+ * Matching requests get a synthetic principal with `principalType:
+ * "local-dev"`. Every other request returns `null`, skipping to the next
+ * entry under {@link routeAuth}, which makes `[localDev(), vercelOidc()]`
+ * the canonical "open on localhost, Vercel OIDC in prod" pattern.
+ *
+ * The check is not based on bare `process.env.VERCEL`: a deployment
+ * outside Vercel (Fly, Railway, raw container) leaves `VERCEL` unset and
+ * would then accept every public request. The one process-level exception
+ * is `vercel dev`, detected by `VERCEL=1` and `VERCEL_ENV=development`
+ * together. Only the local `vercel dev` server sets that pair (preview and
+ * production report `VERCEL_ENV=preview`/`production`), so it opens the
+ * dev server (which may serve over a non-loopback host) without opening a
+ * real deployment.
+ *
+ * Caveat: this assumes a sane edge in front of public origins. An origin
+ * that trusts an attacker-controlled `Host` header (no CDN, no normalizing
+ * reverse proxy) lets an attacker spoof `Host: localhost` and reach
+ * `localDev()`. Layer a real authenticator on such deployments.
+ */
+export declare function localDev(): AuthFn<Request>;
+/**
+ * Options for {@link verifyVercelOidc} and {@link vercelOidc}.
+ */
+export interface VerifyVercelOidcOptions {
+    /**
+     * Optional `sub` patterns granting callers access on top of the always-on
+     * current-project bypass. Patterns use AWS IAM-style `*` wildcards and may
+     * target tokens minted by other Vercel projects (e.g.
+     * `"owner:acme:project:partner-agent:environment:*"`). The current project
+     * is always accepted regardless of this list.
+     */
+    readonly subjects?: readonly string[];
+}
+/**
+ * Verifies a bearer JWT minted by Vercel OIDC.
+ *
+ * Acceptance rule:
+ *
+ * - Tokens whose `project_id` matches `VERCEL_PROJECT_ID` are **always**
+ *   accepted regardless of `subjects`, so the deployment's own runtime
+ *   callers (subagent, internal fetches) authenticate without being
+ *   enumerated.
+ * - Tokens with an `external_sub` claim authenticate as
+ *   `principalType: "user"` when they match the current `VERCEL_PROJECT_ID`
+ *   (if set) and `VERCEL_TARGET_ENV` / `VERCEL_ENV` (if set). `external_sub`
+ *   becomes the Eve subject, `external_iss` or `connector_id` the Eve issuer
+ *   when present, and string-valued OIDC profile claims (`name`, `picture`,
+ *   `email`) are exposed as auth attributes.
+ * - Tokens from other Vercel projects are accepted **only** when their `sub`
+ *   matches one of {@link VerifyVercelOidcOptions.subjects}.
+ *
+ * The `environment` claim is not constrained: production, preview, and
+ * development tokens for the current project all authenticate. Non-user
+ * principals are tagged `"runtime"` when the token's `environment` matches
+ * the current deployment, otherwise `"service"`.
+ */
+export declare function verifyVercelOidc(token: string | null, opts?: VerifyVercelOidcOptions): Promise<VerifyResult>;
+/**
+ * Allowed values for {@link VercelSubjectInput.environment}. Use `"*"`
+ * to match any of `production`, `preview`, and `development` for the
+ * named project.
+ */
+export type VercelSubjectEnvironment = "production" | "preview" | "development" | "*";
+/**
+ * Strict input shape accepted by {@link vercelSubject}.
+ *
+ * The `sub` claim carries human-readable slugs/names, not IDs. Stable
+ * project and team IDs (`prj_...`, `team_...`) live on the separate
+ * `project_id` / `owner_id` claims, which `verifyVercelOidc` matches
+ * against `VERCEL_PROJECT_ID` for the current-project bind. This helper
+ * composes a `sub` matcher, so its inputs are slugs.
+ */
+export interface VercelSubjectInput {
+    /**
+     * Vercel team slug (a.k.a. "owner"; e.g. `"acme"`) as embedded in the
+     * `sub` claim, **not** the stable team ID `team_...` (`VERCEL_TEAM_ID`).
+     *
+     * Must not contain `*` or `:` so authors cannot widen the matcher to
+     * "any team with a project of this name". Hand-write the subject string
+     * when cross-team federation is intentional.
+     */
+    readonly teamSlug: string;
+    /**
+     * Vercel project name (e.g. `"acme_website"`) as embedded in the `sub`
+     * claim, **not** the stable project ID `prj_...` (`VERCEL_PROJECT_ID`).
+     * Same constraints as {@link teamSlug}.
+     */
+    readonly projectName: string;
+    /**
+     * Vercel deployment environment, or `"*"` to match any environment for
+     * the named project. Defaults to `"production"` so an unspecified
+     * environment cannot silently accept preview/development tokens.
+     */
+    readonly environment?: VercelSubjectEnvironment;
+}
+/**
+ * Builds a Vercel OIDC `sub` matcher pattern from a typed input.
+ *
+ * Vercel-issued tokens carry a `sub` of the form
+ * `owner:[TEAM_SLUG]:project:[PROJECT_NAME]:environment:[ENVIRONMENT]`.
+ * Hand-writing it invites two foot-guns: a misspelled slug (silently
+ * rejecting all callers) and over-broad wildcards (silently accepting
+ * unrelated callers). This helper rejects malformed inputs at construction
+ * time and forces an explicit `environment`.
+ *
+ * Use it inside {@link VerifyVercelOidcOptions.subjects} to layer
+ * additional Vercel-project callers on top of the current-project bypass:
+ *
+ * ```ts
+ * vercelOidc({
+ *   subjects: [vercelSubject({ teamSlug: "partner", projectName: "data" })],
+ * });
+ * ```
+ *
+ * The `sub` claim flips when a team or project name changes, so any policy
+ * built on this helper must update with it; the stable team/project IDs are
+ * not exposed in `sub`. See Vercel's OIDC reference for the token anatomy.
+ */
+export declare function vercelSubject(input: VercelSubjectInput): string;
+/**
+ * Returns an HTTP route auth callback backed by Vercel OIDC. See
+ * {@link verifyVercelOidc} for the always-on current-project bypass and how
+ * `subjects` extends acceptance to other Vercel projects.
+ */
+export declare function vercelOidc(opts?: VerifyVercelOidcOptions): AuthFn<Request>;
+/** Returns an {@link AuthFn} that verifies HTTP Basic credentials via {@link verifyHttpBasic}. */
+export declare function httpBasic(credentials: HttpBasicCredentials): AuthFn<Request>;
+/** Returns an {@link AuthFn} that verifies an HMAC-signed bearer JWT via {@link verifyJwtHmac}. */
+export declare function jwtHmac(config: VerifyJwtHmacConfig): AuthFn<Request>;
+/** Returns an {@link AuthFn} that verifies an ECDSA-signed bearer JWT via {@link verifyJwtEcdsa}. */
+export declare function jwtEcdsa(config: VerifyJwtEcdsaConfig): AuthFn<Request>;
+/**
+ * Returns an {@link AuthFn} that verifies an OIDC bearer token on the inbound
+ * request via {@link verifyOidc}. Use {@link vercelOidc} instead for
+ * Vercel-issued tokens: it preconfigures the issuer, audience, and runtime
+ * principal flag.
+ */
+export declare function oidc(config: VerifyOidcConfig): AuthFn<Request>;

package/dist/src/public/channels/auth.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{decodeJwt}from"#compiled/jose/index.js";import{authenticateHttpBasicStrategy}from"#runtime/governance/auth/http-basic.js";import{authenticateJwtEcdsaStrategy}from"#runtime/governance/auth/jwt-ecdsa.js";import{authenticateJwtHmacStrategy}from"#runtime/governance/auth/jwt-hmac.js";import{authenticateOidcStrategy}from"#runtime/governance/auth/oidc.js";import{createRuntimeSessionAuthContext}from"#runtime/governance/auth/types.js";import{createRuntimeIpAllowList,isRuntimeIpAllowed}from"#runtime/governance/network/ip-allow-list.js";const vercelOidcLog=createLogger(`auth.vercel-oidc`);function verifyHttpBasic(e,t){if(e===null)return{ok:!1};let r=authenticateHttpBasicStrategy({authorization:e,strategy:{kind:`http-basic`,password:t.password,username:t.username}});return r.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(r.principal)}:{ok:!1}}async function verifyJwtHmac(e,t){if(e===null||e.length===0)return{ok:!1};let n=await authenticateJwtHmacStrategy({strategy:{algorithm:t.algorithm,audiences:[...t.audiences],clockSkewSeconds:t.clockSkewSeconds??30,issuer:t.issuer,kind:`jwt-hmac`,secret:t.secret,...t.claims===void 0?{}:{claims:t.claims},...t.subjects===void 0?{}:{subjects:t.subjects}},token:e});return n.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(n.principal)}:{ok:!1}}async function verifyJwtEcdsa(e,t){if(e===null||e.length===0)return{ok:!1};let n=await authenticateJwtEcdsaStrategy({strategy:{algorithm:t.algorithm,audiences:[...t.audiences],clockSkewSeconds:t.clockSkewSeconds??30,issuer:t.issuer,kind:`jwt-ecdsa`,publicKey:t.publicKey,...t.claims===void 0?{}:{claims:t.claims},...t.subjects===void 0?{}:{subjects:t.subjects}},token:e});return n.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(n.principal)}:{ok:!1}}async function verifyOidc(e,t){let n=await runOidcVerification(e,{...t,acceptCurrentVercelProject:!1});return n.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(n.principal)}:{ok:!1}}async function runOidcVerification(e,t){return e===null||e.length===0?{kind:`not-authenticated`}:await authenticateOidcStrategy({strategy:{acceptCurrentVercelProject:t.acceptCurrentVercelProject,audiences:[...t.audiences],clockSkewSeconds:t.clockSkewSeconds??30,discoveryUrl:t.discoveryUrl??`${t.issuer.replace(/\/$/,``)}/.well-known/openid-configuration`,issuer:t.issuer,kind:`oidc`,...t.claims===void 0?{}:{claims:t.claims},...t.subjects===void 0?{}:{subjects:t.subjects}},token:e})}function extractBearerToken(e){if(e===null)return null;let t=/^Bearer\s+(.+)$/i.exec(e)?.[1]?.trim();return t===void 0||t.length===0?null:t}function createIpAllowList(e){return createRuntimeIpAllowList(e)}function isIpAllowed(e,t){return e===null?!1:isRuntimeIpAllowed(e,t)}function createUnauthorizedResponse(e={}){let t=e.status??401,n=e.code??(t===403?`forbidden`:`unauthorized`),r=e.message??(t===403?`Forbidden.`:`Authorization is required for this route.`),i=e.challenges??[],a=new Headers({"cache-control":`no-store`});for(let e of i)a.append(`www-authenticate`,formatChallenge(e));return Response.json({code:n,error:r,ok:!1},{headers:a,status:t})}function formatChallenge(e){if(e.parameters===void 0||Object.keys(e.parameters).length===0)return e.scheme;let t=Object.entries(e.parameters).map(([e,t])=>`${e}="${escapeChallengeValue(t)}"`).join(`, `);return`${e.scheme} ${t}`}function escapeChallengeValue(e){return e.replaceAll(`\\`,`\\\\`).replaceAll(`"`,`\\"`)}var UnauthenticatedError=class extends Error{response;constructor(e={}){super(e.message??`Authorization is required for this route.`),this.name=`UnauthenticatedError`,this.response=createUnauthorizedResponse({...e,status:401})}},ForbiddenError=class extends Error{response;constructor(e={}){super(e.message??`Forbidden.`),this.name=`ForbiddenError`,this.response=createUnauthorizedResponse({...e,status:403})}};async function routeAuth(e,t){let n=Array.isArray(t)?t:[t];try{for(let t of n){let n=await t(e);if(n)return n}}catch(e){if(typeof e==`object`&&e&&`response`in e&&e.response instanceof Response)return e.response;throw e}return createUnauthorizedResponse({challenges:[{scheme:`Bearer`}]})}function placeholderAuth(){return()=>{if(process.env.VERCEL_ENV!==`production`)return null;throw new UnauthenticatedError({code:`eve_production_auth_not_configured`,message:`Production auth is not configured. Replace placeholderAuth() in agent/channels/eve.ts with your app's auth provider.`})}}function none(){return()=>ANONYMOUS_SESSION_AUTH_CONTEXT}function localDev(){return e=>process.env.VERCEL&&process.env.VERCEL_ENV===`development`||isLoopbackRequest(e)?LOCAL_DEV_SESSION_AUTH_CONTEXT:null}const LOOPBACK_HOSTNAMES=new Set([`localhost`,`[::1]`]),LOOPBACK_IPV4_PREFIX=/^127\./;function isLoopbackRequest(e){let t;try{t=new URL(e.url).hostname}catch{return!1}return!!(LOOPBACK_HOSTNAMES.has(t)||LOOPBACK_IPV4_PREFIX.test(t)||t.endsWith(`.localhost`))}const ANONYMOUS_SESSION_AUTH_CONTEXT={attributes:{},authenticator:`none`,principalId:`anonymous`,principalType:`anonymous`},LOCAL_DEV_SESSION_AUTH_CONTEXT={attributes:{},authenticator:`local-dev`,principalId:`local-dev`,principalType:`local-dev`};async function verifyVercelOidc(e,t={}){if(e===null||e.length===0)return{ok:!1};let n=decodeUnverifiedJwtClaims(e);if(n===null)return vercelOidcLog.debug(`Rejected token that failed to decode as a JWT.`),{ok:!1};if(!n.issuer.startsWith(`https://oidc.vercel.com/`))return vercelOidcLog.debug(`Rejected token whose issuer is not a Vercel OIDC issuer.`,{issuer:n.issuer}),{ok:!1};if(n.audiences.length===0)return vercelOidcLog.debug(`Rejected token with no audience claim.`,{issuer:n.issuer}),{ok:!1};if(!n.audiences.some(e=>e.startsWith(`https://vercel.com/`)))return vercelOidcLog.debug(`Rejected token whose audience is not a Vercel audience.`,{audiences:n.audiences,issuer:n.issuer}),{ok:!1};let r=await runOidcVerification(e,{acceptCurrentVercelProject:!0,audiences:n.audiences,issuer:n.issuer,subjects:t.subjects??[]});return r.kind===`authenticated`?(vercelOidcLog.debug(`Accepted Vercel OIDC token.`,{issuer:n.issuer,principalType:r.principal.principalType,subject:r.principal.subject}),{ok:!0,sessionAuth:createRuntimeSessionAuthContext(r.principal)}):(vercelOidcLog.debug(`Rejected Vercel OIDC token after verification.`,{audiences:n.audiences,issuer:n.issuer,reason:r.kind,subjectsConfigured:(t.subjects??[]).length>0,...r.kind===`misconfigured`?{detail:r.message}:{}}),{ok:!1})}function vercelSubject(e){assertVercelSubjectSegment(`teamSlug`,e.teamSlug),assertVercelSubjectSegment(`projectName`,e.projectName);let t=e.environment??`production`;if(t!==`production`&&t!==`preview`&&t!==`development`&&t!==`*`)throw Error(`vercelSubject: invalid environment ${JSON.stringify(t)}; expected "production", "preview", "development", or "*".`);return`owner:${e.teamSlug}:project:${e.projectName}:environment:${t}`}function assertVercelSubjectSegment(e,t){if(t.length===0)throw Error(`vercelSubject: ${e} must be a non-empty string.`);if(t.includes(`*`)||t.includes(`:`))throw Error(`vercelSubject: ${e} ${JSON.stringify(t)} may not contain ${t.includes(`:`)?`':'`:`'*'`}. Hand-write the subject string when wildcards are intentional.`)}function vercelOidc(e={}){return async t=>{let n=await verifyVercelOidc(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null}}function httpBasic(e){return t=>{let n=verifyHttpBasic(t.headers.get(`authorization`),e);return n.ok?n.sessionAuth:null}}function jwtHmac(e){return async t=>{let n=await verifyJwtHmac(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null}}function jwtEcdsa(e){return async t=>{let n=await verifyJwtEcdsa(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null}}function oidc(e){return async t=>{let n=await verifyOidc(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null}}function decodeUnverifiedJwtClaims(e){let n;try{n=decodeJwt(e)}catch{return null}return typeof n.iss!=`string`||n.iss.length===0?null:{audiences:typeof n.aud==`string`?[n.aud]:Array.isArray(n.aud)?n.aud.filter(e=>typeof e==`string`):[],issuer:n.iss}}export{ForbiddenError,UnauthenticatedError,createIpAllowList,createUnauthorizedResponse,extractBearerToken,httpBasic,isIpAllowed,jwtEcdsa,jwtHmac,localDev,none,oidc,placeholderAuth,routeAuth,vercelOidc,vercelSubject,verifyHttpBasic,verifyJwtEcdsa,verifyJwtHmac,verifyOidc,verifyVercelOidc};