The Open Framework for Building Agents
docs: clarify connection auth principals (#268)
Allen Zhou293d00311d55
diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdxindex 7552c06cc..a5d78ca3c 100644--- a/docs/connections/overview.mdx+++ b/docs/connections/overview.mdx@@ -1,5 +1,5 @@----title: "Connections"+title: "Overview"description: "Expose external MCP and OpenAPI servers to the model, with connection tokens the model never sees."url: /connections---@@ -28,6 +28,18 @@ When `getToken` is the only auth, `principalType` defaults to `"app"`: one shareeve resolves and caches connection tokens per step; they never land in conversation history or reach the model.+## Choose app vs. user auth++A connection credential can belong to the agent or to the person using it. This choice is separate from route auth, but user-scoped connection auth depends on route auth: eve can only resolve a user token when the active session has `ctx.session.auth.current?.principalType === "user"`.++| Credential owner | Use when | Auth shape |+| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| App | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect. |+| User | Each end-user should authorize and use their own third-party account. | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`. |+| User from a job | Background work should use the same user's OAuth grant that started the work. | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |++`principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.+## No authDrop `auth` entirely for servers that need no token, such as a localhost server during development or a public one:@@ -124,7 +136,33 @@ export default defineMcpClientConnection({});```-`"linear/myagent"` is the UID you chose when registering the Connect client. Connect-managed OAuth is user-scoped by default, so the runtime resolves the per-user token before each tool call. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).+`"linear/myagent"` is the UID you chose when registering the Connect client. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, emits `authorization.required` when that user has not authorized yet, and resumes the parked turn after the callback completes.++That means the channel that creates or continues the session must authenticate a real user. For a web app, configure `agent/channels/eve.ts` so your app session maps to `principalType: "user"`; for platform channels, use the built-in channel auth that maps the sender to a user principal. If no authenticated user is attached to the session, the first user-scoped connection call fails with `reason: "principal_required"`.++If the remote service should act as the agent itself instead of the end-user, make the Connect connection app-scoped:++```ts title="agent/connections/linear.ts"+import { connect } from "@vercel/connect/eve";+import { defineMcpClientConnection } from "eve/connections";++export default defineMcpClientConnection({+ url: "https://mcp.linear.app/sse",+ description: "Linear workspace: issues, projects, cycles, and comments.",+ auth: connect({ connector: "linear/myagent", principalType: "app" }),+});+```++App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).++### Troubleshooting Vercel Connect auth++| Symptom | What it means | Fix |+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |+| `reason: "principal_required"` | A user-scoped connection ran without an authenticated user on the active session. | Return `principalType: "user"` from the channel's route auth, or change the connection to `principalType: "app"` if it should be shared. |+| `authorization.required` appears but no UI | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge. | Render the challenge from the stream event and continue the same session after the callback. |+| OAuth works locally but fails after deploy | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |+| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal. | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work. |## Self-hosted interactive OAuthdiff --git a/docs/guides/auth-and-route-protection.md b/docs/guides/auth-and-route-protection.mdindex 16afa233b..f7d6ec9a8 100644--- a/docs/guides/auth-and-route-protection.md+++ b/docs/guides/auth-and-route-protection.md@@ -224,6 +224,53 @@ Route auth does not enforce session ownership. If multiple users or tenants canTool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools should resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.+The principal for user-scoped tool and connection auth comes from route auth. `connect("...")` from `@vercel/connect/eve` defaults to `principalType: "user"`, so the active session must have `ctx.session.auth.current.principalType === "user"` before the first token lookup can start OAuth. If the session is anonymous, local-dev-only, runtime-scoped, or service-scoped, eve fails fast with `reason: "principal_required"` because there is no end-user identity to bind the OAuth grant to.++Use app-scoped auth when the external service should act as the agent itself:++```ts+auth: connect({ connector: "linear/myagent", principalType: "app" });+```++Use user-scoped auth when the external service should act as the signed-in person:++```ts+auth: connect("linear/myagent");+```++For user-scoped auth in a browser app, the route-auth entry for the eve channel should verify your app session and return a user principal:++```ts title="agent/channels/eve.ts"+import { eveChannel } from "eve/channels/eve";+import { localDev, type AuthFn } from "eve/channels/auth";+import { getSession } from "@/lib/auth";++function appSession(): AuthFn<Request> {+ return async (request) => {+ const session = await getSession(request);+ if (!session) return null;++ return {+ authenticator: "app",+ principalId: session.userId,+ principalType: "user",+ attributes: {+ email: session.email,+ teamId: session.teamId,+ },+ };+ };+}++export default eveChannel({+ auth: [appSession(), localDev()],+});+```++Keep `principalId` stable for the same person, and include an `issuer` when the same app may accept users from multiple identity providers. The connection token cache keys user credentials by issuer and principal id so two providers cannot accidentally share a grant.++Built-in platform channels that identify a human sender, such as Slack, Discord, Teams, Telegram, Twilio, Linear, and GitHub, attach a user principal for that sender by default. A Slack mention, DM, or button click can therefore authorize a user-scoped connection for the Slack user who sent it without adding a separate browser-session auth function.+### On a connectionAttach `connect()` from `@vercel/connect/eve` to the connection:@@ -241,7 +288,7 @@ export default defineMcpClientConnection({});```-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.+The first call that needs a user-scoped 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 or `connect({ connector, principalType: "app" })` in place of user-scoped `connect()`. [Connections](../connections) covers both shapes.### On a single tooldiff --git a/docs/tutorial/connect-a-warehouse.mdx b/docs/tutorial/connect-a-warehouse.mdxindex 67a462154..debb38103 100644--- a/docs/tutorial/connect-a-warehouse.mdx+++ b/docs/tutorial/connect-a-warehouse.mdx@@ -26,6 +26,8 @@ export default defineMcpClientConnection({`"warehouse"` is the UID you chose when registering the Connect client. By default this OAuth is user-scoped. Each end-user authorizes in their own browser, and eve resolves that user's token before every tool call.+Before testing the warehouse from a web app, make sure the eve channel route auth maps your signed-in app user to `principalType: "user"`. A Connect-backed connection can only start per-user OAuth when the active session already has an authenticated user principal. If route auth still only accepts `localDev()`, a runtime token, or a placeholder guard, the first warehouse tool call fails with `reason: "principal_required"` instead of showing the sign-in challenge.+Once Connect is enabled on your account, wire it up:1. Install the package: `npm install @vercel/connect`.