@keycardai/eve 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT LICENSE
+
+Copyright © 2026 Keycard Labs, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @keycardai/eve
+
+> Preview. Keycard auth for [eve](https://eve.dev) agents: a zone token verifier for a channel's auth walk, Keycard-backed connection auth, and interactive authorization over the zone's web flow.
+
+Three adapters, each one plugging into an eve primitive instead of wrapping it:
+
+| Adapter | eve primitive | What it does |
+| --- | --- | --- |
+| `keycardAuth()` | a channel's ordered `auth` array | Verifies a zone-issued bearer and projects the claims onto `SessionAuthContext`. |
+| `Keycard.asSelf()`, `Keycard.onBehalfOf()`, `Keycard.impersonate()` | connection `auth` | Acquires a resource token at the tool-call boundary, for the app or for the turn's current user. |
+| `Keycard.interactive()` | `defineInteractiveAuthorization` | Runs the zone's browser authorization flow and lets eve park the turn until the user consents. |
+
+## Installation
+
+```bash
+pnpm add @keycardai/eve
+```
+
+`eve` is a peer dependency, pinned to `>=0.47.3 <0.48.0`. This package was
+built and verified against eve `0.47.3`. eve is in public beta and ships
+releases most days, and its connection and auth surfaces are still moving, so
+the range deliberately stops at the next minor rather than tracking `^`. Widen
+it only after re-running this package's tests against the newer eve.
+
+eve itself declares `engines.node: ">=24"` and is ESM only. This package
+imports eve for types only (`import type { ... } from "eve/connections"`), so
+nothing here pulls eve into the runtime and the package builds and tests on
+Node 22 as the rest of this repository's CI does. It ships an ESM build only,
+because an eve app is ESM.
+
+## 1. Verify the caller: `keycardAuth()`
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev } from "eve/channels/auth";
+import { keycardAuth } from "@keycardai/eve";
+
+export default eveChannel({
+  auth: [
+    keycardAuth({
+      zoneUrl: process.env.KEYCARD_ZONE_URL!,
+      audience: "https://agent.example.com",
+    }),
+    localDev(),
+  ],
+});
+```
+
+Three outcomes, matching eve's ordered walk:
+
+- No bearer, or a bearer this zone did not issue: returns `null`, so the next
+  entry in the array still gets a turn.
+- A bearer this zone issued that does not verify, has expired, or names another
+  audience: throws with a `401` `Response`, which ends the walk. A broken
+  Keycard credential is a rejection, not an invitation to fall through to
+  something weaker.
+- A verified bearer: returns `{ principalId, principalType, attributes, issuer,
+  subject }`, and retains the raw token for a later on-behalf-of exchange.
+
+The retained subject token stays out of durable state by default: it lives in a
+process-local store keyed by the principal eve projects onto a connection, so
+it never reaches the model, the session record, or the event stream. Pass
+`retainSubjectToken: "attributes"` when connections run in a different process
+from the request that authenticated the caller, which accepts a bearer token in
+eve's session attributes in exchange for surviving restarts. Pass `"none"` for
+zones whose connections only ever run `asSelf` or `impersonate`.
+
+The verifier and its JWKS keyring are built once per `keycardAuth()` call and
+cache discovery and signing keys, so a request pays no discovery round trip.
+
+## 2. Acquire resource tokens: connection auth
+
+```ts title="agent/connections/calendar.ts"
+import { defineMcpClientConnection } from "eve/connections";
+import { Keycard } from "@keycardai/eve";
+
+export default defineMcpClientConnection({
+  url: "https://calendar.example.com/mcp",
+  description: "The signed-in user's calendar.",
+  auth: Keycard.onBehalfOf({
+    zoneUrl: process.env.KEYCARD_ZONE_URL!,
+    resource: "https://calendar.example.com",
+    requestScopes: ["calendar.read"],
+    clientId: process.env.KEYCARD_CLIENT_ID!,
+    clientSecret: process.env.KEYCARD_CLIENT_SECRET!,
+  }),
+});
+```
+
+- `Keycard.onBehalfOf()` is user-scoped, so eve resolves the principal from the
+  active turn's `ctx.session.auth.current` and rejects with
+  `reason: "principal_required"` when there is no authenticated user. It
+  exchanges the subject token `keycardAuth()` verified for that same principal.
+- `Keycard.asSelf()` is app-scoped and runs client credentials under the
+  agent's own identity, so it works on schedules and subagent turns. It never
+  performs an exchange, so nothing about a caller reaches the zone.
+- `Keycard.impersonate({ userIdentifier })` uses the zone's substitute-user
+  exchange for a user the agent holds no token for. A fixed identifier makes
+  the connection app-scoped; a function receives the connection principal and
+  makes it user-scoped.
+
+Nothing falls back to the agent's authority. A user-pattern connection with no
+user principal, a turn whose subject token was never retained, and an expired
+subject token all fail, each with its own reason: `principal_required`,
+`subject_token_unavailable`, and `subject_token_expired`. The last one is the
+sign-in signal, decided by a decode-only expiry check, so an already dead token
+never costs an exchange round trip.
+
+Credentials go in as either `clientId` plus `clientSecret` (shorthand for a
+client-secret credential) or `applicationCredential` (any
+`ApplicationCredential`, including assertion-based workload credentials, whose
+`clientAssertion`, `clientAssertionType`, and `clientId` are forwarded). Setting
+both is a configuration error.
+
+Every factory builds one warm zone client and reuses it, so tool calls do not
+pay per-call discovery or client construction.
+
+### A revoked token mid-call
+
+`getToken` runs before a tool call, so a grant revoked while a tool is in
+flight surfaces as a `401` inside `execute`. Map it to `ctx.requireAuth` so eve
+evicts the rejected bearer and re-challenges instead of handing the model a
+dead-token error:
+
+```ts
+import { requireAuthOnUnauthorized } from "@keycardai/eve";
+
+if (!res.ok) requireAuthOnUnauthorized(res, ctx, calendarAuth);
+```
+
+## 3. Ask the user to sign in: `Keycard.interactive()`
+
+```ts title="agent/connections/docs.ts"
+import { defineMcpClientConnection } from "eve/connections";
+import { Keycard } from "@keycardai/eve";
+
+export default defineMcpClientConnection({
+  url: "https://docs.example.com/mcp",
+  description: "Documents the user has authorized.",
+  auth: Keycard.interactive({
+    zoneUrl: process.env.KEYCARD_ZONE_URL!,
+    clientId: process.env.KEYCARD_CLIENT_ID!,
+    resource: "https://docs.example.com",
+    requestScopes: ["documents.read"],
+  }),
+});
+```
+
+The definition implements the same three-method form as eve's
+`defineInteractiveAuthorization`, over `@keycardai/oauth`'s v3 web-app flow:
+
+- `getToken` returns a token only when this package holds one for the
+  principal. Otherwise it throws `ConnectionAuthorizationRequiredError`, so eve
+  emits `authorization.required`, runs `startAuthorization` in a durable step,
+  and parks the turn on a framework-owned callback.
+- `startAuthorization` calls `beginAuthorization` for the connection's resource
+  list against eve's minted callback URL, and returns the challenge URL plus
+  the `state` and PKCE verifier as JSON resume state.
+- `completeAuthorization` calls `completeAuthorization` with eve's callback
+  params and the journaled resume state, and hands eve the token.
+
+**Resume without authorization cannot yield a credential.** `getToken` is the
+only path that returns a token, and it reads a store only
+`completeAuthorization` writes. A denied, forged, or failed callback writes
+nothing, so a resumed turn either finds a real grant or throws `Required` again
+and parks. eve's own exactly-once settlement makes that terminal instead of a
+loop: it settles each parked authorization once, and a `Required` thrown after
+an authorization has settled ends the tool call. User denial is reported as
+`ConnectionAuthorizationFailedError` with `reason: "access_denied"` and
+`retryable: false`, so eve stops re-prompting.
+
+## Parity with `@keycardai/langchain`
+
+The two packages implement the same Keycard access model against different
+framework primitives. What LangChain needs middleware and interrupts for, eve
+already owns:
+
+| `@keycardai/langchain` | `@keycardai/eve` |
+| --- | --- |
+| `keycardAccess()` middleware wrapping tool execution | connection `auth` definitions; eve calls `getToken` at the tool boundary and attaches the bearer itself |
+| `Access.asSelf()`, `Access.onBehalfOf()`, `Access.impersonate()` | `Keycard.asSelf()`, `Keycard.onBehalfOf()`, `Keycard.impersonate()` |
+| LangGraph `interrupt()` for sign-in and consent | eve durable parks driven by `ConnectionAuthorizationRequiredError` and the `authorization.required` event |
+| middleware-managed token cache and per-run identity | eve's per-step credential cache and session principal (`ctx.session.auth.current`) |
+| middleware keeping credentials out of tool arguments | eve keeping credentials out of the model's view by construction, since auth never appears in a tool's input schema |
+| `subjectTokenExpired()` decode-only expiry check | the same check, exported here as well |
+| fake zone client from `@keycardai/langchain/testing` | fake zone client from `@keycardai/eve/testing` |
+
+There is no middleware to install here, and no tool wrapper. The package
+supplies auth functions and auth definitions, and eve does the rest.
+
+## Testing offline
+
+`@keycardai/eve/testing` provides seams that take no network:
+
+```ts
+import { fakeZoneClient, userPrincipal, validJwt } from "@keycardai/eve/testing";
+import { Keycard, memorySubjectTokenStore } from "@keycardai/eve";
+
+const client = fakeZoneClient({
+  failResources: { "https://calendar.example.com": new Error("exchange refused") },
+});
+const subjectTokens = memorySubjectTokenStore();
+subjectTokens.set("https://zone.example.com|user-1", validJwt(3600));
+
+const auth = Keycard.onBehalfOf({
+  resource: "https://calendar.example.com",
+  client,
+  subjectTokens,
+});
+```
+
+`fakeZoneClient()` records every exchange, impersonation, and client
+credentials call, and can fail one resource or every request. `keycardAuth()`
+takes a `verify` seam in place of the JWKS-backed verifier, and
+`Keycard.interactive()` takes a `flow` seam in place of the two web-flow calls.
+An injected `client` or `flow` supersedes `zoneUrl`, so a test needs no zone.
+
+## Not included: the Keycard gateway MCP proxy
+
+Routing third-party MCP servers through the Keycard gateway is out of scope for
+this release, pending svc-sts #651, exactly as in `@keycardai/langchain`.
+Third-party MCP servers reached directly through eve's native connections are
+supported, and that is what the examples above do.

package/dist/esm/auth.d.ts

@@ -0,0 +1,62 @@
+import { type JWTClaims, type OAuthKeyring } from "@keycardai/oauth";
+import type { AuthFn } from "eve/channels/auth";
+import { type SubjectTokenStore } from "./subjectTokens.js";
+/**
+ * How the verified inbound bearer is kept for a later on-behalf-of exchange.
+ *
+ * - `"memory"` (default): a process-local store keyed by the principal eve
+ *   projects onto a connection. Nothing is written to durable session state.
+ *   A turn that resumes in another process finds no token and fails closed.
+ * - `"attributes"`: the token rides on `SessionAuthContext.attributes`, which
+ *   eve persists with the session and copies onto the connection principal.
+ *   Survives restarts and reaches connections in other processes, at the cost
+ *   of a bearer token in durable state.
+ * - `"none"`: nothing is retained. For zones where connections only ever run
+ *   `asSelf` or `impersonate`.
+ */
+export type SubjectTokenRetention = "attributes" | "memory" | "none";
+export interface KeycardAuthOptions {
+    /** Keycard zone URL (issuer). Required unless `verify` is given. */
+    zoneUrl?: string;
+    /** Audience(s) the token must carry. Omit to skip audience validation. */
+    audience?: string | readonly string[];
+    /** `principalType` for the session context. Defaults to `"user"`. */
+    principalType?: string;
+    /** Scopes the token must carry. Missing scopes reject the request. */
+    requiredScopes?: readonly string[];
+    /** JWT algorithms to accept. Defaults to the verifier's own default. */
+    algorithms?: readonly string[];
+    /** Keyring for signing keys. Defaults to a cached JWKS keyring. */
+    keyring?: OAuthKeyring;
+    /**
+     * Verification seam. Returns the verified claims, or throws to reject.
+     * Replaces the JWKS-backed verifier, so tests take no network.
+     */
+    verify?: (token: string) => Promise<JWTClaims>;
+    /** Extra attributes for the session context, from the verified claims. */
+    attributes?: (claims: JWTClaims) => Readonly<Record<string, string | readonly string[]>>;
+    /** Retention mode for the inbound bearer. Defaults to `"memory"`. */
+    retainSubjectToken?: SubjectTokenRetention;
+    /** Store for `"memory"` retention. Defaults to the shared store. */
+    subjectTokens?: SubjectTokenStore;
+}
+/**
+ * A Keycard `AuthFn` for a channel's `auth` array.
+ *
+ * Verifies a zone-issued bearer and projects its claims onto eve's
+ * `SessionAuthContext`. Three outcomes, matching eve's ordered walk:
+ *
+ * - No bearer, or a bearer this zone did not issue: returns `null`, so a later
+ *   entry in the array (a shared secret, a local dev bypass) still gets a turn.
+ * - A bearer this zone issued that does not verify, is expired, or is for
+ *   another audience: throws with a 401 `Response`, which stops the walk. A
+ *   broken Keycard credential is a rejection, not an invitation to fall
+ *   through to something weaker.
+ * - A verified bearer: returns the session context, and retains the token for
+ *   `onBehalfOf`.
+ *
+ * The verifier and its keyring are built once per `keycardAuth` call and cache
+ * discovery and signing keys, so a request pays no discovery round trip.
+ */
+export declare function keycardAuth(options: KeycardAuthOptions): AuthFn<Request>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/esm/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAKhD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAc5B;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACtC,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,wEAAwE;IACxE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,mEAAmE;IACnE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,UAAU,CAAC,EAAE,CACX,MAAM,EAAE,SAAS,KACd,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC1D,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IAC3C,oEAAoE;IACpE,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,CA6DxE"}

package/dist/esm/auth.js

@@ -0,0 +1,165 @@
+import { JWKSOAuthKeyring, JWTVerifier, } from "@keycardai/oauth";
+import { RouteRejectedError } from "./errors.js";
+import { decodeClaims } from "./expiry.js";
+import { defaultSubjectTokenStore, principalKey, SUBJECT_TOKEN_ATTRIBUTE, } from "./subjectTokens.js";
+/** Claims never copied into `SessionAuthContext.attributes`. */
+const RESERVED_CLAIMS = new Set([
+    "aud",
+    "exp",
+    "iat",
+    "iss",
+    "jti",
+    "nbf",
+    "sub",
+    SUBJECT_TOKEN_ATTRIBUTE,
+]);
+/**
+ * A Keycard `AuthFn` for a channel's `auth` array.
+ *
+ * Verifies a zone-issued bearer and projects its claims onto eve's
+ * `SessionAuthContext`. Three outcomes, matching eve's ordered walk:
+ *
+ * - No bearer, or a bearer this zone did not issue: returns `null`, so a later
+ *   entry in the array (a shared secret, a local dev bypass) still gets a turn.
+ * - A bearer this zone issued that does not verify, is expired, or is for
+ *   another audience: throws with a 401 `Response`, which stops the walk. A
+ *   broken Keycard credential is a rejection, not an invitation to fall
+ *   through to something weaker.
+ * - A verified bearer: returns the session context, and retains the token for
+ *   `onBehalfOf`.
+ *
+ * The verifier and its keyring are built once per `keycardAuth` call and cache
+ * discovery and signing keys, so a request pays no discovery round trip.
+ */
+export function keycardAuth(options) {
+    if (!options.zoneUrl && !options.verify) {
+        throw new Error("keycardAuth requires zoneUrl or verify");
+    }
+    // Zone tokens carry no trailing slash in `iss`; a slash on the configured
+    // zoneUrl would otherwise make every zone token unrecognized.
+    const issuer = options.zoneUrl?.replace(/\/+$/, "");
+    const principalType = options.principalType ?? "user";
+    const retention = options.retainSubjectToken ?? "memory";
+    const store = options.subjectTokens ?? defaultSubjectTokenStore;
+    const verify = options.verify ?? jwksVerifier(options, issuer);
+    return async (request) => {
+        const token = bearerToken(request);
+        if (token === null)
+            return null;
+        if (!recognized(token, issuer))
+            return null;
+        let claims;
+        try {
+            claims = await verify(token);
+        }
+        catch (cause) {
+            throw new RouteRejectedError({
+                message: cause instanceof Error ? cause.message : "Invalid token",
+                code: "invalid_token",
+                error: "invalid_token",
+            });
+        }
+        const missing = missingScopes(claims, options.requiredScopes);
+        if (missing.length > 0) {
+            throw new RouteRejectedError({
+                message: `Token is missing required scope(s): ${missing.join(", ")}`,
+                code: "insufficient_scope",
+                error: "insufficient_scope",
+            });
+        }
+        const principalId = String(claims.sub);
+        const attributes = {
+            ...claimAttributes(claims),
+            ...options.attributes?.(claims),
+        };
+        const context = {
+            attributes,
+            authenticator: "keycard",
+            principalId,
+            principalType,
+            ...(typeof claims.iss === "string" ? { issuer: claims.iss } : {}),
+            subject: principalId,
+        };
+        if (retention === "attributes") {
+            attributes[SUBJECT_TOKEN_ATTRIBUTE] = token;
+        }
+        else if (retention === "memory") {
+            store.set(principalKey(context), token);
+        }
+        return context;
+    };
+}
+/** The warm JWKS-backed verifier used when no `verify` seam is supplied. */
+function jwksVerifier(options, issuer) {
+    const verifier = new JWTVerifier(options.keyring ?? new JWKSOAuthKeyring(), {
+        issuers: issuer,
+        ...(options.audience ? { audiences: options.audience } : {}),
+        ...(options.algorithms ? { algorithms: options.algorithms } : {}),
+    });
+    return (token) => verifier.verify(token);
+}
+/**
+ * Whether this bearer is a caller the zone issued.
+ *
+ * A decode-only issuer peek, so an unrelated credential in the same header
+ * (another provider's token, an opaque API key) falls through to the next
+ * `AuthFn` instead of rejecting the request. Nothing is trusted from this
+ * decode: the verifier re-checks the issuer against the same allowlist before
+ * any key lookup.
+ */
+function recognized(token, issuer) {
+    if (issuer === undefined)
+        return true;
+    const claims = decodeClaims(token);
+    if (claims === null)
+        return false;
+    return claims.iss === issuer;
+}
+function bearerToken(request) {
+    const header = request.headers.get("authorization");
+    if (!header)
+        return null;
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (!scheme || scheme.toLowerCase() !== "bearer")
+        return null;
+    const token = rest.join("");
+    return token || null;
+}
+function missingScopes(claims, required) {
+    if (!required || required.length === 0)
+        return [];
+    const granted = new Set(tokenScopes(claims));
+    return required.filter((scope) => !granted.has(scope));
+}
+function tokenScopes(claims) {
+    const scope = claims.scope;
+    if (typeof scope === "string")
+        return scope.split(" ").filter(Boolean);
+    if (Array.isArray(scope)) {
+        return scope.filter((entry) => typeof entry === "string");
+    }
+    return [];
+}
+/**
+ * Claims projected onto the session context.
+ *
+ * String and string-list claims only, minus JWT plumbing: attributes are
+ * durable session state and reach connection principals, so structured claims
+ * are left to an explicit `attributes` mapper.
+ */
+function claimAttributes(claims) {
+    const attributes = {};
+    for (const [name, value] of Object.entries(claims)) {
+        if (RESERVED_CLAIMS.has(name))
+            continue;
+        if (typeof value === "string") {
+            attributes[name] = value;
+        }
+        else if (Array.isArray(value) &&
+            value.every((entry) => typeof entry === "string")) {
+            attributes[name] = value;
+        }
+    }
+    return attributes;
+}
+//# sourceMappingURL=auth.js.map

package/dist/esm/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,wBAAwB,EACxB,YAAY,EACZ,uBAAuB,GAExB,MAAM,oBAAoB,CAAC;AAE5B,gEAAgE;AAChE,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,uBAAuB;CACxB,CAAC,CAAC;AA6CH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,0EAA0E;IAC1E,8DAA8D;IAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,kBAAkB,IAAI,QAAQ,CAAC;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,IAAI,wBAAwB,CAAC;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,MAAO,CAAC,CAAC;IAEhE,OAAO,KAAK,EAAE,OAAgB,EAAsC,EAAE;QACpE,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5C,IAAI,MAAiB,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,kBAAkB,CAAC;gBAC3B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;gBACjE,IAAI,EAAE,eAAe;gBACrB,KAAK,EAAE,eAAe;aACvB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;QAC9D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,kBAAkB,CAAC;gBAC3B,OAAO,EAAE,uCAAuC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACpE,IAAI,EAAE,oBAAoB;gBAC1B,KAAK,EAAE,oBAAoB;aAC5B,CAAC,CAAC;QACL,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,UAAU,GAA+C;YAC7D,GAAG,eAAe,CAAC,MAAM,CAAC;YAC1B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC;SAChC,CAAC;QAEF,MAAM,OAAO,GAAuB;YAClC,UAAU;YACV,aAAa,EAAE,SAAS;YACxB,WAAW;YACX,aAAa;YACb,GAAG,CAAC,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,OAAO,EAAE,WAAW;SACrB,CAAC;QAEF,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;YAC/B,UAAU,CAAC,uBAAuB,CAAC,GAAG,KAAK,CAAC;QAC9C,CAAC;aAAM,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;YAClC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CACnB,OAA2B,EAC3B,MAAc;IAEd,MAAM,QAAQ,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,gBAAgB,EAAE,EAAE;QAC1E,OAAO,EAAE,MAAM;QACf,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC,CAAC;IACH,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,KAAa,EAAE,MAA0B;IAC3D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,MAAM,CAAC,GAAG,KAAK,MAAM,CAAC;AAC/B,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5B,OAAO,KAAK,IAAI,IAAI,CAAC;AACvB,CAAC;AAED,SAAS,aAAa,CAAC,MAAiB,EAAE,QAAuC;IAC/E,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,WAAW,CAAC,MAAiB;IACpC,MAAM,KAAK,GAAY,MAAM,CAAC,KAAK,CAAC;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAiB;IACxC,MAAM,UAAU,GAA+C,EAAE,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC3B,CAAC;aAAM,IACL,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACpB,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,EAClE,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/esm/config.d.ts

@@ -0,0 +1,50 @@
+import { type ApplicationCredential, type ClientCredentialsRequest } from "@keycardai/oauth";
+import { type ZoneClient } from "./zoneClient.js";
+import { type SubjectTokenStore } from "./subjectTokens.js";
+/** Options shared by every Keycard connection auth factory. */
+export interface KeycardConnectionOptions {
+    /** The resource URL tokens are minted for. */
+    resource: string;
+    /** Keycard zone URL (issuer). Required unless `client` is given. */
+    zoneUrl?: string;
+    /**
+     * How the agent authenticates to the zone: `ClientSecret` for Keycard-issued
+     * client credentials, or any other `ApplicationCredential`. Mutually
+     * exclusive with `clientId` / `clientSecret`.
+     */
+    applicationCredential?: ApplicationCredential;
+    /** Shorthand for `applicationCredential: new ClientSecret(clientId, clientSecret)`. */
+    clientId?: string;
+    /** Shorthand for `applicationCredential: new ClientSecret(clientId, clientSecret)`. */
+    clientSecret?: string;
+    /** Scopes requested from the zone for this connection. */
+    requestScopes?: string | readonly string[];
+    /** Pre-built zone client. Replaces `zoneUrl`, and takes no network in tests. */
+    client?: ZoneClient;
+    /** Name used in error messages and eve's authorization events. */
+    connectionName?: string;
+    /** Where the verified inbound bearer is read from. Defaults to the shared store. */
+    subjectTokens?: SubjectTokenStore;
+}
+/** One factory's resolved configuration, validated once at definition time. */
+export interface ResolvedConnectionConfig {
+    readonly resource: string;
+    readonly scope?: string;
+    readonly connectionName: string;
+    readonly credential?: ApplicationCredential;
+    readonly subjectTokens: SubjectTokenStore;
+    /** The warm zone client, built on first use and reused after that. */
+    zoneClient(): ZoneClient;
+    /** Client-authentication fields an assertion credential adds to a request body. */
+    clientAuthFields(): Promise<Partial<ClientCredentialsRequest>>;
+}
+/**
+ * Validates and resolves factory options.
+ *
+ * Configuration mistakes throw here, when the connection module is loaded,
+ * rather than on the first tool call inside a turn.
+ */
+export declare function resolveConnectionConfig(options: KeycardConnectionOptions, factory: string): ResolvedConnectionConfig;
+/** Absolute expiry for eve, from the zone's relative `expires_in`. */
+export declare function expiresAt(expiresIn: number | undefined): number | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/esm/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEtF,+DAA+D;AAC/D,MAAM,WAAW,wBAAwB;IACvC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3C,gFAAgF;IAChF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,sEAAsE;IACtE,UAAU,IAAI,UAAU,CAAC;IACzB,mFAAmF;IACnF,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,CAAC;CAChE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,MAAM,GACd,wBAAwB,CAiE1B;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG3E"}

package/dist/esm/config.js

@@ -0,0 +1,83 @@
+import { AuthProviderConfigurationError, ClientSecret, } from "@keycardai/oauth";
+import { KeycardZoneClient } from "./zoneClient.js";
+import { defaultSubjectTokenStore } from "./subjectTokens.js";
+/**
+ * Validates and resolves factory options.
+ *
+ * Configuration mistakes throw here, when the connection module is loaded,
+ * rather than on the first tool call inside a turn.
+ */
+export function resolveConnectionConfig(options, factory) {
+    if (!options.resource || !options.resource.trim()) {
+        throw new AuthProviderConfigurationError(`${factory} requires a resource URL`);
+    }
+    if (!options.zoneUrl && !options.client) {
+        throw new AuthProviderConfigurationError(`${factory} requires zoneUrl or client`);
+    }
+    if (options.applicationCredential && (options.clientId || options.clientSecret)) {
+        throw new AuthProviderConfigurationError(`${factory} accepts either applicationCredential or clientId/clientSecret, not both`);
+    }
+    if (Boolean(options.clientId) !== Boolean(options.clientSecret)) {
+        throw new AuthProviderConfigurationError(`${factory} requires both clientId and clientSecret when using the shorthand`);
+    }
+    let credential;
+    if (options.applicationCredential) {
+        credential = options.applicationCredential;
+    }
+    else if (options.clientId && options.clientSecret) {
+        credential = new ClientSecret(options.clientId, options.clientSecret);
+    }
+    let client = options.client;
+    const scope = joinScopes(options.requestScopes);
+    return {
+        resource: options.resource,
+        ...(scope ? { scope } : {}),
+        connectionName: options.connectionName ?? options.resource,
+        ...(credential ? { credential } : {}),
+        subjectTokens: options.subjectTokens ?? defaultSubjectTokenStore,
+        zoneClient() {
+            if (!client)
+                client = new KeycardZoneClient(options.zoneUrl, credential);
+            return client;
+        },
+        /**
+         * Assertion-based credentials carry no HTTP-level auth; their proof rides
+         * in the request body as a jwt-bearer client assertion. The credential
+         * protocol only exposes request preparation for token exchange, so this
+         * prepares one and lifts the client-auth fields for the
+         * client-credentials call. `ClientSecret` authenticates at the HTTP layer
+         * and contributes nothing here.
+         *
+         * The subject token below is a placeholder: client credentials has no
+         * subject, and only the client-auth fields of the prepared request are
+         * read.
+         */
+        async clientAuthFields() {
+            if (!credential)
+                return {};
+            const prepared = await credential.prepareTokenExchangeRequest("client-credentials", options.resource);
+            if (!prepared.clientAssertion)
+                return {};
+            const fields = {
+                clientAssertion: prepared.clientAssertion,
+                clientAssertionType: prepared.clientAssertionType,
+            };
+            if (prepared.clientId)
+                fields.clientId = prepared.clientId;
+            return fields;
+        },
+    };
+}
+/** Absolute expiry for eve, from the zone's relative `expires_in`. */
+export function expiresAt(expiresIn) {
+    if (typeof expiresIn !== "number" || !Number.isFinite(expiresIn))
+        return undefined;
+    return Date.now() + expiresIn * 1000;
+}
+function joinScopes(scopes) {
+    if (scopes === undefined)
+        return undefined;
+    const value = Array.isArray(scopes) ? scopes.join(" ") : scopes;
+    return value || undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}