Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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 whole
diff --git a/packages/eve/src/internal/authored-definition/connection.ts b/packages/eve/src/internal/authored-definition/connection.ts
index 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.ts
index 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.ts
index 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.`
+ );
+}