The Open Framework for Building Agents
fix(eve): improve Connect-backed connection auth error messaging and evict support (#265)
Allen Zhouc8014d160a0e
diff --git a/.changeset/allow-connection-auth-evict.md b/.changeset/allow-connection-auth-evict.mdnew file mode 100644index 000000000..b85ad8a97--- /dev/null+++ b/.changeset/allow-connection-auth-evict.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Improve Vercel Connect-backed connection auth by allowing authored definitions to include the `evict` hook and clarifying `principal_required` guidance when user-scoped connections run without an authenticated user principal.diff --git a/packages/eve/src/internal/authored-definition/connection.test.ts b/packages/eve/src/internal/authored-definition/connection.test.tsindex abb28f624..802edd1b3 100644--- a/packages/eve/src/internal/authored-definition/connection.test.ts+++ b/packages/eve/src/internal/authored-definition/connection.test.ts@@ -101,6 +101,22 @@ describe("normalizeMcpClientConnectionDefinition", () => {});});+ it("preserves the optional auth evict hook", () => {+ const evict = async () => {};+ const result = normalizeMcpClientConnectionDefinition(+ validInput({+ auth: {+ evict,+ getToken: async () => ({ token: "x" }),+ principalType: "app",+ },+ }),+ MSG,+ );++ expect((result.auth as Record<string, unknown>).evict).toBe(evict);+ });+it("drops a malformed vercelConnect marker without throwing", () => {// A misbehaving auth provider could attach a malformed marker; the// normalizer treats it as absent rather than failing the wholediff --git a/packages/eve/src/internal/authored-definition/connection.ts b/packages/eve/src/internal/authored-definition/connection.tsindex 579e24e84..1c41c622c 100644--- a/packages/eve/src/internal/authored-definition/connection.ts+++ b/packages/eve/src/internal/authored-definition/connection.ts@@ -27,6 +27,7 @@ const KNOWN_OPENAPI_TOP_LEVEL_KEYS = [] as const;const KNOWN_AUTHORIZATION_KEYS = ["completeAuthorization",+ "evict","getToken","principalType","startAuthorization",diff --git a/packages/eve/src/runtime/connections/principal.test.ts b/packages/eve/src/runtime/connections/principal.test.tsindex d483a8f4d..17fcd2313 100644--- a/packages/eve/src/runtime/connections/principal.test.ts+++ b/packages/eve/src/runtime/connections/principal.test.ts@@ -104,7 +104,7 @@ describe("resolveConnectionPrincipal", () => {it("throws principal_required (non-retryable) when AuthKey is null", () => {const ctx = ctxWithAuth(null);- expect.assertions(4);+ expect.assertions(5);try {contextStorage.run(ctx, () => resolveConnectionPrincipal("linear", userAuthDef));} catch (error) {@@ -113,6 +113,7 @@ describe("resolveConnectionPrincipal", () => {expect(err.reason).toBe("principal_required");expect(err.retryable).toBe(false);expect(err.connectionName).toBe("linear");+ expect(err.message).toContain("route auth that resolves an authenticated user");}});@@ -126,7 +127,7 @@ describe("resolveConnectionPrincipal", () => {expect(() =>contextStorage.run(ctx, () => resolveConnectionPrincipal("linear", userAuthDef)),- ).toThrow(/principalType "user"/);+ ).toThrow(/active session is scoped to "service"/);});it("accepts an explicit ctx argument and bypasses AsyncLocalStorage", () => {@@ -168,7 +169,7 @@ describe("resolveConnectionPrincipal", () => {});it("throws principal_required for user-typed connections when no context is active", () => {- expect.assertions(4);+ expect.assertions(5);try {resolveConnectionPrincipal("linear", userAuthDef);} catch (error) {@@ -177,6 +178,7 @@ describe("resolveConnectionPrincipal", () => {expect(err.reason).toBe("principal_required");expect(err.retryable).toBe(false);expect(err.message).toMatch(/outside an eve context/);+ expect(err.message).toContain("credentials shared by the agent");}});});diff --git a/packages/eve/src/runtime/connections/principal.ts b/packages/eve/src/runtime/connections/principal.tsindex 44e18b579..a9a689bff 100644--- a/packages/eve/src/runtime/connections/principal.ts+++ b/packages/eve/src/runtime/connections/principal.ts@@ -85,12 +85,7 @@ export function resolveConnectionPrincipal(const current = ctx?.get(AuthKey);if (current === null || current === undefined || current.principalType !== "user") {throw new ConnectionAuthorizationFailedError(connectionName, {- message:- ctx === undefined- ? `Connection "${connectionName}" declares principalType "user" ` +- `but was invoked outside an eve context, so no user principal can be resolved.`- : `Connection "${connectionName}" declares principalType "user" ` +- `but the active session has no authenticated user principal.`,+ message: buildUserPrincipalRequiredMessage(connectionName, ctx, current?.principalType),reason: "principal_required",retryable: false,});@@ -103,3 +98,24 @@ export function resolveConnectionPrincipal(type: "user",};}++function buildUserPrincipalRequiredMessage(+ connectionName: string,+ ctx: AlsContext | undefined,+ currentPrincipalType: string | undefined,+): string {+ let detail: string;+ if (ctx === undefined) {+ detail = "it was invoked outside an eve context, so no authenticated user can be resolved.";+ } else if (currentPrincipalType === undefined) {+ detail = "the active session has no authenticated user.";+ } else {+ detail = `the active session is scoped to "${currentPrincipalType}", not an authenticated user.`;+ }++ return (+ `Connection "${connectionName}" is user-scoped, but ${detail} ` ++ `User-scoped connections require route auth that resolves an authenticated user. ` ++ `If this connection should use credentials shared by the agent instead, configure it as an app-scoped connection.`+ );+}