@open-everywhere/core 0.1.0

package/dist/agent/identity/groups-codemod.js

@@ -0,0 +1,129 @@
+// The only writer of the IdP-group overlay (`agent/identity/groups.generated.ts`): a structural transformation of a plan from the pure diff in identity/group-sync.ts, byte-deterministic and idempotent, so the diff a human reviews was never model-authored.
+// Every overlay group carries the `directory:` prefix and every member is a `{ linkSet }` reference, never a principal key — that keeps the machine-owned and hand-written namespaces disjoint and defers every widening decision to resolve time, where only confirmed accounts count.
+import { overlayModuleHeader, unwrapOverlayModule, wrapOverlayModule } from "../access/overlay-module.js";
+import { DIRECTORY_GROUP_PREFIX, isDirectoryGroupName } from "./groups.js";
+/** A codemod refusal — invalid file or an invariant breach. Distinct type so callers can tell
+ *  "refused by design" from an unexpected failure. */
+export class GroupsCodemodError extends Error {
+}
+export function emptyGroupsFile() {
+    return { groups: [] };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse + shape-check a groups overlay from unknown JSON. STRICT and fail-loud: unknown top-level
+ * keys, un-namespaced group names, unknown Group fields, and any member that is not a
+ * `{ linkSet: string }` all throw — the overlay is machine-written, so any deviation means a
+ * hand-edit went wrong, and a silently mis-parsed access-bearing overlay IS the security bug.
+ *
+ * Deep semantic validation (uniqueness, empty members, duplicate members) stays with
+ * `assertGroupsValid` on the MERGED result; this only pins the overlay-specific rules: shape, the
+ * `directory:` namespace, and the link-set-only member vocabulary.
+ */
+export function parseGroupsFile(value) {
+    if (!isRecord(value))
+        throw new GroupsCodemodError("groups overlay must be a JSON object with a `groups` array");
+    const keys = Object.keys(value).filter((k) => k !== "$comment");
+    const unknown = keys.filter((k) => k !== "groups");
+    if (unknown.length > 0)
+        throw new GroupsCodemodError(`groups overlay has unknown top-level key(s): ${unknown.join(", ")}`);
+    if (!Array.isArray(value.groups))
+        throw new GroupsCodemodError("groups overlay needs a `groups` array (use [] when empty)");
+    const groups = [];
+    for (const g of value.groups) {
+        if (!isRecord(g) || typeof g.name !== "string" || !isDirectoryGroupName(g.name)) {
+            throw new GroupsCodemodError(`every overlay group needs a "${DIRECTORY_GROUP_PREFIX}"-prefixed name (got: ${JSON.stringify(isRecord(g) ? g.name : g)}) — that namespace is what keeps synced groups from colliding with hand-written ones`);
+        }
+        for (const k of Object.keys(g)) {
+            if (!["name", "title", "members"].includes(k)) {
+                throw new GroupsCodemodError(`overlay group "${g.name}" has field "${k}" — the overlay carries only name/title/members; put anything else in a hand-written group`);
+            }
+        }
+        if (g.title !== undefined && typeof g.title !== "string")
+            throw new GroupsCodemodError(`overlay group "${g.name}" title must be a string`);
+        if (!Array.isArray(g.members))
+            throw new GroupsCodemodError(`overlay group "${g.name}" members must be an array`);
+        for (const m of g.members) {
+            // LINK-SET REFS ONLY. A principal key here would be a widening decision written into a file
+            // whose reviewer cannot verify it, and would bypass the confirmed-only rule — see the header.
+            if (!isRecord(m) || typeof m.linkSet !== "string" || m.linkSet.length === 0 || Object.keys(m).length !== 1) {
+                throw new GroupsCodemodError(`overlay group "${g.name}" has a member that is not a { linkSet: "<id>" } reference — the overlay never writes bare principal keys`);
+            }
+        }
+        groups.push(g);
+    }
+    return { groups };
+}
+const GROUP_KEYS = ["name", "title", "members"];
+function orderKeys(obj, order) {
+    const out = {};
+    for (const k of order)
+        if (k in obj)
+            out[k] = obj[k];
+    for (const k of Object.keys(obj).sort())
+        if (!(k in out))
+            out[k] = obj[k];
+    return out;
+}
+function canonicalGroup(g) {
+    const members = [...g.members]
+        .map((m) => (typeof m === "string" ? m : m.linkSet))
+        .sort()
+        .map((linkSet) => ({ linkSet }));
+    return orderKeys({ ...g, members }, GROUP_KEYS);
+}
+/**
+ * Canonical, byte-deterministic serialisation of the overlay's DATA: groups sorted by name, members
+ * sorted by link-set id, fixed key order, 2-space indent, trailing newline. This is the body
+ * {@link emitGroupsModule} wraps the module grammar around, and
+ * `emitGroupsModule(parseGroupsModule(emitGroupsModule(f))) === emitGroupsModule(f)`.
+ */
+export function stringifyGroups(file) {
+    const groups = [...file.groups].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalGroup);
+    return JSON.stringify({ groups }, null, 2) + "\n";
+}
+/** This overlay's fixed module grammar. Constants only: the emitted bytes depend on the data alone. */
+const GROUPS_MODULE = {
+    what: "person-groups overlay",
+    header: overlayModuleHeader("person-groups overlay", "packages/core/agent/identity/groups-codemod.ts"),
+    typeImport: 'import type { GroupsFile } from "@open-everywhere/core/agent/identity/groups-codemod.js";',
+    typeName: "GroupsFile",
+};
+export function emitGroupsModule(file) {
+    return wrapOverlayModule(GROUPS_MODULE, stringifyGroups(file));
+}
+/**
+ * Parse an overlay module's text, VERIFYING THE ROUND TRIP. Strip the grammar (refusing if it was
+ * touched at all), parse the data, then re-emit and demand the bytes come back identical — so a
+ * hand-edit that reorders keys, re-indents or leaves a stray field REFUSES here rather than being
+ * silently rewritten by the next plan, which would put a diff in front of a reviewer that they never
+ * authored.
+ */
+export function parseGroupsModule(text) {
+    const file = parseGroupsFile(unwrapOverlayModule(GROUPS_MODULE, text, (m) => new GroupsCodemodError(m)));
+    if (emitGroupsModule(file) !== text) {
+        throw new GroupsCodemodError("person-groups overlay is not in canonical form — re-emitting its own data does not reproduce the file, so it has been hand-edited. Run `npm run overlays:normalize` and commit the result (the codemod refuses to rewrite a file it did not write).");
+    }
+    return file;
+}
+/** LENIENT re-emit for `npm run overlays:normalize`: take whatever well-shaped data the module
+ *  carries and return the canonical module text. The only path allowed to accept a non-canonical
+ *  file — its whole job is to produce the canonical one. */
+export function renormalizeGroupsModule(text) {
+    return emitGroupsModule(parseGroupsFile(unwrapOverlayModule(GROUPS_MODULE, text, (m) => new GroupsCodemodError(m))));
+}
+/**
+ * The overlay's own groups, recovered from a MERGED registry by filtering on the reserved namespace.
+ *
+ * 🔴 THIS IS ONLY CORRECT BECAUSE THE NAMESPACE IS ENFORCED AT BOTH ENDS: hand-written groups are
+ * refused the `directory:` prefix (`assertReservedGroupNamespace`) and overlay groups are required to
+ * carry it ({@link parseGroupsFile}), so "prefixed" and "from the overlay" are the same set. It
+ * exists so a DEPLOYED instance — which cannot read its own repo — can still diff the live overlay
+ * against a fresh directory snapshot without a second config seam carrying the same data twice.
+ */
+export function directoryGroupsOf(groups) {
+    return { groups: groups.filter((g) => isDirectoryGroupName(g.name)) };
+}
+//# sourceMappingURL=groups-codemod.js.map

package/dist/agent/identity/groups-codemod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-codemod.js","sourceRoot":"","sources":["../../../agent/identity/groups-codemod.ts"],"names":[],"mappings":"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"}

package/dist/agent/identity/groups-delivery.d.ts

@@ -0,0 +1,56 @@
+import { type AccessRequestsConfig } from "../access/config.js";
+import { GitHubContents, type CommitId } from "../scm/contents.js";
+import { createBranch, getBranchSha } from "../scm/refs.js";
+import { createOrUpdatePullRequest } from "../scm/pr.js";
+import { type GroupSyncPlan } from "./group-sync.js";
+/** AccessRequestsConfig with the ONE field the group delivery needs PROVEN present. Unlike the
+ *  grants flow it does not require an admin channel — the group PR has no notification. */
+export type GroupsDeliveryConfig = AccessRequestsConfig & {
+    readonly configRepo: string;
+};
+/**
+ * The group-overlay delivery config, fail-closed: an absent loader or a missing config repo throws.
+ * Mirrors `requireAccessRequestsConfig` but demands only `configRepo` (no `adminChannel`) — a
+ * half-configured courier must refuse loudly, not silently do nothing on a control verb an admin
+ * expected to open a PR.
+ */
+export declare function requireGroupsDeliveryConfig(override?: AccessRequestsConfig): GroupsDeliveryConfig;
+/** Injectable seams for {@link deliverGroupsOverlay} — every network edge and the config lookup, so
+ *  the whole path is offline-testable (scripts/groups-test.ts) with the live defaults used
+ *  byte-for-byte in production. Mirrors AccessRequestExecuteDeps, minus the Slack `post`. */
+export interface GroupsDeliveryDeps {
+    readonly config?: AccessRequestsConfig;
+    readonly contents?: Pick<GitHubContents, "getFile" | "putFile">;
+    readonly getBranchSha?: typeof getBranchSha;
+    readonly createBranch?: typeof createBranch;
+    readonly createPr?: typeof createOrUpdatePullRequest;
+    readonly resolveToken?: (repo: string) => Promise<string>;
+    readonly committer?: CommitId;
+}
+/** What the delivery did. `outcome:"no-op"` means the overlay already matched the directory and no
+ *  PR was opened; `committed` is whether a fresh overlay commit landed (false on a re-run whose
+ *  branch already carries the identical bytes). */
+export interface GroupsDeliveryOutcome {
+    readonly outcome: "no-op" | "opened" | "updated";
+    readonly repo: string;
+    readonly branch: string;
+    readonly committed: boolean;
+    readonly pr?: {
+        readonly number: number;
+        readonly url: string;
+    };
+    readonly note: string;
+}
+/**
+ * The PR body — code-rendered from the machine-computed plan, NO model text at any point. Unlike the
+ * grants flow's body there is no `reason`/`universe` to sanitise: a group-sync plan is a pure diff
+ * of the directory against the overlay (`renderGroupPlan`), so every line here is either that diff or
+ * a host-authored constant. The doctrine footer states why merging is safe to reason about.
+ */
+export declare function groupsPrBody(plan: GroupSyncPlan): string;
+/**
+ * Delivers the plan's overlay as a bot-PR, and touches the SCM plane not at all when the plan changes nothing.
+ * The branch is directory-groups/<provider> and is STABLE, not per-run, so a re-run updates the same PR, and the overlay commit lands only when the bytes differ.
+ */
+export declare function deliverGroupsOverlay(plan: GroupSyncPlan, deps?: GroupsDeliveryDeps): Promise<GroupsDeliveryOutcome>;
+//# sourceMappingURL=groups-delivery.d.ts.map

package/dist/agent/identity/groups-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-delivery.d.ts","sourceRoot":"","sources":["../../../agent/identity/groups-delivery.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAKzD,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKvF;2FAC2F;AAC3F,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAUjG;AAED;;6FAE6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;CAC/B;AAED;;mDAEmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAkBxD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA8D7H"}

package/dist/agent/identity/groups-delivery.js

@@ -0,0 +1,116 @@
+// Bot-PR courier for the person-group overlay: it commits the planner's overlay to the config repo and opens or updates a PR whose merge IS the human approval.
+// Nothing takes effect on a running instance until that PR merges and the merged config redeploys; the path refuses loudly when no config repo is set, and a no-op plan opens no PR.
+import { getConfig } from "../access/config.js";
+import { GitHubContents } from "../scm/contents.js";
+import { createBranch, getBranchSha } from "../scm/refs.js";
+import { createOrUpdatePullRequest } from "../scm/pr.js";
+import { getGitHubApp } from "../scm/provider.js";
+import { resolveConfigRepoWriteToken } from "../scm/config-repo-token.js";
+import { isSafeBranchName } from "../scm/git.js";
+import { emitGroupsModule } from "./groups-codemod.js";
+import { groupPlanIsNoop, renderGroupPlan } from "./group-sync.js";
+/** The default repo-relative path of the person-group overlay — the file the codemod owns. */
+const DEFAULT_GROUPS_OVERLAY_PATH = "agent/identity/groups.generated.ts";
+/**
+ * The group-overlay delivery config, fail-closed: an absent loader or a missing config repo throws.
+ * Mirrors `requireAccessRequestsConfig` but demands only `configRepo` (no `adminChannel`) — a
+ * half-configured courier must refuse loudly, not silently do nothing on a control verb an admin
+ * expected to open a PR.
+ */
+export function requireGroupsDeliveryConfig(override) {
+    const cfg = override ?? getConfig().loadAccessRequests?.() ?? undefined;
+    if (!cfg?.configRepo) {
+        throw new Error("IdP group-overlay bot-PR delivery isn't configured on this deployment — an operator must set the config repo " +
+            "(AppConfig.loadAccessRequests; env OE_ACCESS_CONFIG_REPO). Until then, directory_groups_plan still returns the " +
+            "overlay content for an admin to commit by hand.");
+    }
+    return cfg;
+}
+/**
+ * The PR body — code-rendered from the machine-computed plan, NO model text at any point. Unlike the
+ * grants flow's body there is no `reason`/`universe` to sanitise: a group-sync plan is a pure diff
+ * of the directory against the overlay (`renderGroupPlan`), so every line here is either that diff or
+ * a host-authored constant. The doctrine footer states why merging is safe to reason about.
+ */
+export function groupsPrBody(plan) {
+    const diff = renderGroupPlan(plan);
+    return [
+        `Sync the person-group overlay against the \`${plan.provider}\` directory.`,
+        "",
+        `${plan.people} directory person(s) diffed — ${plan.counts.addGroup} group(s) added, ${plan.counts.dropGroup} dropped, ` +
+            `${plan.counts.addMember} member(s) added, ${plan.counts.removeMember} removed.`,
+        "",
+        ...(diff.length ? diff : ["(no changes)"]),
+        ...(plan.warnings.length ? ["", "Warnings (the planner refused to act on these):", ...plan.warnings.map((w) => `- ${w}`)] : []),
+        "",
+        "---",
+        "This diff was produced by the deterministic person-group codemod from a directory snapshot — no model authored any",
+        "part of it. The groups are `directory:`-namespaced (they cannot collide with hand-written ones) and every member is a",
+        "link-set reference, so a person contributes only the accounts they have CONFIRMED. Merging this PR IS the approval:",
+        "the memberships take effect on the next deploy of the merged config. Closing it unmerged declines the sync.",
+        "See docs/how-it-works/access-and-scoping.md.",
+    ].join("\n");
+}
+/**
+ * Delivers the plan's overlay as a bot-PR, and touches the SCM plane not at all when the plan changes nothing.
+ * The branch is directory-groups/<provider> and is STABLE, not per-run, so a re-run updates the same PR, and the overlay commit lands only when the bytes differ.
+ */
+export async function deliverGroupsOverlay(plan, deps = {}) {
+    const cfg = requireGroupsDeliveryConfig(deps.config);
+    const repo = cfg.configRepo;
+    const base = cfg.configBase ?? "main";
+    const groupsPath = cfg.groupsPath ?? DEFAULT_GROUPS_OVERLAY_PATH;
+    const branch = `directory-groups/${plan.provider}`;
+    if (!isSafeBranchName(branch)) {
+        // provider.id is a stable, operator-controlled token ("okta"); this only fires on a garbage one.
+        throw new Error(`unsafe directory-groups branch name "${branch}" (from provider id "${plan.provider}")`);
+    }
+    if (groupPlanIsNoop(plan)) {
+        return {
+            outcome: "no-op",
+            repo,
+            branch,
+            committed: false,
+            note: "the overlay already matches the directory — no PR opened.",
+        };
+    }
+    const overlayContent = emitGroupsModule(plan.next);
+    const token = await (deps.resolveToken ?? resolveConfigRepoWriteToken)(repo);
+    const contents = deps.contents ?? new GitHubContents();
+    const refSha = deps.getBranchSha ?? getBranchSha;
+    const mkBranch = deps.createBranch ?? createBranch;
+    const openPr = deps.createPr ?? createOrUpdatePullRequest;
+    let branchSha = await refSha({ repo, branch, token });
+    if (branchSha === null) {
+        const baseSha = await refSha({ repo, branch: base, token });
+        if (baseSha === null)
+            throw new Error(`config repo ${repo} has no base branch "${base}" — check accessRequests.configBase.`);
+        await mkBranch({ repo, branch, sha: baseSha, token });
+        branchSha = baseSha;
+    }
+    // The codemod emits byte-stable output, so comparing the committed bytes is an honest test for a real change rather than a formatting artefact.
+    const existing = await contents.getFile(repo, groupsPath, branch, token);
+    let committed = false;
+    if (!existing || existing.content !== overlayContent) {
+        const committer = deps.committer ?? getGitHubApp()?.committer() ?? { name: "open-everywhere[bot]", email: "open-everywhere@users.noreply.github.com" };
+        await contents.putFile(repo, groupsPath, overlayContent, `directory group sync: ${plan.provider}`, branch, token, committer, existing?.sha);
+        committed = true;
+    }
+    const pr = await openPr({
+        repo,
+        head: branch,
+        base,
+        title: `Directory group sync: ${plan.provider}`,
+        body: groupsPrBody(plan),
+        token,
+    });
+    return {
+        outcome: pr.updated ? "updated" : "opened",
+        repo,
+        branch,
+        committed,
+        pr: { number: pr.number, url: pr.url },
+        note: `${pr.updated ? "updated" : "opened"} PR #${pr.number} — ${pr.url}; an admin merges it in GitHub to apply the group overlay (nothing takes effect until they do).`,
+    };
+}
+//# sourceMappingURL=groups-delivery.js.map

package/dist/agent/identity/groups-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-delivery.js","sourceRoot":"","sources":["../../../agent/identity/groups-delivery.ts"],"names":[],"mappings":"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"}

package/dist/agent/identity/groups.d.ts

@@ -0,0 +1,74 @@
+/** 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 declare function defineGroup(group: Group): Group;
+/** Is this member the link-set (one HUMAN) form rather than the principal-key (one ACCOUNT) form? */
+export declare function isLinkSetMember(member: GroupMember): member is GroupLinkSetMember;
+/** 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 declare function groupLinkSets(group: Group): readonly string[];
+/** Every principal key this group names DIRECTLY (the pure, no-DB half of its membership). */
+export declare function groupPrincipalKeys(group: Group): readonly 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 declare 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 declare function directoryGroupName(idpGroup: string): string;
+/** Is this a machine-owned, directory-synced group name? */
+export declare function isDirectoryGroupName(name: string): boolean;
+/**
+ * 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 declare function assertGroupsValid(groups: readonly Group[]): void;
+/**
+ * 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 declare function assertReservedGroupNamespace(groups: readonly Group[]): void;
+/**
+ * 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 declare function groupsForPrincipal(groups: readonly Group[], callerKey: string | undefined, linkSetIds?: readonly string[]): readonly string[];
+//# sourceMappingURL=groups.d.ts.map

package/dist/agent/identity/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../agent/identity/groups.ts"],"names":[],"mappings":"AAMA;wEACwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,kBAAkB,CAAC;AAEtD,MAAM,WAAW,KAAK;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;kEAE8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,IAAI,kBAAkB,CAEjF;AAED;8EAC8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,MAAM,EAAE,CAE7D;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,MAAM,EAAE,CAElE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;iDAEiD;AACjD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CAyChE;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CAY3E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,SAAS,MAAM,EAAE,CAcnB"}

package/dist/agent/identity/groups.js

@@ -0,0 +1,124 @@
+// 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";
+/** Identity-with-types helper (Eve's define* convention; returns unchanged). */
+export function defineGroup(group) {
+    return group;
+}
+/** Is this member the link-set (one HUMAN) form rather than the principal-key (one ACCOUNT) form? */
+export function isLinkSetMember(member) {
+    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) {
+    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) {
+    return group.members.filter((m) => 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) {
+    return `${DIRECTORY_GROUP_PREFIX}${idpGroup}`;
+}
+/** Is this a machine-owned, directory-synced group name? */
+export function isDirectoryGroupName(name) {
+    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) {
+    const bad = [];
+    const seen = new Set();
+    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();
+        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) {
+    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, callerKey, linkSetIds = []) {
+    if (!callerKey)
+        return [];
+    const sets = new Set(linkSetIds);
+    const out = new Set();
+    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();
+}
+//# sourceMappingURL=groups.js.map

package/dist/agent/identity/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../agent/identity/groups.ts"],"names":[],"mappings":"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"}

package/dist/agent/identity/link-challenge.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare 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 declare 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 declare const LINK_CHALLENGE_TTL_MS: number;
+/**
+ * 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 declare function mintLinkCode(): string;
+/**
+ * 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 declare function hashLinkCode(code: string): string;
+/**
+ * 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 declare function redactMachineLinkCodes(text: string): string;
+/**
+ * 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 declare function detectLinkClaim(text: string | undefined): string | 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 declare function detectAddressedLinkClaim(text: string | undefined, addressTokens?: readonly string[]): string | 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 declare function linkClaimInstructions(code: string, ttlMinutes: number): string;
+//# sourceMappingURL=link-challenge.d.ts.map

package/dist/agent/identity/link-challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-challenge.d.ts","sourceRoot":"","sources":["../../../agent/identity/link-challenge.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,kBAAkB,oCAAoC,CAAC;AAEpE;0FAC0F;AAC1F,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;sEAGsE;AACtE,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAmBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI5E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,GAAG,SAAS,CAQ5H;AA2BD;;;;;;;;iGAQiG;AACjG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAa9E"}