@open-everywhere/core 0.1.0

package/dist/agent/identity/directory-sync.js

@@ -0,0 +1,623 @@
+// Directory sync: the pure diff between what the IdP says and what the link tables hold, plus the runner that applies it.
+// Widening lands as a suggested row that waits for the person's own DM confirmation, a deprovision suspends eagerly, and nothing here ever unlinks or revokes an account because the directory stayed silent.
+import { createHash } from "node:crypto";
+import { appendAudit, readAudit } from "../audit/audit.js";
+import { directoryProvider } from "./directory.js";
+import { ensureLinkSet, confirmLinkedId, listLinkSetsWithIds, setLinkSetHold, suggestLinkedId } from "./link-store.js";
+import { isTenantScopedPlatform, tryPrincipalKey } from "./principal-key.js";
+import { LINK_TENANT_NONE, linkTenantUnresolvableMessage, tryLinkTenantOf } from "./link-tenant.js";
+import { admittedTenantsFromConfig } from "../access/tenant-admission.js";
+import { accessReferencedLinkSets } from "../access/access-referenced-link-sets.js";
+import { getConfig } from "../access/config.js";
+import { directoryLinkSetVaultArmed } from "../connections/connector-flags.js";
+function log(msg) {
+    console.log(`[open-everywhere:identity/directory-sync] ${msg}`);
+}
+/**
+ * The access-referenced link-set ids for the C2.4 guard, read from the registered app config. If
+ * config is not registered (a partial boot, a test that never registered it) this returns EMPTY —
+ * which is correct, not fail-open: no registered access config means no link-set is access-bearing,
+ * so nothing to suppress. In production the config is registered at boot before any sync runs.
+ */
+function accessReferencedSetsFromConfig() {
+    try {
+        const cfg = getConfig();
+        return accessReferencedLinkSets({
+            bindings: cfg.loadBindings(),
+            groups: cfg.loadGroups?.() ?? [],
+        });
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Re-exported from connections/connector-flags.ts so this module and identity/link-store.ts can both read the flag without an import cycle. The fail-closed reasoning lives with the implementation. */
+export { directoryLinkSetVaultArmed };
+/**
+ * A workspace the adapter claims is honoured only when this deployment already declares it (access/tenant-admission.ts); an unadmitted claim resolves to undefined and the planner skips the account with a warning.
+ * With no claim the answer is the empty string for a vendor-global platform, the sole admitted workspace for a tenant-scoped one, and undefined when there is not exactly one.
+ */
+function admittedDirectoryTenant(platform, claimed) {
+    const named = claimed?.trim() ?? "";
+    if (named.length === 0 || !isTenantScopedPlatform(platform))
+        return tryLinkTenantOf(platform, undefined);
+    return admittedTenantsFromConfig(platform).has(named) ? named : undefined;
+}
+/** Env var for the auto-confirm policy — exported so tests/docs/the control plane name one string. */
+export const OE_DIRECTORY_AUTOCONFIRM_ENV = "OE_DIRECTORY_AUTOCONFIRM";
+/**
+ * Read the auto-confirm policy. DEFAULT OFF: unset or empty means every link still needs its human,
+ * which is the posture the whole design rests on — this knob is the single documented escape from
+ * it, so it may only be opened deliberately.
+ *
+ * FAIL-LOUD on a value that is neither: a typo in a security knob that silently resolves to the
+ * safe side is still a deployment that believes it armed something it did not. (The polarity of the
+ * *default* is fail-closed; the polarity of a *misconfiguration* is fail-loud. Both, not either.)
+ */
+export function directoryAutoConfirm(env = process.env) {
+    const raw = env[OE_DIRECTORY_AUTOCONFIRM_ENV]?.trim().toLowerCase();
+    if (raw === undefined || raw === "")
+        return "off";
+    if (raw === "off" || raw === "attested")
+        return raw;
+    throw new Error(`${OE_DIRECTORY_AUTOCONFIRM_ENV}="${env[OE_DIRECTORY_AUTOCONFIRM_ENV]}" is not a policy — use "off" (default: every ` +
+        `directory suggestion waits for the person's own DM confirmation) or "attested" (mappings the IdP itself ` +
+        `provisions are auto-confirmed; weaker "asserted" and "email-match" mappings still wait).`);
+}
+/** The audit actor for everything this module writes. Not a person and never mistakable for one. */
+const DIRECTORY_SYNC_ACTOR = "directory-sync";
+/** The audit action carrying one org's sync summary — also the row `directory_sync_status` reads. */
+export const DIRECTORY_SYNC_ACTION = "identity.directory.sync";
+/**
+ * The link-set id a person with no existing accounts gets. DERIVED, not minted: two concurrent
+ * syncs (or a sync racing an admin's "sync now") must converge on ONE set for a person, and a
+ * random uuid per run would instead scatter their accounts across as many sets as there were runs.
+ * A digest, not the raw ids, because a set id shows up in admin lists and audit rows and there is
+ * no reason to print somebody's IdP record key there.
+ */
+export function directoryLinkSetId(provider, externalId) {
+    return `dir-${createHash("sha256").update(`${provider}\u0000${externalId}`, "utf8").digest("hex").slice(0, 32)}`;
+}
+export function planIsNoop(plan) {
+    return plan.steps.every((s) => s.kind === "noop");
+}
+/**
+ * The internal account identity for this module's maps — the WHOLE triple (OPE-309 phase 2).
+ *
+ * NUL-joined rather than `principalKey`-composed for the reason identity/link-resolve.ts's `pairKey`
+ * gives: this is a map key over raw halves where a single-character join could in principle make two
+ * distinct triples collide. It also stays TOTAL — a map key must exist for every account this
+ * planner sees, including one whose tenant it could not resolve, which the principal grammar
+ * (rightly) refuses to compose a key for at all. 🔴 The separator is ALWAYS the `\u0000` ESCAPE, never a literal NUL byte:
+ * one raw NUL makes git classify the whole module as binary, and `rg`/`grep` then skip it silently.
+ */
+function accountKey(platform, tenant, nativeId) {
+    return `${platform}\u0000${tenant}\u0000${nativeId}`;
+}
+/** One account as an operator should READ it in a warning — the principal key when it composes, plus
+ *  the workspace spelled out where the key does not already carry it. Never the NUL-joined map key,
+ *  which is unreadable and looks truncated; and never a bare two-segment string on a tenant-scoped
+ *  platform, which since OPE-309 would name nobody. */
+function describeAccount(acct) {
+    const key = tryPrincipalKey(acct.platform, acct.tenant, acct.nativeId);
+    if (key === undefined)
+        return `the ${acct.platform} account "${acct.nativeId}" (workspace unresolved)`;
+    return acct.tenant === LINK_TENANT_NONE ? key : `${key} (workspace ${acct.tenant})`;
+}
+/** Grade order, strongest first — the single place the vocabulary's ordering is written down, so
+ *  {@link strongerGrade} cannot disagree with directory.ts's header. */
+const GRADE_ORDER = ["attested", "asserted", "email-match"];
+/** Rank of a grade, 0 = strongest. A value NOT in the vocabulary ranks WEAKEST, not strongest: the
+ *  input here crosses an adapter boundary, so an unrecognised string must never be able to win a
+ *  dedupe and carry a mapping into the auto-confirm branch. */
+function gradeRank(g) {
+    const i = GRADE_ORDER.indexOf(g);
+    return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+}
+/** Strongest grade wins when the same account arrives twice for one person (two Okta apps mapping to
+ *  the same platform). attested > asserted > email-match — see directory.ts: a provisioning fact
+ *  beats an IdP statement, which beats an inference over a shared attribute. Written as a ranking
+ *  rather than a chain of `===` so adding a grade cannot silently leave a pair unordered. */
+function strongerGrade(a, b) {
+    return gradeRank(a) <= gradeRank(b) ? a : b;
+}
+/** The `noop.why` sentence for a mapping that was written as a suggestion rather than confirmed —
+ *  one per grade, because the three wait for a human for three different reasons. */
+function whyNotConfirmed(grade) {
+    switch (grade) {
+        case "attested":
+            return "suggested — awaiting this person's DM confirmation";
+        case "asserted":
+            return "suggested (asserted) — the IdP states this mapping but the platform never confirmed it; only this account can";
+        case "email-match":
+            return "suggested (email-match) — only a person can confirm this one";
+        default:
+            // Unreachable while the union is exhausted; an unrecognised grade from an adapter still gets
+            // a sentence rather than `undefined`, and the sentence says the honest thing.
+            return `suggested (${String(grade)}) — unrecognised evidence grade; only this account can confirm it`;
+    }
+}
+/**
+ * THE PURE DIFF. No I/O, no clock, no env — the policy is an argument, so a test states the policy
+ * it is testing instead of mutating the process.
+ */
+export function planDirectorySync(input) {
+    const resolveTenant = input.resolveTenant ?? ((platform, claimed) => (isTenantScopedPlatform(platform) ? (claimed?.trim() || undefined) : LINK_TENANT_NONE));
+    const steps = [];
+    const warnings = [];
+    // 🔴 C2.4 EXTENDED FOR C.3. With the shared user-OAuth vault armed, EVERY confirmed membership of
+    // an active link-set is credential-bearing, so the auto-confirm escape is closed for all sets, not
+    // just the ones access config names. Warned ONCE per run rather than once per target: the reason is
+    // a property of the deployment, not of any one set, and one line per person would bury it.
+    const vaultArmed = input.linkSetVaultArmed === true;
+    if (vaultArmed && input.autoConfirm === "attested") {
+        warnings.push(`connectors.linkSetVault is armed, so EVERY confirmed member of an active link-set can mint that set's SHARED user-OAuth token (C.3) — ` +
+            `directory auto-confirm is therefore SUPPRESSED for ALL link-sets, not only the ones access config names (C2.4, threat (c)). ` +
+            `Every attested mapping lands as a suggestion awaiting the person's own DM confirmation, because an IdP edit must not hand a brand-new account somebody else's live credential.`);
+    }
+    // Index the materialised side once. A row is looked up by principal key because that — not any
+    // name, handle or email — is the only thing the two sides are allowed to be joined on.
+    const rowByKey = new Map();
+    const setById = new Map();
+    const idsBySetId = new Map();
+    for (const { set, ids } of input.current) {
+        setById.set(set.id, set);
+        idsBySetId.set(set.id, ids);
+        for (const row of ids)
+            rowByKey.set(accountKey(row.platform, row.tenant, row.nativeId), { row, set });
+    }
+    // Rule 4's other half: one account claimed by two DIRECTORY people. The store's PK would refuse
+    // the second write anyway, but a refusal buried in a write result is not an operator telling you
+    // your IdP has two records for one human.
+    const claimedBy = new Map();
+    for (const person of input.people) {
+        for (const acct of person.accounts) {
+            const tenant = resolveTenant(acct.platform, acct.tenant);
+            // An account whose workspace this deployment cannot name is not a claim on anything — it is
+            // dropped below with its own noop + warning, so it must not participate in this count either
+            // (it would otherwise conjure a phantom conflict between two people it can't place).
+            if (tenant === undefined)
+                continue;
+            const key = accountKey(acct.platform, tenant, acct.nativeId);
+            const first = claimedBy.get(key);
+            if (first === undefined)
+                claimedBy.set(key, person.externalId);
+            else if (first !== person.externalId)
+                claimedBy.set(key, "\u0000conflict");
+        }
+    }
+    for (const person of input.people) {
+        // Dedupe this person's accounts (two apps can map the same platform account), keeping the
+        // strongest grade — the auto-confirm policy branches on grade, so a weaker duplicate must not
+        // be able to demote a provisioning fact.
+        const accounts = new Map();
+        for (const acct of person.accounts) {
+            const tenant = resolveTenant(acct.platform, acct.tenant);
+            if (tenant === undefined) {
+                // FAIL LOUD, FAIL CLOSED: a suggestion written with an invented workspace is an identity
+                // claim nobody made. The row is not written, the person is told why, and the sweep is
+                // self-healing — declaring that workspace's channel makes the next sync place the account.
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: `cannot name the ${acct.platform} workspace for this account` });
+                warnings.push(`directory person "${person.externalId}": ${linkTenantUnresolvableMessage(acct.platform)}`);
+                continue;
+            }
+            const key = accountKey(acct.platform, tenant, acct.nativeId);
+            const seen = accounts.get(key);
+            accounts.set(key, seen ? { ...seen, grade: strongerGrade(seen.grade, acct.grade) } : { ...acct, tenant });
+        }
+        // Accounts another directory person also claims: skipped, loudly, for BOTH of them.
+        for (const [key, acct] of [...accounts]) {
+            if (claimedBy.get(key) === "\u0000conflict") {
+                accounts.delete(key);
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: "two directory records claim this account" });
+                warnings.push(`${describeAccount(acct)} is claimed by more than one directory person — refusing to link it to any of them. Fix the duplicate in the IdP.`);
+            }
+        }
+        // THE ANCHOR: every link-set any of this person's accounts already sits in — INCLUDING rows in
+        // a revoked set. Excluding those would let a sync mint a brand-new set for somebody who has
+        // been offboarded, which is precisely the resurrection revocation exists to prevent.
+        const anchors = new Set();
+        for (const key of accounts.keys()) {
+            const found = rowByKey.get(key);
+            if (found)
+                anchors.add(found.set.id);
+        }
+        if (anchors.size > 1) {
+            const named = [...anchors].sort().join(", ");
+            warnings.push(`directory person "${person.externalId}" maps accounts that already belong to ${anchors.size} DIFFERENT link-sets (${named}) — refusing to merge them. ` +
+                `An account is exactly one person; an admin has to decide which set is right (link_sets_list / revoke_link_set).`);
+            steps.push({ kind: "noop", externalId: person.externalId, why: `ambiguous: accounts span ${anchors.size} link-sets` });
+            continue;
+        }
+        const anchorId = [...anchors][0];
+        const anchored = anchorId === undefined ? undefined : setById.get(anchorId);
+        const derivedId = directoryLinkSetId(input.provider, person.externalId);
+        const target = anchored ?? setById.get(derivedId);
+        // NARROWING FIRST, and unconditionally: a deprovisioned person gets no suggestions and no
+        // confirmations on this pass, whatever the policy says.
+        if (person.deprovisioned) {
+            if (!target) {
+                // Nothing to narrow, and emphatically nothing to CREATE — a sync must never mint a set for
+                // somebody the IdP has already deactivated.
+                steps.push({ kind: "noop", externalId: person.externalId, why: "deprovisioned in the directory, and holds no link-set here" });
+            }
+            else if (target.status === "active") {
+                // 🔴 SUSPEND ONLY A DIRECTORY-BUILT SET (audit finding F5). The anchor is a (platform,
+                // nativeId) match, which a mis-mapped IdP record can share with the account a REAL person
+                // proved control of via a challenge. Suspending that person's set on an IdP deprovision would
+                // eagerly erase attribution the IdP never built. So a suspend is emitted only when EVERY live
+                // member of the anchored set is itself directory-sync-established; any `challenge:`-established
+                // member (a proof-of-control link, including a DM-confirmed suggestion) makes it a human-built
+                // set the sync must not touch — warn-and-skip and leave the admin's explicit lever
+                // (suspend_link_set / revoke_link_set) for a genuine offboarding.
+                const members = idsBySetId.get(target.id) ?? [];
+                const challengeBuilt = members.some((r) => r.status !== "revoked" && r.establishedBy.startsWith("challenge:"));
+                if (challengeBuilt) {
+                    steps.push({ kind: "noop", externalId: person.externalId, why: "deprovisioned, but the anchored link-set has challenge-proven members — refusing to suspend a set the directory did not build" });
+                    warnings.push(`directory person "${person.externalId}" is deprovisioned, but the link-set it anchors (${target.id}) contains challenge-established account(s) — refusing to suspend a proof-of-control-built set on an IdP deprovision. ` +
+                        `If this offboarding is real, an admin has suspend_link_set / revoke_link_set.`);
+                }
+                else {
+                    steps.push({ kind: "suspend", externalId: person.externalId, linkSetId: target.id, handle: target.handle });
+                }
+            }
+            else {
+                steps.push({ kind: "noop", externalId: person.externalId, why: `deprovisioned; link-set is already ${target.status}` });
+            }
+            continue;
+        }
+        if (accounts.size === 0) {
+            steps.push({ kind: "noop", externalId: person.externalId, why: "directory maps no platform accounts for this person" });
+            continue;
+        }
+        if (target && target.status !== "active") {
+            // Widening into a held or terminal set is refused here so the refusal has a REASON attached;
+            // `suggestLinkedId` would refuse it too (defence in depth, same shape as link-store.ts's
+            // pre-checks next to its primary keys).
+            for (const acct of accounts.values()) {
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: `link-set is ${target.status}` });
+            }
+            continue;
+        }
+        const targetId = target?.id ?? derivedId;
+        const newSet = target === undefined;
+        // 🔴 C2.4: an access-bearing target set is never auto-confirmed into — the widening waits for a
+        // human's DM tap even under the EMU-grade escape. Two independent reasons a set is access-bearing,
+        // and either alone suppresses: config NAMES it, or the C.3 vault makes membership of ANY set
+        // credential-bearing. The per-set warning is emitted only for the config reason (so an operator
+        // sees WHY a set they named keeps getting suggestions); the blanket reason was already warned once
+        // above, and repeating it per person would drown it.
+        const targetAccessReferenced = vaultArmed || (input.accessReferencedSets?.has(targetId) ?? false);
+        if (!vaultArmed && targetAccessReferenced && input.autoConfirm === "attested" && accounts.size > 0) {
+            warnings.push(`link-set ${targetId} is referenced by ACCESS config (a \`principal\` credential binding or a person-group), so directory auto-confirm is SUPPRESSED for it (C2.4) — an attested mapping still lands as a suggestion awaiting the person's own DM confirmation, because an IdP attestation must not widen an access-bearing set without a human in the loop.`);
+        }
+        for (const [key, acct] of accounts) {
+            const found = rowByKey.get(key);
+            const mayAutoConfirm = input.autoConfirm === "attested" && acct.grade === "attested" && !targetAccessReferenced;
+            if (!found) {
+                steps.push({
+                    kind: "suggest",
+                    externalId: person.externalId,
+                    platform: acct.platform,
+                    tenant: acct.tenant,
+                    nativeId: acct.nativeId,
+                    grade: acct.grade,
+                    linkSetId: targetId,
+                    newSet,
+                    handle: person.displayName || person.externalId,
+                    autoConfirm: mayAutoConfirm,
+                });
+                continue;
+            }
+            if (found.set.id !== targetId) {
+                // Unreachable while anchors.size ≤ 1 (every known row is in the anchor set). Kept as a
+                // refusal rather than an assertion: the one thing that must not happen if the invariant
+                // ever slips is a silent cross-set write.
+                warnings.push(`${describeAccount(acct)} belongs to link-set ${found.set.id}, not ${targetId} — refusing to move it.`);
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: "belongs to another link-set" });
+                continue;
+            }
+            if (found.row.status === "revoked") {
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: "revoked (terminal)" });
+                continue;
+            }
+            if (found.row.status === "confirmed") {
+                // Rule 3. Whatever established it — a challenge, an earlier sync — it stands untouched.
+                steps.push({ kind: "noop", externalId: person.externalId, platform: acct.platform, nativeId: acct.nativeId, why: "already confirmed" });
+                continue;
+            }
+            if (mayAutoConfirm) {
+                steps.push({ kind: "confirm", externalId: person.externalId, platform: acct.platform, tenant: acct.tenant, nativeId: acct.nativeId, grade: acct.grade, linkSetId: targetId });
+            }
+            else {
+                steps.push({
+                    kind: "noop",
+                    externalId: person.externalId,
+                    platform: acct.platform,
+                    nativeId: acct.nativeId,
+                    // GRADE-KEYED, not binary: the three grades are refused for three different reasons, and
+                    // an operator reading `directory_sync_status` is entitled to the one that applies. An
+                    // `asserted` row in particular is NOT "the escape is off" — it is "the IdP said so and
+                    // nobody downstream agreed", which is why only the account itself can ratify it (the
+                    // same rule `pendingDirectorySuggestionsFor` (c) enforces on the read side).
+                    why: whyNotConfirmed(acct.grade),
+                });
+            }
+        }
+    }
+    const counts = {
+        suggest: steps.filter((s) => s.kind === "suggest").length,
+        confirm: steps.filter((s) => s.kind === "confirm").length,
+        suspend: steps.filter((s) => s.kind === "suspend").length,
+        noop: steps.filter((s) => s.kind === "noop").length,
+    };
+    return { provider: input.provider, policy: input.autoConfirm, people: input.people.length, steps, warnings, counts };
+}
+/**
+ * Sync ONE org against the registered directory provider. Returns null when no provider is wired —
+ * the cleanly-off answer, not an error (see directory.ts).
+ *
+ * `provider` may be injected for tests; production resolves the boot-registered one. `now` is
+ * injected for the same reason every dated write in this tree takes a clock.
+ */
+export async function syncDirectoryOrg(input) {
+    const provider = input.provider ?? directoryProvider();
+    if (!provider)
+        return null;
+    const policy = input.autoConfirm ?? directoryAutoConfirm();
+    const startedAt = (input.now ?? new Date()).toISOString();
+    const accessReferencedSets = input.accessReferencedSets ?? accessReferencedSetsFromConfig();
+    const vaultArmed = input.linkSetVaultArmed ?? directoryLinkSetVaultArmed();
+    // THE VENDOR CALL AND THE STORE READ, in that order and both before any write. If the directory
+    // throws, nothing has been written and nothing is inferred from the silence (rule 2).
+    const people = await provider.listPeople();
+    const current = await listLinkSetsWithIds(input.org);
+    const plan = planDirectorySync({
+        provider: provider.id,
+        people,
+        current,
+        autoConfirm: policy,
+        accessReferencedSets,
+        linkSetVaultArmed: vaultArmed,
+        // Production's tenant answer: the workspace the operator's app map named, admission-checked before it is believed. A platform this cannot name yields undefined and the planner skips those accounts loudly.
+        resolveTenant: (platform, claimed) => admittedDirectoryTenant(platform, claimed),
+    });
+    const refusals = [];
+    let setsCreated = 0;
+    let suggested = 0;
+    let confirmed = 0;
+    let suspended = 0;
+    const ensured = new Set();
+    for (const step of plan.steps) {
+        const now = input.now;
+        if (step.kind === "noop")
+            continue;
+        if (step.kind === "suspend") {
+            // EAGER, and never a revoke: terminal decisions stay human (link-store.ts's revokeLinkSet is
+            // the admin's lever, not this one's).
+            const res = await setLinkSetHold({ org: input.org, linkSetId: step.linkSetId, hold: "suspended", actor: `${DIRECTORY_SYNC_ACTOR}:${provider.id}`, ...(now ? { now } : {}) });
+            if (res.ok)
+                suspended++;
+            else
+                refusals.push(`suspend ${step.linkSetId}: ${res.reason}`);
+            continue;
+        }
+        const evidence = { kind: "directory-sync", provider: provider.id, grade: step.grade, externalId: step.externalId };
+        if (step.kind === "suggest") {
+            if (step.newSet && !ensured.has(step.linkSetId)) {
+                const { created } = await ensureLinkSet({ org: input.org, linkSetId: step.linkSetId, handle: step.handle, ...(now ? { now } : {}) });
+                if (created)
+                    setsCreated++;
+                ensured.add(step.linkSetId);
+            }
+            const res = await suggestLinkedId({
+                org: input.org,
+                linkSetId: step.linkSetId,
+                account: { platform: step.platform, tenant: step.tenant, nativeId: step.nativeId },
+                evidence,
+                ...(now ? { now } : {}),
+            });
+            if (!res.ok) {
+                refusals.push(`suggest ${describeAccount(step)}: ${res.reason}`);
+                continue;
+            }
+            suggested++;
+            if (!step.autoConfirm)
+                continue;
+        }
+        // Either an explicit confirm step, or the just-written suggestion the policy allows to skip the
+        // DM tap. The evidence recorded is the ATTESTATION — the thing that actually convinced the
+        // system — which is what link-store.ts's invariant 2 asks for.
+        const res = await confirmLinkedId({ org: input.org, account: { platform: step.platform, tenant: step.tenant, nativeId: step.nativeId }, evidence, ...(now ? { now } : {}) });
+        if (res.ok)
+            confirmed++;
+        else
+            refusals.push(`confirm ${describeAccount(step)}: ${res.reason}`);
+    }
+    const finishedAt = new Date(input.now ?? Date.now()).toISOString();
+    const result = {
+        org: input.org,
+        provider: provider.id,
+        policy,
+        plan,
+        applied: { setsCreated, suggested, confirmed, suspended },
+        refusals,
+        startedAt,
+        finishedAt,
+    };
+    // ONE summary row per org per run — the durable record `directory_sync_status` reads back, and
+    // the row `deploy:census`'s liveness check reads the AGE of (OPE-635). It carries counts and
+    // warnings, never the directory's contents: the per-row `identity.link.*` appends (link-store.ts,
+    // one per mutation) are where the specifics already live, and duplicating them here would put a
+    // second, drifting copy of the same facts in the same log. `outcome` is always present so a reader
+    // never has to infer live-vs-idle from the absence of other fields (OPE-635) — this is the ARMED
+    // branch, so it is always "synced" here; the unarmed no-op branch is `runDirectorySync` below.
+    await appendAudit({
+        org: input.org,
+        platform: "directory",
+        workspace: provider.id,
+        principalId: `${DIRECTORY_SYNC_ACTOR}:${provider.id}`,
+        action: DIRECTORY_SYNC_ACTION,
+        detail: {
+            outcome: "synced",
+            provider: provider.id,
+            policy,
+            people: plan.people,
+            planned: plan.counts,
+            applied: result.applied,
+            warnings: plan.warnings.slice(0, 20),
+            refusals: refusals.slice(0, 20),
+            startedAt,
+            finishedAt,
+        },
+    });
+    for (const w of plan.warnings)
+        log(`⚠ ${input.org}: ${w}`);
+    log(`${input.org} (${provider.id}, autoconfirm=${policy}): ${plan.people} person(s) — ` +
+        `${result.applied.suggested} suggested, ${result.applied.confirmed} confirmed, ${result.applied.suspended} suspended, ` +
+        `${plan.counts.noop} no-op, ${plan.warnings.length} warning(s), ${refusals.length} refusal(s)`);
+    return result;
+}
+/**
+ * Best-effort PER ORG: a directory outage or one bad org never aborts the sweep for the rest, because a sync that stops at the first error is a deprovision that silently did not land for everybody after it.
+ * An unarmed deployment and a per-org sync that throws each write one DIRECTORY_SYNC_ACTION row per swept org, so the liveness read sees a fresh row either way.
+ */
+export async function runDirectorySync(opts = {}) {
+    const provider = directoryProvider();
+    const orgs = opts.orgs ?? directorySyncOrgs();
+    const ts = new Date(opts.now ?? Date.now()).toISOString();
+    if (!provider) {
+        log("no directory provider registered — nothing to sync (set OE_DIRECTORY_PROVIDER and wire the adapter to arm it)");
+        for (const org of orgs) {
+            await appendAudit({
+                org,
+                platform: "directory",
+                workspace: "none",
+                principalId: DIRECTORY_SYNC_ACTOR,
+                action: DIRECTORY_SYNC_ACTION,
+                detail: {
+                    outcome: "no-op: no provider configured",
+                    note: "set OE_DIRECTORY_PROVIDER and wire the adapter to arm it",
+                    startedAt: ts,
+                    finishedAt: ts,
+                },
+            });
+        }
+        return [];
+    }
+    const out = [];
+    for (const org of orgs) {
+        try {
+            const res = await syncDirectoryOrg({ org, provider, ...(opts.now ? { now: opts.now } : {}) });
+            if (res)
+                out.push(res);
+        }
+        catch (err) {
+            log(`skip ${org} — ${String(err)}`);
+            const failedAt = new Date(opts.now ?? Date.now()).toISOString();
+            await appendAudit({
+                org,
+                platform: "directory",
+                workspace: provider.id,
+                principalId: `${DIRECTORY_SYNC_ACTOR}:${provider.id}`,
+                action: DIRECTORY_SYNC_ACTION,
+                // Bounded: outcome is durable audit detail — first line of the message only, never a stack.
+                detail: { outcome: `failed: ${String(err instanceof Error ? err.message : err).split("\n")[0].slice(0, 160)}`, provider: provider.id, startedAt: failedAt, finishedAt: failedAt },
+            });
+        }
+    }
+    return out;
+}
+/** The orgs a sweep covers. Reuses `OE_TIDY_ORGS` — the deployment already answers "which orgs does
+ *  this sweep" once, and a second env var for the same question is how the two come to disagree.
+ *  Imported lazily-by-copy rather than from schedules/tidy.ts to keep this module free of the
+ *  schedule layer (identity must not depend on eve). */
+function directorySyncOrgs(env = process.env) {
+    const raw = env.OE_TIDY_ORGS;
+    if (!raw)
+        return ["default"];
+    const orgs = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    return orgs.length > 0 ? orgs : ["default"];
+}
+/** The last sync summary for an org, or null if this org has never synced. DERIVED FROM AUDIT rather
+ *  than a status table: the audit log is already durable, org-partitioned and hash-chained, the row
+ *  is written on every run regardless, and a second store table for the same fact would need a
+ *  schema migration to tell us something the log already knows. */
+export async function lastDirectorySync(org) {
+    const rows = await readAudit({ org, action: DIRECTORY_SYNC_ACTION, limit: 1 });
+    const row = rows[0];
+    return row ? { ts: row.ts, detail: { ...(row.detail ?? {}) } } : null;
+}
+/**
+ * The directory suggestions this caller may confirm — the read behind confirm_link's one-tap path, narrow by construction so no confirming caller can weaken it. A confirmed member sees the set's attested suggestions, a merely suggested caller sees only their own account, and a suggestion that is not attested is ratifiable only by the account itself.
+ * A set that is not active, a revoked row, and any suggestion whose evidence is not directory-sync are all excluded.
+ */
+export async function pendingDirectorySuggestionsFor(org, platform, tenant, nativeId) {
+    const sets = await listLinkSetsWithIds(org);
+    // 🔴 THE CALLER IS THE WHOLE TRIPLE (OPE-309 phase 2). `principalKey` is still two segments until
+    // phase 1, so identity here is decided by comparing (platform, tenant, nativeId) column-wise
+    // rather than by comparing composed keys — otherwise a caller in workspace A would match their
+    // id-twin's row in workspace B and be shown, and allowed to ratify, that person's suggestions.
+    const isMe = (r) => r.platform === platform && r.tenant === tenant && r.nativeId === nativeId;
+    for (const { set, ids } of sets) {
+        if (set.status !== "active")
+            continue;
+        const mine = ids.find(isMe);
+        // (a) standing needs a CONFIRMED row; (b) a `suggested` caller is a BOOTSTRAP — own account only.
+        // Anything else (absent, revoked, any other status) is no standing at all.
+        if (!mine || (mine.status !== "confirmed" && mine.status !== "suggested"))
+            continue;
+        const bootstrapOnly = mine.status !== "confirmed"; // suggested caller ⇒ own account only (b)
+        const out = [];
+        for (const row of ids) {
+            if (row.status !== "suggested")
+                continue;
+            if (!row.establishedBy.startsWith("directory-sync:"))
+                continue;
+            const isOwn = isMe(row);
+            // (b) a bootstrap (suggested) caller sees ONLY their own account.
+            if (bootstrapOnly && !isOwn)
+                continue;
+            let grade = "unknown";
+            try {
+                const parsed = JSON.parse(row.evidenceJson ?? "{}");
+                if (typeof parsed.grade === "string")
+                    grade = parsed.grade;
+            }
+            catch {
+                /* evidence is written by this tree; an unparseable blob is reported as an unknown grade
+                   rather than hiding the suggestion — the person still sees WHAT is being proposed. */
+            }
+            // (c) ONLY AN `attested` SUGGESTION MAY BE RATIFIED BY SOMEBODY ELSE. Every other grade —
+            // `asserted`, `email-match`, and any string this tree does not recognise (including the
+            // "unknown" an unparseable evidence blob produces above) — is not proof of control, so only
+            // the account ITSELF may ratify it, never another member of the set whatever their standing.
+            // Phrased as `!== "attested"` rather than a list of weak grades so a grade added later is
+            // fail-CLOSED by default: a new vocabulary entry must earn cross-member ratification
+            // explicitly, not inherit it by not being on a list.
+            if (grade !== "attested" && !isOwn)
+                continue;
+            // (d) A ROW WHOSE PRINCIPAL KEY DOES NOT COMPOSE IS NOT OFFERED (OPE-309 phase 1). `principal`
+            // is not a label here — `confirm_link` matches the person's typed `accounts` against it
+            // exactly — so it has to be the real, typable key. A pre-rung slack row (blank tenant, not yet
+            // healed by identity/link-tenant-backfill.ts) has none, and confirming it would key a write
+            // nothing can address; it is already dormant everywhere else, so it is dropped here too rather
+            // than shown as something a person could act on.
+            const principal = tryPrincipalKey(row.platform, row.tenant, row.nativeId);
+            if (principal === undefined)
+                continue;
+            out.push({
+                linkSetId: set.id,
+                platform: row.platform,
+                tenant: row.tenant,
+                nativeId: row.nativeId,
+                principal,
+                grade,
+                provider: row.establishedBy.slice("directory-sync:".length),
+            });
+        }
+        return out;
+    }
+    return [];
+}
+//# sourceMappingURL=directory-sync.js.map