@open-everywhere/core 0.1.0

package/agent/identity/link-store.ts

@@ -0,0 +1,889 @@
+// The ONLY writer over identity_link_sets, identity_linked_ids and identity_link_challenges, so the judgement about who somebody is lives in one file: an account is exactly one person (the whole platform, tenant, nativeId triple), a confirmed row requires evidence, revoked is terminal, and nothing here joins on a handle, an email or a display name.
+// Every mutation appends an identity.link audit row, issued unconditionally — a link written with no audit row would be an identity merge nobody can account for.
+
+import { randomUUID } from "node:crypto";
+import { getOperationalStore } from "../operational/provider.js";
+import { appendAudit } from "../audit/audit.js";
+import { auditErrorDetail } from "../audit/tool-action.js";
+import { tryPrincipalKey } from "./principal-key.js";
+import { surfaceIdsFromAccounts, type PrincipalAccountRef } from "./principals.js";
+import { linkTenantOf } from "./link-tenant.js";
+import { hashLinkCode, mintLinkCode, LINK_CHALLENGE_TTL_MS } from "./link-challenge.js";
+import type { LinkTransport } from "./link-flow.js";
+import { rawVaultSubject, sharedVaultSubject } from "./oauth-vault-share.js";
+import { purgeSubjectCredentials, purgeSubjectsCredentials, type CredentialPurgeOutcome } from "../credentials/purge.js";
+import { directoryLinkSetVaultArmed } from "../connections/connector-flags.js";
+import type { LinkChallengeRow, LinkChallengeStatus, LinkSetRow, LinkSetStatus, LinkedIdRow, LinkedIdStatus } from "../operational/store.js";
+import type { LinkSetPrincipal } from "./link-resolve.js";
+
+export type { LinkChallengeRow, LinkChallengeStatus, LinkSetRow, LinkSetStatus, LinkedIdRow, LinkedIdStatus };
+
+/**
+ * WHY the system believes an account belongs to a person. Every confirmation records one, so
+ * invariant 2 has somewhere to land.
+ *
+ * `directory-sync` and `config-import` exist as vocabulary from day one deliberately: P2 writes
+ * `suggested` rows with `directory-sync` evidence and then CONFIRMS them through
+ * {@link confirmLinkedId} with the person's own DM tap recorded as a `challenge` — so the trust
+ * anchor stays uniform and no phase needs to widen this API to get its own back door.
+ */
+export type LinkEvidence =
+  | { readonly kind: "challenge"; readonly challengeId: string }
+  | { readonly kind: "config-import"; readonly note: string }
+  | {
+      readonly kind: "directory-sync";
+      readonly provider: string;
+      readonly grade: string;
+      /** The IdP's own user id for the person this mapping came from (P2). Recorded so the answer to
+       *  "which directory record produced this row" is a column and not an inference; NEVER a join
+       *  key (invariant 4 holds one level up — see identity/directory.ts). */
+      readonly externalId?: string;
+    };
+
+/** The canonical `established_by` label for one evidence record — the short, greppable form that
+ *  rides on the row and in audit details next to the full JSON. */
+function evidenceLabel(e: LinkEvidence): string {
+  switch (e.kind) {
+    case "challenge":
+      return `challenge:${e.challengeId}`;
+    case "config-import":
+      return "config-import";
+    case "directory-sync":
+      return `directory-sync:${e.provider}`;
+  }
+}
+
+/** What a write attempt did. A refusal is a VALUE, not a throw: every caller here is a tool or a
+ *  hook that must turn "no" into a sentence a person reads, and an exception would make the two
+ *  indistinguishable from a store outage. */
+export type LinkWriteResult =
+  | { readonly ok: true; readonly linkSetId: string; readonly note: string }
+  | { readonly ok: false; readonly reason: string };
+
+/** One account, in the shape the read path hands out — the WHOLE triple, never a (platform, id)
+ *  pair (invariant 1). Build `tenant` with identity/link-tenant.ts's `linkTenantOf`, never by hand:
+ *  it is `""` for every vendor-global platform and the real workspace on a tenant-scoped one, and
+ *  getting that backwards is precisely the aliasing this column exists to delete. */
+export interface LinkedAccount {
+  readonly platform: string;
+  readonly tenant: string;
+  readonly nativeId: string;
+}
+
+/**
+ * The LABEL for one account: its principal key when the tenant can be named, and a deliberately un-key-shaped sentence when it cannot, so a reader cannot paste it into a roster.
+ * A row with a blank tenant on a tenant-scoped platform already matches nothing, so the label says the workspace is unnamed rather than turning a completed write's audit append into an exception.
+ */
+function accountLabel(platform: string, tenant: string | undefined, nativeId: string): string {
+  const key = tryPrincipalKey(platform, tenant, nativeId);
+  return key ?? `the ${platform} account "${nativeId}" (workspace unnamed — pre-OPE-309 row)`;
+}
+
+/**
+ * The RAW vault subject for one account, or undefined when its tenant cannot be named. Undefined only ever reaches a PURGE list, and both purge paths are fail-open, so a vault outage never turns a completed unlink or revoke into an error.
+ * Such a row's credentials sit under a subject nothing composes any more; destroying that dead weight is an out-of-band operator job — packages/core/scripts/purge-orphaned-vault-rows.ts.
+ */
+function accountVaultSubject(org: string, account: { readonly platform: string; readonly tenant: string; readonly nativeId: string }): string | undefined {
+  if (tryPrincipalKey(account.platform, account.tenant, account.nativeId) === undefined) return undefined;
+  return rawVaultSubject(org, account.platform, account.tenant, account.nativeId);
+}
+
+/**
+ * The link-set this (platform, nativeId) belongs to, or null. FAIL-CLOSED on every axis that is not
+ * a live, proven link: a `suggested` row (not yet proven), a `revoked` row (terminal), and a set
+ * that is suspended or revoked all read as "no link-set" — so attribution degrades to per-surface
+ * identity, which is exactly the §5 fallback the config map already has.
+ */
+export async function resolveLinkSet(org: string, platform: string, nativeId: string, tenant?: string | null): Promise<LinkSetRow | null> {
+  const store = getOperationalStore();
+  // `tenant` is OPTIONAL and last, because most callers reach here from a surface that names its
+  // workspace and a few (the connector gate's vault-subject derivation) do not. `linkTenantOf` fills
+  // the gap from the deployment's sole admitted tenant when it can and THROWS when it cannot —
+  // callers catch that into their own fail-closed answer (no link-set), which costs standing and
+  // never grants it.
+  const row = await store.getLinkedId(org, platform, linkTenantOf(platform, tenant), nativeId);
+  if (!row || row.status !== "confirmed") return null;
+  const set = await store.getLinkSet(org, row.linkSetId);
+  return set && set.status === "active" ? set : null;
+}
+
+/**
+ * Every CONFIRMED account in a link-set — the expansion G (person-groups) will call to turn one
+ * human into the platform ids they speak with. `suggested` and `revoked` rows are excluded for the
+ * same reason `resolveLinkSet` excludes them: an unproven or withdrawn account is not this person.
+ * Returns [] for an unknown, suspended or revoked set.
+ */
+export async function expandLinkSet(org: string, linkSetId: string): Promise<readonly LinkedAccount[]> {
+  const store = getOperationalStore();
+  const set = await store.getLinkSet(org, linkSetId);
+  if (!set || set.status !== "active") return [];
+  const rows = await store.listLinkedIds(org, linkSetId);
+  return rows.filter((r) => r.status === "confirmed").map((r) => ({ platform: r.platform, tenant: r.tenant, nativeId: r.nativeId }));
+}
+
+/**
+ * Every ACTIVE link-set's CONFIRMED accounts, in the flat shape identity/link-resolve.ts unions
+ * with the config map — the ONE edge read the attribution path makes (P1.5). It lives here rather
+ * than in link-resolve.ts so that module stays pure: the resolver is a function of two lists, and
+ * the I/O is the caller's, exactly as `getConfig().loadPrincipals?.()` already is.
+ *
+ * A set whose confirmed accounts collapse to nothing is dropped rather than emitted empty — an
+ * entry with no ids can never join anything and would only be noise in the union.
+ */
+export async function confirmedLinkSetPrincipals(org: string): Promise<readonly LinkSetPrincipal[]> {
+  const store = getOperationalStore();
+  const sets = await store.listLinkSets(org);
+  const rows = await store.listLinkedIds(org);
+  const out: LinkSetPrincipal[] = [];
+  for (const set of sets) {
+    if (set.status !== "active") continue;
+    // Every confirmed account is projected WITH its workspace, so a set that legitimately holds two accounts on one platform is not collapsed into one.
+    // A row whose tenant is blank stays blank — a truthful "nobody named the workspace yet" that identity/link-tenant-backfill.ts heals; inventing one here would be an identity claim.
+    const accounts: PrincipalAccountRef[] = [];
+    for (const r of rows) {
+      if (r.linkSetId !== set.id || r.status !== "confirmed") continue;
+      accounts.push(r.tenant ? { platform: r.platform, tenant: r.tenant, id: r.nativeId } : { platform: r.platform, id: r.nativeId });
+    }
+    if (accounts.length === 0) continue;
+    out.push({ linkSetId: set.id, handle: set.handle, ids: surfaceIdsFromAccounts(accounts) });
+  }
+  return out;
+}
+
+/** Every link-set in an org with its accounts — the admin list view (P1.4). Includes suspended and
+ *  revoked sets and non-confirmed rows on purpose: this is the view an admin OFFBOARDS from, and a
+ *  view that hid the withdrawn rows would hide the thing they are checking. */
+export async function listLinkSetsWithIds(org: string): Promise<readonly { readonly set: LinkSetRow; readonly ids: readonly LinkedIdRow[] }[]> {
+  const store = getOperationalStore();
+  const sets = await store.listLinkSets(org);
+  const all = await store.listLinkedIds(org);
+  return sets.map((set) => ({ set, ids: all.filter((r) => r.linkSetId === set.id) }));
+}
+
+/** A freshly-issued challenge: the row (for the caller's bookkeeping) plus the RAW code, which
+ *  exists nowhere else and must be shown to the initiator and then forgotten. */
+export interface IssuedChallenge {
+  readonly challenge: LinkChallengeRow;
+  /** The raw code. NEVER logged, NEVER audited, NEVER persisted — see link-challenge.ts. ABSENT on
+   *  the DIRECTORY transport, which mints no claimable code at all: the target is asked in their own
+   *  DM instead, so there is nothing for a person to carry between surfaces. */
+  readonly code?: string;
+}
+
+/**
+ * Issue a proof-of-control challenge from `initiator`'s DM. Sweeps this org's expired challenges
+ * first (the prune-on-write posture every TTL'd table here uses — a serverless deployment has no
+ * reliable cron to hang a sweep on, so the bound has to live on the path that creates the rows).
+ *
+ * The audit row records the challenge id and the initiator, never the code.
+ */
+export async function issueLinkChallenge(input: {
+  readonly org: string;
+  readonly platform: string;
+  /** WHICH TRANSPORT this request uses (OPE-617, identity/link-flow.ts). Absent ⇒ `"code"`, the
+   *  bearer-code path, which is what every caller before this ticket meant. */
+  readonly transport?: LinkTransport;
+  /** The account the DIRECTORY transport asks. Recorded at ISSUE time — the consent CAS matches
+   *  against it, so a consent from any other account matches no row. Ignored (and refused, see
+   *  below) on the code transport, where the target is unknown until something claims. */
+  readonly target?: LinkedAccount;
+  /** The initiating DM's own workspace (`binding.workspace`). Optional only because a caller may
+   *  genuinely not have one; `linkTenantOf` then resolves the deployment's sole admitted tenant, or
+   *  throws. It is RECORDED on the row rather than re-derived at ratification: the workspace the DM
+   *  came from is a fact of THIS turn, and the ratifying turn can be days later. */
+  readonly tenant?: string;
+  readonly nativeId: string;
+  readonly surfaceKey: string;
+  readonly now?: Date;
+}): Promise<IssuedChallenge> {
+  const store = getOperationalStore();
+  const now = input.now ?? new Date();
+  const nowIso = now.toISOString();
+  await store.expireLinkChallenges(input.org, nowIso);
+
+  const transport: LinkTransport = input.transport ?? "code";
+  if (transport === "directory" && !input.target) throw new Error("issueLinkChallenge: the directory transport must name its target account.");
+  if (transport === "code" && input.target) throw new Error("issueLinkChallenge: the code transport has no target until something claims it.");
+  // 🔴 THE DIRECTORY TRANSPORT MINTS NO CLAIMABLE CODE. `nonce_hash` is NOT NULL and indexed, so the
+  // row still needs a value — it gets the digest of a random string NOBODY IS EVER SHOWN. That is the
+  // difference between "this challenge has no code" and "this challenge has a code lying around":
+  // nothing can post a message that hashes to it, so `claimLinkChallenge` can never match a directory
+  // row, and the ONLY way that row leaves `pending` is the target's own consent CAS.
+  const code = transport === "code" ? mintLinkCode() : undefined;
+  const challenge: LinkChallengeRow = {
+    org: input.org,
+    id: randomUUID(),
+    nonceHash: hashLinkCode(code ?? randomUUID()),
+    initiatingPlatform: input.platform,
+    initiatingTenant: linkTenantOf(input.platform, input.tenant),
+    initiatingNativeId: input.nativeId,
+    initiatingSurfaceKey: input.surfaceKey,
+    transport,
+    ...(input.target
+      ? { targetPlatform: input.target.platform, targetTenant: input.target.tenant, targetNativeId: input.target.nativeId }
+      : {}),
+    status: "pending",
+    createdAt: nowIso,
+    expiresAt: new Date(now.getTime() + LINK_CHALLENGE_TTL_MS).toISOString(),
+  };
+  await store.addLinkChallenge(input.org, challenge);
+  await auditLink(input.org, input.platform, input.surfaceKey, accountLabel(input.platform, challenge.initiatingTenant, input.nativeId), "identity.link.challenge_issued", {
+    challengeId: challenge.id,
+    transport,
+    ...(input.target ? { target: accountLabel(input.target.platform, input.target.tenant, input.target.nativeId) } : {}),
+    expiresAt: challenge.expiresAt,
+  });
+  return { challenge, ...(code ? { code } : {}) };
+}
+
+/**
+ * The DIRECTORY transport's act 2: the TARGET consents, in their own DM.
+ *
+ * The whole decision is the store's one CAS (see the store contract): still pending, inside the TTL,
+ * and the consenting account IS the account this challenge named. A consent from anybody else matches
+ * no row and returns null — which is the property this transport rests on, since the initiator picked
+ * the target out of a directory and any other yes would make that pick meaningless.
+ *
+ * 🔴 `consenter` MUST come from the CONSENTING TURN'S OWN BINDING, never from tool input. It is the
+ * whole evidentiary content of a consent: the DM proves control of the account, and the account is
+ * what the challenge named.
+ *
+ * `backCode` is the raw code-2 when the consent step minted one (identity/link-flow.ts
+ * `codeBackDecision`); only its digest is stored, and the raw value is the caller's to show once and
+ * forget.
+ */
+export async function consentLinkChallenge(input: {
+  readonly org: string;
+  readonly challengeId: string;
+  readonly consenter: LinkedAccount;
+  readonly backCode?: string;
+  readonly now?: Date;
+}): Promise<LinkChallengeRow | null> {
+  const store = getOperationalStore();
+  const nowIso = (input.now ?? new Date()).toISOString();
+  const consented = await store.consentLinkChallenge(
+    input.org,
+    input.challengeId,
+    input.consenter,
+    nowIso,
+    input.backCode ? hashLinkCode(input.backCode) : undefined,
+  );
+  if (!consented) return null;
+  await auditLink(
+    input.org,
+    input.consenter.platform,
+    consented.initiatingSurfaceKey,
+    accountLabel(input.consenter.platform, input.consenter.tenant, input.consenter.nativeId),
+    "identity.link.consented",
+    {
+      challengeId: consented.id,
+      initiator: accountLabel(consented.initiatingPlatform, consented.initiatingTenant, consented.initiatingNativeId),
+      codeBack: input.backCode !== undefined,
+    },
+  );
+  return consented;
+}
+
+/**
+ * A code-back was REQUIRED by transport and could not be delivered (OPE-617) — one audit row, so the
+ * downgrade has a reader.
+ *
+ * The consent still stands and the finalizer degrades to the acknowledged ratification. That is a
+ * deliberate fail-soft (identity/link-flow.ts `codeBackDecision` states why), and a fail-soft nobody
+ * can see is indistinguishable from a bug — so the row records which surface had nowhere to put the
+ * code. It lands in the INITIATOR's partition, like the notice row above, because the initiator is
+ * the person whose finalize just became weaker.
+ */
+export async function auditLinkCodeBackUndeliverable(input: { readonly org: string; readonly challenge: LinkChallengeRow; readonly claimantPlatform: string }): Promise<void> {
+  const c = input.challenge;
+  await auditLink(input.org, c.initiatingPlatform, c.initiatingSurfaceKey, accountLabel(c.initiatingPlatform, c.initiatingTenant, c.initiatingNativeId), "identity.link.code_back_undeliverable", {
+    challengeId: c.id,
+    claimantPlatform: input.claimantPlatform,
+    reason: `no way to post the second code back to "${input.claimantPlatform}" — the finalize degrades to an acknowledged confirm`,
+  });
+}
+
+/**
+ * A well-formed `link <code>` line arrived on an UNADDRESSED wake and was refused (OPE-1788) — one
+ * audit row, so a refusal that is otherwise only a console line has a reader.
+ *
+ * The row lands in the CLAIMANT's own partition, because the claimant is the only account this
+ * refusal knows about: the code was never looked up, so there is no challenge and no initiator to
+ * name. That is the point of where the gate sits — the refusal runs before the claim CAS, so the code
+ * is not spent and a code that never existed is indistinguishable from one that did.
+ *
+ * 🔴 THE ROW CARRIES NEITHER THE CODE NOR ITS DIGEST. A link code is a live bearer secret for its
+ * 10-minute life, and the digest is unsalted over a 39-bit value (identity/link-challenge.ts
+ * `hashLinkCode` says why that is right at rest), so a reader of the audit log could brute-force a
+ * digest back to a code well inside the TTL. What an incident reviewer needs is that somebody posted
+ * a claim-shaped line where it could not count, and from which account — never the value.
+ */
+export async function auditLinkClaimUnaddressed(input: {
+  readonly org: string;
+  readonly platform: string;
+  readonly tenant: string | undefined;
+  readonly nativeId: string;
+  readonly mode: string | undefined;
+}): Promise<void> {
+  await auditLink(input.org, input.platform, undefined, accountLabel(input.platform, input.tenant, input.nativeId), "identity.link.claim_unaddressed", {
+    mode: input.mode ?? "unknown",
+    reason: "a `link <code>` line on an unaddressed wake — a claim must be addressed to the agent by the surface's own addressing form (an @mention, a DM, or a name-drop where the surface has neither)",
+  });
+}
+
+/**
+ * Claim a challenge as `claimant`. The single-use + TTL decision is the store's one CAS statement,
+ * so a second claimer, a replayed code and an expired code are all the same answer: null.
+ *
+ * 🔴 `claimant` MUST come from the WAKE'S OWN CAPTURED AUTHOR, never from the message that carried
+ * the code. That is the entire evidentiary content of a claim — the code proves the claimer saw the
+ * DM, the captured author proves WHICH account posted it. A caller that passed a self-declared id
+ * would turn this from proof-of-control into an honour system.
+ */
+export async function claimLinkChallenge(input: {
+  readonly org: string;
+  readonly code: string;
+  readonly claimant: LinkedAccount;
+  /** The raw CODE-BACK (code-2) this claim mints, when one is required and deliverable (OPE-617,
+   *  identity/link-flow.ts). Only its digest is stored, in the SAME CAS — so a claimed row either
+   *  carries its finalize requirement or was never claimed. */
+  readonly backCode?: string;
+  readonly now?: Date;
+}): Promise<LinkChallengeRow | null> {
+  const store = getOperationalStore();
+  const nowIso = (input.now ?? new Date()).toISOString();
+  const claimed = await store.claimLinkChallenge(
+    input.org,
+    hashLinkCode(input.code),
+    input.claimant.platform,
+    input.claimant.tenant,
+    input.claimant.nativeId,
+    nowIso,
+    input.backCode ? hashLinkCode(input.backCode) : undefined,
+  );
+  if (!claimed) return null;
+  await auditLink(input.org, input.claimant.platform, claimed.initiatingSurfaceKey, accountLabel(input.claimant.platform, input.claimant.tenant, input.claimant.nativeId), "identity.link.challenge_claimed", {
+    challengeId: claimed.id,
+    initiator: accountLabel(claimed.initiatingPlatform, claimed.initiatingTenant, claimed.initiatingNativeId),
+  });
+  return claimed;
+}
+
+/**
+ * The OPEN challenge this account ANSWERED, or undefined when it has none.
+ *
+ * ONE LIVE CODE PER PROOF-OF-CONTROL LOOP (Tommy, 2026-09-19). An answered challenge is a loop that
+ * is half finished: the account that answered still owes the initiator a step. A second code minted
+ * into that same conversation gives the person two live codes and two contradictory instructions,
+ * which is what the S-LINK-SLACK board leg read back on 2026-09-19 — so `link_identity` reads this
+ * before it starts anything (tools/link_identity.ts).
+ *
+ * 🔴 "ANSWERED" IS BOTH DOORS, WHICH IS WHY THIS IS NOT NAMED FOR THE CLAIM. The `claimed_*` triple
+ * is written by `claimLinkChallenge` (the CODE transport's claim) AND by `consentLinkChallenge` (the
+ * DIRECTORY transport's consent) — one column set, two acts, and the store contract says so. Read
+ * `transport` off the returned row before you put words in front of a person: a consenter never
+ * claimed anything.
+ *
+ * 🔴 THE TTL IS COMPARED HERE, NOT LEFT TO THE SWEEP. `expireLinkChallenges` is prune-on-write and
+ * this is a READ, so a row whose TTL has passed can still carry `status = "claimed"`. An expired
+ * answer blocks nothing: its code-back is already dead, and refusing on it would strand the person
+ * with no way to start again.
+ *
+ * 🔴 `account` MUST be the account of the turn that is asking, resolved from its own binding —
+ * never from tool input. The whole question is "is the person in front of me mid-loop", and an id
+ * the caller supplied would answer it about somebody else.
+ */
+export async function openChallengeAnsweredBy(input: {
+  readonly org: string;
+  readonly account: LinkedAccount;
+  readonly now?: Date;
+}): Promise<LinkChallengeRow | undefined> {
+  const store = getOperationalStore();
+  const nowMs = (input.now ?? new Date()).getTime();
+  const rows = await store.listLinkChallenges(input.org, {
+    status: "claimed",
+    claimedPlatform: input.account.platform,
+    claimedTenant: input.account.tenant,
+    claimedNativeId: input.account.nativeId,
+  });
+  return rows.find((r) => Date.parse(r.expiresAt) > nowMs);
+}
+
+/**
+ * One audit row when the claim NOTICE could not be delivered, so a person left waiting on a DM that never came is diagnosable. The claim itself still stands and the flow survives a dead notice.
+ * The row lands in the INITIATOR's partition, on their own surface key, and auditErrorDetail truncates and scrubs the provider's refusal text — untrusted text that can echo a token back.
+ */
+export async function auditLinkNoticeUndeliverable(input: { readonly org: string; readonly challenge: LinkChallengeRow; readonly error: unknown }): Promise<void> {
+  const c = input.challenge;
+  await auditLink(input.org, c.initiatingPlatform, c.initiatingSurfaceKey, accountLabel(c.initiatingPlatform, c.initiatingTenant, c.initiatingNativeId), "identity.link.notice_undeliverable", {
+    challengeId: c.id,
+    platform: c.initiatingPlatform,
+    ...auditErrorDetail(input.error),
+  });
+}
+
+/**
+ * A DENY. Terminal, and it writes NOTHING to the link tables — the point of the ratification step is
+ * that a copied code buys an attacker a question in somebody's DM and nothing else. Returns false
+ * when the challenge was not in one of `from` (already decided, expired, unknown).
+ *
+ * TWO PEOPLE MAY DENY, and `from` is which of them is calling (OPE-617). The INITIATOR denies a
+ * consent that already landed (`claimed`, the default). The TARGET of a directory request denies
+ * BEFORE consenting (`pending`) — "I do not recognise that person" is the answer this whole transport
+ * is built to make easy, and it has to be reachable from the side that was asked. Both write nothing,
+ * so neither needs a TTL conjunct.
+ */
+export async function denyLinkChallenge(input: {
+  readonly org: string;
+  readonly challengeId: string;
+  readonly from?: readonly LinkChallengeStatus[];
+  readonly now?: Date;
+}): Promise<boolean> {
+  const store = getOperationalStore();
+  const nowIso = (input.now ?? new Date()).toISOString();
+  const challenge = await store.getLinkChallenge(input.org, input.challengeId);
+  if (!challenge) return false;
+  const decided = await store.decideLinkChallenge(input.org, input.challengeId, input.from ?? ["claimed"], "denied", nowIso);
+  if (!decided) return false;
+  await auditLink(input.org, challenge.initiatingPlatform, challenge.initiatingSurfaceKey, accountLabel(challenge.initiatingPlatform, challenge.initiatingTenant, challenge.initiatingNativeId), "identity.link.denied", {
+    challengeId: challenge.id,
+    claimed: challenge.claimedPlatform && challenge.claimedNativeId ? accountLabel(challenge.claimedPlatform, challenge.claimedTenant, challenge.claimedNativeId) : undefined,
+  });
+  return true;
+}
+
+/**
+ * The initiator's CONFIRM — the one path that creates a confirmed link from a challenge.
+ *
+ * Order matters and is chosen to fail in the safe direction: the challenge is CAS'd to `ratified`
+ * FIRST, so a double-confirm loses the race and cannot produce two joins; only then is the link
+ * written. A crash between the two leaves a ratified challenge and no link — recoverable by
+ * re-running the flow, and strictly better than a link with no challenge to account for it.
+ *
+ * Both accounts are joined: the initiator's own id is confirmed into the set alongside the
+ * claimant's, because the DM that issued the challenge is itself proof of control of that account.
+ */
+export async function ratifyLinkChallenge(input: {
+  readonly org: string;
+  readonly challengeId: string;
+  /** Display handle for a set created by this ratification. DISPLAY ONLY (invariant 4). */
+  readonly handle: string;
+  readonly now?: Date;
+}): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const now = input.now ?? new Date();
+  const nowIso = now.toISOString();
+
+  const challenge = await store.getLinkChallenge(input.org, input.challengeId);
+  if (!challenge) return { ok: false, reason: "that link request no longer exists." };
+  if (challenge.status !== "claimed") {
+    return { ok: false, reason: `that link request is "${challenge.status}", not awaiting your confirmation — codes are single-use and expire.` };
+  }
+  if (!challenge.claimedPlatform || !challenge.claimedNativeId || challenge.claimedTenant === undefined) {
+    // Unreachable while the claim CAS stamps all three columns in the same statement it sets claimed; refused rather than assumed, because a half-claimed row is the one shape that could join an account nobody named.
+    // claimedTenant is the empty string, not absent, for a vendor-global platform, so this tests for undefined rather than falsiness.
+    return { ok: false, reason: "that link request has no recorded claimant — refusing to link." };
+  }
+  // BOTH ACCOUNTS COME OFF THE ROW, tenants included — never recomposed from the ratifying turn's
+  // binding. The challenge is the evidence, and re-deriving either half here would let a ratification
+  // from workspace B join an account the challenge never named.
+  const initiator: LinkedAccount = { platform: challenge.initiatingPlatform, tenant: challenge.initiatingTenant, nativeId: challenge.initiatingNativeId };
+  const claimed: LinkedAccount = { platform: challenge.claimedPlatform, tenant: challenge.claimedTenant, nativeId: challenge.claimedNativeId };
+  if (initiator.platform === claimed.platform && initiator.tenant === claimed.tenant && initiator.nativeId === claimed.nativeId) {
+    return { ok: false, reason: "that code was claimed by the SAME account that asked for it — post it from the other account." };
+  }
+
+  // Invariant 1, checked here so the refusal can NAME the conflict (the PK enforces it regardless).
+  const existingClaim = await store.getLinkedId(input.org, claimed.platform, claimed.tenant, claimed.nativeId);
+  const existingInitiator = await store.getLinkedId(input.org, initiator.platform, initiator.tenant, initiator.nativeId);
+  // 🔴 ADOPT THE INITIATOR'S SET ONLY WHEN THEY ARE A *CONFIRMED* MEMBER OF IT (audit finding F3).
+  // A `suggested` initiator row is a PROPOSAL the initiator never ratified — typically a directory
+  // sync that put their account into some other person's set. Adopting that set as the target would
+  // silently promote BOTH this challenge's accounts into a set the initiator never confirmed into,
+  // on the strength of an unrelated legitimate link. So a non-confirmed initiator row is NOT a
+  // target: this challenge builds/uses the initiator's OWN set (a fresh one below), and the stale
+  // proposal is dropped just before the join so joinConfirmed lands the initiator HERE rather than
+  // confirming the proposal in place (updateLinkedIdStatus keys on the account, not the set).
+  const initiatorConfirmed = existingInitiator?.status === "confirmed";
+  const targetSetId = initiatorConfirmed ? existingInitiator!.linkSetId : undefined;
+  if (existingClaim && existingClaim.linkSetId !== targetSetId) {
+    return { ok: false, reason: `${accountLabel(claimed.platform, claimed.tenant, claimed.nativeId)} already belongs to another person — an account is exactly one person. An admin must revoke that link-set first.` };
+  }
+  if (existingClaim && existingClaim.status === "revoked") {
+    return { ok: false, reason: `${accountLabel(claimed.platform, claimed.tenant, claimed.nativeId)} was revoked — that is terminal. An admin has to sort this out.` };
+  }
+  if (existingInitiator && existingInitiator.status === "revoked") {
+    return { ok: false, reason: "your own account is on a revoked link — that is terminal. An admin has to sort this out." };
+  }
+  if (targetSetId) {
+    const set = await store.getLinkSet(input.org, targetSetId);
+    if (set && set.status !== "active") return { ok: false, reason: `your link-set is ${set.status} — an admin has to reactivate it before it can grow.` };
+  }
+
+  // The single-use gate, again and terminally: a second confirm loses this CAS. The CAS ALSO
+  // carries the TTL conjunct (`expires_at > at`) for the `ratified` transition (audit finding F7):
+  // a claimed-but-EXPIRED challenge cannot be ratified even if the caller forgot to sweep first, so
+  // the TTL is a property of the statement — matching link-challenge.ts's "TTL enforced inside the
+  // statement" doctrine — not of a caller remembering to compare clocks.
+  if (!(await store.decideLinkChallenge(input.org, challenge.id, ["claimed"], "ratified", nowIso))) {
+    return { ok: false, reason: "that link request is no longer open — codes are single-use and expire." };
+  }
+
+  const evidence: LinkEvidence = { kind: "challenge", challengeId: challenge.id };
+  const linkSetId = targetSetId ?? randomUUID();
+  if (!targetSetId) {
+    await store.putLinkSet(input.org, { org: input.org, id: linkSetId, handle: input.handle, status: "active", createdAt: nowIso, updatedAt: nowIso });
+    // F3: when we did NOT adopt the initiator's set, the initiator may still hold a stale `suggested`
+    // row in some OTHER (proposed) set. joinConfirmed keys on the account (not the set), so without
+    // this it would CONFIRM that proposal in place — splitting the initiator into the foreign set and
+    // the claimed account into this new one. Drop the inert proposal so both accounts land HERE. A
+    // revoked initiator row was already refused above, so this only ever removes a `suggested` one.
+    if (existingInitiator && !initiatorConfirmed) {
+      await store.deleteLinkedId(input.org, initiator.platform, initiator.tenant, initiator.nativeId);
+    }
+  }
+  // The initiator's own account joins too — issuing the challenge from their DM IS control of it.
+  // `insertLinkedId` is DO NOTHING, so re-joining an id already in this set is a harmless no-op.
+  await joinConfirmed(input.org, linkSetId, initiator, evidence, nowIso);
+  await joinConfirmed(input.org, linkSetId, claimed, evidence, nowIso);
+
+  await auditLink(input.org, challenge.initiatingPlatform, challenge.initiatingSurfaceKey, accountLabel(initiator.platform, initiator.tenant, initiator.nativeId), "identity.link.confirmed", {
+    challengeId: challenge.id,
+    linkSetId,
+    linked: [accountLabel(initiator.platform, initiator.tenant, initiator.nativeId), accountLabel(claimed.platform, claimed.tenant, claimed.nativeId)],
+    evidence: evidenceLabel(evidence),
+    ...(await linkSetBlastRadius(input.org, linkSetId)),
+  });
+  return { ok: true, linkSetId, note: `linked ${accountLabel(claimed.platform, claimed.tenant, claimed.nativeId)} to ${accountLabel(initiator.platform, initiator.tenant, initiator.nativeId)}.` };
+}
+
+/** Insert-or-confirm one account into a set. Insert wins on a fresh account; on a row that already
+ *  belongs to THIS set (a `suggested` one from a directory sync, or a re-join) the CAS lifts it to
+ *  `confirmed` with the new evidence. `revoked` is never in the `from` list — invariant 3. */
+async function joinConfirmed(org: string, linkSetId: string, account: LinkedAccount, evidence: LinkEvidence, at: string): Promise<void> {
+  const store = getOperationalStore();
+  const row: LinkedIdRow = {
+    org,
+    linkSetId,
+    platform: account.platform,
+    tenant: account.tenant,
+    nativeId: account.nativeId,
+    status: "confirmed",
+    establishedBy: evidenceLabel(evidence),
+    evidenceJson: JSON.stringify(evidence),
+    createdAt: at,
+    updatedAt: at,
+  };
+  if (await store.insertLinkedId(org, row)) return;
+  await store.updateLinkedIdStatus(org, account.platform, account.tenant, account.nativeId, ["suggested", "confirmed"], "confirmed", row.establishedBy, row.evidenceJson, at);
+}
+
+/**
+ * Get-or-create the link-set a directory sync will hang a person's suggestions on (P2.3). The ONE
+ * place a set is created outside the challenge flow, and it lives here for the same reason
+ * everything else does: this module is the only writer over these tables.
+ *
+ * 🔴 READ-THEN-CREATE, NEVER UPSERT. `store.putLinkSet` is an upsert on (org, id) that would
+ * overwrite `status` — so calling it unconditionally would RESURRECT a suspended or revoked set
+ * on the next sync, quietly reversing an admin's offboarding. So an existing set is returned
+ * UNTOUCHED, whatever its status, and the caller decides (the planner refuses to widen into a set
+ * that is not `active`; invariant 3 keeps `revoked` terminal).
+ *
+ * CONCURRENCY: `linkSetId` is expected to be DETERMINISTIC in the caller (directory-sync.ts derives
+ * it from the provider + the IdP's user id), so two syncs racing here both compute the same id and
+ * write the same `active` row — the upsert makes the loser's write a no-op in content. A random id
+ * per run would instead produce two half-populated sets for one person, which is precisely the
+ * failure mode this contract exists to remove.
+ */
+export async function ensureLinkSet(input: {
+  readonly org: string;
+  readonly linkSetId: string;
+  /** Display handle for a set created here. DISPLAY ONLY (invariant 4) — never a lookup key. */
+  readonly handle: string;
+  readonly now?: Date;
+}): Promise<{ readonly set: LinkSetRow; readonly created: boolean }> {
+  const store = getOperationalStore();
+  const existing = await store.getLinkSet(input.org, input.linkSetId);
+  if (existing) return { set: existing, created: false };
+  const at = (input.now ?? new Date()).toISOString();
+  const set: LinkSetRow = { org: input.org, id: input.linkSetId, handle: input.handle, status: "active", createdAt: at, updatedAt: at };
+  await store.putLinkSet(input.org, set);
+  await auditLink(input.org, "directory", undefined, input.linkSetId, "identity.link.set_created", { linkSetId: input.linkSetId, handle: input.handle });
+  return { set, created: true };
+}
+
+/**
+ * Record a SUGGESTED account — a directory sync's proposal, which is NOT yet a link: `suggested`
+ * rows are invisible to `resolveLinkSet` and `expandLinkSet`, so nothing about attribution changes
+ * until a person confirms. It still takes the (org, platform, nativeId) PK, which is deliberate:
+ * a suggestion that collided with a proven link would be a bad merge waiting to be confirmed, so
+ * the collision is refused at suggestion time rather than at confirmation time.
+ */
+export async function suggestLinkedId(input: {
+  readonly org: string;
+  readonly linkSetId: string;
+  readonly account: LinkedAccount;
+  readonly evidence: LinkEvidence;
+  readonly now?: Date;
+}): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const at = (input.now ?? new Date()).toISOString();
+  const set = await store.getLinkSet(input.org, input.linkSetId);
+  if (!set) return { ok: false, reason: `no link-set "${input.linkSetId}".` };
+  if (set.status !== "active") return { ok: false, reason: `link-set "${input.linkSetId}" is ${set.status}.` };
+  const inserted = await store.insertLinkedId(input.org, {
+    org: input.org,
+    linkSetId: input.linkSetId,
+    platform: input.account.platform,
+    tenant: input.account.tenant,
+    nativeId: input.account.nativeId,
+    status: "suggested",
+    establishedBy: evidenceLabel(input.evidence),
+    evidenceJson: JSON.stringify(input.evidence),
+    createdAt: at,
+    updatedAt: at,
+  });
+  if (!inserted) return { ok: false, reason: `${accountLabel(input.account.platform, input.account.tenant, input.account.nativeId)} already belongs to a link-set.` };
+  await auditLink(input.org, input.account.platform, undefined, accountLabel(input.account.platform, input.account.tenant, input.account.nativeId), "identity.link.suggested", {
+    linkSetId: input.linkSetId,
+    evidence: evidenceLabel(input.evidence),
+  });
+  return { ok: true, linkSetId: input.linkSetId, note: `suggested ${accountLabel(input.account.platform, input.account.tenant, input.account.nativeId)}.` };
+}
+
+/**
+ * `suggested` → `confirmed`, and ONLY with evidence (invariant 2) — the entry point P2's one-tap
+ * DM confirmation uses. The evidence a caller passes must be the thing that actually convinced the
+ * system: a DM tap records the `challenge` it degenerately is, an EMU-grade auto-confirm records
+ * the `directory-sync` attestation. There is no evidence-free confirm, on purpose.
+ */
+export async function confirmLinkedId(input: {
+  readonly org: string;
+  readonly account: LinkedAccount;
+  readonly evidence: LinkEvidence;
+  readonly now?: Date;
+}): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const at = (input.now ?? new Date()).toISOString();
+  const row = await store.getLinkedId(input.org, input.account.platform, input.account.tenant, input.account.nativeId);
+  if (!row) return { ok: false, reason: `${accountLabel(input.account.platform, input.account.tenant, input.account.nativeId)} is not on any link-set.` };
+  if (row.status === "revoked") return { ok: false, reason: "that link was revoked — revocation is terminal." };
+  const set = await store.getLinkSet(input.org, row.linkSetId);
+  if (!set || set.status !== "active") return { ok: false, reason: `that link-set is ${set?.status ?? "missing"}.` };
+  const label = evidenceLabel(input.evidence);
+  if (!(await store.updateLinkedIdStatus(input.org, input.account.platform, input.account.tenant, input.account.nativeId, ["suggested", "confirmed"], "confirmed", label, JSON.stringify(input.evidence), at))) {
+    return { ok: false, reason: "that link could not be confirmed (it changed underneath this call)." };
+  }
+  await auditLink(input.org, input.account.platform, undefined, accountLabel(input.account.platform, input.account.tenant, input.account.nativeId), "identity.link.confirmed", {
+    linkSetId: row.linkSetId,
+    linked: [accountLabel(input.account.platform, input.account.tenant, input.account.nativeId)],
+    evidence: label,
+    ...(await linkSetBlastRadius(input.org, row.linkSetId)),
+  });
+  return { ok: true, linkSetId: row.linkSetId, note: `confirmed ${accountLabel(input.account.platform, input.account.tenant, input.account.nativeId)}.` };
+}
+
+/**
+ * Sever one account from `actor`'s OWN link-set — the person's unilateral off switch.
+ *
+ * THE RULE, stated because it is a choice and not an obvious one: a caller may remove ANY account
+ * from THEIR OWN set, not only the one they are speaking from. It is their set — every id in it is
+ * an account they proved control of — and the narrower rule ("your current account only") has a
+ * nasty failure: someone who loses access to their GitHub account could never remove it, which is
+ * precisely when they most want to. Removing an id from SOMEBODY ELSE'S set is refused; that is an
+ * admin act (`revoke_link_set`).
+ *
+ * A sever DELETES the row rather than tombstoning it, so the account is joinable again — unlink,
+ * then re-link, works. Admin REVOCATION tombstones instead, and that asymmetry is the point:
+ * offboarding must not leave an account quietly re-claimable.
+ *
+ * It also PURGES the severed account's own stored credentials (OPE-300 G3) — see the call site.
+ * Re-linking is unaffected; the person simply re-consents, which is the same thing they would do on
+ * a fresh account.
+ */
+export async function unlinkOwnId(input: {
+  readonly org: string;
+  readonly actor: LinkedAccount;
+  /** The account to remove; defaults to the actor's own. Must be in the actor's link-set. */
+  readonly target?: LinkedAccount;
+  readonly now?: Date;
+}): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const at = (input.now ?? new Date()).toISOString();
+  const target = input.target ?? input.actor;
+  const mine = await store.getLinkedId(input.org, input.actor.platform, input.actor.tenant, input.actor.nativeId);
+  if (!mine) return { ok: false, reason: "you have no linked accounts to unlink." };
+  if (mine.status === "revoked") return { ok: false, reason: "your link was revoked — revocation is terminal, and an admin has to sort it out." };
+  const row = input.target ? await store.getLinkedId(input.org, target.platform, target.tenant, target.nativeId) : mine;
+  if (!row || row.linkSetId !== mine.linkSetId) {
+    return { ok: false, reason: `${accountLabel(target.platform, target.tenant, target.nativeId)} is not on your link-set — you can only unlink your own accounts.` };
+  }
+  if (row.status === "revoked") return { ok: false, reason: "that link was revoked — revocation is terminal." };
+  // C.3 (membership IS consent): dropping the membership IS the severance of shared-vault reach — the
+  // next connector resolve reads no set (`callerLinkSets` → []) and keys the vault by the raw
+  // principal id again. There is no separate per-connector grant to purge (that machinery was removed
+  // when consent collapsed to link-level), so a re-join simply re-derives shared reach from the fresh
+  // confirmed membership — exactly the intended "adding/rejoining a DM must not prompt" behaviour.
+  if (!(await store.deleteLinkedId(input.org, target.platform, target.tenant, target.nativeId))) {
+    return { ok: false, reason: "that link had already gone." };
+  }
+  // (OPE-300 G3) DESTROY the removed account's own stored credentials. Dropping the membership
+  // sends this account back to keying the vault by its RAW subject — which is exactly where a
+  // pre-link token, or an Identity Center SSO token (never stored under any other key), is sitting.
+  // Without this, "unlink" would quietly hand the severed account back a credential it minted while
+  // it still had standing. Narrowing, self-initiated (the actor is unlinking their own account),
+  // and it costs the person only a re-consent. Fail-OPEN like every purge: a vault outage must not
+  // turn a completed unlink into an error, so the outcome is audited rather than thrown.
+  const targetSubject = accountVaultSubject(input.org, target);
+  const purge = targetSubject ? await purgeSubjectCredentials(targetSubject) : { purged: 0, failed: false };
+  await auditLink(input.org, input.actor.platform, undefined, accountLabel(input.actor.platform, input.actor.tenant, input.actor.nativeId), "identity.link.unlinked", {
+    linkSetId: row.linkSetId,
+    unlinked: accountLabel(target.platform, target.tenant, target.nativeId),
+    at,
+    credentialsPurged: purge.purged,
+    ...(purge.failed ? { purgeFailed: true } : {}),
+    // Counted AFTER the delete, so the row records what the set became — the reader's question on a
+    // sever is "how much is left", not "how much was there".
+    ...(await linkSetBlastRadius(input.org, row.linkSetId)),
+  });
+  return { ok: true, linkSetId: row.linkSetId, note: `unlinked ${accountLabel(target.platform, target.tenant, target.nativeId)}.` };
+}
+
+/**
+ * Suspend / reactivate a link-set — the reversible hold (P1.4, and P2's deprovision landing spot).
+ * A suspended set resolves to NOTHING (`resolveLinkSet` requires `active`), so attribution degrades
+ * to per-surface identity while it is held. `revoked` is not reachable from here — that is
+ * {@link revokeLinkSet}, and keeping the terminal act in its own function is what stops it being
+ * reached by passing a different string.
+ */
+export async function setLinkSetHold(input: {
+  readonly org: string;
+  readonly linkSetId: string;
+  readonly hold: "suspended" | "active";
+  readonly actor: string;
+  readonly now?: Date;
+}): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const at = (input.now ?? new Date()).toISOString();
+  const from: readonly LinkSetStatus[] = input.hold === "suspended" ? ["active"] : ["suspended"];
+  if (!(await store.updateLinkSetStatus(input.org, input.linkSetId, from, input.hold, at))) {
+    const set = await store.getLinkSet(input.org, input.linkSetId);
+    return { ok: false, reason: set ? `link-set "${input.linkSetId}" is ${set.status} — cannot ${input.hold === "suspended" ? "suspend" : "reactivate"} it.` : `no link-set "${input.linkSetId}".` };
+  }
+  await auditLink(input.org, "control", undefined, input.actor, input.hold === "suspended" ? "identity.link.suspended" : "identity.link.reactivated", { linkSetId: input.linkSetId });
+  return { ok: true, linkSetId: input.linkSetId, note: `link-set ${input.linkSetId} is now ${input.hold}.` };
+}
+
+/**
+ * REVOKE a link-set — TERMINAL, and the offboarding lever. Tombstones every id in the set (they
+ * keep their rows, so those accounts cannot be re-linked by a challenge), closes the set, and then
+ * PURGES the credentials the set's shared vault subject holds. There is deliberately no inverse: a
+ * mistake here is repaired by building a new set through the ordinary challenge flow with fresh
+ * accounts, not by un-revoking, because "this person no longer has standing" is exactly the
+ * statement that must not be quietly reversible.
+ *
+ * ORDER IS LOAD-BEARING: tombstone FIRST, purge SECOND. The tombstone is what severs reachability
+ * and it is the part that must be durable; the purge is best-effort on top (see below). Reversing
+ * them would open a window where the credentials are gone but the set still resolves — a person who
+ * is still standing with a connection that now silently fails.
+ */
+export async function revokeLinkSet(input: { readonly org: string; readonly linkSetId: string; readonly actor: string; readonly now?: Date }): Promise<LinkWriteResult> {
+  const store = getOperationalStore();
+  const at = (input.now ?? new Date()).toISOString();
+  if (!(await store.updateLinkSetStatus(input.org, input.linkSetId, ["active", "suspended"], "revoked", at))) {
+    const set = await store.getLinkSet(input.org, input.linkSetId);
+    return { ok: false, reason: set ? `link-set "${input.linkSetId}" is already revoked.` : `no link-set "${input.linkSetId}".` };
+  }
+  const tombstoned = await store.revokeLinkedIdsForSet(input.org, input.linkSetId, at);
+  // The tombstone above severs shared-vault reachability, but severance is not credential death: the terminal act also destroys the stored OAuth tokens — vendor-side revocation (RFC 7009), then the at-rest row.
+  // The sweep covers every tombstoned account's RAW subject as well as the shared one, and it reads the member rows AFTER the tombstone, which is safe because a tombstone flips a row's status and never deletes it.
+  const purge = await purgeLinkSetCredentialsBestEffort(input.org, input.linkSetId);
+  await auditLink(input.org, "control", undefined, input.actor, "identity.link.revoked", {
+    linkSetId: input.linkSetId,
+    tombstoned,
+    credentialsPurged: purge.purged,
+    ...(purge.failed ? { purgeFailed: true } : {}),
+  });
+  return {
+    ok: true,
+    linkSetId: input.linkSetId,
+    note:
+      `revoked link-set ${input.linkSetId} (${tombstoned} account(s) tombstoned, ${purge.purged} credential(s) purged)` +
+      (purge.failed ? " — the credential purge FAILED; the revoke stands, re-run purge_link_set_credentials." : "."),
+  };
+}
+
+/**
+ * Purge EVERY vault subject a link-set addresses — best effort, never throws. Shared by revokeLinkSet and the purge_link_set_credentials verb so the two can never drift into purging different rows for the same set.
+ * Both key spaces are swept: the set's shared subject and each account's own RAW subject, the only key an AWS Identity Center SSO token is ever stored under. Only the accounts ON THE SET are swept.
+ */
+async function purgeLinkSetCredentialsBestEffort(org: string, linkSetId: string): Promise<CredentialPurgeOutcome> {
+  // Fail-soft on the enumeration too: if listing the member rows fails we still purge the shared
+  // subject rather than skipping the purge entirely — same direction as every other edge here.
+  const rows = await getOperationalStore()
+    .listLinkedIds(org, linkSetId)
+    .catch(() => [] as readonly LinkedIdRow[]);
+  return purgeSubjectsCredentials([
+    sharedVaultSubject(org, linkSetId),
+    ...rows.map((r) => accountVaultSubject(org, r)).filter((sub): sub is string => sub !== undefined),
+  ]);
+}
+
+/**
+ * The STANDALONE credential purge for a link-set (OPE-287) — the repair lever behind the
+ * `purge_link_set_credentials` control verb, for sets revoked before the purge-on-revoke existed
+ * and for a suspected compromise where an admin wants the token dead without spending the terminal
+ * revoke.
+ *
+ * Deliberately reachable on a set in ANY status, not only `revoked`. A purge is unconditionally
+ * NARROWING — it destroys authority and grants none — and the alternative (revoked-only) would push
+ * an admin who suspects a compromised token into an irreversible offboarding just to kill it. The
+ * one thing it insists on is that the set EXISTS, so a typo'd id is a refusal rather than a
+ * cheerful "0 purged".
+ *
+ * Unlike the on-revoke path this one does NOT swallow a failure into a note: an admin who asked for
+ * a purge and got none must be told, so the write result is `ok: false` when the hook failed.
+ */
+export async function purgeLinkSetCredentials(input: { readonly org: string; readonly linkSetId: string; readonly actor: string }): Promise<LinkWriteResult & { readonly purged?: number }> {
+  const store = getOperationalStore();
+  const set = await store.getLinkSet(input.org, input.linkSetId);
+  if (!set) return { ok: false, reason: `no link-set "${input.linkSetId}".` };
+  const purge = await purgeLinkSetCredentialsBestEffort(input.org, input.linkSetId);
+  await auditLink(input.org, "control", undefined, input.actor, "identity.link.credentials_purged", {
+    linkSetId: input.linkSetId,
+    setStatus: set.status,
+    credentialsPurged: purge.purged,
+    ...(purge.failed ? { purgeFailed: true } : {}),
+  });
+  if (purge.failed) return { ok: false, reason: `credential purge for link-set "${input.linkSetId}" failed — nothing was destroyed; check the vault/adapter and retry.` };
+  return { ok: true, linkSetId: input.linkSetId, purged: purge.purged, note: `purged ${purge.purged} credential(s) for link-set ${input.linkSetId} (set is ${set.status}).` };
+}
+
+/**
+ * Stamps two numbers a reader cannot reconstruct later onto a membership-change audit row: how many CONFIRMED accounts the set held at the moment of the change, and whether connectors.linkSetVault was armed — the flag that decides whether the same action was an attribution merge or a credential grant.
+ * Best-effort: a store failure yields memberCount -1, an explicitly impossible value, because a silent 0 would read as an empty set.
+ */
+async function linkSetBlastRadius(org: string, linkSetId: string): Promise<{ memberCount: number; vaultArmed: boolean }> {
+  const vaultArmed = directoryLinkSetVaultArmed();
+  try {
+    return { memberCount: (await expandLinkSet(org, linkSetId)).length, vaultArmed };
+  } catch {
+    return { memberCount: -1, vaultArmed };
+  }
+}
+
+/** One audit append for a link mutation. `surfaceKey` is `platform/workspace/surface`; when a
+ *  mutation has no surface (a control-plane act, a directory sync) the workspace reads as the
+ *  platform token, matching how the control-plane writes already stamp `platform:"control"`. */
+async function auditLink(org: string, platform: string, surfaceKey: string | undefined, principalId: string, action: string, detail: Record<string, unknown>): Promise<void> {
+  const parts = surfaceKey?.split("/") ?? [];
+  await appendAudit({
+    org,
+    platform,
+    workspace: parts[1] ?? platform,
+    ...(surfaceKey ? { surface: surfaceKey } : {}),
+    principalId,
+    action,
+    detail,
+  });
+}