Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): support inline tool auth providers (#47)

Allen Zhou86a35ebc9461
diff --git a/.changeset/inline-tool-auth-provider.md b/.changeset/inline-tool-auth-provider.md
new file mode 100644
index 000000000..0398e1627
--- /dev/null
+++ b/.changeset/inline-tool-auth-provider.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add inline tool auth provider overloads so tools can call `ctx.getToken(provider, options?)` and `ctx.requireAuth(provider, options?)` without declaring a single top-level `auth`. Vercel Connect providers can be authored inline with `connect("service/agent")` or `connect({ connector, tokenParams })`; the existing top-level tool `auth` field and no-argument tool auth accessors remain supported for compatibility, but are now deprecated in favor of inline providers.
diff --git a/docs/connections.mdx b/docs/connections.mdx
index 5e8180cc2..5fe608d4c 100644
--- a/docs/connections.mdx
+++ b/docs/connections.mdx
@@ -124,11 +124,11 @@ import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
url: "https://mcp.linear.app/sse",
description: "Linear workspace: issues, projects, cycles, and comments.",
- auth: connect("linear"),
+ auth: connect("linear/myagent"),
});
```
-`"linear"` 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](./guides/auth-and-route-protection).
+`"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](./guides/auth-and-route-protection).
## Self-hosted interactive OAuth
@@ -183,7 +183,7 @@ export default defineMcpClientConnection({
Drop `resume` when the provider keeps flow state server-side, so nothing has to cross the step boundary.
-`displayName` is presentation-only. The connection's path-derived name still keys the authorization scope, token cache, and callback URL. You can also set `displayName` on the `auth` definition itself (e.g. `auth: { ...connect("sfdc"), displayName: "Salesforce" }`); that definition-level value wins over one the strategy stamps on the challenge, and channels fall back to title-casing the connection name when neither is set.
+`displayName` is presentation-only. The connection's path-derived name still keys the authorization flow, token cache, and callback URL. You can also set `displayName` on the `auth` definition itself (e.g. `auth: { ...connect("salesforce/myagent"), displayName: "Salesforce" }`); that definition-level value wins over one the strategy stamps on the challenge, and channels fall back to title-casing the connection name when neither is set.
### Signaling authorization state
@@ -205,23 +205,26 @@ To narrow a caught error, use `isConnectionAuthorizationRequiredError(err)` and
### Handling a revoked token mid-call
-`getToken` only runs _before_ a tool call, so a grant revoked while a tool is mid-flight first surfaces as a downstream `401` inside your `execute`. A plain throw there is only a tool error, so the model sees a failure and the cached bearer sticks around. Instead, map a provider `401` to `ctx.requireAuth()` (or rethrow `ConnectionAuthorizationRequiredError`). eve then evicts the rejected token from its per-step cache and re-runs the consent flow with a fresh one, exactly as it does for a connection whose server rejects the bearer.
+`getToken` only runs _before_ a tool call, so a grant revoked while a tool is mid-flight first surfaces as a downstream `401` inside your `execute`. A plain throw there is only a tool error, so the model sees a failure and the cached bearer sticks around. Instead, map a provider `401` to `ctx.requireAuth(provider)`. eve then evicts the rejected token from its per-step cache and re-runs the consent flow with a fresh one, exactly as it does for a connection whose server rejects the bearer.
```ts title="agent/tools/list_issues.ts"
+import { connect } from "@vercel/connect/eve";
import { defineTool } from "eve/tools";
import { z } from "zod";
+const linearAuth = connect("linear/myagent");
+
export default defineTool({
description: "List open Linear issues.",
inputSchema: z.object({}),
async execute(_input, ctx) {
- const { token } = await ctx.getToken();
+ const { token } = await ctx.getToken(linearAuth);
const res = await fetch("https://api.linear.app/graphql", {
headers: { authorization: `Bearer ${token}` },
});
// The grant was revoked since getToken ran: re-challenge instead of
// returning a dead-token error to the model.
- if (res.status === 401) ctx.requireAuth();
+ if (res.status === 401) ctx.requireAuth(linearAuth);
return await res.json();
},
});
diff --git a/docs/guides/auth-and-route-protection.md b/docs/guides/auth-and-route-protection.md
index d3f3f65b6..1bec79476 100644
--- a/docs/guides/auth-and-route-protection.md
+++ b/docs/guides/auth-and-route-protection.md
@@ -222,7 +222,7 @@ Route auth does not enforce session ownership. If multiple users or tenants can
## 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.
+Tool 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.
### On a connection
@@ -236,7 +236,7 @@ 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"),
+ auth: connect("linear/myagent"),
approval: once(),
});
```
@@ -245,19 +245,20 @@ The first call that needs the connection kicks off an OAuth sign-in, surfaced as
### 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.
+When one tool calls a service behind OAuth, keep the auth provider at the call site and skip the separate connection. Providers take the same shapes as connection `auth`: `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";
+const oktaAuth = connect("okta/myagent");
+
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 { token } = await ctx.getToken(oktaAuth);
const res = await fetch("https://api.okta-proxy.internal/groups", {
headers: { authorization: `Bearer ${token}` },
});
@@ -266,14 +267,62 @@ export default defineTool({
});
```
-Declaring `auth` adds two accessors to the tool's `ctx`:
+This same inline shape naturally handles tools that need more than one credential:
+
+```ts title="agent/tools/sync_ticket.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const githubAuth = connect("github/myagent");
+const linearAuth = connect("linear/myagent");
+
+export default defineTool({
+ description: "Sync GitHub context into Linear.",
+ inputSchema: z.object({ issueId: z.string() }),
+ async execute({ issueId }, ctx) {
+ const { token: githubToken } = await ctx.getToken(githubAuth);
+ const { token: linearToken } = await ctx.getToken(linearAuth);
+
+ const repo = await fetch("https://api.github.com/user/repos", {
+ headers: { authorization: `Bearer ${githubToken}` },
+ });
+ if (repo.status === 401) ctx.requireAuth(githubAuth);
+
+ return updateLinearIssue(issueId, linearToken, await repo.json());
+ },
+});
+```
+
+Configure provider-specific OAuth targeting on the provider itself. For Vercel Connect, pass `tokenParams` to `connect(...)` when you need explicit OAuth scopes, resource indicators, or rich authorization requests:
+
+```ts
+const githubAuth = connect({
+ connector: "github/myagent",
+ tokenParams: {
+ authorizationDetails: [
+ {
+ type: "github_app_installation",
+ org: "acme",
+ repositories: ["agent-runtime"],
+ },
+ ],
+ },
+});
+```
+
+The tool's `ctx` exposes provider-scoped auth accessors:
+
+- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in machinery as connection auth, scoped to that provider instead of the tool's legacy top-level `auth`.
+- `ctx.requireAuth(provider, options?)` evicts the cached token for that inline provider and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token returned by `ctx.getToken(provider)`.
+
+Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to trigger the consent flow for that provider. If a downstream request later rejects an already-resolved token, call `ctx.requireAuth(provider)` to evict and re-authorize it.
-- `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.
+Vercel Connect providers usually supply their own display name in the authorization challenge. Set `displayName` in the inline options only when you need to override what users see, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`. It is presentation-only.
-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.
+Inline providers derive a stable tool-qualified auth key from Vercel Connect metadata when available. If you pass multiple custom providers that do not carry provider metadata, give each one an explicit auth key, for example `ctx.getToken(auth, { authKey: "github" })`. This `authKey` controls Eve's cache and callback keys; it is not an OAuth scope.
-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.
+Older tools may still declare a top-level `auth` field and call `ctx.getToken()` or `ctx.requireAuth()` without arguments. That compatibility path is deprecated; prefer inline providers for new tools.
## What to read next
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 6e9b6a66f..2e28bc6c1 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -56,13 +56,15 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
`ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
-| Member | Use |
-| -------------------------- | ----------------------------------------------------------------------------- |
-| `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) |
-| `ctx.getSandbox()` | Live sandbox handle for the current agent |
-| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent |
-| `ctx.getToken()` | Resolve the bearer token for a tool's declared `auth` (throws without `auth`) |
-| `ctx.requireAuth()` | Force the tool's authorization flow before proceeding |
+| Member | Use |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) |
+| `ctx.getSandbox()` | Live sandbox handle for the current agent |
+| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent |
+| `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` |
+| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
+| `ctx.getToken()` | Deprecated compatibility path for a tool's legacy top-level `auth` |
+| `ctx.requireAuth()` | Deprecated compatibility path for a tool's legacy top-level `auth` |
## Imports at a glance
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index bcb341766..0da52e598 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -21,7 +21,7 @@ import { findRegisteredRuntimeTool } from "#runtime/tools/registry.js";
import { SUBAGENT_TOOL_INPUT_SCHEMA } from "#runtime/subagents/registry.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
import { preserveFrameworkStateOnCompaction } from "#execution/compaction.js";
-import { buildUnauthorizedToolContext, createAuthorizedToolExecute } from "#execution/tool-auth.js";
+import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
const log = createLogger("execution.node-step");
@@ -229,11 +229,10 @@ function resolveHarnessToolDefinition(input: {
* - Framework tools (`eve:` source) run their `execute` verbatim — they
* manage their own context and never receive an authored
* {@link ToolContext}.
- * - Tools that declare `auth` are wrapped by
- * {@link createAuthorizedToolExecute}, which builds a token-aware
- * context and drives the interactive consent flow scoped to the tool
- * name.
- * - Plain authored tools receive a freshly built callback context.
+ * - Authored tools are wrapped by {@link createToolExecuteWithAuth},
+ * which builds a token-aware context. Top-level `auth` drives the
+ * interactive consent flow scoped to the tool name; inline providers
+ * passed to `ctx.getToken(provider)` use their own derived scopes.
* - Tools without `execute` (provider-managed) stay `undefined`.
*/
function resolveAuthoredExecute(input: {
@@ -250,10 +249,7 @@ function resolveAuthoredExecute(input: {
return rawExecute;
}
const authored = rawExecute as (toolInput: unknown, ctx: unknown) => unknown;
- if (auth !== undefined) {
- return createAuthorizedToolExecute({ auth, execute: authored, scope });
- }
- return (toolInput: unknown) => authored(toolInput, buildUnauthorizedToolContext(scope));
+ return createToolExecuteWithAuth({ execute: authored, scope, topLevelAuth: auth });
}
function maybeJsonSchema(
diff --git a/packages/eve/src/execution/tool-auth.integration.test.ts b/packages/eve/src/execution/tool-auth.integration.test.ts
index 35c9d65d2..40c3980ed 100644
--- a/packages/eve/src/execution/tool-auth.integration.test.ts
+++ b/packages/eve/src/execution/tool-auth.integration.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { createAuthorizedToolExecute } from "#execution/tool-auth.js";
+import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
import { evictScopedToken, resolveScopedToken } from "#runtime/connections/scoped-authorization.js";
import { loadContext } from "#context/container.js";
import { AuthKey, SessionIdKey } from "#context/keys.js";
@@ -21,7 +21,7 @@ import type { ResolvedToolDefinition } from "#runtime/types.js";
/**
* Integration coverage for tool-hosted authorization: the
- * {@link createAuthorizedToolExecute} wrapper drives token resolution,
+ * {@link createToolExecuteWithAuth} wrapper drives token resolution,
* the per-step cache, the park-on-`Required` flow, callback completion
* on resume, and the loop guard — all scoped by the tool's name.
*/
@@ -56,15 +56,22 @@ function authTool(input: {
readonly name: string;
readonly auth: AuthorizationDefinition;
readonly execute: (toolInput: unknown, ctx: ToolContext) => unknown;
+}): ResolvedToolDefinition {
+ return authoredTool(input);
+}
+
+function authoredTool(input: {
+ readonly name: string;
+ readonly auth?: AuthorizationDefinition;
+ readonly execute: (toolInput: unknown, ctx: ToolContext) => unknown;
}): ResolvedToolDefinition {
const logicalPath = `tools/${input.name}.ts`;
- return {
- auth: input.auth,
+ const base: ResolvedToolDefinition = {
description: `${input.name} auth tool.`,
- execute: createAuthorizedToolExecute({
- auth: input.auth,
+ execute: createToolExecuteWithAuth({
execute: input.execute as (toolInput: unknown, ctx: unknown) => unknown,
scope: input.name,
+ topLevelAuth: input.auth,
}),
inputSchema: null,
logicalPath,
@@ -72,6 +79,7 @@ function authTool(input: {
sourceId: logicalPath,
sourceKind: "module",
};
+ return input.auth === undefined ? base : { ...base, auth: input.auth };
}
describe("tool-hosted authorization", () => {
@@ -102,6 +110,140 @@ describe("tool-hosted authorization", () => {
expect(calls).toBe(1);
});
+ it("resolves and caches an inline provider on a plain tool", async () => {
+ let calls = 0;
+ const inlineAuth: AuthorizationDefinition = {
+ principalType: "app",
+ async getToken(): Promise<TokenResult> {
+ calls += 1;
+ return { token: `inline-${calls}` };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ const first = await ctx.getToken(inlineAuth);
+ const second = await ctx.getToken(inlineAuth);
+ return { first: first.token, second: second.token };
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const result = await runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {}));
+
+ expect(result).toEqual({ first: "inline-1", second: "inline-1" });
+ expect(calls).toBe(1);
+ });
+
+ it("keeps explicit auth keys separate for anonymous inline providers", async () => {
+ const githubAuth: AuthorizationDefinition = {
+ principalType: "app",
+ async getToken(): Promise<TokenResult> {
+ return { token: "github-token" };
+ },
+ };
+ const linearAuth: AuthorizationDefinition = {
+ principalType: "app",
+ async getToken(): Promise<TokenResult> {
+ return { token: "linear-token" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ const github = await ctx.getToken(githubAuth, { authKey: "github" });
+ const linear = await ctx.getToken(linearAuth, { authKey: "linear" });
+ return { github: github.token, linear: linear.token };
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const result = await runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {}));
+
+ expect(result).toEqual({ github: "github-token", linear: "linear-token" });
+ });
+
+ it("rejects multiple anonymous inline providers without explicit auth keys", async () => {
+ const githubAuth: AuthorizationDefinition = {
+ principalType: "app",
+ async getToken(): Promise<TokenResult> {
+ return { token: "github-token" };
+ },
+ };
+ const linearAuth: AuthorizationDefinition = {
+ principalType: "app",
+ async getToken(): Promise<TokenResult> {
+ return { token: "linear-token" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ await ctx.getToken(githubAuth);
+ await ctx.getToken(linearAuth);
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ await expect(
+ runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {})),
+ ).rejects.toThrow(/explicit auth keys/);
+ });
+
+ it("keeps no-arg ctx.getToken() guarded on tools without top-level auth", async () => {
+ const tool = authoredTool({
+ name: "plain_tool",
+ async execute(_input, ctx) {
+ return await ctx.getToken();
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ await expect(
+ runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {})),
+ ).rejects.toThrow(/does not declare an "auth" strategy/);
+ });
+
+ it("parks the turn with a challenge for an inline provider", async () => {
+ const inlineAuth: AuthorizationDefinition = {
+ principalType: "user",
+ vercelConnect: { connector: "oauth/linear" },
+ async getToken(): Promise<TokenResult> {
+ throw requiredError();
+ },
+ async startAuthorization() {
+ return { challenge: { url: "https://idp.example/auth" }, resume: { nonce: "n1" } };
+ },
+ async completeAuthorization(): Promise<TokenResult> {
+ return { token: "after-signin" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ return await ctx.getToken(inlineAuth, { displayName: "Linear" });
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const result = await runtime.runAsSession(
+ { sessionId: "session_inline_auth_park" },
+ async () => {
+ seedUserPrincipal();
+ loadContext().set(CallbackBaseUrlKey, "https://app.example");
+ return runtime.executeTool(tool, {});
+ },
+ );
+
+ expect(isAuthorizationSignal(result)).toBe(true);
+ if (!isAuthorizationSignal(result)) throw new Error("expected signal");
+ expect(result.challenges).toHaveLength(1);
+ expect(result.challenges[0]).toMatchObject({
+ name: "sync_ticket__oauth_linear",
+ challenge: { displayName: "Linear", url: "https://idp.example/auth" },
+ });
+ });
+
it("parks the turn with a challenge when getToken throws Required", async () => {
const auth: AuthorizationDefinition = {
principalType: "user",
@@ -293,6 +435,93 @@ describe("tool-hosted authorization", () => {
expect(result).toEqual({ token: "minted" });
});
+ it("completes an inline provider callback on resume and serves the minted token", async () => {
+ let completeCalls = 0;
+ const inlineAuth: AuthorizationDefinition = {
+ principalType: "user",
+ vercelConnect: { connector: "oauth/linear" },
+ async getToken(): Promise<TokenResult> {
+ throw requiredError();
+ },
+ async startAuthorization() {
+ return { challenge: { url: "https://idp.example/auth" }, resume: {} };
+ },
+ async completeAuthorization(): Promise<TokenResult> {
+ completeCalls += 1;
+ return { token: "inline-minted" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ return await ctx.getToken(inlineAuth);
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const result = await runtime.runAsSession({ sessionId: "session_inline_resume" }, async () => {
+ seedUserPrincipal();
+ loadContext().set(CallbackBaseUrlKey, "https://app.example");
+ loadContext().set(PendingAuthorizationResultKey, [
+ {
+ name: "sync_ticket__oauth_linear",
+ hookUrl: "https://app.example/callback",
+ callback: {
+ params: { code: "abc" },
+ method: "GET",
+ },
+ },
+ ]);
+ return runtime.executeTool(tool, {});
+ });
+
+ expect(completeCalls).toBe(1);
+ expect(result).toEqual({ token: "inline-minted" });
+ });
+
+ it("maps inline ctx.requireAuth(auth) to eviction and a fresh challenge", async () => {
+ const evicted: ConnectionPrincipal[] = [];
+ const inlineAuth: AuthorizationDefinition = {
+ principalType: "user",
+ vercelConnect: { connector: "oauth/github" },
+ async getToken(): Promise<TokenResult> {
+ return { token: "stale" };
+ },
+ evict({ principal }) {
+ evicted.push(principal);
+ },
+ async startAuthorization() {
+ return { challenge: { url: "https://idp.example/auth" }, resume: {} };
+ },
+ async completeAuthorization(): Promise<TokenResult> {
+ return { token: "fresh" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ await ctx.getToken(inlineAuth);
+ ctx.requireAuth(inlineAuth);
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const result = await runtime.runAsSession({ sessionId: "session_inline_require" }, async () => {
+ seedUserPrincipal();
+ loadContext().set(CallbackBaseUrlKey, "https://app.example");
+ return runtime.executeTool(tool, {});
+ });
+
+ expect(evicted).toHaveLength(1);
+ expect(evicted[0]).toMatchObject({ type: "user" });
+ expect(isAuthorizationSignal(result)).toBe(true);
+ if (!isAuthorizationSignal(result)) throw new Error("expected signal");
+ expect(result.challenges[0]).toMatchObject({
+ name: "sync_ticket__oauth_github",
+ challenge: { url: "https://idp.example/auth" },
+ });
+ });
+
it("fails terminally when the token is rejected immediately after sign-in", async () => {
const auth: AuthorizationDefinition = {
principalType: "user",
@@ -342,6 +571,53 @@ describe("tool-hosted authorization", () => {
expect(isConnectionAuthorizationFailedError(error)).toBe(true);
});
+ it("fails terminally when an inline provider token is rejected immediately after sign-in", async () => {
+ const inlineAuth: AuthorizationDefinition = {
+ principalType: "user",
+ vercelConnect: { connector: "oauth/github" },
+ async getToken(): Promise<TokenResult> {
+ return { token: "rejected" };
+ },
+ async startAuthorization() {
+ return { challenge: { url: "https://idp.example/auth" }, resume: {} };
+ },
+ async completeAuthorization(): Promise<TokenResult> {
+ return { token: "rejected" };
+ },
+ };
+ const tool = authoredTool({
+ name: "sync_ticket",
+ async execute(_input, ctx) {
+ await ctx.getToken(inlineAuth);
+ ctx.requireAuth(inlineAuth);
+ },
+ });
+ const runtime = createTestRuntime({ tools: [tool] });
+
+ const error = await runtime
+ .runAsSession({ sessionId: "session_inline_loop_guard" }, async () => {
+ seedUserPrincipal();
+ loadContext().set(CallbackBaseUrlKey, "https://app.example");
+ loadContext().set(PendingAuthorizationResultKey, [
+ {
+ name: "sync_ticket__oauth_github",
+ hookUrl: "https://app.example/callback",
+ callback: {
+ params: { code: "abc" },
+ method: "GET",
+ },
+ },
+ ]);
+ return runtime.executeTool(tool, {});
+ })
+ .then(
+ () => null,
+ (err: unknown) => err,
+ );
+
+ expect(isConnectionAuthorizationFailedError(error)).toBe(true);
+ });
+
it("evictScopedToken drops the cached bearer so the next resolve re-fetches", async () => {
let calls = 0;
const auth: AuthorizationDefinition = {
diff --git a/packages/eve/src/execution/tool-auth.ts b/packages/eve/src/execution/tool-auth.ts
index 32fc2e6bc..f3fbfcdb1 100644
--- a/packages/eve/src/execution/tool-auth.ts
+++ b/packages/eve/src/execution/tool-auth.ts
@@ -18,12 +18,14 @@ import {
ConnectionAuthorizationRequiredError,
isConnectionAuthorizationRequiredError,
} from "#public/connections/errors.js";
-import type { ToolContext } from "#public/definitions/tool.js";
+import type { ToolAuthOptions, ToolAuthProvider, ToolContext } from "#public/definitions/tool.js";
+import { type AuthorizationChallenge, requestAuthorization } from "#harness/authorization.js";
import {
type AuthorizationDefinition,
supportsInteractiveAuthorization,
type TokenResult,
} from "#runtime/connections/types.js";
+import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
import {
completeScopedAuthorization,
evictScopedToken,
@@ -57,59 +59,62 @@ export function createAuthorizedToolExecute(input: {
readonly auth: AuthorizationDefinition;
readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
}): (toolInput: unknown) => Promise<unknown> {
- const { scope, auth, execute } = input;
- const scoped: ScopedAuthorization = {
- authorization: auth,
- connection: { url: "" },
- scope,
- };
+ return createToolExecuteWithAuth({
+ execute: input.execute,
+ scope: input.scope,
+ topLevelAuth: input.auth,
+ });
+}
+
+/**
+ * Wraps one authored tool's `execute` with a context that supports both
+ * top-level tool auth (`ctx.getToken()`) and inline provider auth
+ * (`ctx.getToken(connect("..."))`).
+ */
+export function createToolExecuteWithAuth(input: {
+ readonly scope: string;
+ readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
+ readonly topLevelAuth?: AuthorizationDefinition;
+}): (toolInput: unknown) => Promise<unknown> {
+ const { scope, execute, topLevelAuth } = input;
+ const topLevelScoped: ScopedAuthorization | undefined =
+ topLevelAuth === undefined
+ ? undefined
+ : {
+ authorization: topLevelAuth,
+ connection: { url: "" },
+ scope,
+ };
return async (toolInput: unknown): Promise<unknown> => {
- const justAuthorized = await completeScopedAuthorization(scoped);
+ const justAuthorizedScopes = new Set<string>();
+ if (topLevelScoped !== undefined && (await completeScopedAuthorization(topLevelScoped))) {
+ justAuthorizedScopes.add(topLevelScoped.scope);
+ }
try {
- return await execute(toolInput, buildToolContext(scoped));
+ return await execute(
+ toolInput,
+ buildToolContext({
+ inlineAuthState: {},
+ justAuthorizedScopes,
+ scope,
+ topLevelScoped,
+ }),
+ );
} catch (err) {
- if (!isConnectionAuthorizationRequiredError(err)) throw err;
-
- // Loop guard: a token minted this turn that is still rejected
- // means the grant itself is broken — fail terminally instead of
- // re-prompting into an infinite sign-in loop.
- if (justAuthorized) {
- throw new ConnectionAuthorizationFailedError(scope, {
- message: `Tool "${scope}" rejected the token immediately after authorization.`,
- reason: "token_rejected_after_authorization",
- retryable: false,
- });
+ if (isToolAuthorizationRequiredError(err)) {
+ return await handleAuthorizationRequests(err.requests);
}
- // The resolved bearer was rejected (a downstream 401 mapped to
- // requireAuth, or getToken re-reporting Required). Drop it from
- // every cache layer — eve's per-step cache and the strategy's own
- // (e.g. the @vercel/connect token cache) — so the
- // re-authorization re-resolves a genuinely fresh token instead of
- // re-reading the rejected one. Mirrors the MCP client.
- await evictScopedToken(scoped);
-
- const signal = await startScopedAuthorization(scoped);
- if (signal !== undefined) return signal;
-
- // No park signal. For an interactive strategy this means the
- // framework could not mint a callback URL (no session id / base
- // URL in context). Never let the raw `Required` reach the model —
- // it improvises by surfacing the auth URL as text and loops
- // (see research/per-tool-auth-known-issues.md, issue 2). Fail with
- // a classified, terminal authorization error instead. Non-interactive
- // strategies have no consent flow, so their original error is the
- // right thing for the model to see.
- if (supportsInteractiveAuthorization(auth)) {
- throw new ConnectionAuthorizationFailedError(scope, {
- message:
- `Tool "${scope}" requires sign-in, but no authorization callback URL ` +
- `could be minted for this run (missing session context).`,
- reason: "authorization_callback_unavailable",
- retryable: false,
- });
+ if (topLevelScoped !== undefined && isConnectionAuthorizationRequiredError(err)) {
+ return await handleAuthorizationRequests([
+ {
+ cause: err,
+ justAuthorized: justAuthorizedScopes.has(topLevelScoped.scope),
+ scoped: topLevelScoped,
+ },
+ ]);
}
throw err;
@@ -118,44 +123,257 @@ export function createAuthorizedToolExecute(input: {
}
/**
- * Builds the {@link ToolContext} for an authored tool that does **not**
- * declare `auth`. The token accessors are present (the type promises
- * them) but throw, since there is no strategy to resolve a token from.
+ * Builds the {@link ToolContext} for an authored tool without top-level
+ * `auth`. No-arg token accessors throw, but provider-scoped accessors
+ * still work.
*/
export function buildUnauthorizedToolContext(scope: string): ToolContext {
+ return buildToolContext({
+ inlineAuthState: {},
+ justAuthorizedScopes: new Set<string>(),
+ scope,
+ });
+}
+
+function buildToolContext(input: {
+ readonly scope: string;
+ readonly topLevelScoped?: ScopedAuthorization;
+ readonly justAuthorizedScopes: Set<string>;
+ readonly inlineAuthState: InlineAuthState;
+}): ToolContext {
+ const { scope, topLevelScoped, justAuthorizedScopes, inlineAuthState } = input;
const base = buildCallbackContext();
return {
...base,
- getToken(): Promise<TokenResult> {
- throw noAuthError(scope);
+ async getToken(provider?: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult> {
+ if (provider === undefined) {
+ if (topLevelScoped === undefined) throw noAuthError(scope);
+ return resolveScopedToken(topLevelScoped);
+ }
+
+ return await resolveInlineToken({
+ inlineAuthState,
+ justAuthorizedScopes,
+ options,
+ provider,
+ toolScope: scope,
+ });
},
- requireAuth(): never {
- throw noAuthError(scope);
+ requireAuth(provider?: ToolAuthProvider, options?: ToolAuthOptions): never {
+ if (provider === undefined) {
+ if (topLevelScoped === undefined) throw noAuthError(scope);
+ throw new ConnectionAuthorizationRequiredError(topLevelScoped.scope);
+ }
+
+ const scoped = buildInlineScopedAuthorization({
+ inlineAuthState,
+ options,
+ provider,
+ toolScope: scope,
+ });
+ throw new ToolAuthorizationRequiredError([
+ {
+ justAuthorized: justAuthorizedScopes.has(scoped.scope),
+ scoped,
+ },
+ ]);
},
};
}
-/**
- * Builds the {@link ToolContext} handed to an authorized tool's
- * `execute`: the base session context plus token accessors bound to the
- * tool's scope.
- */
-function buildToolContext(scoped: ScopedAuthorization): ToolContext {
- const base = buildCallbackContext();
+async function resolveInlineToken(input: {
+ readonly toolScope: string;
+ readonly provider: ToolAuthProvider;
+ readonly options?: ToolAuthOptions;
+ readonly justAuthorizedScopes: Set<string>;
+ readonly inlineAuthState: InlineAuthState;
+}): Promise<TokenResult> {
+ const { justAuthorizedScopes } = input;
+ const scoped = buildInlineScopedAuthorization(input);
+ if (!justAuthorizedScopes.has(scoped.scope) && (await completeScopedAuthorization(scoped))) {
+ justAuthorizedScopes.add(scoped.scope);
+ }
+
+ try {
+ return await resolveScopedToken(scoped);
+ } catch (err) {
+ if (!isConnectionAuthorizationRequiredError(err)) throw err;
+ throw new ToolAuthorizationRequiredError([
+ {
+ cause: err,
+ justAuthorized: justAuthorizedScopes.has(scoped.scope),
+ scoped,
+ },
+ ]);
+ }
+}
+
+async function handleAuthorizationRequests(
+ requests: readonly ToolAuthorizationRequiredRequest[],
+): Promise<unknown> {
+ const challenges: AuthorizationChallenge[] = [];
+ let nonInteractiveError: Error | undefined;
+
+ for (const request of requests) {
+ const { scoped } = request;
+
+ // Loop guard: a token minted this turn that is still rejected
+ // means the grant itself is broken — fail terminally instead of
+ // re-prompting into an infinite sign-in loop.
+ if (request.justAuthorized) {
+ throw new ConnectionAuthorizationFailedError(scoped.scope, {
+ message: `Tool "${scoped.scope}" rejected the token immediately after authorization.`,
+ reason: "token_rejected_after_authorization",
+ retryable: false,
+ });
+ }
+
+ // The resolved bearer was rejected (a downstream 401 mapped to
+ // requireAuth, or getToken re-reporting Required). Drop it from
+ // every cache layer — eve's per-step cache and the strategy's own
+ // (e.g. the @vercel/connect token cache) — so the
+ // re-authorization re-resolves a genuinely fresh token instead of
+ // re-reading the rejected one. Mirrors the MCP client.
+ await evictScopedToken(scoped);
+
+ const signal = await startScopedAuthorization(scoped);
+ if (signal !== undefined) {
+ challenges.push(...signal.challenges);
+ continue;
+ }
+
+ // No park signal. For an interactive strategy this means the
+ // framework could not mint a callback URL (no session id / base
+ // URL in context). Never let the raw `Required` reach the model —
+ // it improvises by surfacing the auth URL as text and loops
+ // (see research/per-tool-auth-known-issues.md, issue 2). Fail with
+ // a classified, terminal authorization error instead. Non-interactive
+ // strategies have no consent flow, so their original error is the
+ // right thing for the model to see.
+ if (supportsInteractiveAuthorization(scoped.authorization)) {
+ throw new ConnectionAuthorizationFailedError(scoped.scope, {
+ message:
+ `Tool "${scoped.scope}" requires sign-in, but no authorization callback URL ` +
+ `could be minted for this run (missing session context).`,
+ reason: "authorization_callback_unavailable",
+ retryable: false,
+ });
+ }
+
+ nonInteractiveError ??=
+ request.cause instanceof Error
+ ? request.cause
+ : new ConnectionAuthorizationRequiredError(scoped.scope);
+ }
+
+ if (challenges.length > 0) {
+ return requestAuthorization(challenges);
+ }
+
+ throw nonInteractiveError ?? new Error("Tool authorization is required.");
+}
+
+function buildInlineScopedAuthorization(input: {
+ readonly toolScope: string;
+ readonly provider: ToolAuthProvider;
+ readonly options?: ToolAuthOptions;
+ readonly inlineAuthState: InlineAuthState;
+}): ScopedAuthorization {
+ const authorization = normalizeInlineProvider(input.provider, input.options);
return {
- ...base,
- getToken(): Promise<TokenResult> {
- return resolveScopedToken(scoped);
- },
- requireAuth(): never {
- throw new ConnectionAuthorizationRequiredError(scoped.scope);
- },
+ authorization,
+ connection: input.options?.connection ?? { url: "" },
+ scope:
+ input.options?.authKey === undefined
+ ? deriveInlineScope({
+ authorization,
+ inlineAuthState: input.inlineAuthState,
+ provider: input.provider,
+ toolScope: input.toolScope,
+ })
+ : validateInlineAuthKey(input.options.authKey),
};
}
+function normalizeInlineProvider(
+ provider: ToolAuthProvider,
+ options: ToolAuthOptions | undefined,
+): AuthorizationDefinition {
+ const authorization = normalizeAuthorizationSpec(provider, "ctx.getToken:", "provider");
+ if (options?.displayName === undefined) {
+ return authorization;
+ }
+ if (options.displayName.length === 0) {
+ throw new Error(`ctx.getToken: The "options.displayName" field must be a non-empty string.`);
+ }
+ return { ...authorization, displayName: options.displayName };
+}
+
+function deriveInlineScope(input: {
+ readonly toolScope: string;
+ readonly authorization: AuthorizationDefinition;
+ readonly provider: ToolAuthProvider;
+ readonly inlineAuthState: InlineAuthState;
+}): string {
+ const connector = input.authorization.vercelConnect?.connector;
+ if (connector !== undefined) {
+ return `${input.toolScope}__${sanitizeScopeSegment(connector)}`;
+ }
+
+ if (input.inlineAuthState.anonymousProvider === undefined) {
+ input.inlineAuthState.anonymousProvider = input.provider;
+ } else if (input.inlineAuthState.anonymousProvider !== input.provider) {
+ throw new Error(
+ `ctx.getToken: Multiple inline auth providers without provider metadata need explicit auth keys. ` +
+ `Pass options.authKey for each provider, for example ` +
+ `ctx.getToken(auth, { authKey: "github" }).`,
+ );
+ }
+
+ return `${input.toolScope}__inline_auth`;
+}
+
+function validateInlineAuthKey(authKey: string): string {
+ if (!/^[A-Za-z0-9_.:-]+$/u.test(authKey)) {
+ throw new Error(
+ `ctx.getToken: The "options.authKey" field must contain only letters, digits, "_", "-", ".", or ":".`,
+ );
+ }
+ return authKey;
+}
+
+function sanitizeScopeSegment(value: string): string {
+ const sanitized = value.replace(/[^A-Za-z0-9_.:-]+/gu, "_").replace(/^_+|_+$/gu, "");
+ return sanitized.length > 0 ? sanitized : "provider";
+}
+
+interface ToolAuthorizationRequiredRequest {
+ readonly scoped: ScopedAuthorization;
+ readonly justAuthorized: boolean;
+ readonly cause?: unknown;
+}
+
+interface InlineAuthState {
+ anonymousProvider?: ToolAuthProvider;
+}
+
+class ToolAuthorizationRequiredError extends Error {
+ readonly requests: readonly ToolAuthorizationRequiredRequest[];
+
+ constructor(requests: readonly ToolAuthorizationRequiredRequest[]) {
+ super("Tool authorization required.");
+ this.name = "ToolAuthorizationRequiredError";
+ this.requests = requests;
+ }
+}
+
+function isToolAuthorizationRequiredError(err: unknown): err is ToolAuthorizationRequiredError {
+ return err instanceof Error && err.name === "ToolAuthorizationRequiredError";
+}
+
function noAuthError(scope: string): Error {
return new Error(
- `Tool "${scope}" called ctx.getToken()/ctx.requireAuth() but does not declare an "auth" strategy. ` +
- `Add \`auth\` to the tool definition (e.g. \`connect("...")\` from "@vercel/connect/eve").`,
+ `Tool "${scope}" called ctx.getToken()/ctx.requireAuth() without a provider but does not declare an "auth" strategy. ` +
+ `Add \`auth\` to the tool definition or pass a provider like \`ctx.getToken(connect("..."))\`.`,
);
}
diff --git a/packages/eve/src/public/definitions/tool-auth.test.ts b/packages/eve/src/public/definitions/tool-auth.test.ts
index 6025d1cf4..f2d2fa7fe 100644
--- a/packages/eve/src/public/definitions/tool-auth.test.ts
+++ b/packages/eve/src/public/definitions/tool-auth.test.ts
@@ -72,6 +72,30 @@ describe("defineTool auth normalization", () => {
expect(tool.auth).toMatchObject({ vercelConnect: { connector: "okta" } });
});
+ it("retains the provider cache eviction hook", () => {
+ const evict = async () => {};
+ const tool = defineTool({
+ description: "Connect-backed tool.",
+ inputSchema: { type: "object" },
+ auth: {
+ evict,
+ principalType: "user",
+ async getToken(): Promise<TokenResult> {
+ return { token: "live" };
+ },
+ async startAuthorization() {
+ return { challenge: { url: "https://idp.example/auth" }, resume: {} };
+ },
+ async completeAuthorization(): Promise<TokenResult> {
+ return { token: "live" };
+ },
+ },
+ execute: () => null,
+ });
+
+ expect(tool.auth?.evict).toBe(evict);
+ });
+
it("retains the authored displayName", () => {
const tool = defineTool({
description: "Branded tool.",
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 3f716513e..007e6f89c 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -6,6 +6,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { JsonObject } from "#shared/json.js";
import type {
AuthorizationDefinition,
+ ConnectionAuthorizationContext,
NonInteractiveAuthorizationDefinition,
TokenResult,
} from "#runtime/connections/types.js";
@@ -41,7 +42,7 @@ export type { ToolModelOutput } from "#shared/tool-definition.js";
* `auth` field. Accepts the same shapes as a connection's `auth`:
* - a `getToken`-only object (static API keys, pre-provisioned JWTs);
* `principalType` may be omitted and defaults to `"app"`.
- * - a full interactive OAuth definition (e.g. `connect("okta")` from
+ * - a full interactive OAuth definition (e.g. `connect("okta/myagent")` from
* `@vercel/connect/eve`, or {@link defineInteractiveAuthorization}).
*/
export type ToolAuthDefinition =
@@ -50,13 +51,41 @@ export type ToolAuthDefinition =
})
| AuthorizationDefinition;
+export type ToolAuthProvider = ToolAuthDefinition;
+
+/**
+ * Controls Eve runtime behavior for an inline tool auth provider.
+ */
+export interface ToolAuthOptions {
+ /**
+ * Connection metadata passed through to provider callbacks. Tool-only
+ * providers usually leave this unset; connection-backed helpers can use it
+ * to receive the upstream server URL.
+ */
+ readonly connection?: ConnectionAuthorizationContext;
+ /**
+ * Optional human-readable provider name shown in sign-in UI. Presentation
+ * only; it does not affect OAuth scopes, token cache keys, or callback URLs.
+ */
+ readonly displayName?: string;
+ /**
+ * Optional Eve auth-flow key for token caches, callback URLs, pending
+ * authorization state, and authorization completion. This is not an OAuth
+ * scope. For Vercel Connect OAuth targeting such as `scopes`, `resources`,
+ * or `authorizationDetails`, configure the provider with
+ * `connect({ connector, tokenParams })`.
+ */
+ readonly authKey?: string;
+}
+
/**
* Authored tool context. Passed as the last argument to
* {@link ToolDefinition.execute}.
*
- * Extends {@link SessionContext} with token accessors. {@link getToken} and
- * {@link requireAuth} only do useful work when the tool declares `auth`;
- * calling them on a tool without `auth` throws.
+ * Extends {@link SessionContext} with token accessors. Passing a provider
+ * resolves that provider inline, which lets one tool use multiple credentials.
+ * For backwards compatibility, calling the accessors without a provider uses
+ * the tool's deprecated top-level `auth` field and throws when no `auth` exists.
*/
export type ToolContext = SessionContext & {
/**
@@ -69,16 +98,34 @@ export type ToolContext = SessionContext & {
* callback completes.
*
* Throws when the tool does not declare an `auth` strategy.
+ *
+ * @deprecated Prefer `ctx.getToken(provider)` so auth dependencies live at
+ * the call site and compose when a tool needs multiple credentials.
*/
getToken(): Promise<TokenResult>;
/**
- * Signals that the caller must complete this tool's authorization flow
- * before proceeding. Throws `ConnectionAuthorizationRequiredError`, which
- * the runtime converts into a consent prompt (for interactive strategies)
- * and re-runs the tool after sign-in. Use it to gate a tool on
- * authorization without resolving a token first.
+ * Resolves the bearer token for an inline provider. This accepts the same
+ * auth shapes as a connection's `auth` field, including `connect("...")`
+ * from `@vercel/connect/eve`.
+ */
+ getToken(provider: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult>;
+ /**
+ * Signals that the caller must complete this tool's authorization flow.
+ * Throws `ConnectionAuthorizationRequiredError`, which the runtime converts
+ * into a consent prompt (for interactive strategies) and re-runs the tool
+ * after sign-in. Use it after a downstream request rejects a token returned
+ * by the deprecated no-argument {@link getToken}.
+ *
+ * @deprecated Prefer `ctx.requireAuth(provider)` so auth dependencies live at
+ * the call site and compose when a tool needs multiple credentials.
*/
requireAuth(): never;
+ /**
+ * Signals that the caller must complete authorization for an inline
+ * provider before proceeding. Use this after a downstream `401` rejects a
+ * token returned by {@link getToken}.
+ */
+ requireAuth(provider: ToolAuthProvider, options?: ToolAuthOptions): never;
};
/**
@@ -94,17 +141,13 @@ export type ToolDefinition<TInput = unknown, TOutput = unknown> = PublicToolDefi
> & {
execute(input: TInput, ctx: ToolContext): Promise<TOutput> | TOutput;
/**
- * Optional authorization strategy. When set, the execute context gains a
- * working {@link ToolContext.getToken} / {@link ToolContext.requireAuth},
- * and a thrown `ConnectionAuthorizationRequiredError` (implicit from
- * `getToken()` or explicit via `requireAuth()`) drives the framework's
- * interactive consent flow, the same machinery MCP connections use, scoped
- * to this tool's name.
+ * Optional authorization strategy used by the deprecated no-argument
+ * {@link ToolContext.getToken} / {@link ToolContext.requireAuth} accessors.
*
- * Use `connect("...")` from `@vercel/connect/eve` for Vercel
- * Connect-backed OAuth, {@link defineInteractiveAuthorization} for a
- * custom interactive flow, or a plain `{ getToken }` object for
- * static/pre-provisioned credentials.
+ * @deprecated Prefer passing a provider at the call site:
+ * `ctx.getToken(connect("..."))` or `ctx.requireAuth(connect("..."))`.
+ * Inline providers use the same auth shapes and compose when a tool needs
+ * multiple credentials.
*/
auth?: ToolAuthDefinition;
/**
@@ -158,6 +201,7 @@ export function defineTool<
unknown,
StandardJSONSchemaV1.InferOutput<TOutputSchema>
>["toModelOutput"];
+ /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
auth?: ToolAuthDefinition;
}): ToolDefinition<
StandardJSONSchemaV1.InferOutput<TInputSchema>,
@@ -179,6 +223,7 @@ export function defineTool<
unknown
>["needsApproval"];
toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
+ /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
auth?: ToolAuthDefinition;
}): ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>;
export function defineTool<
@@ -198,6 +243,7 @@ export function defineTool<
unknown,
StandardJSONSchemaV1.InferOutput<TOutputSchema>
>["toModelOutput"];
+ /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
auth?: ToolAuthDefinition;
}): ToolDefinition<Record<string, unknown>, StandardJSONSchemaV1.InferOutput<TOutputSchema>>;
export function defineTool<TOutput>(definition: {
@@ -207,6 +253,7 @@ export function defineTool<TOutput>(definition: {
execute(input: Record<string, unknown>, ctx: ToolContext): Promise<TOutput> | TOutput;
needsApproval?: ToolDefinition<Record<string, unknown>, unknown>["needsApproval"];
toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
+ /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
auth?: ToolAuthDefinition;
}): ToolDefinition<Record<string, unknown>, TOutput>;
export function defineTool<TInput = unknown, TOutput = unknown>(
diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.ts
index f1d0e2c04..7c9a964b1 100644
--- a/packages/eve/src/public/tools/index.ts
+++ b/packages/eve/src/public/tools/index.ts
@@ -11,6 +11,8 @@ export {
isDisabledToolSentinel,
isEnableWorkflowToolSentinel,
type NeedsApprovalContext,
+ type ToolAuthOptions,
+ type ToolAuthProvider,
type ToolDefinition,
type ToolContext,
type ToolModelOutput,
diff --git a/packages/eve/src/runtime/connections/validate-authorization.ts b/packages/eve/src/runtime/connections/validate-authorization.ts
index 4518dcb3d..25c61838e 100644
--- a/packages/eve/src/runtime/connections/validate-authorization.ts
+++ b/packages/eve/src/runtime/connections/validate-authorization.ts
@@ -85,6 +85,8 @@ export function normalizeAuthorizationSpec(
const auth = authorization as Record<string, unknown>;
const vercelConnect = extractVercelConnectMarker(auth.vercelConnect);
const displayName = auth.displayName as string | undefined;
+ const evict =
+ typeof auth.evict === "function" ? (auth.evict as AuthorizationDefinition["evict"]) : undefined;
if (auth.startAuthorization !== undefined && auth.completeAuthorization !== undefined) {
let interactive: InteractiveAuthorizationDefinition = {
completeAuthorization:
@@ -96,6 +98,7 @@ export function normalizeAuthorizationSpec(
};
if (vercelConnect !== undefined) interactive = { ...interactive, vercelConnect };
if (displayName !== undefined) interactive = { ...interactive, displayName };
+ if (evict !== undefined) interactive = { ...interactive, evict };
return interactive;
}
@@ -106,6 +109,7 @@ export function normalizeAuthorizationSpec(
};
if (vercelConnect !== undefined) nonInteractive = { ...nonInteractive, vercelConnect };
if (displayName !== undefined) nonInteractive = { ...nonInteractive, displayName };
+ if (evict !== undefined) nonInteractive = { ...nonInteractive, evict };
return nonInteractive;
}