@open-everywhere/core 0.1.0

package/agent/identity/groups.ts

@@ -0,0 +1,174 @@
+// Person-groups: a named set of humans bound to a bundle at group scope, resolving ONLY in each member's own DM universe. A group grants people, never rooms.
+// Groups are access-bearing, so membership lives in a reviewed diff and never in the database, and a linkSet member expands only to that person's CONFIRMED accounts.
+
+import { isQualifiedPrincipalKey } from "./principal-key.js";
+import { tenantRungRemedy } from "../access/tenant-admission.js";
+
+/** A member that names a HUMAN by their link-set, rather than one of their accounts. Expanded to
+ *  every CONFIRMED (platform, nativeId) on that set at resolve time. */
+export interface GroupLinkSetMember {
+  readonly linkSet: string;
+}
+
+/**
+ * One member of a group: either a qualified principal key (`"slack/U0EXOWNER"` — the no-DB floor)
+ * or a link-set reference (`{ linkSet: "…" }`). The discriminant is the SHAPE — a string is an
+ * account, an object is a person — so neither form can be mistaken for the other by a reader or by
+ * a `typeof` test.
+ */
+export type GroupMember = string | GroupLinkSetMember;
+
+export interface Group {
+  /**
+   * Stable id, referenced by `Scope.group` on every binding that grants this group anything.
+   *
+   * ⚠️ IMMUTABLE ONCE REFERENCED. Renaming it orphans every binding naming it — the merged
+   * config-load assert (`assertBindingsValid` with the group registry) catches the ones in this
+   * repo and fails LOUD, but it is still an identifier, not a label: change {@link Group.title}
+   * for anything a human reads.
+   */
+  readonly name: string;
+  /** Optional human-facing display label. Cosmetic only — no binding, resolver rule, lint or audit
+   *  record reads it. Absent → `name`. The IdP-group overlay puts the verbatim directory group
+   *  name here, since the `name` carries a namespace prefix. */
+  readonly title?: string;
+  /** The humans in this group. Non-empty — an empty group is dead config that grants nothing. */
+  readonly members: readonly GroupMember[];
+}
+
+/** Identity-with-types helper (Eve's define* convention; returns unchanged). */
+export function defineGroup(group: Group): Group {
+  return group;
+}
+
+/** Is this member the link-set (one HUMAN) form rather than the principal-key (one ACCOUNT) form? */
+export function isLinkSetMember(member: GroupMember): member is GroupLinkSetMember {
+  return typeof member !== "string";
+}
+
+/** Every link-set id this group references — what the caller's edge expands (access/group-request.ts)
+ *  and what the broad-grant lint counts as unbounded-by-review membership. */
+export function groupLinkSets(group: Group): readonly string[] {
+  return group.members.filter(isLinkSetMember).map((m) => m.linkSet);
+}
+
+/** Every principal key this group names DIRECTLY (the pure, no-DB half of its membership). */
+export function groupPrincipalKeys(group: Group): readonly string[] {
+  return group.members.filter((m): m is string => typeof m === "string");
+}
+
+/**
+ * The reserved prefix for groups written by the IdP-group codemod (`directory:<okta-group-name>`).
+ *
+ * It exists so a synced group can NEVER collide with a hand-written one: hand-written groups are
+ * refused this prefix ({@link assertReservedGroupNamespace}) and overlay groups are required to
+ * carry it (identity/groups-codemod.ts), so the two name spaces are disjoint by construction rather
+ * than by everybody remembering. The same trick as the grants overlay's `grants:` bundle names.
+ */
+export const DIRECTORY_GROUP_PREFIX = "directory:";
+
+/** The namespaced group name for one verbatim IdP group. The verbatim name rides through unchanged
+ *  (IdP group names carry spaces, slashes and punctuation, and mangling them would make the plan
+ *  unreadable against the IdP's own console). */
+export function directoryGroupName(idpGroup: string): string {
+  return `${DIRECTORY_GROUP_PREFIX}${idpGroup}`;
+}
+
+/** Is this a machine-owned, directory-synced group name? */
+export function isDirectoryGroupName(name: string): boolean {
+  return name.startsWith(DIRECTORY_GROUP_PREFIX);
+}
+
+/**
+ * Validates the group registry at config load and throws with EVERY problem listed: a silent misconfiguration on an access-bearing registry IS the security bug.
+ * Overlapping membership is deliberately not an error. A person may be in as many groups as they like, and the resolver unions the grants.
+ */
+export function assertGroupsValid(groups: readonly Group[]): void {
+  const bad: string[] = [];
+  const seen = new Set<string>();
+  for (const [index, g] of groups.entries()) {
+    const where = g.name && g.name.trim().length > 0 ? `group "${g.name}"` : `group (entry #${index})`;
+    if (!g.name || g.name.trim().length === 0) {
+      bad.push(`  ${where} has an empty name — a group's name is the id every binding references`);
+    } else if (seen.has(g.name)) {
+      bad.push(`  group name "${g.name}" is defined more than once (bindings reference groups by name — names must be unique)`);
+    } else {
+      seen.add(g.name);
+    }
+    const members = g.members ?? [];
+    if (members.length === 0) {
+      bad.push(`  ${where} has no members — an empty group grants nothing; list its people or drop the group`);
+    }
+    const seenMembers = new Set<string>();
+    for (const m of members) {
+      if (typeof m === "string") {
+        if (!isQualifiedPrincipalKey(m)) {
+          bad.push(
+            `  ${where} member "${m}" must be the qualified principal key "platform/<principal-id>" — or, on a tenant-scoped platform, "platform/<tenant-id>/<principal-id>" (e.g. "slack/T0AB1CD2E/U0123ABC", "discord/300000000000000104"). A BARE member id has no platform namespace and will NEVER match; on Slack a key without its workspace has no tenant namespace and will never match either (identity/principal-key.ts).${tenantRungRemedy(m)} To name a whole HUMAN across their platforms, use { linkSet: "<id>" } instead.`,
+          );
+        }
+        if (seenMembers.has(`key\u0000${m}`)) bad.push(`  ${where} lists member "${m}" more than once — remove the duplicate`);
+        seenMembers.add(`key\u0000${m}`);
+        continue;
+      }
+      if (typeof m?.linkSet !== "string" || m.linkSet.trim().length === 0) {
+        bad.push(`  ${where} has a link-set member with an empty \`linkSet\` id — name the link-set, or use a qualified principal key`);
+        continue;
+      }
+      if (seenMembers.has(`set\u0000${m.linkSet}`)) bad.push(`  ${where} lists link-set "${m.linkSet}" more than once — remove the duplicate`);
+      seenMembers.add(`set\u0000${m.linkSet}`);
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      "open-everywhere: invalid person-group(s):\n" + bad.join("\n") + "\n(identity/groups.ts assertGroupsValid / docs/how-it-works/access-and-scoping.md).",
+    );
+  }
+}
+
+/**
+ * Refuse a HAND-WRITTEN group in the machine-owned namespace. Called by the app tier on the
+ * code-declared list only (never on the merged one, which is where the overlay's own
+ * `directory:`-prefixed groups legitimately live).
+ *
+ * This is what makes {@link DIRECTORY_GROUP_PREFIX} a real partition rather than a convention: a
+ * hand-written `directory:Engineering` could otherwise be silently replaced — or duplicated — by the
+ * next sync plan, and the diff a human merged would stop meaning what they approved.
+ */
+export function assertReservedGroupNamespace(groups: readonly Group[]): void {
+  const bad = groups
+    .filter((g) => isDirectoryGroupName(g.name))
+    .map(
+      (g) =>
+        `  group "${g.name}" uses the reserved "${DIRECTORY_GROUP_PREFIX}" namespace — that prefix belongs to the machine-owned IdP-group overlay (agent/identity/groups.generated.ts), which the directory codemod rewrites. Rename this group.`,
+    );
+  if (bad.length > 0) {
+    throw new Error(
+      "open-everywhere: hand-written person-group(s) in the machine-owned namespace:\n" + bad.join("\n") + "\n(identity/groups.ts assertReservedGroupNamespace).",
+    );
+  }
+}
+
+/**
+ * Pure and fail-closed: no principal key means no groups, never all groups, and the link-set half is a database fact read at the caller's edge so access resolution never depends on store availability.
+ * The result is sorted and de-duplicated, so it is stable in previews and audit records.
+ */
+export function groupsForPrincipal(
+  groups: readonly Group[],
+  callerKey: string | undefined,
+  linkSetIds: readonly string[] = [],
+): readonly string[] {
+  if (!callerKey) return [];
+  const sets = new Set(linkSetIds);
+  const out = new Set<string>();
+  for (const g of groups) {
+    for (const m of g.members ?? []) {
+      const hit = typeof m === "string" ? m === callerKey : sets.has(m.linkSet);
+      if (hit) {
+        out.add(g.name);
+        break;
+      }
+    }
+  }
+  return [...out].sort();
+}

package/agent/identity/link-challenge.ts

@@ -0,0 +1,147 @@
+// Pure, leaf primitives for the proof-of-control half of identity linking: how a link code is minted, how it is stored, and how a message is recognised as claiming one.
+// The code is the only secret in the flow and is never at rest: the row keeps a digest, so a copy of the operational store yields no usable codes.
+
+import { createHash, randomInt } from "node:crypto";
+
+/**
+ * The code alphabet: upper-case letters and digits with one member of every confusable pair
+ * removed — no `0`, `1`, `I`, `O` or `B`, and no lower case at all. 31 symbols.
+ */
+export const LINK_CODE_ALPHABET = "23456789ACDEFGHJKLMNPQRSTUVWXYZ";
+
+/** Code length. 8 symbols over a 31-symbol alphabet is ~39 bits — far beyond guessable inside a
+ *  10-minute, single-use, ratification-gated window, and still one short line to type. */
+export const LINK_CODE_LENGTH = 8;
+
+/** How long a challenge stays claimable. Long enough to switch devices and post on another
+ *  platform, short enough that a code seen over someone's shoulder is worthless by the time it
+ *  could be used. The TTL is enforced INSIDE the claim statement (a `expires_at > at` conjunct in
+ *  the same CAS), never by a caller remembering to compare clocks. */
+export const LINK_CHALLENGE_TTL_MS = 10 * 60_000;
+
+/**
+ * Mint one code. Uses `crypto.randomInt` — a CSPRNG with rejection sampling, so the distribution
+ * over the alphabet is uniform and there is no modulo bias. NEVER `Math.random`: this is a bearer
+ * token, and a predictable one hands a stranger somebody else's link-set.
+ */
+export function mintLinkCode(): string {
+  let out = "";
+  for (let i = 0; i < LINK_CODE_LENGTH; i++) out += LINK_CODE_ALPHABET[randomInt(LINK_CODE_ALPHABET.length)];
+  return out;
+}
+
+/**
+ * The at-rest form of a code: sha-256 (hex) of its UPPERCASED text. Uppercasing here (rather than
+ * at each caller) is what makes the claim case-insensitive without the store holding two spellings
+ * — a person typing `link ab3k…` in a GitHub comment must match a code shown as `AB3K…`.
+ *
+ * A plain unsalted digest is correct here and a KDF would not be: the pre-image is a fresh
+ * 39-bit CSPRNG value with a 10-minute life and single-use semantics, not a human-chosen secret,
+ * so there is no dictionary to slow down — and a per-row salt would break the by-hash lookup the
+ * claim path is built on (the claimer's message carries the code, never the row id).
+ */
+export function hashLinkCode(code: string): string {
+  return createHash("sha256").update(code.trim().toUpperCase(), "utf8").digest("hex");
+}
+
+/**
+ * WHOLE-MESSAGE anchored on purpose (audit finding F1): a mid-string match let a code planted in someone else's backscroll line be claimed by whoever woke the agent next.
+ * The code and the claimant must come from ONE message, so a code embedded in a larger blob, such as a rendered envelope or another person's message, is not a claim.
+ */
+const CLAIM_RE = new RegExp(String.raw`^link[\s:]+([${LINK_CODE_ALPHABET}]{${LINK_CODE_LENGTH}})$`, "i");
+
+// A MODEL projection may retain a human-authored claim because message.received needs that exact
+// body to spend code-1. Machine-authored history is different: it can contain either the host's
+// `link CODE` instruction (code-1) or code-2 on an indented line of its own. Those values must not
+// come back through backscroll or a read verb after the host privately delivered them.
+const MACHINE_LINK_CLAIM_RE = new RegExp(String.raw`\blink([\s:]+)[${LINK_CODE_ALPHABET}]{${LINK_CODE_LENGTH}}\b`, "gi");
+const MACHINE_LINK_CODE_LINE_RE = new RegExp(
+  String.raw`(^|\n)([ \t]*)[${LINK_CODE_ALPHABET}]{${LINK_CODE_LENGTH}}(?=[ \t]*(?:\n|$))`,
+  "gi",
+);
+const PRIVATE_LINK_CODE_MARKER = "[private identity-link code omitted]";
+
+/**
+ * Remove live identity-link bearer codes from a MACHINE-authored string before a model sees it.
+ * Callers decide authorship from host-captured structure; this function never guesses it from text.
+ * Human claim bodies deliberately do not pass through here, so the pre-model claim hook keeps the
+ * exact `link CODE` bytes it must compare-and-swap.
+ */
+export function redactMachineLinkCodes(text: string): string {
+  return text
+    .replace(MACHINE_LINK_CLAIM_RE, (_whole: string, separator: string) => `link${separator}${PRIVATE_LINK_CODE_MARKER}`)
+    .replace(MACHINE_LINK_CODE_LINE_RE, (_whole: string, start: string, indent: string) => `${start}${indent}${PRIVATE_LINK_CODE_MARKER}`);
+}
+
+/**
+ * The code is the only thing taken from content. Which account claimed it, and on which platform, comes from the wake's own captured author and never from the message.
+ * The input must be ONE message body, the trigger's own, never a rendered envelope.
+ */
+export function detectLinkClaim(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  const m = CLAIM_RE.exec(text.trim());
+  return m ? m[1]!.toUpperCase() : undefined;
+}
+
+/**
+ * Call this ONLY when the surface itself classified the wake as addressed (an authoritative, host-set signal, never text-sniffing) and only over the trigger's own body. An ambient wake must use the strict detectLinkClaim, which is what keeps the F1 backscroll attack refused.
+ * It strips at most one leading address token, then requires the remainder to be exactly the claim.
+ */
+export function detectAddressedLinkClaim(text: string | undefined, addressTokens: readonly string[] = []): string | undefined {
+  if (!text) return undefined;
+  const trimmed = text.trim();
+  // A bare whole-message claim (an addressed DM / @mention that eve already stripped) always counts.
+  const bare = detectLinkClaim(trimmed);
+  if (bare) return bare;
+  const rest = stripLeadingAddress(trimmed, addressTokens);
+  return rest === undefined ? undefined : detectLinkClaim(rest);
+}
+
+/** Separators that may sit between a leading address token and the `link …` that follows it. */
+const ADDRESS_SEP = String.raw`[\s,:]+`;
+
+/**
+ * Strip a SINGLE leading address token — an @mention (`<@U…>`/`<@!…>`/`<@&…>` or a bare `@handle`),
+ * or one of the deployment's name tokens (word-boundary, whitespace-elastic, case-insensitive) —
+ * followed by at least one separator. Returns the remainder, or undefined when the body does not
+ * begin with a recognised address. Only the FIRST token is stripped (a claim is `address? link code`,
+ * never `address address … link`), keeping the operative content tight.
+ */
+function stripLeadingAddress(text: string, addressTokens: readonly string[]): string | undefined {
+  const mention = new RegExp(String.raw`^(?:<@[!&]?[^>\s]+>|@[\p{L}\p{N}][\p{L}\p{N}_.-]*)${ADDRESS_SEP}`, "u");
+  const m = mention.exec(text);
+  if (m) return text.slice(m[0].length);
+  for (const tok of addressTokens) {
+    const t = tok.trim();
+    if (t.length < 2) continue; // mirror agentNameTokens' min-length guard
+    const escaped = t.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&").replace(/\s+/gu, "\\s*");
+    const re = new RegExp(String.raw`^${escaped}(?=$|[^\p{L}\p{N}_])${ADDRESS_SEP}`, "iu");
+    const mm = re.exec(text);
+    if (mm) return text.slice(mm[0].length);
+  }
+  return undefined;
+}
+
+/** The instructions a person is given after `link_identity` mints them a code. Core-owned
+ *  TRUSTED text (no interpolation but the code itself, which this module minted).
+ *
+ *  🔴 IT SAYS "DM ME WHERE YOU CAN" BECAUSE THE CLAIM PATH NOW REQUIRES IT (OPE-617). On a platform
+ *  this deployment can DM, a claim made in a room is REFUSED — a code is a secret for as long as it
+ *  lasts. On every platform with no DM arm a comment addressed to the agent is still the way, and
+ *  stays so. The copy states both rather than one, because a person reading it does not know which
+ *  kind of platform they are about to use — and it names NO platform, because which ones can be DM'd
+ *  is a registry fact that changes when a provider ships an arm (today only Slack ships one). */
+export function linkClaimInstructions(code: string, ttlMinutes: number): string {
+  return (
+    `From your OTHER account, send me this line — on its own in a DM, or with my @mention (or my ` +
+    `name) in front of it anywhere else:\n\n    link ${code}\n\n` +
+    `Nothing else in the message either way. DM it to me if that account can DM me — a code is a ` +
+    `secret, so I only take it in a one-to-one conversation where I have one. Where I have no DMs at ` +
+    `all, @mention me or name-drop me in a comment instead; a bare, unaddressed line will not count. ` +
+    `If you send it somewhere I cannot accept it, I will say so and the code stays good.\n\n` +
+    `It is single-use and expires in ${ttlMinutes} minutes. When it lands I will answer that account ` +
+    `with a SECOND code and come back HERE naming the account that claimed the first one. Give me the ` +
+    `second code in this conversation to finish — that is what proves one person reads both. If a ` +
+    `name you do not recognise comes back, deny it.`
+  );
+}

package/agent/identity/link-consent.ts

@@ -0,0 +1,216 @@
+// The consent step of the directory link transport: it records the named account's consent, mints the code-back when the deployment arms one, and tells the initiator. It never writes a link.
+// A challenge id is not a bearer token: holding one lets you name a request, never answer one, because the lookup and the consent CAS are both conjunct on BEING the named account.
+
+import { appendAudit } from "../audit/audit.js";
+import { canDeliverDirectMessage, dispatchDirectMessage, type DirectMessageAction } from "../channels/post-arms.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { humanAccountLabel } from "./account-display-name.js";
+import { mintLinkCode } from "./link-challenge.js";
+import { asLinkTransport, codeBackDecision, linkConsentButtonLabels, linkConsentClickAnswers } from "./link-flow.js";
+import { consentLinkChallenge, denyLinkChallenge, type LinkChallengeRow } from "./link-store.js";
+import { getSettings } from "../settings/settings.js";
+
+/** The account answering a consent request, as the three columns every write is conjunct on. */
+export interface ConsentingAccount {
+  readonly platform: string;
+  readonly tenant: string;
+  readonly nativeId: string;
+}
+
+/**
+ * Record the named account's CONSENT — the commit half, shared by the typed door
+ * (tools/confirm_link.ts) and the button door ({@link resolveLinkConsentClick}).
+ *
+ * Returns the raw code-back when one was minted. 🔴 THE RAW CODE EXISTS ONLY IN THIS RETURN VALUE —
+ * the row keeps a digest and nothing else — so the CALLER must put it in front of the person in the
+ * same breath. A caller that drops it makes the request unfinishable until its TTL expires. That is
+ * fail-CLOSED and recoverable in one challenge TTL, which is the right direction; the alternative is
+ * storing a spendable secret so it can be re-shown.
+ *
+ * Throws when the CAS finds no row — the request was already answered, or it expired.
+ */
+export async function commitLinkConsent(input: {
+  readonly org: string;
+  readonly challenge: LinkChallengeRow;
+  readonly consenter: ConsentingAccount;
+  /** Can this caller put a raw code in front of the person right now? The typed door always can
+   *  through a host-owned post into the verified DM; the button door can through its private
+   *  interaction answer. A caller that CANNOT must pass false, so `codeBackDecision` records an
+   *  undeliverable code-back instead of minting one nobody will ever see. */
+  readonly deliverable: boolean;
+}): Promise<{ readonly codeBack?: string }> {
+  const c = input.challenge;
+  const decision = codeBackDecision({
+    transport: asLinkTransport(c.transport),
+    knobArmed: getSettings().identityLinking.codeBack,
+    deliverable: input.deliverable,
+  });
+  const backCode = decision.mint ? mintLinkCode() : undefined;
+  const consented = await consentLinkChallenge({
+    org: input.org,
+    challengeId: c.id,
+    consenter: input.consenter,
+    ...(backCode ? { backCode } : {}),
+  });
+  if (!consented) throw new Error("that request is no longer open — it was already answered, or it expired. Ask them to start it again.");
+
+  // Tell the INITIATOR their request was answered. Best-effort: they find the same fact on their next
+  // confirm_link turn (the peek names this consent), so an undeliverable notice costs a prompt and
+  // never the flow. PLAIN TEXT, and it never carries the code — the point of the code is that the
+  // initiator reads it off THIS side.
+  if (canDeliverDirectMessage(c.initiatingPlatform)) {
+    const consenterName = await humanAccountLabel(input.consenter.platform, input.consenter.nativeId, input.consenter.tenant);
+    await dispatchDirectMessage(c.initiatingPlatform, {
+      principalId: c.initiatingNativeId,
+      text:
+        `${consenterName} agreed to the link you asked for.\n\n` +
+        (backCode
+          ? `Ask them for the code I gave them and tell me here to finish it. Nothing is linked until you do.`
+          : `Tell me here to finish it. Nothing is linked until you do.`),
+    }).catch((err: unknown) => console.log(`[open-everywhere:identity] consent notice for ${c.id} could not be delivered: ${String(err)}`));
+  }
+
+  return backCode ? { codeBack: backCode } : {};
+}
+
+/** Every consent-button id this feature owns starts with this. A surface's interaction router
+ *  classifies "ours vs. somebody else's" on exactly this prefix, so it must not collide with the
+ *  approval plane's or with eve's own — see the Discord front route. */
+export const LINK_CONSENT_CLICK_PREFIX = "oe-link:";
+
+/** What a tap MEANS. A closed set: the id is parsed, never interpreted. */
+export type LinkConsentVerdict = "confirm" | "deny";
+
+/**
+ * The verdict rides LAST so the parse peels it off the end: a challenge id is our own store key and may contain a colon, which a front-splitting grammar would mis-read.
+ * The cap is Discord's 100-character component limit, so linkConsentClickId refuses a longer id rather than emitting one the platform silently rejects at post time.
+ */
+const LINK_CONSENT_CLICK_ID_MAX = 100;
+
+export function linkConsentClickId(challengeId: string, verdict: LinkConsentVerdict): string {
+  const id = `${LINK_CONSENT_CLICK_PREFIX}${challengeId}:${verdict}`;
+  if (id.length > LINK_CONSENT_CLICK_ID_MAX) {
+    throw new Error(`link consent button id is ${id.length} characters and the cap is ${LINK_CONSENT_CLICK_ID_MAX}`);
+  }
+  return id;
+}
+
+/** Parse one consent-button id, or undefined when it is not one of ours / not well-formed. PURE. */
+export function parseLinkConsentClickId(raw: string | undefined): { readonly challengeId: string; readonly verdict: LinkConsentVerdict } | undefined {
+  if (typeof raw !== "string" || !raw.startsWith(LINK_CONSENT_CLICK_PREFIX)) return undefined;
+  const body = raw.slice(LINK_CONSENT_CLICK_PREFIX.length);
+  const cut = body.lastIndexOf(":");
+  if (cut <= 0) return undefined;
+  const challengeId = body.slice(0, cut);
+  const verdict = body.slice(cut + 1);
+  if (challengeId.length === 0) return undefined;
+  if (verdict !== "confirm" && verdict !== "deny") return undefined;
+  return { challengeId, verdict };
+}
+
+/**
+ * The two buttons a consent ask carries. CORE-OWNED COPY — no interpolation at all, so no
+ * attacker-chosen string can ever reach a button label. The ask's TEXT already names the initiator
+ * and attributes their self-set name as a claim (identity/link-flow.ts `linkConsentAsk`); the
+ * buttons only say what the two answers are.
+ *
+ * Returns an empty list when the id would not fit the wire cap, so an unusually long challenge id
+ * degrades to a text-only ask rather than failing the whole consent DM.
+ */
+export function linkConsentActions(challengeId: string): readonly DirectMessageAction[] {
+  const labels = linkConsentButtonLabels();
+  try {
+    return [
+      { id: linkConsentClickId(challengeId, "confirm"), label: labels.confirm, intent: "affirm" },
+      { id: linkConsentClickId(challengeId, "deny"), label: labels.deny, intent: "reject" },
+    ];
+  } catch {
+    return [];
+  }
+}
+
+/** The audit action a consent-button click writes. One greppable string, shared with its test. */
+export const LINK_CONSENT_CLICK_ACTION = "identity.link.consent_click";
+
+/** What a click resolved to, as the private answer the surface shows the person who tapped. */
+export interface LinkConsentClickResult {
+  readonly outcome: "consented" | "denied" | "not-yours" | "gone";
+  /** The message to show ONLY the clicker. Plain text — the direct-post path has no formatter. */
+  readonly text: string;
+}
+
+/**
+ * Resolve one consent-button tap end-to-end. NEVER THROWS — an interaction endpoint has seconds to
+ * answer, and a throw there is an error the person cannot act on. Every failure resolves to an
+ * honest `outcome` plus copy that says what did or did not happen.
+ *
+ * 🔴 `clicker` MUST come from the surface's own verified interaction envelope, never from the click
+ * payload's body fields. On Discord that is `interaction.user.id` under the Ed25519 signature check
+ * the front route already performs. This function cannot tell the difference, so the contract is
+ * stated here and pinned by the provider's own test.
+ */
+export async function resolveLinkConsentClick(input: {
+  readonly org: string;
+  readonly challengeId: string;
+  readonly verdict: LinkConsentVerdict;
+  readonly clicker: ConsentingAccount;
+}): Promise<LinkConsentClickResult> {
+  const answers = linkConsentClickAnswers();
+  try {
+    const store = getOperationalStore();
+    // Sweep first, so an expired request is `expired` before a late tap can answer it. The TTL is a
+    // bound on the whole flow, not just on the ask.
+    await store.expireLinkChallenges(input.org, new Date().toISOString());
+    // 🔴 THE STANDING IS THE FILTER. Narrowed to the CLICKER's own account triple and to `pending`,
+    // so a challenge aimed at anybody else is not in this list at all — "you may only answer your
+    // own" is a property of the lookup, not of a check below it.
+    const pending = await store.listLinkChallenges(input.org, {
+      targetPlatform: input.clicker.platform,
+      targetTenant: input.clicker.tenant,
+      targetNativeId: input.clicker.nativeId,
+      status: "pending",
+    });
+    const challenge = pending.find((c) => c.id === input.challengeId);
+    if (!challenge) {
+      // Deliberately ONE answer for two cases: the request is not this person's, and the request is
+      // gone. Splitting them would turn the button into an oracle that confirms a challenge id
+      // belongs to somebody, which is the one thing a stranger holding an id could learn.
+      await noteClick(input, "not-yours");
+      return { outcome: "not-yours", text: answers.notYours };
+    }
+
+    if (input.verdict === "deny") {
+      // From `pending`, not `claimed`: this side answers BEFORE any consent exists. Writes nothing,
+      // and it is terminal — the initiator cannot re-ask on the same request.
+      const denied = await denyLinkChallenge({ org: input.org, challengeId: challenge.id, from: ["pending"] });
+      await noteClick(input, denied ? "denied" : "gone");
+      return denied ? { outcome: "denied", text: answers.denied } : { outcome: "gone", text: answers.gone };
+    }
+
+    // `deliverable: true` — the code-back, when the deployment arms one, rides this call's own
+    // private answer back to the person who tapped, just as the typed door host-posts it into the
+    // verified DM without returning it to the model.
+    const { codeBack } = await commitLinkConsent({ org: input.org, challenge, consenter: input.clicker, deliverable: true });
+    await noteClick(input, "consented");
+    return { outcome: "consented", text: codeBack ? answers.consentedWithCode(codeBack) : answers.consented };
+  } catch (err) {
+    console.log(`[open-everywhere:identity] consent click for ${input.challengeId} did not resolve: ${String(err)}`);
+    return { outcome: "gone", text: answers.gone };
+  }
+}
+
+/** One audit row per tap — ids and the outcome only, never a code and never a profile name.
+ *  Best-effort: a click must not fail because a row could not be written. */
+async function noteClick(input: { readonly org: string; readonly challengeId: string; readonly verdict: LinkConsentVerdict; readonly clicker: ConsentingAccount }, outcome: string): Promise<void> {
+  try {
+    await appendAudit({
+      org: input.org,
+      platform: input.clicker.platform,
+      workspace: input.clicker.tenant || "unknown",
+      action: LINK_CONSENT_CLICK_ACTION,
+      detail: { challengeId: input.challengeId, verdict: input.verdict, outcome, clicker: input.clicker.nativeId },
+    });
+  } catch (err) {
+    console.warn(`[open-everywhere:audit] ${LINK_CONSENT_CLICK_ACTION} row was not written: ${String(err)}`);
+  }
+}