@lanes-sh/link 0.2.1 → 0.3.0

package/src/connectivity/auth/oauth-jwt/index.ts

@@ -0,0 +1,237 @@
+import type { ProviderManifest } from '#connectivity';
+import type { SecretStore } from '#secrets';
+import { credentialRefForConnection } from '../../manifest/credential-ref.ts';
+import { parseAssertionKey, signAssertion } from './key.ts';
+
+/**
+ * OAuth 2.0 JWT bearer (RFC 7523) — a key the operator holds, in place of a
+ * person approving a consent screen.
+ *
+ * The one property that earns this its own folder: there is no refresh token,
+ * because there is nothing to refresh. A fresh assertion is signed whenever the
+ * last access token ages out, so nothing an issuer can expire sits between the
+ * operator and their data. An authorization-code refresh token is subject to
+ * whatever policy the issuer applies to it — one such policy expires them after
+ * seven days, and re-approving a browser screen every week is the failure this
+ * folder exists to remove.
+ *
+ * What it costs is reach. An assertion authenticates the *key*, and a key is
+ * not a person: it holds only what has been shared with it, unless the identity
+ * provider has been configured to let it act as someone, which is an
+ * administrator's grant rather than the operator's. `auth.assertion.delegation`
+ * on the manifest is which of the two a provider is, and the CLI is where that
+ * becomes a sentence.
+ */
+
+/** RFC 7523's grant type, and the marker that identifies a stored credential as one. */
+export const ASSERTION_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+
+/**
+ * What a connection stores when it authenticates this way.
+ *
+ * A pointer and not the key itself. One key covers every provider of a vendor,
+ * so it lives at a profile-shared ref and each connection records where to find
+ * it plus the one thing that genuinely differs per connection — who it acts as.
+ * Copying the key into seven connections would mean seven things to rotate.
+ */
+export interface StoredAssertion {
+  readonly grant: typeof ASSERTION_GRANT;
+  readonly key_ref: string;
+  readonly subject?: string;
+}
+
+/**
+ * Whether a stored credential is one of these.
+ *
+ * Both methods write to the same ref — `<provider>/<connection>` — and this is
+ * what tells them apart. Shape rather than a flag in config, because
+ * `credentialResolver` is handed a registry and a store and never a connection
+ * row, so a declaration in config would be invisible exactly where the decision
+ * has to be made.
+ */
+export function isStoredAssertion(value: unknown): value is StoredAssertion {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { grant?: unknown }).grant === ASSERTION_GRANT &&
+    typeof (value as { key_ref?: unknown }).key_ref === 'string'
+  );
+}
+
+/**
+ * The stored credential for this connection, if it is an assertion pointer.
+ *
+ * `null` covers both "nothing stored" and "stored, but an authorization-code
+ * blob" — the caller wants the same thing in either case, which is to carry on
+ * down the path it was already on. Asked through `credentialRefForConnection`
+ * rather than by assembling the ref here, because two files deriving that
+ * separately is exactly the disagreement that function was extracted to end.
+ */
+export async function storedAssertionFor(
+  manifest: ProviderManifest,
+  connectionId: string,
+  credentials: SecretStore,
+): Promise<StoredAssertion | null> {
+  const ref = credentialRefForConnection(manifest, connectionId);
+  if (!ref) return null;
+
+  const raw = await credentials.get(ref);
+  if (!raw) return null;
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isStoredAssertion(parsed) ? parsed : null;
+  } catch {
+    // A credential that is not JSON at all is a pasted token, which is somebody
+    // else's case entirely. Not an error here.
+    return null;
+  }
+}
+
+/**
+ * Minted tokens, for as long as this process lives.
+ *
+ * In memory rather than in the store, and that is a deliberate difference from
+ * the authorization-code path. There, the refresh token is the credential and
+ * persisting the rotation is the whole point. Here the credential is the key,
+ * which nothing at request time modifies — so writing the token back would make
+ * this ref rotatable, which a deployed revision would then need write access to
+ * bind, to cache something that costs one signature and one POST to remake.
+ */
+const minted = new Map<string, { token: string; expiresAt: number }>();
+
+/** Re-mint slightly early: a token that expires mid-flight fails the call it was fetched for. */
+const EXPIRY_SKEW_MS = 60_000;
+
+/**
+ * Emptied when a reload lands, and by tests.
+ *
+ * The cache key is `<provider>.<connection>` with no subject in it, so a
+ * connection re-connected to act as somebody else — or re-connected to a route
+ * that is not this one at all — would otherwise keep serving the token minted
+ * for who it used to be, for up to an hour after the config said otherwise.
+ * `server/generations.ts` clears this beside `clearUpstreamTokens`, which
+ * exists for the same reason on the other path.
+ */
+export function clearMintedTokens(): void {
+  minted.clear();
+}
+
+interface TokenResponse {
+  readonly access_token?: string;
+  readonly expires_in?: number;
+  readonly error?: string;
+  readonly error_description?: string;
+}
+
+/**
+ * An access token for a connection that authenticates with a key.
+ *
+ * Reads the pointer, reads the key it names, signs, exchanges, caches. The
+ * manifest supplies the scopes and nothing else — where to exchange comes from
+ * the key file, so this stays a protocol implementation rather than a vendor's.
+ */
+export async function resolveAssertionToken(input: {
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly stored: StoredAssertion;
+  readonly credentials: SecretStore;
+  readonly fetch?: typeof globalThis.fetch;
+}): Promise<string> {
+  const { manifest, connectionId, stored, credentials } = input;
+  const cacheKey = `${manifest.id}.${connectionId}`;
+
+  const cached = minted.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now() + EXPIRY_SKEW_MS) return cached.token;
+
+  const raw = await credentials.get(stored.key_ref);
+  if (!raw) {
+    throw new Error(
+      `No key stored at ${stored.key_ref}, which ${manifest.id}.${connectionId} authenticates with. ` +
+        `Run: lanes link connect ${manifest.id} --replace`,
+    );
+  }
+
+  const key = parseAssertionKey(raw, stored.key_ref);
+  const scopes = manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [];
+
+  const assertion = await signAssertion({
+    key,
+    scopes,
+    ...(stored.subject ? { subject: stored.subject } : {}),
+  });
+
+  const response = await (input.fetch ?? globalThis.fetch)(key.token_uri, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ grant_type: ASSERTION_GRANT, assertion }),
+  });
+
+  const body = (await response.json().catch(() => ({}))) as TokenResponse;
+
+  if (!response.ok || !body.access_token) {
+    throw new Error(refusalMessage(manifest, stored, body, response.status));
+  }
+
+  minted.set(cacheKey, {
+    token: body.access_token,
+    expiresAt: Date.now() + (body.expires_in ?? 3600) * 1000,
+  });
+
+  return body.access_token;
+}
+
+/**
+ * Why the exchange was refused, in terms of what the operator can act on.
+ *
+ * Three of these are the whole population in practice and each has a different
+ * fix in a different console, so the raw `invalid_grant` is worth translating.
+ * An operator who reads only the error code goes looking in the wrong place —
+ * most often at the key, when the actual gap is a grant an administrator has
+ * not made yet.
+ */
+function refusalMessage(
+  manifest: ProviderManifest,
+  stored: StoredAssertion,
+  body: TokenResponse,
+  status: number,
+): string {
+  const detail = body.error_description ?? body.error ?? `HTTP ${status}`;
+  const scopes = manifest.auth.kind === 'oauth' ? manifest.auth.scopes : [];
+
+  const lines = [`${manifest.name} refused the key at ${stored.key_ref}: ${detail}`];
+
+  if (body.error === 'unauthorized_client') {
+    lines.push(
+      '',
+      stored.subject
+        ? `  The key is not permitted to act as ${stored.subject}. An administrator of that` +
+            '\n  domain has to authorise this key for these scopes, all of them, exactly:'
+        : '  The key is not authorised for these scopes:',
+      ...scopes.map((scope) => `    ${scope}`),
+      '',
+      '  A partial list is refused the same way a missing one is.',
+    );
+  } else if (body.error === 'invalid_grant') {
+    // Listed rather than diagnosed. This one code covers an account that does
+    // not exist, a key that was deleted, a clock that is wrong, and a missing
+    // subject — and the description above is the only thing that distinguishes
+    // them. Asserting one of the four would send the reader to the wrong
+    // console three times in four, which is worse than naming all of them.
+    lines.push(
+      '',
+      '  The description above is the part that identifies which of these it is:',
+      '  - the account in the key no longer exists, or the key was deleted or disabled;',
+      "  - this machine's clock is wrong by more than a few minutes, and an assertion is",
+      '    signed with a timestamp;',
+      ...(stored.subject
+        ? [`  - ${stored.subject} is not an account the key may act as.`]
+        : [
+            '  - this account has to be reached by acting as someone, and this connection acts',
+            `    as nobody. Re-run and name one: lanes link connect ${manifest.id} --replace`,
+          ]),
+    );
+  }
+
+  return lines.join('\n');
+}

package/src/connectivity/auth/oauth-jwt/key.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+
+/**
+ * The key half of RFC 7523: a private key on disk, and the assertion it signs.
+ *
+ * Split from `index.ts` because it is the only part with no I/O — no store, no
+ * network — which is what makes the claim set and the signature testable
+ * against a locally generated key rather than against a live token endpoint.
+ *
+ * Nothing here knows which vendor issued the key. The layout below is the one
+ * every authorization server that accepts this grant ships, and the endpoint to
+ * present the assertion at comes from the key file itself rather than from a
+ * constant, so adding a second vendor is a manifest and no code.
+ */
+
+/**
+ * The issued key file, as the vendor's console writes it.
+ *
+ * Parsed rather than trusted: the common mistake is pasting the *client* JSON —
+ * the one with `installed` or `web` at the top level — which is a different
+ * file with a different purpose and would otherwise fail much later, at the
+ * token endpoint, as an unexplained 400.
+ */
+export const assertionKeySchema = z.object({
+  /** Who the assertion is from. Also the address a resource is shared with. */
+  client_email: z.string().min(1),
+  /** PKCS#8 PEM. */
+  private_key: z.string().min(1),
+  /** Where the assertion is exchanged. Read from the file so no vendor is named here. */
+  token_uri: z.url(),
+  /** Names which key signed it, for a server holding more than one. */
+  private_key_id: z.string().optional(),
+});
+
+export type AssertionKey = z.infer<typeof assertionKeySchema>;
+
+export function parseAssertionKey(raw: string, ref: string): AssertionKey {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `The key at ${ref} is not JSON. It should be the whole file the console downloaded, pasted verbatim.`,
+    );
+  }
+
+  const parsed = assertionKeySchema.safeParse(json);
+  if (parsed.success) return parsed.data;
+
+  // The two files are easy to confuse and the console offers both on adjacent
+  // pages, so say which one is in hand rather than listing missing fields.
+  const shape = json as Record<string, unknown> | null;
+  if (shape && (shape['installed'] !== undefined || shape['web'] !== undefined)) {
+    throw new Error(
+      `The key at ${ref} is an OAuth *client* file, not an account key. That one is for the ` +
+        'browser flow. The key needed here is downloaded from the account itself and has ' +
+        '"private_key" in it.',
+    );
+  }
+
+  throw new Error(
+    `The key at ${ref} is missing ${parsed.error.issues.map((issue) => issue.path.join('.')).join(', ')}.`,
+  );
+}
+
+/** JWT's own encoding: base64 with a URL-safe alphabet and no padding. */
+function base64url(bytes: Uint8Array | string): string {
+  const raw =
+    typeof bytes === 'string'
+      ? btoa(bytes)
+      : btoa(String.fromCharCode(...new Uint8Array(bytes)));
+  return raw.replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+/**
+ * PKCS#8 PEM to the DER bytes `importKey` wants.
+ *
+ * Tolerant of how the key arrives: a console download carries real newlines, a
+ * value pasted through an environment variable or a JSON string often carries
+ * literal `\n` instead, and both are the same key. Rejecting the second would
+ * be a failure whose cause is invisible in a terminal.
+ */
+function derFromPem(pem: string): Uint8Array {
+  const body = pem
+    .replaceAll('\\n', '\n')
+    .replace(/-----[^-]+-----/g, '')
+    .replace(/\s+/g, '');
+
+  const binary = atob(body);
+  const der = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) der[index] = binary.charCodeAt(index);
+  return der;
+}
+
+/** How long the assertion is good for. Kept short: it is minted per exchange. */
+const ASSERTION_LIFETIME_SECONDS = 3600;
+
+/**
+ * Sign the assertion this grant exchanges for a token.
+ *
+ * `sub` is what makes one identity act as another, and it is present only when
+ * the caller supplies one — an assertion carrying an empty `sub` is not the
+ * same request as one carrying none, and servers treat it as malformed rather
+ * than as absent.
+ */
+export async function signAssertion(input: {
+  readonly key: AssertionKey;
+  readonly scopes: readonly string[];
+  /** The account to act as, where the key is only permitted to borrow one. */
+  readonly subject?: string | undefined;
+  /** Injected by tests so the claim set is checkable. */
+  readonly now?: number;
+}): Promise<string> {
+  const issuedAt = Math.floor((input.now ?? Date.now()) / 1000);
+
+  const header = {
+    alg: 'RS256',
+    typ: 'JWT',
+    ...(input.key.private_key_id ? { kid: input.key.private_key_id } : {}),
+  };
+
+  const claims = {
+    iss: input.key.client_email,
+    scope: input.scopes.join(' '),
+    aud: input.key.token_uri,
+    iat: issuedAt,
+    exp: issuedAt + ASSERTION_LIFETIME_SECONDS,
+    ...(input.subject ? { sub: input.subject } : {}),
+  };
+
+  const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+
+  const privateKey = await crypto.subtle.importKey(
+    'pkcs8',
+    derFromPem(input.key.private_key) as unknown as ArrayBuffer,
+    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+
+  const signature = await crypto.subtle.sign(
+    'RSASSA-PKCS1-v1_5',
+    privateKey,
+    new TextEncoder().encode(signingInput) as unknown as ArrayBuffer,
+  );
+
+  return `${signingInput}.${base64url(new Uint8Array(signature))}`;
+}

package/src/connectivity/auth/resolve.ts

@@ -42,7 +42,7 @@ export function credentialResolver(
     const ref = credentialRefForConnection(manifest, connectionId)!;
     const value = await secrets.get(ref);
     if (!value) {
-      throw new Error(`No credential stored at ${ref}. Run: lanes link connect ${providerId}`);
+      throw new Error(`No credential stored at ${ref}. Connecting "${providerId}" again for this profile and target would store one.`);
     }
 
     switch (auth.kind) {

package/src/connectivity/auth/token.ts

@@ -2,6 +2,7 @@ import { type ProviderManifest } from '#connectivity';
 import type { ProviderRegistry } from '#registry';
 import type { SecretStore } from '#secrets';
 import { credentialResolver } from './resolve.ts';
+import { resolveAssertionToken, storedAssertionFor } from './oauth-jwt/index.ts';
 import { CredentialOAuthProvider } from './oauth-authcode/provider.ts';
 
 /**
@@ -81,6 +82,16 @@ export async function bearerTokenAsStored(
 ): Promise<string | null> {
   if (manifest.auth.kind !== 'oauth') return bearerToken(manifest, connectionId, secrets);
 
+  // An assertion credential has no token stored to prefer — the token is minted
+  // from the key, which is what "as stored" means here. Without this branch the
+  // identity call `connect` makes immediately after writing the pointer reads
+  // `access_token` off a blob that has none, sends no Authorization header, and
+  // reports the credential rejected.
+  const assertion = await storedAssertionFor(manifest, connectionId, secrets);
+  if (assertion) {
+    return resolveAssertionToken({ manifest, connectionId, stored: assertion, credentials: secrets });
+  }
+
   const provider = new CredentialOAuthProvider({
     manifest,
     connectionId,

package/src/connectivity/index.ts

@@ -53,6 +53,7 @@ export { defineLocalProvider, defineProviderWithCapabilities } from './provider.
 export type {
   ProviderManifest,
   ConnectorConfig,
+  AuthAssertion,
   AuthBroker,
   AuthConfig,
   SetupDeclaration,
@@ -69,6 +70,7 @@ export {
   bundleSchema,
   credentialRefForConnection,
   rotatableCredentialRefs,
+  hasOwnClientPath,
   setupRequirements,
   UNNAMED_ID,
   RESERVED_PROVIDER_IDS,

package/src/connectivity/manifest/auth.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { credentialRef, identifier } from './primitives.ts';
+import { setupSchema } from './setup.ts';
 
 /**
  * Credential types — how we prove who we are, orthogonal to how we connect.
@@ -34,14 +35,86 @@ export const authBrokerSchema = z.object({
 
 export type AuthBroker = z.infer<typeof authBrokerSchema>;
 
+/**
+ * A second way in, for an authorization server that also accepts an assertion.
+ *
+ * RFC 7523: instead of a person approving a consent screen, the operator holds
+ * a private key, signs a short-lived JWT with it, and exchanges that for an
+ * access token. There is no refresh token because there is nothing to refresh —
+ * a new assertion is signed whenever the last token ages out — which is the
+ * whole reason this exists beside `oauth`. An authorization-code refresh token
+ * can be expired by the issuer's own policy; a key the operator holds cannot.
+ *
+ * Declared *on* the OAuth block rather than as a fourth `kind`, because it is
+ * an alternative arrangement for the same provider rather than a different
+ * provider. Everything that branches on `kind` — where the credential lands,
+ * what setup requires, which refs a deployed revision may rewrite — is
+ * unchanged, and a manifest that omits this reads and behaves exactly as before.
+ *
+ * Which one a connection actually uses is not recorded here or in config. The
+ * stored credential's *shape* is the switch, the same way an `oauth_apps` entry
+ * is the switch between a broker's client and the operator's own.
+ */
+export const authAssertionSchema = z.object({
+  /**
+   * What the operator types after `--auth`, and how a chosen method is named
+   * back to them.
+   *
+   * The provider's word rather than the protocol's. "Assertion" is what this is
+   * to the authorization server and means nothing to the person holding the
+   * file; they downloaded a service account key, and that is what the prompt
+   * and the flag should say. Keeping it here is also what stops the CLI from
+   * learning a vendor's vocabulary in order to print it.
+   */
+  method: identifier,
+  /** The short name shown beside the choice — a noun, not a sentence. */
+  label: z.string().min(1),
+  /**
+   * Whether the assertion may stand for itself, or must name a user to act as.
+   *
+   * `optional` — the key is an identity in its own right, and reaches whatever
+   * has been shared with it. `required` — it can only borrow someone else's,
+   * so a connection without a subject would authenticate cleanly and then find
+   * nothing there. The CLI refuses a blank subject on `required` for that
+   * reason: the failure is otherwise a 404 on every call with no explanation.
+   */
+  delegation: z.enum(['optional', 'required']).default('optional'),
+  /**
+   * Where the profile-shared key lives.
+   *
+   * Shared, not per-connection: one key covers every provider of a vendor, and
+   * asking for it once per provider would be seven pastes of the same file.
+   * The per-connection half is the subject, which is not a secret and is small
+   * enough to sit in the pointer the connection stores.
+   */
+  key_ref: credentialRef,
+  /** One line for the choice prompt: what this method reaches, and what it does not. */
+  reach: z.string().min(1),
+  /**
+   * What to call the account this acts as, when it acts as one.
+   *
+   * Asked per connection and stored beside the pointer. Not a secret — it is an
+   * address — but it lives in the credential store rather than in config
+   * because it is half of a credential, and splitting a credential across two
+   * files is how the halves come to disagree.
+   */
+  subject_label: z.string().min(1),
+  /** The console walkthrough for this method, rendered by the same code as `setup`. */
+  setup: setupSchema,
+});
+
+export type AuthAssertion = z.infer<typeof authAssertionSchema>;
+
 export const authOAuthSchema = z.object({
   kind: z.literal('oauth'),
   /**
    * `dynamic` — the authorization server offers Dynamic Client Registration, so
    * we register ourselves and the operator does nothing at all (Notion, Linear).
    *
-   * `manual` — the vendor requires a pre-registered client, so the operator
-   * supplies an id and secret (Google, including for Google's own MCP servers).
+   * `manual` — the vendor requires a pre-registered client. Who supplies it is
+   * the profile's to decide and not this field's: an id and secret the operator
+   * registered (Google, if they choose to), or the client behind `broker`.
+   * `manual` says only that self-registration is not on offer.
    */
   registration: z.enum(['dynamic', 'manual']).default('dynamic'),
   /** Which `oauth_apps` entry holds the client, for `manual`. Shared across providers of a vendor. */
@@ -57,6 +130,30 @@ export const authOAuthSchema = z.object({
    * that claimed one or the other would be wrong half the time.
    */
   broker: authBrokerSchema.optional(),
+  /**
+   * The other way in, where the vendor offers one. Absent means browser or nothing.
+   *
+   * Additive and inert on its own: declaring it makes `connect` offer a choice
+   * and makes the resolver able to read an assertion credential. It changes
+   * nothing about a connection that authorised in a browser.
+   */
+  assertion: authAssertionSchema.optional(),
+  /**
+   * Whether a token response carrying no refresh token is a failure.
+   *
+   * `required` — it is, and stopping is kinder than succeeding: the connection
+   * would work until the access token expires and then quietly stop. Google
+   * omits one when the account was already authorised for the app, which is a
+   * real and recoverable mistake.
+   *
+   * `optional` — the vendor issues a long-lived token and no refresh token is
+   * the normal, successful answer. Slack does this unless token rotation is
+   * enabled on the app, so demanding one would refuse every connection that
+   * worked.
+   */
+  refresh_token: z.enum(['required', 'optional']).default('required'),
+  /** Where the operator withdraws a grant, named in the refusal above. */
+  revoke_url: z.url().optional(),
   scopes: z.array(z.string()).default([]),
   /**
    * Usually discovered from the resource's metadata; set only to override.

package/src/connectivity/manifest/identity.ts

@@ -30,6 +30,18 @@ export const identitySchema = z.discriminatedUnion('kind', [
     url: z.url(),
     /** Dotted path into the JSON body, e.g. `emailAddress` or `user.emailAddress`. */
     field: z.string().min(1),
+    /**
+     * A second path, shown in brackets, where `field` alone is not unique.
+     *
+     * Almost no provider needs one: an address identifies a Google or iCloud
+     * account globally, and a GitHub login is unique across GitHub. Slack is
+     * the exception, because the thing it calls a user is scoped to a
+     * workspace — the same person in two workspaces answers `auth.test` with
+     * the same `user`, and one account string is how `settleIdentity` decides a
+     * connect is a *reconnect*. Without this, connecting a second workspace
+     * matches the first and overwrites its credential.
+     */
+    qualifier: z.string().min(1).optional(),
   }),
   z.object({
     kind: z.literal('tool'),

package/src/connectivity/manifest/index.ts

@@ -22,11 +22,13 @@ export {
 
 export {
   authNoneSchema,
+  authAssertionSchema,
   authBrokerSchema,
   authOAuthSchema,
   authSchema,
   authStrategySchema,
   authTokenSchema,
+  type AuthAssertion,
   type AuthBroker,
   type AuthConfig,
 } from './auth.ts';
@@ -43,4 +45,4 @@ export {
 } from './provider.ts';
 
 export type { SetupRequirement, SetupNeeds } from './requirements.ts';
-export { setupRequirements, UNNAMED_ID } from './requirements.ts';
+export { hasOwnClientPath, setupRequirements, UNNAMED_ID } from './requirements.ts';

package/src/connectivity/manifest/provider.ts

@@ -65,7 +65,7 @@ export const providerManifestSchema = z.object({
 export type ProviderManifest = z.infer<typeof providerManifestSchema>;
 
 /** Provider ids reserved for the owner layer. */
-export const RESERVED_PROVIDER_IDS: readonly string[] = ['memory', 'skills', 'vault', 'setup'];
+export const RESERVED_PROVIDER_IDS: readonly string[] = ['memory', 'skills', 'vault', 'setup', 'identity'];
 
 /**
  * Validate a manifest, with the cross-field rules the schema alone cannot
@@ -114,18 +114,47 @@ export function defineProvider(input: unknown): ProviderManifest {
         `Provider "${manifest.id}": a broker supplies a pre-registered client, so auth must declare registration "manual" and an "app" naming the oauth_apps entry that overrides it.`,
       );
     }
-    // An MCP provider hands the exchange to the SDK, which posts to the token
-    // endpoint with whatever `clientInformation()` returned. There is no seam
-    // to route that through a broker without reimplementing its auth path, so
-    // this is refused at definition rather than discovered after consent.
+    if (!manifest.auth.authorize_url) {
+      throw new Error(
+        `Provider "${manifest.id}": a broker performs the exchange, but the browser still goes to the vendor, so auth.authorize_url is required.`,
+      );
+    }
+    // An MCP provider hands the whole flow to the SDK, which posts to the token
+    // endpoint with whatever `clientInformation()` returned and has nowhere to
+    // route an exchange somebody else performs. Declaring both endpoints is
+    // what opts it off that path and onto the direct one, where the exchange is
+    // ours — so on an mcp connector the two arrive together or the manifest is
+    // describing a flow that cannot run. Refused here rather than discovered
+    // after the operator has already approved a consent screen. See ADR-040.
+    if (manifest.connector.kind === 'mcp' && !manifest.auth.token_url) {
+      throw new Error(
+        `Provider "${manifest.id}": an mcp connector runs the exchange through the SDK, which cannot route it through a broker, unless the manifest declares its own endpoints. Add auth.token_url beside auth.authorize_url, or drop the broker and register dynamically.`,
+      );
+    }
+  }
+
+  if (manifest.auth.kind === 'oauth' && manifest.auth.assertion) {
+    // Same seam, same absence as the broker rule above. The SDK owns an mcp
+    // provider's exchange and takes a client, not a signed assertion — so the
+    // choice would be offered, accepted, and then have nowhere to go.
     if (manifest.connector.kind === 'mcp') {
       throw new Error(
-        `Provider "${manifest.id}": an mcp connector runs the exchange through the SDK, which cannot route it through a broker. Register a client (registration "manual") or use dynamic registration.`,
+        `Provider "${manifest.id}": an mcp connector runs the exchange through the SDK, which cannot present a signed assertion. Remove auth.assertion.`,
       );
     }
-    if (!manifest.auth.authorize_url) {
+    // The assertion carries `aud` from the key file, but the *scopes* it claims
+    // come from the manifest. A provider requesting none would mint a token
+    // permitted to do nothing and only find out at the first call.
+    if (manifest.auth.scopes.length === 0) {
       throw new Error(
-        `Provider "${manifest.id}": a broker performs the exchange, but the browser still goes to the vendor, so auth.authorize_url is required.`,
+        `Provider "${manifest.id}": auth.assertion exchanges a signed assertion for a token scoped to auth.scopes, which is empty. There would be nothing to grant.`,
+      );
+    }
+    // The whole point of the alternative is that it asks for something. A block
+    // with no prompt reaches the walkthrough and then has nothing to collect.
+    if (manifest.auth.assertion.setup.prompts.length === 0) {
+      throw new Error(
+        `Provider "${manifest.id}": auth.assertion declares no setup prompts, so there is no way to learn what key to ask for.`,
       );
     }
   }