@retinue/agentkit 0.2.0 → 0.3.0

package/dist/connections/oauth/client.js

@@ -0,0 +1,141 @@
+/**
+ * Which OAuth app a tenant connects through — REQ-063 (#259), task #263.
+ *
+ * Two ways to reach a provider, and both must work.
+ *
+ * **The deployment's shared app.** One registration per provider; every tenant consents to it. Simplest for the
+ * customer — nothing to register — and the path most will take.
+ *
+ * **The tenant's own app.** A customer who already has a registered Slack app, GitHub App or Google Cloud
+ * project uses their own client id and secret. This is not a nicety. Meta's app review is per app, so a shared
+ * app's approved use case may not cover a customer's; X's access tier is per app, so a customer paying for a
+ * higher tier gains nothing from a shared one on a lower; and an enterprise whose security team will not
+ * approve a third-party app in their Google tenant has no other route.
+ *
+ * ## The fallback is explicit, never silent
+ *
+ * `resolveOAuthClient` reports **which** app it chose. A caller that logs or displays it can see the difference;
+ * one that ignores it behaves as before. The reason is AC-7: removing a tenant's app configuration must not
+ * quietly migrate their live connections to the shared app, because that is a credential swap nobody
+ * authorised — the tokens were issued by a client that no longer participates, and the shared app cannot
+ * refresh or revoke them.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { assertSecureEndpoint, isAllowedRedirect } from "./index.js";
+/**
+ * A tenant's registration, stored as an `oauth-app` row.
+ *
+ * The client secret is sealed by the same `SecretCipher` as every token — AC-2 — because it is exactly as much
+ * a secret and exactly as much the tenant's. The client id, redirect URI and scopes are metadata, readable,
+ * because a settings screen should render without a key.
+ */
+export const registerTenantOAuthApp = async (input) => {
+    if (input.redirectUris.length === 0)
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: "a tenant's OAuth app must declare at least one redirect URI, or no flow could ever complete",
+            retryable: false,
+        });
+    return input.store.create({
+        tenantId: input.context.tenantId,
+        connection: {
+            id: input.id ?? `${input.provider}-app`,
+            kind: "oauth-app",
+            provider: input.provider,
+            ...(input.label === undefined ? {} : { label: input.label }),
+            mode: "oauth2",
+            scheme: "bearer",
+            metadata: {
+                clientId: input.clientId,
+                redirectUris: input.redirectUris.join(" "),
+                ...(input.scopes === undefined ? {} : { scopes: input.scopes.join(" ") }),
+            },
+            sealed: await input.cipher.seal(input.clientSecret),
+        },
+    });
+};
+/**
+ * The client this tenant connects through — theirs if registered, otherwise the deployment's.
+ *
+ * A tenant's own app brings its **own** redirect URIs, and they are still allowlisted: this is the obvious place
+ * that check gets loosened into a wildcard to make BYO work, and the whole of #262's second defence would go
+ * with it. The registration's URIs simply *become* the allowlist for that tenant's flow — an allowlist chosen by
+ * the customer, not a pattern.
+ */
+export const resolveOAuthClient = async (input) => {
+    const registrations = await input.store.list({
+        tenantId: input.context.tenantId,
+        provider: input.config.provider,
+        kind: "oauth-app",
+    });
+    const registration = registrations[0];
+    if (registration === undefined) {
+        return {
+            clientId: input.config.clientId,
+            ...(input.config.clientSecret === undefined ? {} : { clientSecret: input.config.clientSecret }),
+            redirectUris: input.config.redirectUris,
+            scopes: input.config.scopes,
+            source: "deployment",
+        };
+    }
+    const clientId = registration.metadata?.clientId;
+    const redirectUris = (registration.metadata?.redirectUris ?? "").split(" ").filter(Boolean);
+    if (clientId === undefined || redirectUris.length === 0) {
+        // A half-written registration is refused rather than silently falling back: falling back here is exactly
+        // the credential swap AC-7 forbids, and it would happen at the worst moment — mid-migration.
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `this workspace's ${input.config.provider} app registration is incomplete (needs metadata.clientId and ` +
+                "metadata.redirectUris). Refusing rather than falling back to the shared app: that would issue tokens " +
+                "from a different client than the one your existing connections were created with.",
+            retryable: false,
+        });
+    }
+    for (const uri of redirectUris)
+        assertSecureEndpoint("a tenant redirect URI", uri);
+    const scopes = (registration.metadata?.scopes ?? "").split(" ").filter(Boolean);
+    return {
+        clientId,
+        clientSecret: await input.cipher.open(registration.sealed),
+        redirectUris,
+        // A tenant's app may be approved for a different scope set — Meta's review is per app.
+        scopes: scopes.length > 0 ? scopes : input.config.scopes,
+        source: "tenant",
+        registrationId: registration.id,
+    };
+};
+/** The provider config a flow should run with, for this tenant. */
+export const configForTenant = (base, client) => ({
+    ...base,
+    clientId: client.clientId,
+    ...(client.clientSecret === undefined ? {} : { clientSecret: client.clientSecret }),
+    // Still an allowlist, and still matched exactly — see the note on `resolveOAuthClient`.
+    redirectUris: client.redirectUris,
+    scopes: client.scopes,
+});
+/**
+ * Refuses to use a connection with a client that did not issue it — AC-4.
+ *
+ * A token obtained through one app is not usable through another: refresh and revocation both authenticate as
+ * the client, so a connection whose client changed underneath it fails at the provider with a message about an
+ * invalid client — which reads as "your integration is broken" and sends nobody to the actual cause.
+ *
+ * Failing loudly here, naming both clients, is the difference between a five-minute fix and an afternoon.
+ */
+export const assertClientMatches = (connection, client) => {
+    const issuedBy = connection.metadata?.clientId;
+    // A connection created before client ids were recorded cannot be checked. Refusing those would break every
+    // existing connection to enforce a property they predate.
+    if (issuedBy === undefined || issuedBy === client.clientId)
+        return;
+    throw new AgentPlatformError({
+        code: "capability_unavailable",
+        message: `this ${connection.provider} connection was created with OAuth client "${issuedBy}" and this workspace ` +
+            `now resolves to "${client.clientId}". Refresh and revocation both authenticate as the client, so it ` +
+            "cannot be used — reconnect, or restore the previous app registration.",
+        retryable: false,
+    });
+};
+/** Whether a redirect is allowed for this tenant's resolved client. Exactly matched, as always. */
+export const isAllowedRedirectForClient = (client, candidate) => isAllowedRedirect(client.redirectUris, candidate);
+//# sourceMappingURL=client.js.map

package/dist/connections/oauth/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * OAuth 2.0, authorization-code with PKCE — REQ-063 (#259), task #262.
+ *
+ * Shipped so a deployment mounts a flow rather than implementing one. That matters beyond convenience: this is
+ * the piece where a mistake is *exploitable* rather than merely broken, and twenty deployments writing it
+ * themselves is twenty chances at the same three mistakes.
+ *
+ * ## The three ways an OAuth callback is attacked
+ *
+ * Each has its own defence here and its own sabotage test. None is theoretical; all three are routine findings.
+ *
+ * **1. No `state`, or a `state` not bound to the session.** An attacker completes their own consent and gets
+ * their code delivered into the victim's session — the victim's tenant ends up holding an attacker-controlled
+ * connection, which is a *login CSRF* and is worse than it sounds: every subsequent action the agent takes
+ * against that provider is the attacker's account. So `state` is single-use, TTL-bounded, and bound to the
+ * tenant *and* the principal who started it, verified before the code is touched.
+ *
+ * **2. An unallowlisted `redirect_uri`.** Any reflection of a caller-supplied redirect turns the callback into
+ * an open redirect and the code into a token somebody else holds. Redirect URIs come from configuration and are
+ * matched **exactly** — no prefix matching, which `https://app.example.com.evil.tld` defeats, and no wildcard
+ * subdomains.
+ *
+ * **3. No PKCE.** With a public client, or an intercepted code, the verifier is what stops the exchange. Used
+ * everywhere the provider supports it rather than only where a client secret is absent, because "we have a
+ * secret so we do not need PKCE" is an argument about one threat and PKCE defends another.
+ *
+ * ## What is deliberately not here
+ *
+ * No transport. This produces a URL, consumes a callback, and returns a `Connection` — a host mounts it on its
+ * own router with its own authentication, exactly as `./mcp-server` leaves the transport to the host. A
+ * convenience wrapper would have to guess at the authentication, and guessing about authentication is how a
+ * surface ends up open.
+ */
+import type { ExecutionContext } from "../../core/context.js";
+/** How long an authorization attempt may stay open. Long enough to read a consent screen, not to leave open. */
+export declare const DEFAULT_STATE_TTL_MS: number;
+export type OAuthProviderConfig = {
+    readonly provider: string;
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    /** Absent for a public client. PKCE is used either way. */
+    readonly clientSecret?: string;
+    readonly scopes: readonly string[];
+    /**
+     * Every redirect URI this provider may return to. **Matched exactly.**
+     *
+     * A list rather than one value, because a deployment legitimately has several environments — and a list is
+     * still an allowlist. What it must never become is a prefix or a pattern.
+     */
+    readonly redirectUris: readonly string[];
+    /** Some providers need extra authorization parameters (`access_type=offline`, `prompt=consent`). */
+    readonly extraAuthorizationParams?: Readonly<Record<string, string>>;
+    /** Providers that reject PKCE outright. Absent means use it — the safe default. */
+    readonly usePkce?: boolean;
+};
+/**
+ * One in-flight authorization attempt.
+ *
+ * The verifier is here and **never leaves the server**: sending it to the browser would defeat PKCE entirely,
+ * since the whole point is that only the party that began the flow can finish it.
+ */
+export type OAuthAttempt = {
+    readonly state: string;
+    readonly provider: string;
+    readonly tenantId: string;
+    /** Who began it. A code must not be redeemable by a different person in the same tenant. */
+    readonly principalId: string;
+    readonly redirectUri: string;
+    readonly codeVerifier?: string;
+    readonly expiresAt: number;
+    /** Where to send the person afterwards. Validated by the host, not reflected from the request. */
+    readonly returnTo?: string;
+};
+/**
+ * Where in-flight attempts live.
+ *
+ * A port, because the answer differs by deployment shape: one process can hold a `Map`, and several behind a
+ * load balancer cannot — the callback may land on a different instance from the one that started the flow.
+ *
+ * `consume` is **take-once**: it returns the attempt and removes it in the same step. A `get` followed by a
+ * `delete` is a replay window, and a replay window is the first attack in the list above.
+ *
+ * **The store does not judge expiry.** The flow writes `expiresAt` from its own clock and checks it with the
+ * same one; a store that also checked would be a *second* clock deciding one fact, and injecting a clock into
+ * one and not the other yields attempts that are expired the instant they are written. Found by a test doing
+ * exactly that. The store still drops stale entries as housekeeping — that is a memory concern, not a security
+ * decision.
+ */
+export interface OAuthAttemptStore {
+    put(attempt: OAuthAttempt): Promise<void>;
+    /** Returns and removes. `null` only for a state this store does not have. */
+    consume(state: string): Promise<OAuthAttempt | null>;
+}
+/** Single-process store. Adequate for one instance; see the port's note for why that is a real limit. */
+export declare const createMemoryOAuthAttemptStore: (now?: () => number) => OAuthAttemptStore;
+/** RFC 7636 S256. Plain is not offered: it is PKCE in name only. */
+export declare const codeChallengeOf: (verifier: string) => string;
+/**
+ * Exact match, and the reason it is a function rather than an `includes` is that it must stay one.
+ *
+ * `https://app.example.com.evil.tld/callback` starts with `https://app.example.com`, so a prefix check accepts
+ * an attacker's host. A `URL`-based comparison would also be wrong in a subtler way: it normalises, so a
+ * trailing slash or a default port could make two different strings compare equal and widen the allowlist by
+ * accident.
+ */
+export declare const isAllowedRedirect: (allowlist: readonly string[], candidate: string) => boolean;
+export type StartInput = {
+    readonly context: ExecutionContext;
+    readonly redirectUri: string;
+    /** Extra scopes beyond the provider's defaults — a tenant's own app may need different ones (#263). */
+    readonly scopes?: readonly string[];
+    readonly returnTo?: string;
+};
+export type OAuthFlowDeps = {
+    readonly config: OAuthProviderConfig;
+    readonly attempts: OAuthAttemptStore;
+    readonly now?: () => number;
+    readonly randomBytesOf?: (size: number) => Buffer;
+    readonly stateTtlMs?: number;
+    /** Injected so the exchange is testable without a provider. */
+    readonly fetchImpl?: typeof fetch;
+};
+export type TokenResponse = {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly expiresAt?: string;
+    readonly grantedScopes?: readonly string[];
+    /** Everything else the provider returned that is not a secret — Atlassian's cloud id, Slack's team id. */
+    readonly metadata?: Readonly<Record<string, string>>;
+};
+/**
+ * Refuses a provider endpoint that is not HTTPS — checked at construction.
+ *
+ * The token request carries the **client secret and the authorization code** in its body. Over cleartext, both
+ * are readable by anything on the path, and the failure is completely silent: the flow works.
+ *
+ * `localhost` is allowed over HTTP, because a provider emulator on a developer's machine is a real and harmless
+ * case, and refusing it would push people to disable the check entirely — which is how a check stops applying
+ * in production too.
+ */
+export declare const assertSecureEndpoint: (label: string, value: string) => void;
+export declare const createOAuthFlow: (deps: OAuthFlowDeps) => {
+    /** The URL to send a person to, and the attempt recorded server-side. */
+    start(input: StartInput): Promise<{
+        readonly url: string;
+        readonly state: string;
+    }>;
+    /**
+     * Verifies the callback and exchanges the code.
+     *
+     * **The state is verified before the code is touched.** Every check that can be made without contacting the
+     * provider is made first, so an attacker probing the callback never causes an outbound request.
+     */
+    callback(input: {
+        readonly state: string;
+        readonly code: string;
+        readonly context: ExecutionContext;
+    }): Promise<{
+        readonly tokens: TokenResponse;
+        readonly attempt: OAuthAttempt;
+    }>;
+};
+/** Constant-time state comparison, for a caller checking one against another outside the store. */
+export declare const stateEquals: (a: string, b: string) => boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/connections/oauth/index.js

@@ -0,0 +1,226 @@
+/**
+ * OAuth 2.0, authorization-code with PKCE — REQ-063 (#259), task #262.
+ *
+ * Shipped so a deployment mounts a flow rather than implementing one. That matters beyond convenience: this is
+ * the piece where a mistake is *exploitable* rather than merely broken, and twenty deployments writing it
+ * themselves is twenty chances at the same three mistakes.
+ *
+ * ## The three ways an OAuth callback is attacked
+ *
+ * Each has its own defence here and its own sabotage test. None is theoretical; all three are routine findings.
+ *
+ * **1. No `state`, or a `state` not bound to the session.** An attacker completes their own consent and gets
+ * their code delivered into the victim's session — the victim's tenant ends up holding an attacker-controlled
+ * connection, which is a *login CSRF* and is worse than it sounds: every subsequent action the agent takes
+ * against that provider is the attacker's account. So `state` is single-use, TTL-bounded, and bound to the
+ * tenant *and* the principal who started it, verified before the code is touched.
+ *
+ * **2. An unallowlisted `redirect_uri`.** Any reflection of a caller-supplied redirect turns the callback into
+ * an open redirect and the code into a token somebody else holds. Redirect URIs come from configuration and are
+ * matched **exactly** — no prefix matching, which `https://app.example.com.evil.tld` defeats, and no wildcard
+ * subdomains.
+ *
+ * **3. No PKCE.** With a public client, or an intercepted code, the verifier is what stops the exchange. Used
+ * everywhere the provider supports it rather than only where a client secret is absent, because "we have a
+ * secret so we do not need PKCE" is an argument about one threat and PKCE defends another.
+ *
+ * ## What is deliberately not here
+ *
+ * No transport. This produces a URL, consumes a callback, and returns a `Connection` — a host mounts it on its
+ * own router with its own authentication, exactly as `./mcp-server` leaves the transport to the host. A
+ * convenience wrapper would have to guess at the authentication, and guessing about authentication is how a
+ * surface ends up open.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { AgentPlatformError } from "../../core/errors.js";
+/** How long an authorization attempt may stay open. Long enough to read a consent screen, not to leave open. */
+export const DEFAULT_STATE_TTL_MS = 10 * 60 * 1000;
+/** Single-process store. Adequate for one instance; see the port's note for why that is a real limit. */
+export const createMemoryOAuthAttemptStore = (now = Date.now) => {
+    const attempts = new Map();
+    return {
+        async put(attempt) {
+            // Expired entries are dropped on write rather than by a timer: a timer keeps the process alive and needs
+            // clearing, and the set is small by construction.
+            for (const [key, value] of attempts)
+                if (value.expiresAt <= now())
+                    attempts.delete(key);
+            attempts.set(attempt.state, attempt);
+        },
+        async consume(state) {
+            const attempt = attempts.get(state);
+            // Deleted whether or not it is expired: a state presented once is spent, and leaving an expired one
+            // behind is a row that can be presented again after a clock correction. Expiry itself is the *flow's*
+            // judgement — see the port's note.
+            attempts.delete(state);
+            return attempt ?? null;
+        },
+    };
+};
+const base64url = (buffer) => buffer.toString("base64url");
+/** RFC 7636 S256. Plain is not offered: it is PKCE in name only. */
+export const codeChallengeOf = (verifier) => base64url(createHash("sha256").update(verifier).digest());
+function refuse(message, code = "invalid_input") {
+    // A function declaration, not an arrow: TypeScript narrows on a `never`-returning *declaration* used as a
+    // statement, and an arrow assigned to a const does not narrow the code after the call. Without this the
+    // callback below reads as "attempt is possibly null" everywhere after the guard.
+    throw new AgentPlatformError({ code, message, retryable: false });
+}
+/**
+ * Exact match, and the reason it is a function rather than an `includes` is that it must stay one.
+ *
+ * `https://app.example.com.evil.tld/callback` starts with `https://app.example.com`, so a prefix check accepts
+ * an attacker's host. A `URL`-based comparison would also be wrong in a subtler way: it normalises, so a
+ * trailing slash or a default port could make two different strings compare equal and widen the allowlist by
+ * accident.
+ */
+export const isAllowedRedirect = (allowlist, candidate) => allowlist.some((allowed) => allowed === candidate);
+/**
+ * Refuses a provider endpoint that is not HTTPS — checked at construction.
+ *
+ * The token request carries the **client secret and the authorization code** in its body. Over cleartext, both
+ * are readable by anything on the path, and the failure is completely silent: the flow works.
+ *
+ * `localhost` is allowed over HTTP, because a provider emulator on a developer's machine is a real and harmless
+ * case, and refusing it would push people to disable the check entirely — which is how a check stops applying
+ * in production too.
+ */
+export const assertSecureEndpoint = (label, value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        refuse(`${label} is not a URL`);
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !local) {
+        refuse(`${label} must be https — the token request carries the client secret and the authorization code in its ` +
+            "body, and over cleartext both are readable by anything on the path while the flow still works.");
+    }
+};
+export const createOAuthFlow = (deps) => {
+    assertSecureEndpoint("authorizationUrl", deps.config.authorizationUrl);
+    assertSecureEndpoint("tokenUrl", deps.config.tokenUrl);
+    const now = deps.now ?? Date.now;
+    const random = deps.randomBytesOf ?? randomBytes;
+    const ttl = deps.stateTtlMs ?? DEFAULT_STATE_TTL_MS;
+    const usePkce = deps.config.usePkce ?? true;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    return {
+        /** The URL to send a person to, and the attempt recorded server-side. */
+        async start(input) {
+            if (!isAllowedRedirect(deps.config.redirectUris, input.redirectUri)) {
+                // Refused before anything is stored, so an attacker probing redirects leaves no attempts behind.
+                refuse(`redirect_uri "${input.redirectUri}" is not in this provider's allowlist. It is matched exactly — a ` +
+                    "prefix match would accept https://app.example.com.evil.tld.");
+            }
+            const state = base64url(random(32));
+            const codeVerifier = usePkce ? base64url(random(32)) : undefined;
+            await deps.attempts.put({
+                state,
+                provider: deps.config.provider,
+                tenantId: String(input.context.tenantId),
+                principalId: String(input.context.principalId),
+                redirectUri: input.redirectUri,
+                ...(codeVerifier === undefined ? {} : { codeVerifier }),
+                expiresAt: now() + ttl,
+                ...(input.returnTo === undefined ? {} : { returnTo: input.returnTo }),
+            });
+            const url = new URL(deps.config.authorizationUrl);
+            url.searchParams.set("response_type", "code");
+            url.searchParams.set("client_id", deps.config.clientId);
+            url.searchParams.set("redirect_uri", input.redirectUri);
+            url.searchParams.set("scope", (input.scopes ?? deps.config.scopes).join(" "));
+            url.searchParams.set("state", state);
+            if (codeVerifier !== undefined) {
+                url.searchParams.set("code_challenge", codeChallengeOf(codeVerifier));
+                url.searchParams.set("code_challenge_method", "S256");
+            }
+            for (const [key, value] of Object.entries(deps.config.extraAuthorizationParams ?? {})) {
+                url.searchParams.set(key, value);
+            }
+            return { url: url.toString(), state };
+        },
+        /**
+         * Verifies the callback and exchanges the code.
+         *
+         * **The state is verified before the code is touched.** Every check that can be made without contacting the
+         * provider is made first, so an attacker probing the callback never causes an outbound request.
+         */
+        async callback(input) {
+            const attempt = await deps.attempts.consume(input.state);
+            /**
+             * One message for every state failure — unknown, replayed, expired, wrong tenant.
+             *
+             * A callback that distinguishes them is an oracle: it tells an attacker whether a state existed, which is
+             * enough to confirm a guess. The server-side log can say which; the response cannot.
+             */
+            if (attempt === null)
+                refuse("this authorization attempt is not valid", "forbidden");
+            // Expiry judged here, with the clock that wrote it. Same message as every other state failure, so the
+            // callback stays free of an oracle.
+            if (attempt.expiresAt <= now())
+                refuse("this authorization attempt is not valid", "forbidden");
+            if (attempt.tenantId !== String(input.context.tenantId) ||
+                attempt.principalId !== String(input.context.principalId)) {
+                refuse("this authorization attempt is not valid", "forbidden");
+            }
+            if (input.code === "")
+                refuse("the callback carried no authorization code");
+            const body = new URLSearchParams({
+                grant_type: "authorization_code",
+                code: input.code,
+                // The *recorded* redirect URI, never one from the request. A provider checks it matches what the
+                // authorization used, and taking it from the request would let an attacker choose both halves.
+                redirect_uri: attempt.redirectUri,
+                client_id: deps.config.clientId,
+            });
+            if (deps.config.clientSecret !== undefined)
+                body.set("client_secret", deps.config.clientSecret);
+            if (attempt.codeVerifier !== undefined)
+                body.set("code_verifier", attempt.codeVerifier);
+            const response = await fetchImpl(deps.config.tokenUrl, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+                body: body.toString(),
+            });
+            if (!response.ok) {
+                // The provider's body is not echoed: it routinely quotes the request, which carries the client secret
+                // and the code.
+                refuse(`the provider refused the token exchange with status ${response.status}`, "provider_error");
+            }
+            const payload = (await response.json());
+            const accessToken = payload["access_token"];
+            if (typeof accessToken !== "string" || accessToken === "") {
+                refuse("the provider's token response carried no access_token", "provider_error");
+            }
+            const expiresIn = payload["expires_in"];
+            const scope = payload["scope"];
+            return {
+                attempt,
+                tokens: {
+                    accessToken: accessToken,
+                    ...(typeof payload["refresh_token"] === "string" ? { refreshToken: payload["refresh_token"] } : {}),
+                    ...(typeof expiresIn === "number"
+                        ? { expiresAt: new Date(now() + expiresIn * 1000).toISOString() }
+                        : {}),
+                    /**
+                     * The scopes the provider **granted**, which is not what we asked for.
+                     *
+                     * A provider may grant fewer, and #259's AC-7 — telling somebody to *reconnect and grant X* rather
+                     * than surfacing a 403 — is answerable only from what was actually granted.
+                     */
+                    ...(typeof scope === "string" ? { grantedScopes: scope.split(" ").filter(Boolean) } : {}),
+                },
+            };
+        },
+    };
+};
+/** Constant-time state comparison, for a caller checking one against another outside the store. */
+export const stateEquals = (a, b) => {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+//# sourceMappingURL=index.js.map

package/dist/connections/oauth/service.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Connect, disconnect, list — the operations a host mounts — task #262, AC-1, AC-7, AC-8 and AC-9.
+ *
+ * The flow in `./index.ts` produces a URL and consumes a callback. This is what turns that into a stored
+ * connection, and what takes one away.
+ *
+ * Deliberately not a router. A host mounts these on its own paths with its own authentication, exactly as
+ * `./mcp-server` leaves the transport alone: every method here takes an already-authenticated
+ * `ExecutionContext`, so a host that has not authenticated has nothing to pass.
+ */
+import type { ExecutionContext } from "../../core/context.js";
+import type { AuthMode, CredentialScheme } from "../../tools/credentials.js";
+import type { SecretCipher } from "../cipher.js";
+import type { Connection, ConnectionId, ConnectionStore } from "../index.js";
+import type { OAuthProviderConfig, TokenResponse } from "./index.js";
+/**
+ * Where a provider's token may be revoked, when it has such an endpoint.
+ *
+ * Optional because many providers do not offer one, and #262's AC-7 asks that the absence be *documented*
+ * rather than silently skipped — which is what `revocationUrl: undefined` plus this comment is.
+ */
+export type RevocationConfig = {
+    readonly revocationUrl?: string;
+    /** RFC 7009 calls it `token`; some providers differ. */
+    readonly tokenParam?: string;
+};
+export type OAuthConnectionServiceDeps = {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    readonly config: OAuthProviderConfig & RevocationConfig;
+    readonly fetchImpl?: typeof fetch;
+    readonly newId?: () => string;
+    readonly now?: () => string;
+};
+/**
+ * What a connection is missing, for a caller deciding whether to send somebody back through consent — AC-9.
+ *
+ * Reads what was **granted**, never what the deployment's app requests: a tenant using their own OAuth app
+ * (#263) may have granted a different set, and the whole point is to say *reconnect and grant X* rather than
+ * surfacing a vendor 403 that names nothing actionable.
+ *
+ * A connection with no recorded grant returns `[]` rather than "everything is missing" — the provider did not
+ * tell us, and inventing a refusal from an absence would block working connections.
+ */
+export declare const missingScopes: (connection: Pick<Connection, "grantedScopes">, required: readonly string[]) => readonly string[];
+export declare const createOAuthConnectionService: (deps: OAuthConnectionServiceDeps) => {
+    /**
+     * Stores the result of a completed exchange — AC-8.
+     *
+     * The token is sealed on the way in and the non-secret parts are not, which is what lets a connection list
+     * render without a key. `metadata` carries whatever the provider disclosed at consent time — Atlassian's
+     * cloud id, Slack's team id — because those are needed on every subsequent request and are per connection.
+     */
+    complete(input: {
+        readonly context: ExecutionContext;
+        readonly tokens: TokenResponse;
+        readonly label?: string;
+        readonly scheme?: CredentialScheme;
+        readonly mode?: AuthMode;
+        readonly metadata?: Readonly<Record<string, string>>;
+    }): Promise<Connection>;
+    /** A tenant's live connections for this provider. Never decrypts anything. */
+    list(context: ExecutionContext): Promise<readonly Connection[]>;
+    /**
+     * Revokes at the provider, then locally — AC-7.
+     *
+     * **In that order.** Deleting first and then failing to revoke leaves a live token nobody can see and
+     * nobody can stop, which is strictly the worst outcome: the credential still works and the record of it is
+     * gone. Revoking first means a provider failure leaves a connection that is still listed and still
+     * revocable, which a person can retry.
+     *
+     * A provider with no revocation endpoint is **reported**, not silently skipped: a caller that believes a
+     * token was revoked when it was not will not go and remove it by hand.
+     */
+    disconnect(input: {
+        readonly context: ExecutionContext;
+        readonly id: ConnectionId;
+    }): Promise<{
+        readonly revokedAtProvider: boolean;
+        readonly reason?: string;
+    }>;
+    /**
+     * What a caller should tell somebody when a tool needs a scope this connection lacks — AC-9.
+     *
+     * Returns the message rather than throwing, because the caller decides what to do with it: #264 turns it
+     * into a login URL and pauses the run, and a simpler host may just show it.
+     */
+    scopeGap(connection: Connection, required: readonly string[]): string | null;
+};
+//# sourceMappingURL=service.d.ts.map