@open-everywhere/adapters 0.1.0

package/agent/aws/sso.ts

@@ -0,0 +1,567 @@
+// The per-user AWS Identity Center (SSO) adapter: LINK once with auth-code + PKCE, then mint through
+// `sso:GetRoleCredentials`, so the portal bounds the call by that person's own entitlement. Zero npm deps.
+
+import {
+  warmCredential,
+  encryptedKvVault,
+  requireAwsSsoLinkStore,
+  checkAwsSsoIdentityBinding,
+  OE_AWS_SSO_CALLBACK_PATH,
+  type AwsCredentials,
+  type AwsIdentityRequest,
+  type AwsSsoLinkStore,
+  type CredentialPurgeHook,
+  type EncryptedKvVault,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { makePkce, makeState } from "../oe-oauth/pkce.js";
+
+/** A `fetch`-shaped transport — the DI seam the offline test injects (defaults to global fetch). */
+export type FetchLike = typeof fetch;
+
+// Core owns the canonical const; re-exported here so this module's existing consumers keep resolving it.
+export { OE_AWS_SSO_CALLBACK_PATH };
+
+/** Default OAuth scopes for the Identity Center link. `openid` is LOAD-BEARING, not decoration: it is
+ *  what makes the token response carry an id-token, and the id-token's `sub` is the only statement of
+ *  WHO completed the sign-in the callback can observe. Without it {@link AwsSsoMinter.completeLink}
+ *  refuses every completion, because it cannot name the signer (OPE-1955). An operator who overrides
+ *  `OE_AWS_SSO_SCOPES` must keep `openid` in the list. */
+const DEFAULT_SSO_SCOPES = ["sso:account:access", "openid"] as const;
+/** Consent window for a pending link (15 min, matching the own-rolled OAuth pending TTL). */
+const DEFAULT_PENDING_TTL_MS = 15 * 60 * 1000;
+/** Refresh the SSO access token when within this margin of its expiry. */
+const DEFAULT_EXPIRY_SKEW_MS = 60 * 1000;
+/** Fallback creds TTL requested from the warm cache when the portal states no expiry (1h SSO floor). */
+const DEFAULT_CRED_TTL_SECONDS = 3600;
+
+/** The stored SSO token record. Serialized to the opaque string the core {@link AwsSsoLinkStore} holds
+ *  per principal — core never parses this; only this adapter reads/writes it. */
+interface AwsSsoTokenRecord {
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  /** Absolute ms expiry of the ACCESS token, if the OIDC server stated `expires_in`. */
+  readonly expiresAtMs?: number;
+  readonly region: string;
+  readonly obtainedAtMs: number;
+  /** The Identity Center `sub` of the human whose sign-in minted this token — the account the link
+   *  completion MATCHED against the requester's confirmed `aws` link (OPE-1955). It is the durable
+   *  record of which AWS identity this row actually holds, so "whose access is this?" is answerable
+   *  from the row rather than inferred from the key it is stored under. Absent on a row written
+   *  before the binding check landed; {@link freshAccessToken} treats such a row as UNPROVEN and makes
+   *  the person link again, because a row minted under the old rule may hold a stranger's access. */
+  readonly identityCenterSubject?: string;
+}
+
+/** A persisted pending link (keyed by the opaque state), holding the PKCE verifier server-side. */
+interface AwsSsoPendingRecord {
+  /** The QUALIFIED vault subject the completed link will be stored under (never a bare native id). */
+  readonly principalSubject: string;
+  readonly verifier: string;
+  readonly region: string;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly consumed?: boolean;
+}
+
+/** The acting principal has not linked their Identity Center identity (or their token is dead and must
+ *  be re-linked). Carries the authorization URL so the caller can relay a "connect your AWS account"
+ *  link. Stable `code` so it is duck-typed (cross-module) as authorization-required, mirroring the
+ *  own-rolled OAuth needs-consent error. Carries NO token material. */
+export class AwsSsoLinkRequiredError extends Error {
+  readonly code = "aws_sso_link_required";
+  readonly authorizationUrl: string;
+  constructor(authorizationUrl: string, why: string) {
+    super(
+      `your AWS account isn't linked yet — ${why}. Open this personal link to connect it (expires soon): ` +
+        `${authorizationUrl} — complete the AWS sign-in, then ask again. The link completes ONLY for the ` +
+        `Identity Center account already linked to you; a sign-in by anyone else is refused and links ` +
+        `nothing, so forwarding it gains nobody access. Once linked, the agent acts as YOU with YOUR own ` +
+        `Identity Center access, bounded by the role granted to this channel. If you later say you've ` +
+        `signed in, RETRY the operation to re-check.`,
+    );
+    this.name = "AwsSsoLinkRequiredError";
+    this.authorizationUrl = authorizationUrl;
+  }
+}
+
+/** True iff `e` is the "must link your AWS SSO account" signal — duck-typed on the stable `code` so a
+ *  cross-module instance still matches (mirrors errors.ts isUserAuthRequiredError). */
+export function isAwsSsoLinkRequired(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  const code = (e as { code?: unknown }).code;
+  return code === "aws_sso_link_required" || e.name === "AwsSsoLinkRequiredError";
+}
+
+/**
+ * The per-principal SSO link store over core's encrypted KV vault. The ref interpolates the caller's
+ * QUALIFIED subject verbatim, and the older bare form cannot alias it — so the migration needs no fallback.
+ */
+export function awsSsoTokenRef(principalSubject: string): string {
+  return `aws-sso:tok:${principalSubject}`;
+}
+
+export function makeAwsSsoLinkStore(vault: EncryptedKvVault = encryptedKvVault()): AwsSsoLinkStore {
+  return {
+    async read(principalSubject: string): Promise<string | null> {
+      return vault.read(awsSsoTokenRef(principalSubject));
+    },
+    async write(principalSubject: string, token: string): Promise<void> {
+      await vault.write(awsSsoTokenRef(principalSubject), token, { connector: "aws-sso" });
+    },
+    async clear(principalSubject: string): Promise<void> {
+      await vault.write(awsSsoTokenRef(principalSubject), "", { connector: "aws-sso" });
+    },
+  };
+}
+
+/**
+ * The offboarding half of the SSO link: a REAL delete, not `clear()`, which leaves the row and its envelope.
+ * No vendor-side revocation — Identity Center publishes none per token, and its `Logout` ends every session.
+ */
+export function makeAwsSsoPurgeHook(vault: EncryptedKvVault = encryptedKvVault()): CredentialPurgeHook {
+  return {
+    async purgeSubject(subjectId: string): Promise<number> {
+      return (await vault.delete(awsSsoTokenRef(subjectId))) ? 1 : 0;
+    },
+  };
+}
+
+/** A minimal pending-link store (state → serialized {@link AwsSsoPendingRecord}). Default backs onto the
+ *  encrypted KV vault; the offline test injects a Map-backed fake. */
+export interface AwsSsoPendingStore {
+  read(state: string): Promise<string | null>;
+  write(state: string, value: string): Promise<void>;
+}
+
+/** Construction options — every seam has a real default; the offline test injects fetch + the stores. */
+export interface AwsSsoMinterOptions {
+  /** Identity Center region (oidc.<region> + portal.sso.<region>). Required for any link/mint. */
+  readonly region?: string;
+  /** The public PKCE OIDC client id for the link flow. Required for {@link startLink}/{@link completeLink}. */
+  readonly clientId?: string;
+  /** OAuth scopes requested on the link (default {@link DEFAULT_SSO_SCOPES}). `openid` MUST stay in any
+   *  override — {@link startLink} refuses without it, because no completion could then name its signer. */
+  readonly scopes?: readonly string[];
+  /** Transport for OIDC + portal calls. Default: global `fetch`. */
+  readonly fetch?: FetchLike;
+  /** The per-principal SSO token store. Default: the registered core {@link AwsSsoLinkStore}. */
+  readonly store?: AwsSsoLinkStore;
+  /** The pending-link store. Default: encrypted KV vault under `aws-sso:pend:<state>`. */
+  readonly pending?: AwsSsoPendingStore;
+  /** The completion's identity check — does the Identity Center account that signed in belong to the
+   *  requester? Default: core's {@link checkAwsSsoIdentityBinding}, which reads the identity-link plane
+   *  and writes the refusal's audit row. The seam exists because that read needs a live operational
+   *  store and this adapter's tier has none; it is the same TEST seam shape as `store` and `pending`
+   *  above, and the boot path (register.ts) passes none, so production always takes the real default. */
+  readonly bindIdentity?: typeof checkAwsSsoIdentityBinding;
+  /** The OAuth redirect URI. Default: OE_PUBLIC_BASE_URL + {@link OE_AWS_SSO_CALLBACK_PATH}. */
+  readonly redirectUri?: () => string | undefined;
+  /** Clock. Default `Date.now`. */
+  readonly now?: () => number;
+  /** PKCE pair. Default {@link makePkce}. */
+  readonly newPkce?: () => { readonly verifier: string; readonly challenge: string };
+  /** Opaque state. Default {@link makeState}. */
+  readonly newState?: () => string;
+  readonly pendingTtlMs?: number;
+  readonly expirySkewMs?: number;
+}
+
+/** What {@link makeAwsSsoMinter} returns: the user-sso `mint`, plus the link start/complete steps. */
+export interface AwsSsoMinter {
+  /** Mint short-lived creds for a user-sso request (the {@link AwsIdentityRequest} planAwsIdentity built).
+   *  Throws {@link AwsSsoLinkRequiredError} (carrying the authorization URL) when unlinked / token dead;
+   *  throws a fail-closed error when the user is not entitled to the granted role. */
+  mint(req: AwsIdentityRequest): Promise<AwsCredentials>;
+  /** Begin an Identity Center link for the acting principal — returns the authorization URL to open.
+   *  Takes the QUALIFIED subject, not a bare native id (the pending row and the eventual token row are
+   *  both keyed by it). */
+  startLink(principalSubject: string): Promise<{ url: string }>;
+  /** Complete the callback: exchange the code for a token, prove the Identity Center account that signed
+   *  in is one the pending principal has CONFIRMED as their own, and only then store the token for them.
+   *  Throws on a mismatch, on an unnameable signer, and on an unknown/expired/consumed state. */
+  completeLink(state: string, code: string): Promise<{ principalSubject: string }>;
+}
+
+function defaultRedirectUri(): string | undefined {
+  const base = process.env.OE_PUBLIC_BASE_URL?.trim().replace(/\/+$/u, "");
+  if (!base) return undefined;
+  const withScheme = /^https?:\/\//iu.test(base) ? base : `https://${base}`;
+  return `${withScheme}${OE_AWS_SSO_CALLBACK_PATH}`;
+}
+
+function defaultPendingStore(vault: EncryptedKvVault): AwsSsoPendingStore {
+  const pendRef = (state: string) => `aws-sso:pend:${state}`;
+  return {
+    read: (state) => vault.read(pendRef(state)),
+    write: async (state, value) => {
+      await vault.write(pendRef(state), value, { connector: "aws-sso" });
+    },
+  };
+}
+
+/** Parse an IAM role ARN into its account id + role NAME. `arn:aws:iam::<ACCOUNT>:role/<NAME>` (the
+ *  role name may contain a path, e.g. `role/team/name` → name "team/name"). Throws on a non-role ARN. */
+export function parseRoleArn(roleArn: string): { accountId: string; roleName: string } {
+  const m = /^arn:aws[\w-]*:iam::(\d{12}):role\/(.+)$/u.exec(roleArn);
+  if (!m) {
+    throw new Error(
+      `AWS SSO mint: granted roleArn "${roleArn}" is not an IAM role ARN (expected ` +
+        `arn:aws:iam::<account>:role/<name>). Fail-closed: no AWS access.`,
+    );
+  }
+  return { accountId: m[1]!, roleName: m[2]! };
+}
+
+/**
+ * The `sub` claim of an OIDC id-token — the Identity Center account that completed the sign-in — or
+ * undefined when the value is not an id-token carrying one.
+ *
+ * 🔴 IT DOES NOT VERIFY THE SIGNATURE, AND DOES NOT NEED TO. This id-token is the body of the response
+ * to OUR OWN back-channel `authorization_code` exchange: we posted the code and the PKCE verifier to the
+ * pinned Identity Center token endpoint over TLS and read the reply on that same socket. OIDC Core
+ * §3.1.3.7 states exactly this case — a token received by direct communication with the token endpoint
+ * may rest on TLS server validation instead of signature checking. Nothing an attacker controls reaches
+ * this parser without first breaking that TLS session, at which point the access token is theirs anyway.
+ * A caller that ever reads an id-token from a FRONT channel (a redirect fragment, a posted form) must
+ * verify the signature and must not use this function.
+ */
+export function idTokenSubject(idToken: string | undefined): string | undefined {
+  if (typeof idToken !== "string") return undefined;
+  const parts = idToken.split(".");
+  if (parts.length !== 3) return undefined;
+  let claims: unknown;
+  try {
+    claims = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"));
+  } catch {
+    return undefined;
+  }
+  if (typeof claims !== "object" || claims === null) return undefined;
+  const sub = (claims as { sub?: unknown }).sub;
+  return typeof sub === "string" && sub.length > 0 ? sub : undefined;
+}
+
+export function makeAwsSsoMinter(opts: AwsSsoMinterOptions = {}): AwsSsoMinter {
+  const fetchImpl = opts.fetch ?? fetch;
+  const region = opts.region;
+  const clientId = opts.clientId;
+  const scopes = opts.scopes ?? DEFAULT_SSO_SCOPES;
+  const vault = encryptedKvVault();
+  const pendingStore = opts.pending ?? defaultPendingStore(vault);
+  const bindIdentity = opts.bindIdentity ?? checkAwsSsoIdentityBinding;
+  const store = () => opts.store ?? requireAwsSsoLinkStore();
+  const redirectUriOf = opts.redirectUri ?? defaultRedirectUri;
+  const now = opts.now ?? Date.now;
+  const newPkce = opts.newPkce ?? makePkce;
+  const newState = opts.newState ?? makeState;
+  const pendingTtl = opts.pendingTtlMs ?? DEFAULT_PENDING_TTL_MS;
+  const skew = opts.expirySkewMs ?? DEFAULT_EXPIRY_SKEW_MS;
+
+  function requireRegion(): string {
+    if (!region) {
+      throw new Error(
+        "AWS SSO is not configured — no Identity Center region (set OE_AWS_SSO_REGION or OE_AWS_REGION). " +
+          "Fail-closed: no per-user AWS access.",
+      );
+    }
+    return region;
+  }
+  function requireClientId(): string {
+    if (!clientId) {
+      throw new Error(
+        "AWS SSO link is not configured — no OIDC client id (set OE_AWS_SSO_CLIENT_ID). Register a public " +
+          "PKCE client in Identity Center. Fail-closed: no per-user AWS link.",
+      );
+    }
+    return clientId;
+  }
+  /** 🔴 REFUSE THE LINK AT ITS START, not after a human has signed in. Without `openid` the token
+   *  response carries no id-token, so `completeLink` cannot name the signer and refuses every
+   *  completion — a config error that would otherwise surface only once somebody had already handed
+   *  their AWS credentials to the portal. */
+  function requireOpenIdScope(): void {
+    if (scopes.includes("openid")) return;
+    throw new Error(
+      "AWS SSO link: the configured scopes omit \"openid\" (OE_AWS_SSO_SCOPES). Without it the Identity " +
+        "Center token response carries no id-token, so the account that signs in cannot be named and the " +
+        "link can never complete. Fail-closed: no link was started.",
+    );
+  }
+  const authorizeEndpoint = () => `https://oidc.${requireRegion()}.amazonaws.com/authorize`;
+  const tokenEndpoint = () => `https://oidc.${requireRegion()}.amazonaws.com/token`;
+  const portalEndpoint = () => `https://portal.sso.${requireRegion()}.amazonaws.com/federation/credentials`;
+
+  /** Build the authorization URL a human opens (auth-code + PKCE + RFC 8707-style resource omitted;
+   *  Identity Center uses plain scopes). */
+  async function startLink(principalSubject: string): Promise<{ url: string }> {
+    const reg = requireRegion();
+    const cid = requireClientId();
+    requireOpenIdScope();
+    const redirectUri = redirectUriOf();
+    if (!redirectUri) {
+      throw new Error(
+        "AWS SSO link: OE_PUBLIC_BASE_URL is unset — cannot build a redirect_uri for the Identity Center " +
+          "callback. Fail-closed.",
+      );
+    }
+    const pkce = newPkce();
+    const state = newState();
+    const pending: AwsSsoPendingRecord = {
+      principalSubject,
+      verifier: pkce.verifier,
+      region: reg,
+      createdAt: now(),
+      expiresAt: now() + pendingTtl,
+    };
+    await pendingStore.write(state, JSON.stringify(pending));
+    const u = new URL(authorizeEndpoint());
+    u.searchParams.set("response_type", "code");
+    u.searchParams.set("client_id", cid);
+    u.searchParams.set("redirect_uri", redirectUri);
+    u.searchParams.set("state", state);
+    u.searchParams.set("code_challenge", pkce.challenge);
+    u.searchParams.set("code_challenge_method", "S256");
+    if (scopes.length) u.searchParams.set("scope", scopes.join(" "));
+    return { url: u.toString() };
+  }
+
+  /** Complete the callback: look up the pending record, exchange the code, BIND the result to the human
+   *  who actually signed in, store the token for the pending principal, consume the pending row. Throws
+   *  on unknown/expired/consumed state, on exchange failure, and on an identity the pending principal
+   *  has not confirmed as their own. */
+  async function completeLink(state: string, code: string): Promise<{ principalSubject: string }> {
+    const cid = requireClientId();
+    const redirectUri = redirectUriOf();
+    if (!redirectUri) throw new Error("AWS SSO link: OE_PUBLIC_BASE_URL is unset — cannot complete without a redirect_uri.");
+    const raw = await pendingStore.read(state);
+    if (!raw) throw new Error("AWS SSO link: unknown or expired authorization state.");
+    const pending = JSON.parse(raw) as AwsSsoPendingRecord;
+    if (pending.consumed) throw new Error("AWS SSO link: authorization state already used.");
+    if (now() > pending.expiresAt) throw new Error("AWS SSO link: authorization state expired.");
+    const tok = await exchangeToken({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: cid,
+      code_verifier: pending.verifier,
+    });
+    // 🔴 BIND TO THE SIGNER, NOT THE REQUESTER (OPE-1955). The link is a capability URL, so the human who
+    // completed this sign-in need not be the human who asked for it. Everything below runs BEFORE the
+    // token is stored: a refused completion must leave no token behind at all.
+    const signerSubject = idTokenSubject(tok.id_token);
+    // Consume the pending row whatever the verdict. A link that has been opened is spent — leaving a
+    // refused one live would hand the forwarder a second attempt at the same capability.
+    const consume = () => pendingStore.write(state, JSON.stringify({ ...pending, consumed: true, verifier: "" }));
+    // An UNNAMEABLE signer takes the same road as a wrong one, so every refusal leaves an audit row. An
+    // OIDC client that silently stops issuing id-tokens refuses every person's link, and a trail that
+    // held nothing at all would hide exactly that outage from the reader these rows exist for.
+    const verdict = await bindIdentity({ principalSubject: pending.principalSubject, signerSubject });
+    if (!verdict.ok) {
+      await consume();
+      throw new Error(
+        signerSubject === undefined
+          ? "AWS SSO link: the Identity Center sign-in returned no id-token subject, so the account that " +
+            "signed in cannot be named. The link requested `openid`, so the provider answered without one — " +
+            "check that the OIDC client may issue id-tokens. Fail-closed: nothing was linked."
+          : `AWS SSO link: refused — ${verdict.reason}. Fail-closed: nothing was linked.`,
+      );
+    }
+
+    const record: AwsSsoTokenRecord = {
+      accessToken: tok.access_token,
+      ...(tok.refresh_token ? { refreshToken: tok.refresh_token } : {}),
+      ...(typeof tok.expires_in === "number" ? { expiresAtMs: now() + tok.expires_in * 1000 } : {}),
+      region: pending.region,
+      obtainedAtMs: now(),
+      identityCenterSubject: verdict.awsNativeId,
+    };
+    await store().write(pending.principalSubject, JSON.stringify(record));
+    // Consume single-use + scrub the verifier (defeats replay).
+    await consume();
+    return { principalSubject: pending.principalSubject };
+  }
+
+  interface OidcTokenResponse {
+    readonly access_token: string;
+    readonly refresh_token?: string;
+    readonly expires_in?: number;
+    readonly token_type?: string;
+    /** The OIDC id-token, returned because the link requests the `openid` scope. Its `sub` names the
+     *  human who just signed in — see {@link idTokenSubject}. */
+    readonly id_token?: string;
+  }
+
+  /** POST the Identity Center OIDC token endpoint (auth-code exchange or refresh). Public PKCE client —
+   *  no secret. Throws (never returns empty) on a non-2xx or a body missing access_token. */
+  async function exchangeToken(form: Record<string, string>): Promise<OidcTokenResponse> {
+    const endpoint = tokenEndpoint();
+    let res: Response;
+    try {
+      res = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams(form).toString(),
+      });
+    } catch (err) {
+      throw new Error(
+        `AWS SSO OIDC token transport error against ${endpoint}: ${err instanceof Error ? err.message : String(err)}. Fail-closed.`,
+      );
+    }
+    if (!res.ok) {
+      // Read only the RFC 6749 `error` code — never the raw body (may echo a submitted value).
+      let code: string | undefined;
+      try {
+        const body = (await res.json()) as { error?: unknown };
+        if (typeof body?.error === "string") code = body.error;
+      } catch {
+        /* non-JSON error body */
+      }
+      throw new Error(`AWS SSO OIDC token endpoint returned ${res.status}${code ? ` (${code})` : ""}. Fail-closed.`);
+    }
+    const body = (await res.json().catch(() => ({}))) as OidcTokenResponse;
+    if (typeof body.access_token !== "string" || !body.access_token) {
+      throw new Error(`AWS SSO OIDC token endpoint returned no access_token. Fail-closed.`);
+    }
+    return body;
+  }
+
+  /** Read the principal's stored token, refreshing (and re-storing) it if within the expiry skew. Throws
+   *  {@link AwsSsoLinkRequiredError} when there is no token or the refresh is rejected. */
+  async function freshAccessToken(principalSubject: string): Promise<string> {
+    const raw = await store().read(principalSubject);
+    if (!raw) {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "no linked AWS Identity Center identity");
+    }
+    let rec: AwsSsoTokenRecord;
+    try {
+      rec = JSON.parse(raw) as AwsSsoTokenRecord;
+    } catch {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "your stored AWS link is unreadable");
+    }
+    if (!rec.identityCenterSubject) {
+      // A row written before the binding check landed (OPE-1955). Its token was stored under this
+      // requester's subject whatever identity signed in, so it may hold a stranger's AWS access and
+      // nothing recorded whose it is. Unproven is not usable: the person links again, once.
+      // 🔴 DESTROY IT, do not merely decline to read it. The row holds a live, still-REFRESHABLE
+      // Identity Center session that this code has just judged may be another human's. Leaving it at
+      // rest makes that judgement depend on one reader staying the only reader.
+      await store().clear(principalSubject);
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "your AWS link predates the identity check and must be made again");
+    }
+    const expired = rec.expiresAtMs !== undefined && now() >= rec.expiresAtMs - skew;
+    if (!expired) return rec.accessToken;
+    if (!rec.refreshToken) {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "your AWS session expired and cannot be refreshed");
+    }
+    let tok: OidcTokenResponse;
+    try {
+      tok = await exchangeToken({ grant_type: "refresh_token", refresh_token: rec.refreshToken, client_id: requireClientId() });
+    } catch {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "your AWS session expired and the refresh was rejected");
+    }
+    const updated: AwsSsoTokenRecord = {
+      accessToken: tok.access_token,
+      refreshToken: tok.refresh_token ?? rec.refreshToken,
+      ...(typeof tok.expires_in === "number" ? { expiresAtMs: now() + tok.expires_in * 1000 } : {}),
+      region: rec.region,
+      obtainedAtMs: now(),
+      // A refresh re-mints the SAME person's token, so the binding carries forward unchanged. Dropping
+      // it here would silently demote a proven row to the unproven shape above on the first refresh.
+      identityCenterSubject: rec.identityCenterSubject,
+    };
+    await store().write(principalSubject, JSON.stringify(updated));
+    return updated.accessToken;
+  }
+
+  interface PortalRoleCredentials {
+    readonly roleCredentials?: {
+      readonly accessKeyId?: string;
+      readonly secretAccessKey?: string;
+      readonly sessionToken?: string;
+      readonly expiration?: number;
+    };
+  }
+
+  /** Call sso:GetRoleCredentials with the user's bearer token — creds iff they are ENTITLED to the role.
+   *  401 (bad/expired token) → re-link; 403 (not entitled) → fail closed; other non-2xx → fail closed. */
+  async function getRoleCredentials(
+    accessToken: string,
+    principalSubject: string,
+    accountId: string,
+    roleName: string,
+  ): Promise<AwsCredentials> {
+    const u = new URL(portalEndpoint());
+    u.searchParams.set("account_id", accountId);
+    u.searchParams.set("role_name", roleName);
+    let res: Response;
+    try {
+      res = await fetchImpl(u.toString(), { method: "GET", headers: { "x-amz-sso_bearer_token": accessToken, accept: "application/json" } });
+    } catch (err) {
+      throw new Error(
+        `AWS SSO GetRoleCredentials transport error against ${u.origin}: ${err instanceof Error ? err.message : String(err)}. Fail-closed.`,
+      );
+    }
+    if (res.status === 401) {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "your AWS session token was rejected");
+    }
+    if (!res.ok) {
+      // 403 = not entitled to this role in Identity Center; any other non-2xx = fail closed loudly.
+      throw new Error(
+        `AWS SSO GetRoleCredentials failed (HTTP ${res.status}) for role "${roleName}" in account ${accountId} — ` +
+          `you are not entitled to that role in Identity Center, or the portal refused. Fail-closed: no AWS access.`,
+      );
+    }
+    const body = (await res.json().catch(() => ({}))) as PortalRoleCredentials;
+    const rc = body.roleCredentials;
+    if (!rc?.accessKeyId || !rc.secretAccessKey || !rc.sessionToken) {
+      throw new Error(`AWS SSO GetRoleCredentials returned no role credentials for "${roleName}". Fail-closed.`);
+    }
+    return {
+      accessKeyId: rc.accessKeyId,
+      secretAccessKey: rc.secretAccessKey,
+      sessionToken: rc.sessionToken,
+      ...(typeof rc.expiration === "number" && Number.isFinite(rc.expiration) ? { expiresAtMs: rc.expiration } : {}),
+    };
+  }
+
+  // Warm-cache the portal creds per subject:role, so a second mint inside the TTL never re-calls the portal.
+  // 🔴 The key's person half is the QUALIFIED subject: a key two humans could compose hands over a session.
+  const warm = warmCredential<{ req: AwsIdentityRequest; principalSubject: string }>({
+    name: "aws.sso-role-credentials",
+    platform: "aws",
+    auditAction: "aws.sso.mint_failed",
+    refresh: "re-mint",
+    fallbackTtlSeconds: DEFAULT_CRED_TTL_SECONDS,
+    key: ({ req, principalSubject }) => `user-sso:${req.roleArn}:${principalSubject}`,
+    mint: async ({ req, principalSubject }) => {
+      const { accountId, roleName } = parseRoleArn(req.roleArn);
+      const accessToken = await freshAccessToken(principalSubject);
+      const creds = await getRoleCredentials(accessToken, principalSubject, accountId, roleName);
+      return { value: JSON.stringify(creds), ...(creds.expiresAtMs !== undefined ? { expiresAtMs: creds.expiresAtMs } : {}) };
+    },
+  });
+
+  async function mint(req: AwsIdentityRequest): Promise<AwsCredentials> {
+    const principalSubject = req.principalSubject;
+    if (!principalSubject) {
+      // Defence in depth: planAwsIdentity only builds a user-sso request WITH a verified acting sender.
+      throw new Error("AWS SSO mint: a user-sso request arrived with no principalSubject — refusing. Fail-closed.");
+    }
+    // Cheap existence check BEFORE the warm cache: the common "not linked yet" path throws the
+    // link-required relay without an audited mint-failure row.
+    const existing = await store().read(principalSubject);
+    if (!existing) {
+      const { url } = await startLink(principalSubject);
+      throw new AwsSsoLinkRequiredError(url, "no linked AWS Identity Center identity");
+    }
+    const serialised = await warm.get({ req, principalSubject });
+    return JSON.parse(serialised) as AwsCredentials;
+  }
+
+  return { mint, startLink, completeLink };
+}