--- title: Auth & Route Protection description: Secure your agent's HTTP routes with an ordered auth walk, verifier helpers, and connection OAuth via Vercel Connect. --- # Auth & Route Protection Eve has two independent auth systems: * **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer, gating the request before any model work runs. * **Tool and connection auth** (outbound) is how your agent signs in to an external service it calls, like an OAuth MCP server. It happens later, when a tool or connection actually reaches out. Start with route auth. ## Route auth The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards three routes: * `POST /eve/v1/session` * `POST /eve/v1/session/:sessionId` * `GET /eve/v1/session/:sessionId/stream` `GET /eve/v1/health` is always public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials. ```ts title="agent/channels/eve.ts" import { eveChannel } from "eve/channels/eve"; import { localDev, vercelOidc } from "eve/channels/auth"; export default eveChannel({ auth: [localDev(), vercelOidc()], }); ``` ## The ordered auth walk `auth` takes a single `AuthFn` or an array that Eve walks in order. Each entry has three possible outcomes: * returns a `SessionAuthContext`: accept the request and stop the walk * returns `null` / `undefined`: skip to the next entry * **throws**: reject with a specific status If every entry skips, the request gets a `401`. An empty array `auth: []` rejects everything. ```ts import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth"; import { eveChannel } from "eve/channels/eve"; import { getSession } from "@/lib/auth"; function appSession(): AuthFn { return async (request) => { const session = await getSession(request); if (!session) return null; // skip; fall through to the next entry return { attributes: { providerId: session.providerId }, authenticator: "app", principalId: session.userId, principalType: "user", }; }; } export default eveChannel({ auth: [appSession(), localDev(), vercelOidc()], }); ``` Put your own providers ahead of the catch-all helpers. Any entry that doesn't recognize the caller returns `null`, and the walk moves on. To reject with a precise status instead of skipping, throw: ```ts import { ForbiddenError, UnauthenticatedError } from "eve/channels/auth"; throw new UnauthenticatedError({ code: "authentication_required", message: "Sign in to continue.", }); // 401 throw new ForbiddenError({ message: "Not allowed on this workspace." }); // 403 ``` Any other thrown error follows the normal channel failure path. When building a custom channel on `defineChannel`, call `routeAuth(request, auth)` from `eve/channels/auth` to reuse the same walk semantics. ## Verifier helpers `eve/channels/auth` ships these channel-auth helpers: | Helper | Use when | | ---------------- | ------------------------------------------------------------------------- | | `localDev()` | Local development. Accepts requests addressed to a loopback hostname. | | `vercelOidc()` | The common Vercel deployment path. Verifies a Vercel OIDC bearer JWT. | | `none()` | You want to accept anonymous traffic explicitly (use as the final entry). | | `httpBasic(...)` | Operator or service access via a shared username/password. | | `jwtHmac(...)` | You control a shared-secret JWT signer. | | `jwtEcdsa(...)` | You verify asymmetric JWTs minted by another system. | | `oidc(...)` | You want Eve to verify OIDC-issued tokens from an arbitrary issuer. | ### `localDev()` Authenticates a synthetic `local-dev` principal, but only when the inbound request is addressed to a loopback hostname (`localhost`, `*.localhost`, `127.0.0.0/8`, or `::1`). The check keys off the request URL's hostname rather than the bare `process.env.VERCEL` flag, and that's deliberate: a deployment outside Vercel leaves `VERCEL` unset, so sniffing that flag alone would wave through all public traffic. There's one process-level exception. `vercel dev`, detected by `VERCEL=1` and `VERCEL_ENV=development` together, opens the local dev server even when it serves over a non-loopback host. Every other non-loopback request returns `null` and falls through. `localDev()` trusts the advertised hostname, so an attacker who can inject a `Host` header (no normalizing proxy in front of your origin) can spoof it. Always layer a real authenticator on top; never run on `localDev()` alone. ### `vercelOidc()` Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted, which is why internal subagent and runtime callers authenticate with zero configuration. Tokens carrying an `external_sub` authenticate as user callers, but only when their `project_id` matches `VERCEL_PROJECT_ID` and their environment matches `VERCEL_TARGET_ENV` / `VERCEL_ENV`. In that case `external_sub` becomes the session subject, and the profile claims (`name`, `picture`, `email`) show up in `ctx.session.auth.current.attributes`. To admit tokens minted by other Vercel projects, pass `subjects: [...]` (AWS IAM-style `*` wildcards). Auth fails closed: routes reject unauthenticated traffic by default, and the OIDC user branch verifies `external_sub` against `VERCEL_PROJECT_ID` and the deployment environment, returning `false` when either is unset. An external-subject token cannot authenticate on a deployment that hasn't pinned its project. #### `subjects` patterns and `vercelSubject(...)` Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner::project::environment:`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time, and defaults `environment` to `"production"` when you omit it, so an unspecified environment cannot silently accept preview or development tokens: ```ts import { vercelOidc, vercelSubject } from "eve/channels/auth"; vercelOidc({ subjects: [ vercelSubject({ teamSlug: "partner", projectName: "data" }), // environment defaults to "production" vercelSubject({ teamSlug: "acme", projectName: "agent", environment: "*" }), ], }); ``` `teamSlug` and `projectName` are the human-readable slugs Vercel embeds in `sub` (not the stable `team_…` / `prj_…` IDs), so they can't contain `:` or `*`. `environment` is `"production" | "preview" | "development" | "*"`. Only hand-write the subject string yourself when you actually mean to match across teams with a wildcard. ### Custom verifiers When none of the shipped helpers fit, write your own `AuthFn` (the array example above) or call the low-level verifiers directly. Each verifier is the pure function sitting behind the matching strategy helper, and returns `{ ok: true, sessionAuth }` or `{ ok: false }`: | Verifier | Behind | Input | | -------------------------------------- | -------------- | -------------------------------- | | `verifyHttpBasic(header, credentials)` | `httpBasic()` | raw `Authorization` header value | | `verifyJwtHmac(token, config)` | `jwtHmac()` | bearer token (HMAC-signed JWT) | | `verifyJwtEcdsa(token, config)` | `jwtEcdsa()` | bearer token (ECDSA-signed JWT) | | `verifyOidc(token, config)` | `oidc()` | bearer token (OIDC, any issuer) | | `verifyVercelOidc(token, opts)` | `vercelOidc()` | bearer token (Vercel OIDC) | Pull the token with `extractBearerToken(request.headers.get("authorization"))` before you hand it to the JWT/OIDC verifiers. The configs (`VerifyJwtHmacConfig`, `VerifyJwtEcdsaConfig`, `VerifyOidcConfig`) take `issuer`, `audiences`, the signing material (`secret` / `publicKey` / `discoveryUrl`), and optional `subjects` / `claims` matchers. ```ts import { extractBearerToken, verifyJwtHmac, type AuthFn } from "eve/channels/auth"; function hmacAuth(): AuthFn { return async (request) => { const token = extractBearerToken(request.headers.get("authorization")); const result = await verifyJwtHmac(token, { algorithm: "HS256", issuer: "https://auth.example.com", audiences: ["agent"], secret: process.env.JWT_SECRET!, }); return result.ok ? result.sessionAuth : null; }; } ``` ### Failure responses in custom `defineChannel` routes If a `defineChannel` route handler runs its own checks instead of `routeAuth`, it can still emit a framework-shaped failure with `createUnauthorizedResponse(...)`. You get back a `Response` with `cache-control: no-store`, a `{ ok: false, code, error }` JSON body, and one `www-authenticate` header per challenge: ```ts title="agent/channels/intake.ts" import { defineChannel, POST } from "eve/channels"; import { createUnauthorizedResponse } from "eve/channels/auth"; export default defineChannel({ routes: [ POST("/message", async (req, { send }) => { if (!isAllowed(req)) { return createUnauthorizedResponse({ status: 403, // defaults to 401; code defaults to "forbidden" / "unauthorized" message: "Not allowed on this workspace.", challenges: [{ scheme: "Bearer" }], }); } // authenticated: handle the request }), ], }); ``` `UnauthenticatedError` and `ForbiddenError` wrap this builder (status `401` / `403`). Throw those from an `AuthFn` that `routeAuth` walks. Call `createUnauthorizedResponse` directly only when you're returning a `Response` from a hand-rolled route. ## Network policy `eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)` for cutting off requests before any model work starts. A request that fails the network policy is dropped ahead of both auth and runtime execution. ## Replace `placeholderAuth` before production `eve init` scaffolds `agent/channels/eve.ts` with a `placeholderAuth()` guardrail: ```ts import { eveChannel } from "eve/channels/eve"; import { localDev, placeholderAuth, vercelOidc } from "eve/channels/auth"; export default eveChannel({ auth: [localDev(), vercelOidc(), placeholderAuth()], }); ``` In production, `placeholderAuth()` returns a structured `401` so a generated web chat app can say "auth isn't configured yet" instead of throwing an internal error. Replace it before a browser caller submits a production request: swap in your app's `AuthFn` or one of the shipped helpers. Delete the authored channel file entirely and Eve falls back to the framework default `[localDev(), vercelOidc()]`, which also rejects production browser traffic. Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets never land in compiled artifacts. The runtime re-materializes them from the authored channel definition at boot. ## What reaches `ctx.session.auth` Inside runtime code, `ctx.session.auth` carries the result of the channel's route auth (the walk above) forward as the caller snapshot: * `auth.current`: the caller on the active inbound turn. * `auth.initiator`: the caller that started the durable session. * A follow-up message updates `auth.current` but leaves `auth.initiator` alone. When a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it. * Both are `null` only on internal runtime paths (subagents, for instance) that never went through an authored route. HTTP traffic always populates `auth.current`, since the walk either accepts with a `SessionAuthContext` or returns `401`. Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth. Access is decided at the HTTP boundary, and the durable session carries the caller snapshot forward into your runtime code. ## Tool and connection auth Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Both a connection and an individual tool can declare an `auth` strategy; Eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes. ### On a connection Attach `connect()` from `@vercel/connect/eve` to the connection: ```ts title="agent/connections/linear.ts" import { connect } from "@vercel/connect/eve"; import { defineMcpClientConnection } from "eve/connections"; import { once } from "eve/tools/approval"; export default defineMcpClientConnection({ url: "https://mcp.linear.app/mcp", description: "Linear: project management, issue tracking, and team workflows.", auth: connect("oauth/linear"), approval: once(), }); ``` The first call that needs the connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token in place of `connect()`. [Connections](../connections) covers both shapes. ### On a single tool When one tool calls a service behind OAuth, it can declare its own `auth` and skip the separate connection. `auth` takes the same shapes: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials. ```ts title="agent/tools/list_okta_groups.ts" import { defineTool } from "eve/tools"; import { connect } from "@vercel/connect/eve"; import { z } from "zod"; export default defineTool({ description: "List the caller's Okta groups.", inputSchema: z.object({}), auth: connect("okta"), async execute(_input, ctx) { const { token } = await ctx.getToken(); const res = await fetch("https://api.okta-proxy.internal/groups", { headers: { authorization: `Bearer ${token}` }, }); return res.json(); }, }); ``` Declaring `auth` adds two accessors to the tool's `ctx`: * `ctx.getToken()` resolves the bearer for the declared strategy, checking the per-step token cache first. With an interactive strategy, a cache miss suspends the turn on a framework-owned callback URL, shows a "Sign in" affordance, and re-runs the tool once the OAuth callback completes. * `ctx.requireAuth()` throws `ConnectionAuthorizationRequiredError` to gate the tool on authorization before any token resolves. The runtime turns that into the same consent prompt. Throw `ConnectionAuthorizationRequiredError` anywhere in `execute` (directly, via `requireAuth()`, or implicitly from `getToken()`) and you trigger the consent flow, keyed by the tool's name. Calling either accessor on a tool that does not declare `auth` throws. By default the sign-in affordance title-cases the tool's path-derived name, so a tool file named `sfdc_lookup.ts` renders "Sign in with Sfdc\_lookup". Set `displayName` on the `auth` definition to control what users see instead, for example `auth: { ...connect("sfdc"), displayName: "Salesforce" }`. It is presentation-only. The tool's name still keys the authorization scope, token cache, and callback URL, and a definition-level `displayName` wins over one the strategy stamps on the challenge. ## What to read next * [Security model](../concepts/security-model): trust boundaries and the pre-production checklist * [Connections](../connections): connection auth shapes (`connect()` vs static token) * [Deployment](./deployment): where route-auth secrets live in production --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)