eve 0.83.2 → 0.84.0

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

@@ -1,518 +1,2 @@
-/**
- * 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 "#channel/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. Both
- * values are normalized to Unicode NFC before comparison, matching the
- * `charset="UTF-8"` challenge advertised by {@link httpBasic}.
- */
-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;
-/** @internal Escapes a value for an HTTP auth challenge quoted string. */
-export declare function escapeAuthChallengeParameter(value: string): string;
-/**
- * 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);
-}
-export interface AuthResult extends SessionAuthContext {
-    /**
-     * Set to true to let this authenticated caller create sessions with tool stubs.
-     * Callers without this permission cannot supply stubs.
-     */
-    readonly allowToolStubs?: boolean;
-}
-/**
- * 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) => AuthResult | null | undefined | Promise<AuthResult | null | undefined>;
-/**
- * OAuth protected-resource metadata attached to an inbound auth policy.
- * `issuer` is shorthand for a single authorization server.
- */
-export type OAuthResourceOptions = {
-    readonly metadataPath?: string;
-    readonly resource?: string;
-    readonly scopes?: readonly string[];
-} & ({
-    readonly authorizationServers?: never;
-    readonly issuer: string;
-} | {
-    readonly authorizationServers: readonly string[];
-    readonly issuer?: never;
-});
-declare const OAUTH_RESOURCE_SYMBOL: unique symbol;
-/**
- * An ordinary route authenticator decorated with OAuth protected-resource
- * discovery metadata.
- */
-export type OAuthResourceAuth = AuthFn<Request> & {
-    readonly [OAUTH_RESOURCE_SYMBOL]: OAuthResourceOptions;
-};
-/**
- * Adds OAuth protected-resource metadata to an existing inbound auth policy.
- *
- * The returned value remains an {@link AuthFn}: it preserves the ordered auth
- * walk and can be used by any channel. A protocol-aware channel such as
- * `mcpChannel` may additionally publish the metadata and discovery challenge.
- */
-export declare function oauthResource(auth: AuthFn<Request> | readonly AuthFn<Request>[], options: OAuthResourceOptions): OAuthResourceAuth;
-/** @internal Reads OAuth resource metadata without widening `AuthFn`. */
-export declare function readOAuthResourceOptions(auth: AuthFn<Request> | readonly AuthFn<Request>[]): OAuthResourceOptions | undefined;
-/**
- * Attaches declared `www-authenticate` challenges to an {@link AuthFn}
- * without changing its call signature or behavior. {@link routeAuth} reads
- * the declared challenges back when every entry in the walk skips, so the
- * resulting 401 advertises the scheme(s) the configured strategies actually
- * accept (e.g. `Basic` for {@link httpBasic}) instead of a fixed default.
- *
- * Built-in strategies (`httpBasic`, `jwtHmac`, `jwtEcdsa`, `oidc`,
- * `vercelOidc`) already declare their challenge. Use this directly when
- * authoring a custom `AuthFn`:
- *
- * ```ts
- * const apiKey = withAuthChallenges(
- *   (request) => (isValidApiKey(request) ? sessionAuth : null),
- *   [{ scheme: "Bearer" }],
- * );
- * ```
- */
-export declare function withAuthChallenges<TEvent>(fn: AuthFn<TEvent>, challenges: readonly UnauthorizedChallenge[]): AuthFn<TEvent>;
-/**
- * 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}
- * whose `www-authenticate` challenges are collected from the entries'
- * declared schemes (see {@link withAuthChallenges}), falling back to
- * `Bearer` when none declared any.
- *
- * 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<AuthResult | 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: [vercelOidc(), localDev(), 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 a synthetic `local-dev`
- * principal while the process is a local development server, and returns
- * `null` everywhere else so the {@link routeAuth} walk falls through to the
- * next entry.
- *
- * A process counts as a local development server when it is `eve dev`
- * (`EVE_DEV=1`) or `vercel dev` (`VERCEL=1` with `VERCEL_ENV=development`).
- * This is a property of the deployment, never of the inbound request, so no
- * request header (for example `Host`) can flip the decision. A production
- * deployment (`eve start`, a Vercel deployment, or any container host) sets
- * neither flag, so `localDev()` authenticates nothing there. Layer a real
- * authenticator on those hosts.
- */
-export declare function localDev(): AuthFn<Request>;
-/**
- * Options for verifying a Vercel OIDC token with {@link verifyVercelOidc}.
- */
-export interface VerifyVercelOidcOptions {
-    /**
-     * Explicit current-project binding for the verified token. When omitted,
-     * the verifier reads `VERCEL_PROJECT_ID` and `VERCEL_TARGET_ENV` /
-     * `VERCEL_ENV` from the runtime environment.
-     */
-    readonly currentVercelProject?: {
-        readonly environment?: string;
-        readonly projectId: string;
-    };
-    /**
-     * 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:
- *
- * - Current-project tokens that reach the service/runtime path are 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 configured current project
- *   and environment. `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.
- * - Development tokens with a `user_id` claim authenticate as
- *   `principalType: "user"` only when both the token and configured current
- *   project environment are `development`. Other same-project target
- *   environments may use one as a `"service"` principal.
- * - Tokens from other Vercel projects are accepted **only** when their `sub`
- *   matches one of {@link VerifyVercelOidcOptions.subjects}.
- *
- * Tokens without a `user_id` claim are accepted for the current project in
- * production, preview, and development. They 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;
-export interface VercelOidcOptions extends Omit<VerifyVercelOidcOptions, "subjects"> {
-    /**
-     * Additional token subjects allowed to authenticate.
-     * To allow stubs, use { subject, allowToolStubs: true } for that subject.
-     */
-    readonly subjects?: readonly (string | {
-        readonly subject: string;
-        readonly allowToolStubs?: boolean;
-    })[];
-}
-/**
- * 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. Declares a
- * `Bearer` {@link withAuthChallenges} challenge for {@link routeAuth}'s 401.
- */
-export declare function vercelOidc(opts?: VercelOidcOptions): AuthFn<Request>;
-/**
- * Options accepted by {@link httpBasic}.
- */
-export interface HttpBasicAuthOptions {
-    /**
-     * Optional `realm` parameter advertised on the `WWW-Authenticate: Basic`
-     * challenge (e.g. browsers show it in the native login prompt). Defaults
-     * to `"eve"`.
-     */
-    readonly realm?: string;
-}
-/**
- * Returns an {@link AuthFn} that verifies HTTP Basic credentials via
- * {@link verifyHttpBasic}. Declares a `Basic` {@link withAuthChallenges}
- * challenge so a {@link routeAuth} 401 advertises `WWW-Authenticate: Basic`
- * (with `realm` first, when given, then `charset="UTF-8"`) instead of the
- * `Bearer` fallback.
- */
-export declare function httpBasic(credentials: HttpBasicCredentials, options?: HttpBasicAuthOptions): AuthFn<Request>;
-/**
- * Returns an {@link AuthFn} that verifies an HMAC-signed bearer JWT via
- * {@link verifyJwtHmac}. Declares a `Bearer` {@link withAuthChallenges}
- * challenge for {@link routeAuth}'s 401.
- */
-export declare function jwtHmac(config: VerifyJwtHmacConfig): AuthFn<Request>;
-/**
- * Returns an {@link AuthFn} that verifies an ECDSA-signed bearer JWT via
- * {@link verifyJwtEcdsa}. Declares a `Bearer` {@link withAuthChallenges}
- * challenge for {@link routeAuth}'s 401.
- */
-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. Declares a `Bearer` {@link withAuthChallenges} challenge
- * for {@link routeAuth}'s 401.
- */
-export declare function oidc(config: VerifyOidcConfig): AuthFn<Request>;
-export {};
+/** HTTP authentication strategies and verifiers. */
+export { verifyHttpBasic, verifyJwtHmac, verifyJwtEcdsa, verifyOidc, extractBearerToken, createIpAllowList, isIpAllowed, createUnauthorizedResponse, oauthResource, withAuthChallenges, routeAuth, placeholderAuth, none, localDev, verifyVercelOidc, vercelSubject, vercelOidc, httpBasic, jwtHmac, jwtEcdsa, oidc, type VerifyResult, type HttpBasicCredentials, type VerifyJwtHmacConfig, type VerifyJwtEcdsaConfig, type VerifyOidcConfig, type IpAllowList, type UnauthorizedChallenge, type UnauthorizedResponseOptions, type AuthErrorOptions, UnauthenticatedError, ForbiddenError, type AuthResult, type AuthFn, type OAuthResourceOptions, type OAuthResourceAuth, type VerifyVercelOidcOptions, type VercelSubjectEnvironment, type VercelSubjectInput, type VercelOidcOptions, type HttpBasicAuthOptions, } from "#channel/auth/definitions.js";

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

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";import{decodeJwt}from"#compiled/jose/index.js";import{areTokenClaimMatchersSatisfied}from"#channel/auth/token-claims.js";import{isVercelOidcIssuer}from"#shared/vercel-project.js";import{isLoopbackHostname}from"#shared/network-address.js";import{isEveDevEnvironment}from"#internal/application/dev-environment.js";import{ANONYMOUS_SESSION_AUTH_CONTEXT}from"#channel/principal-identity.js";import{resolveVercelOidcCurrentProject}from"#channel/auth/vercel-oidc-project.js";import{authenticateHttpBasicStrategy}from"#channel/auth/http-basic.js";import{authenticateJwtEcdsaStrategy}from"#channel/auth/jwt-ecdsa.js";import{authenticateJwtHmacStrategy}from"#channel/auth/jwt-hmac.js";import{authenticateOidcStrategy}from"#channel/auth/oidc.js";import{createRuntimeSessionAuthContext}from"#channel/auth/types.js";import{createRuntimeIpAllowList,isRuntimeIpAllowed}from"#channel/ip-allow-list.js";const vercelOidcLog=createLogger(`auth.vercel-oidc`);function verifyHttpBasic(e,t){if(e===null)return{ok:!1};let n=authenticateHttpBasicStrategy({authorization:e,strategy:{kind:`http-basic`,password:t.password,username:t.username}});return n.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(n.principal)}:{ok:!1}}async function verifyJwtHmac(e,t){if(e===null||e.length===0)return{ok:!1};let n={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}},r=await authenticateJwtHmacStrategy({strategy:n,token:e});return r.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(r.principal)}:{ok:!1}}async function verifyJwtEcdsa(e,t){if(e===null||e.length===0)return{ok:!1};let n={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}},r=await authenticateJwtEcdsaStrategy({strategy:n,token:e});return r.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(r.principal)}:{ok:!1}}async function verifyOidc(e,t){let n=await runOidcVerification(e,{...t,acceptCurrentVercelProject:!1,currentVercelProject:void 0});return n.kind===`authenticated`?{ok:!0,sessionAuth:createRuntimeSessionAuthContext(n.principal)}:{ok:!1}}async function runOidcVerification(e,t){if(e===null||e.length===0)return{kind:`not-authenticated`};let n={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}},r=t.currentVercelProject===void 0?n:{...n,currentVercelProject:t.currentVercelProject};return await authenticateOidcStrategy({strategy:r,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&&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}="${escapeAuthChallengeParameter(t)}"`).join(`, `);return`${e.scheme} ${t}`}function escapeAuthChallengeParameter(e){return e.replaceAll(`\\`,`\\\\`).replaceAll(`"`,`\\"`)}function isValidOAuthIdentifierUrl(e){try{let t=new URL(e);return(t.protocol===`https:`||t.protocol===`http:`&&isLoopbackHostname(t.hostname))&&t.username.length===0&&t.password.length===0&&t.search.length===0&&t.hash.length===0}catch{return!1}}function isValidMetadataPath(e){if(!e.startsWith(`/`)||e.startsWith(`//`))return!1;let t=new URL(e,`https://eve.invalid`);return t.origin===`https://eve.invalid`&&t.search.length===0&&t.hash.length===0}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})}};const OAUTH_RESOURCE_SYMBOL=Symbol.for(`eve.channels.auth.oauthResource`);function oauthResource(e,t){let n=t.issuer===void 0?t.authorizationServers:[t.issuer];if(n.length===0||n.some(e=>!isValidOAuthIdentifierUrl(e)))throw Error(`oauthResource requires at least one HTTPS authorization server URL (HTTP is allowed only on loopback).`);if(t.resource!==void 0&&!isValidOAuthIdentifierUrl(t.resource))throw Error(`oauthResource resource must be an HTTPS URL without credentials, query, or fragment (HTTP is allowed only on loopback).`);if(t.metadataPath!==void 0&&!isValidMetadataPath(t.metadataPath))throw Error(`oauthResource metadataPath must be an absolute path without a host, query, or fragment.`);let r=Array.isArray(e)?e:[e],composed=async e=>{for(let t of r){let n=await t(e);if(n)return n}return null},i=collectDeclaredChallenges(r),a=withAuthChallenges(composed,i.length>0?i:[{scheme:`Bearer`}]);return Object.defineProperty(a,OAUTH_RESOURCE_SYMBOL,{enumerable:!1,value:t}),a}function readOAuthResourceOptions(e){if(!Array.isArray(e))return e[OAUTH_RESOURCE_SYMBOL]}const AUTH_CHALLENGES_SYMBOL=Symbol.for(`eve.channels.auth.challenges`);function withAuthChallenges(e,t){let wrapped=t=>e(t);return Object.defineProperty(wrapped,AUTH_CHALLENGES_SYMBOL,{value:t}),wrapped}function getDeclaredChallenges(e){return e[AUTH_CHALLENGES_SYMBOL]}function collectDeclaredChallenges(e){let t=new Set,n=[];for(let r of e)for(let e of getDeclaredChallenges(r)??[]){let r=formatChallenge(e);t.has(r)||(t.add(r),n.push(e))}return n}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}let r=collectDeclaredChallenges(n);return createUnauthorizedResponse({challenges:r.length>0?addInvalidBearerTokenError(e,r):[{scheme:`Bearer`}]})}function addInvalidBearerTokenError(e,t){let n=e.headers.get(`authorization`);return n===null||!/^Bearer(?:\s|$)/i.test(n.trim())||!t.some(e=>e.scheme===`Bearer`)?t:t.map(e=>e.scheme!==`Bearer`||e.parameters?.error!==void 0?e:{...e,parameters:{...e.parameters,error:`invalid_token`}})}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()=>isLocalDevelopmentServer()?LOCAL_DEV_SESSION_AUTH_CONTEXT:null}function isLocalDevelopmentServer(){return process.env.VERCEL&&process.env.VERCEL_ENV===`development`?!0:isEveDevEnvironment()}const 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(!isVercelOidcIssuer(n.issuer))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=resolveCurrentVercelProject(t),i=await runOidcVerification(e,{acceptCurrentVercelProject:!0,audiences:n.audiences,currentVercelProject:r,issuer:n.issuer,subjects:t.subjects??[]});return i.kind===`authenticated`?(vercelOidcLog.debug(`Accepted Vercel OIDC token.`,{issuer:n.issuer,principalType:i.principal.principalType,subject:i.principal.subject}),{ok:!0,sessionAuth:createRuntimeSessionAuthContext(i.principal)}):(vercelOidcLog.debug(`Rejected Vercel OIDC token after verification.`,{audiences:n.audiences,issuer:n.issuer,reason:i.kind,subjectsConfigured:(t.subjects??[]).length>0,...i.kind===`misconfigured`?{detail:i.message}:{}}),{ok:!1})}function resolveCurrentVercelProject(e){if(e.currentVercelProject!==void 0)return e.currentVercelProject;let t=process.env.VERCEL_PROJECT_ID?.trim();if(t===void 0||t.length===0)return;let n=process.env.VERCEL_TARGET_ENV?.trim()||process.env.VERCEL_ENV?.trim();return n===void 0||n.length===0?{projectId:t}:{environment:n,projectId:t}}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={}){let{subjects:t,...n}=e,r={...n,subjects:t?.map(e=>typeof e==`string`?e:e.subject)};return withAuthChallenges(async n=>{let i=extractBearerToken(n.headers.get(`authorization`)),a=e.currentVercelProject??(i!==null&&isLocalDevelopmentVercelOidc()?await resolveVercelOidcCurrentProject(n):void 0),o=await verifyVercelOidc(i,a===void 0?r:{...r,currentVercelProject:a});if(!o.ok)return null;let s=o.sessionAuth;return(s.principalType===`service`||s.principalType===`runtime`)&&t?.some(e=>typeof e!=`string`&&e.allowToolStubs===!0&&areTokenClaimMatchersSatisfied({sub:s.subject},{subjects:[e.subject]}))?{...s,allowToolStubs:!0}:s},[{scheme:`Bearer`}])}function isLocalDevelopmentVercelOidc(){return process.env.VERCEL_ENV===`development`?!0:process.env.VERCEL_ENV===`preview`||process.env.VERCEL_ENV===`production`?!1:isEveDevEnvironment()}function httpBasic(e,t){return withAuthChallenges(t=>{let n=verifyHttpBasic(t.headers.get(`authorization`),e);return n.ok?n.sessionAuth:null},[{parameters:{realm:t?.realm??`eve`,charset:`UTF-8`},scheme:`Basic`}])}function jwtHmac(e){return withAuthChallenges(async t=>{let n=await verifyJwtHmac(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null},[{scheme:`Bearer`}])}function jwtEcdsa(e){return withAuthChallenges(async t=>{let n=await verifyJwtEcdsa(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null},[{scheme:`Bearer`}])}function oidc(e){return withAuthChallenges(async t=>{let n=await verifyOidc(extractBearerToken(t.headers.get(`authorization`)),e);return n.ok?n.sessionAuth:null},[{scheme:`Bearer`}])}function decodeUnverifiedJwtClaims(e){let t;try{t=decodeJwt(e)}catch{return null}return typeof t.iss!=`string`||t.iss.length===0?null:{audiences:typeof t.aud==`string`?[t.aud]:Array.isArray(t.aud)?t.aud.filter(e=>typeof e==`string`):[],issuer:t.iss}}export{ForbiddenError,UnauthenticatedError,createIpAllowList,createUnauthorizedResponse,escapeAuthChallengeParameter,extractBearerToken,httpBasic,isIpAllowed,jwtEcdsa,jwtHmac,localDev,none,oauthResource,oidc,placeholderAuth,readOAuthResourceOptions,routeAuth,vercelOidc,vercelSubject,verifyHttpBasic,verifyJwtEcdsa,verifyJwtHmac,verifyOidc,verifyVercelOidc,withAuthChallenges};
+import{ForbiddenError,UnauthenticatedError,createIpAllowList,createUnauthorizedResponse,extractBearerToken,httpBasic,isIpAllowed,jwtEcdsa,jwtHmac,localDev,none,oauthResource,oidc,placeholderAuth,routeAuth,vercelOidc,vercelSubject,verifyHttpBasic,verifyJwtEcdsa,verifyJwtHmac,verifyOidc,verifyVercelOidc,withAuthChallenges}from"#channel/auth/definitions.js";export{ForbiddenError,UnauthenticatedError,createIpAllowList,createUnauthorizedResponse,extractBearerToken,httpBasic,isIpAllowed,jwtEcdsa,jwtHmac,localDev,none,oauthResource,oidc,placeholderAuth,routeAuth,vercelOidc,vercelSubject,verifyHttpBasic,verifyJwtEcdsa,verifyJwtHmac,verifyOidc,verifyVercelOidc,withAuthChallenges};

package/dist/src/public/channels/chat-sdk/authorization.d.ts

@@ -1,3 +1,6 @@
+import { type SignInSurface } from "#channel/sign-in.js";
 import type { ChatSdkChannelEvents } from "#public/channels/chat-sdk/chatSdkChannel.js";
-/** Built-in connection authorization handlers for Chat SDK threads. */
-export declare function defaultAuthorizationEvents(): Pick<ChatSdkChannelEvents, "authorization.completed" | "authorization.required">;
+type SignInChannel = Parameters<NonNullable<ChatSdkChannelEvents["interaction.opened"]>>[1]["channel"];
+/** A Chat SDK thread as a sign-in shows on it: a DM is private; elsewhere the challenge goes to the person alone. */
+export declare function chatSdkSignIns(channel: SignInChannel): SignInSurface | undefined;
+export {};

package/dist/src/public/channels/chat-sdk/authorization.js

@@ -1,3 +1 @@
-import{createLogger,logError}from"#internal/logging.js";import{isNotImplemented}from"#public/channels/chat-sdk/notImplemented.js";const log=createLogger(`chat-sdk.authorization`);function defaultAuthorizationEvents(){return{async"authorization.required"(e,t,n){if(!t.thread||e.candidateId!==void 0)return;let r=t.state.pendingAuthMessageIds??{};if(r[e.name]!==void 0)return;let i=authorizationDisplayName(e.name,e.authorization?.displayName),a=authorizationPrompt({displayName:i,instructions:e.authorization?.instructions,url:e.authorization?.url,userCode:e.authorization?.userCode}),o=a;if(!t.thread.isDM){let n=e.principalId===void 0?void 0:t.state.usersByPrincipal?.[e.principalId];o=typeof n==`string`&&await postPrivately(t.thread,n,a)?`Authorization required for ${i}. I sent you the sign-in details privately.`:`Authorization required for ${i}. Continue in a direct message with this agent.`}let s=await t.thread.post({markdown:o});s.id&&(t.state.pendingAuthMessageIds={...r,[e.name]:s.id})},async"authorization.completed"(e,t,n){if(!t.thread||e.candidateId!==void 0)return;let r=t.state.pendingAuthMessageIds??{},i=r[e.name];if(i===void 0)return;let a=authorizationCompleted({displayName:authorizationDisplayName(e.name,e.authorization?.displayName),outcome:e.outcome,reason:e.reason});try{await editMessage(t.thread,i,a)}catch(e){if(!isNotImplemented(e))throw e;t.state.editSupported=!1,await t.thread.post({markdown:a})}let o={...r};delete o[e.name],t.state.pendingAuthMessageIds=o,e.outcome===`authorized`&&await safeStartTyping(t.thread,`Connected. Resuming...`)}}}async function postPrivately(e,t,n){try{return await e.postEphemeral(t,{markdown:n},{fallbackToDM:!0})!==null}catch(t){return isNotImplemented(t)||logError(log,`failed to deliver sign-in privately`,t,{threadId:e.id}),!1}}async function safeStartTyping(e,t){try{await e.startTyping(t)}catch(e){if(!isNotImplemented(e))throw e}}async function editMessage(e,t,n){await e.adapter.editMessage(e.id,t,{markdown:n})}function authorizationDisplayName(e,t){return t===void 0?e.length===0?e:e.charAt(0).toUpperCase()+e.slice(1):t}function authorizationPrompt(e){return[`Authorization required for ${e.displayName}.`,e.instructions,e.userCode===void 0?void 0:`Code: ${e.userCode}`,e.url].filter(e=>e!==void 0&&e.length>0).join(`
-
-`)}function authorizationCompleted(e){if(e.outcome===`authorized`)return`${e.displayName} connected.`;let t=e.reason===void 0?``:` (${e.reason})`,n=e.outcome===`timed-out`?`timed out`:e.outcome;return`${e.displayName} authorization ${n}${t}.`}export{defaultAuthorizationEvents};
+import{createLogger,logError}from"#internal/logging.js";import{postedIn,signInChallengeText}from"#channel/sign-in.js";import{isNotImplemented}from"#public/channels/chat-sdk/notImplemented.js";const log=createLogger(`chat-sdk.authorization`);function chatSdkSignIns(e){let{thread:t}=e;if(!t)return;let post=async e=>(await t.post({markdown:e})).id||void 0;return{private:t.isDM,postChallenge:e=>post(signInChallengeText(e)),async deliverPrivately(n){let r=n.principalId===void 0?void 0:e.state.usersByPrincipal?.[n.principalId];return typeof r==`string`&&postPrivately(t,r,signInChallengeText(n))},post,async edit(n,r){try{await t.adapter.editMessage(t.id,n,{markdown:r})}catch(n){if(!isNotImplemented(n))throw n;e.state.editSupported=!1,await t.post({markdown:r})}},async typing(e){try{await t.startTyping(e)}catch(e){if(!isNotImplemented(e))throw e}},posted:postedIn(e.state,`pendingAuthMessageIds`)}}async function postPrivately(e,t,n){try{return await e.postEphemeral(t,{markdown:n},{fallbackToDM:!0})!==null}catch(t){return isNotImplemented(t)||logError(log,`failed to deliver sign-in privately`,t,{threadId:e.id}),!1}}export{chatSdkSignIns};

package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts

@@ -1,19 +1,24 @@
 import { type PromptQueueState } from "#channel/prompt-queue.js";
-import type { UserContent } from "ai";
+import type { MessageContent } from "#shared/message-content.js";
 import type { ChannelRespondOptions, ChannelSendOptions } from "#channel/channel-operations.js";
 import type { SessionAuthContext, TurnPolicy } from "#channel/types.js";
-import type { InputResolution } from "#protocol/message.js";
-import type { InputRequest } from "#shared/input.js";
-import { type InputResponse, type StrictInputResponses } from "#shared/input.js";
+import type { RequestSettlement } from "#channel/interaction-prompts.js";
+import type { Interaction } from "#channel/interaction-prompts.js";
+import { type Answer, type StrictAnswers } from "#shared/input.js";
 import type { ActionEvent, Adapter, ChatConfig, SerializedThread, Thread, WebhookOptions } from "#compiled/chat/index.js";
 import { Chat } from "#compiled/chat/index.js";
-import { type Channel, type ChannelEvents, type ChannelContinuationOps, type Session } from "#public/definitions/channel.js";
+import { type UndeliveredReplyState } from "#public/channels/undelivered-reply.js";
+import { type Channel, type ChannelEvents, type ChannelContinuationOps, type Delivery } from "#public/definitions/channel.js";
 type ChatSdkAdapters = Record<string, Adapter>;
 /** Durable Chat SDK thread state plus default-handler streaming bookkeeping. */
-export interface ChatSdkChannelState extends Record<string, unknown>, PromptQueueState {
+export interface ChatSdkChannelState extends Record<string, unknown>, PromptQueueState, UndeliveredReplyState {
     thread: SerializedThread | null;
     /** Message id of the in-flight streamed assistant post (edit fallback). */
     anchorMessageId?: string | null;
+    /** Text streamed for the anchor so far, including deltas no throttled edit has shown yet. */
+    streamText?: string | null;
+    /** Text the anchor showed after its last successful post or edit. */
+    shownText?: string | null;
     /**
      * Whether `adapter.editMessage` works for this session. Set to `false` once
      * an edit throws {@link isNotImplemented}, which disables streaming edits for
@@ -33,14 +38,14 @@ export interface ChatSdkChannelState extends Record<string, unknown>, PromptQueu
     usersByPrincipal?: Record<string, string | null>;
     /** Posted input request cards, keyed by message id, until eve resolves every request on them. */
     pendingInputCards?: Record<string, ChatSdkPendingInputCard>;
+    streamPartId?: string | null;
     /** Id of the latest message someone other than the bot sent in the thread. */
     latestMessageId?: string;
-    streamStepIndex?: number | null;
 }
 /** One posted card's requests and the resolutions eve has reported for them so far. */
 export interface ChatSdkPendingInputCard {
-    readonly requests: readonly InputRequest[];
-    readonly resolved: Readonly<Record<string, InputResolution>>;
+    readonly requests: readonly Interaction[];
+    readonly resolved: Readonly<Record<string, RequestSettlement>>;
 }
 /**
  * Thread selector accepted by `chatSdkChannel().receive`. Pass a serialized
@@ -182,12 +187,12 @@ export interface ChatSdkChannelBridge<TAdapters extends ChatSdkAdapters = ChatSd
      * Use `channel.receive(...)` for proactive sends that are not handling an
      * inbound Chat SDK webhook.
      */
-    send(message: string | UserContent, options: ChatSdkSendOptions): Promise<Session>;
+    send(message: MessageContent, options: ChatSdkSendOptions): Promise<Delivery>;
     /**
      * Answers pending input requests on the thread's session from inside a Chat
      * SDK webhook handler. Never creates a session.
      */
-    respond<const TResponses extends readonly InputResponse[]>(inputResponses: StrictInputResponses<TResponses>, options: ChatSdkRespondOptions): Promise<Session>;
+    respond<const TResponses extends readonly Answer[]>(answers: StrictAnswers<TResponses>, options: ChatSdkRespondOptions): Promise<Delivery>;
 }
 /**
  * Creates an eve channel backed by one Chat SDK runtime and its adapters.