@bevel-software/platform-core-backend 0.9.1 → 0.11.0

package/dist/modules/access/directory-sync-bot.js

@@ -0,0 +1,64 @@
+import { eq } from 'drizzle-orm';
+import { users } from '../database/core-schema.js';
+/**
+ * Synthetic identity for the synced-groups materializer's commits: every
+ * `synced-groups.yaml` regeneration lands attributed to this bot, so the git
+ * history reads as "the system mirrored the IdP", never as any human.
+ * Same `<role>-bot@<host>` convention (and race-safe ensure shape) as the
+ * recovery bot.
+ */
+// Trimmed BEFORE the empty-fallback so a whitespace-only override falls back,
+// and so the constant always compares equal to a trimmed caller email (the
+// machine-owned write rule trims the caller's side).
+export const DIRECTORY_SYNC_BOT_EMAIL = (process.env.DIRECTORY_SYNC_BOT_EMAIL?.trim() || 'directory-sync@bevel.local').toLowerCase();
+export const DIRECTORY_SYNC_BOT_NAME = 'Directory Sync Bot';
+export async function ensureDirectorySyncBot(db) {
+    const inserted = await db
+        .insert(users)
+        .values({ email: DIRECTORY_SYNC_BOT_EMAIL, name: DIRECTORY_SYNC_BOT_NAME })
+        .onConflictDoNothing({ target: users.email })
+        .returning();
+    if (inserted.length > 0) {
+        const row = inserted[0];
+        console.log(`[directory-sync] created sync-bot user id=${row.id} email=${row.email}`);
+        return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
+    }
+    const [row] = await db
+        .select()
+        .from(users)
+        .where(eq(users.email, DIRECTORY_SYNC_BOT_EMAIL))
+        .limit(1);
+    if (!row) {
+        throw new Error(`directory-sync bot (${DIRECTORY_SYNC_BOT_EMAIL}) disappeared between insert-conflict and re-select`);
+    }
+    // The bot's IDENTITY is its email: the machine-owned write rule on
+    // synced-groups.yaml authorizes by DIRECTORY_SYNC_BOT_EMAIL alone. If the
+    // email already belongs to a pre-existing HUMAN account (a person signed up
+    // with it, or the override points at someone's address), silently binding
+    // the materializer to that row would attribute every sync commit to them —
+    // and, worse, hand their interactive session the bot's exclusive write
+    // authority. The users schema carries no dedicated bot/provenance column,
+    // so adoption gates on the strongest invariants the row can carry:
+    //   1. NO PASSWORD. The bot is only ever created by this function, without
+    //      credentials, and never signs in — nothing legitimate ever provisions
+    //      it a password. A row with a password hash is a login-capable account
+    //      (a person, or a credential a person could use) no matter what its
+    //      display name says, so the hash is the hard evidence a name can't be.
+    //   2. THE EXPECTED NAME. A display name is mutable and a human account
+    //      could carry the bot's name (e.g. an SSO service account), so this is
+    //      only a tripwire — it still catches password-less human rows created
+    //      under their real names.
+    // A password-less SSO account that also mimics the bot's exact display name
+    // is indistinguishable at this layer; that shape only arises from the
+    // operator deliberately configuring it. Refuse loudly instead of adopting.
+    if (row.passwordHash !== null || row.name !== DIRECTORY_SYNC_BOT_NAME) {
+        const evidence = row.passwordHash !== null
+            ? `it can sign in with a password (name '${row.name}')`
+            : `its name is '${row.name}'`;
+        throw new Error(`directory-sync bot email ${DIRECTORY_SYNC_BOT_EMAIL} already belongs to an existing account ` +
+            `(id=${row.id}) that is not the sync bot — ${evidence}. Refusing to bind the materializer ` +
+            `to it. Set DIRECTORY_SYNC_BOT_EMAIL to an address no person uses.`);
+    }
+    return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
+}
+//# sourceMappingURL=directory-sync-bot.js.map

package/dist/modules/access/directory-sync-bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-sync-bot.js","sourceRoot":"","sources":["../../../src/modules/access/directory-sync-bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAGjC,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAEnD;;;;;;GAMG;AAEH,8EAA8E;AAC9E,2EAA2E;AAC3E,qDAAqD;AACrD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,IAAI,4BAA4B,CAC7E,CAAC,WAAW,EAAE,CAAC;AAEhB,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAAY;IACvD,MAAM,QAAQ,GAAG,MAAM,EAAE;SACtB,MAAM,CAAC,KAAK,CAAC;SACb,MAAM,CAAC,EAAE,KAAK,EAAE,wBAAwB,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;SAC1E,mBAAmB,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;SAC5C,SAAS,EAAE,CAAC;IACf,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,6CAA6C,GAAG,CAAC,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QACtF,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;IACjG,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,EAAE;SACR,IAAI,CAAC,KAAK,CAAC;SACX,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAC;SAChD,KAAK,CAAC,CAAC,CAAC,CAAC;IACZ,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,uBAAuB,wBAAwB,qDAAqD,CACrG,CAAC;IACJ,CAAC;IACD,mEAAmE;IACnE,0EAA0E;IAC1E,4EAA4E;IAC5E,0EAA0E;IAC1E,2EAA2E;IAC3E,uEAAuE;IACvE,0EAA0E;IAC1E,mEAAmE;IACnE,2EAA2E;IAC3E,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,wEAAwE;IACxE,4EAA4E;IAC5E,2EAA2E;IAC3E,+BAA+B;IAC/B,4EAA4E;IAC5E,sEAAsE;IACtE,2EAA2E;IAC3E,IAAI,GAAG,CAAC,YAAY,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,uBAAuB,EAAE,CAAC;QACtE,MAAM,QAAQ,GACZ,GAAG,CAAC,YAAY,KAAK,IAAI;YACvB,CAAC,CAAC,yCAAyC,GAAG,CAAC,IAAI,IAAI;YACvD,CAAC,CAAC,gBAAgB,GAAG,CAAC,IAAI,GAAG,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,4BAA4B,wBAAwB,0CAA0C;YAC5F,OAAO,GAAG,CAAC,EAAE,gCAAgC,QAAQ,sCAAsC;YAC3F,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;AACjG,CAAC"}

package/dist/modules/access/group-files.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Group files — the "who you are" half of the roles/groups split.
+ *
+ * Groups are people-sets referenced by access grants ("GTM Team can read the
+ * battlecards"). A deployment has exactly ONE group source at a time — a mode
+ * derived from which file exists, so it holds at any git ref:
+ *
+ *   - `synced-groups.yaml` EXISTS  → IdP mode. The file is MACHINE-OWNED,
+ *     regenerated wholesale from the SCIM directory mirror; membership is
+ *     managed in the IdP. `groups.yaml` is ignored entirely.
+ *   - otherwise                    → manual mode. `groups.yaml` (UI-edited)
+ *     is the source.
+ *
+ * Both files share one format, the group twin of roles.yaml:
+ *
+ *   groups:
+ *     Engineering:
+ *       - ada@x.io
+ *       - bo@x.io
+ *     Empty Group: []
+ *
+ * Parsing is FORGIVING at the entry level by design — a malformed email or a
+ * reserved/duplicate name skips that entry with a warning, it never takes the
+ * whole file down. Only structural failures (unparsable YAML, `groups:` not a
+ * mapping) reject the file, and even then the RESOLVER degrades to "this file
+ * contributes nothing" rather than throwing: unlike roles.yaml there is no
+ * admin-lockout risk here, so groups must never be able to brick access
+ * resolution. Strict acceptance for WRITES is the job of the write-side
+ * validator (`validateGroupsFile` below), which treats warnings as refusals.
+ */
+export declare const GROUPS_YAML = "groups.yaml";
+export declare const SYNCED_GROUPS_YAML = "synced-groups.yaml";
+/**
+ * THE name-safety predicate for principal display names — the single source
+ * of truth every surface derives from (group creation/rename, IdP sync
+ * materialization; thin assert wrappers sit on top). Returns a human-readable
+ * reason the name is unsafe, or null when it is fine.
+ *
+ * The character rules keep the emitted YAML parseable and the entry grammar
+ * unambiguous:
+ *   `:`        mis-tokenises as a nested mapping key
+ *   `#`        truncated as a comment by the subset parser's stripComment
+ *   `<` / `>`  collide with the `Name <email>` user-reference shape
+ *   leading -  tokenises as a list item
+ *   \x00-\x1f  control chars / newlines break line structure outright
+ *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
+ *              entries — a group carrying it could never be referenced.
+ */
+export declare function unsafeNameReason(displayName: string): string | null;
+/** One parsed group: display name + canonicalised member emails. */
+export interface GroupDefinition {
+    displayName: string;
+    emails: Set<string>;
+}
+/** Canonical group name → definition, in file order. */
+export type GroupsIndex = Map<string, GroupDefinition>;
+export interface ParsedGroupsFile {
+    ok: true;
+    groups: GroupsIndex;
+    /** Entry-level problems that were skipped over (bad email, dup name, …). */
+    warnings: string[];
+}
+export interface GroupsFileError {
+    ok: false;
+    errors: string[];
+}
+/**
+ * Parse a group file (either of the two — same grammar). See the module note
+ * for the forgiving-vs-structural split.
+ */
+export declare function parseGroupsFile(text: string, filename: string): ParsedGroupsFile | GroupsFileError;
+/**
+ * Write-gate twin of {@link parseGroupsFile}: strict — structural errors AND
+ * entry-level warnings both refuse the candidate, so a UI write can never land
+ * a group the resolver would silently skip.
+ */
+export declare function validateGroupsFile(text: string, filename: string): {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+//# sourceMappingURL=group-files.d.ts.map

package/dist/modules/access/group-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-files.d.ts","sourceRoot":"","sources":["../../../src/modules/access/group-files.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWnE;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,WAAW,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,gBAAgB,GAAG,eAAe,CAyFpC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhD"}

package/dist/modules/access/group-files.js

@@ -0,0 +1,167 @@
+import { EMAIL_REGEX, GROUP_REF_PREFIX, RESERVED_ROLE_NAMES, ROLE_TOKEN_PREFIX, canonicalEmail, canonicalRoleName, parseYamlSubset, } from './access-control.service.js';
+/**
+ * Group files — the "who you are" half of the roles/groups split.
+ *
+ * Groups are people-sets referenced by access grants ("GTM Team can read the
+ * battlecards"). A deployment has exactly ONE group source at a time — a mode
+ * derived from which file exists, so it holds at any git ref:
+ *
+ *   - `synced-groups.yaml` EXISTS  → IdP mode. The file is MACHINE-OWNED,
+ *     regenerated wholesale from the SCIM directory mirror; membership is
+ *     managed in the IdP. `groups.yaml` is ignored entirely.
+ *   - otherwise                    → manual mode. `groups.yaml` (UI-edited)
+ *     is the source.
+ *
+ * Both files share one format, the group twin of roles.yaml:
+ *
+ *   groups:
+ *     Engineering:
+ *       - ada@x.io
+ *       - bo@x.io
+ *     Empty Group: []
+ *
+ * Parsing is FORGIVING at the entry level by design — a malformed email or a
+ * reserved/duplicate name skips that entry with a warning, it never takes the
+ * whole file down. Only structural failures (unparsable YAML, `groups:` not a
+ * mapping) reject the file, and even then the RESOLVER degrades to "this file
+ * contributes nothing" rather than throwing: unlike roles.yaml there is no
+ * admin-lockout risk here, so groups must never be able to brick access
+ * resolution. Strict acceptance for WRITES is the job of the write-side
+ * validator (`validateGroupsFile` below), which treats warnings as refusals.
+ */
+export const GROUPS_YAML = 'groups.yaml';
+export const SYNCED_GROUPS_YAML = 'synced-groups.yaml';
+/**
+ * THE name-safety predicate for principal display names — the single source
+ * of truth every surface derives from (group creation/rename, IdP sync
+ * materialization; thin assert wrappers sit on top). Returns a human-readable
+ * reason the name is unsafe, or null when it is fine.
+ *
+ * The character rules keep the emitted YAML parseable and the entry grammar
+ * unambiguous:
+ *   `:`        mis-tokenises as a nested mapping key
+ *   `#`        truncated as a comment by the subset parser's stripComment
+ *   `<` / `>`  collide with the `Name <email>` user-reference shape
+ *   leading -  tokenises as a list item
+ *   \x00-\x1f  control chars / newlines break line structure outright
+ *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
+ *              entries — a group carrying it could never be referenced.
+ */
+export function unsafeNameReason(displayName) {
+    const trimmed = displayName.trim();
+    if (!trimmed)
+        return 'empty name';
+    if (/[:#<>]/.test(trimmed))
+        return "contains ':', '#', '<', or '>'";
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f]/.test(trimmed))
+        return 'contains control characters';
+    if (trimmed.startsWith('-'))
+        return "starts with '-'";
+    if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
+        return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
+    }
+    return null;
+}
+/**
+ * Parse a group file (either of the two — same grammar). See the module note
+ * for the forgiving-vs-structural split.
+ */
+export function parseGroupsFile(text, filename) {
+    // Tolerate empty keys at parse: this file's contract is ENTRY-level
+    // forgiveness (a blank group name is skipped with a warning below), and a
+    // hard tokenizer error here would retire every OTHER group fail-closed.
+    const parsed = parseYamlSubset(text, { tolerateEmptyKeys: true });
+    if (!parsed.ok)
+        return { ok: false, errors: [`${filename}: ${parsed.error}`] };
+    const root = parsed.value;
+    if (root == null || typeof root !== 'object' || Array.isArray(root)) {
+        return { ok: false, errors: [`${filename}: must be a top-level mapping`] };
+    }
+    const groupsNode = root.groups;
+    // An empty file (or one with no `groups:` key yet) is a valid empty set —
+    // a fresh deployment's groups.yaml starts this way.
+    if (groupsNode == null)
+        return { ok: true, groups: new Map(), warnings: [] };
+    if (typeof groupsNode !== 'object' || Array.isArray(groupsNode)) {
+        return { ok: false, errors: [`${filename}: 'groups' must be a mapping`] };
+    }
+    const groups = new Map();
+    const warnings = [];
+    for (const [displayName, value] of Object.entries(groupsNode)) {
+        const canonical = canonicalRoleName(displayName);
+        if (!canonical) {
+            warnings.push(`${filename}: empty group name — skipped`);
+            continue;
+        }
+        // THE shared name-safety predicate (see `unsafeNameReason` above) — the
+        // same rules every write surface asserts. The parser must apply it too:
+        // a name the writers refuse (control chars, `<`/`>`, a leading `-`, the
+        // reserved `role/` prefix) can still reach a group file by hand edit or
+        // through a skewed writer, and accepting it here would let the resolver
+        // honor — and `validateGroupsFile` pass — a name no editor can ever
+        // produce or reference safely.
+        const unsafe = unsafeNameReason(displayName);
+        if (unsafe) {
+            warnings.push(`${filename}: group ${JSON.stringify(displayName)} ${unsafe} — skipped`);
+            continue;
+        }
+        if (RESERVED_ROLE_NAMES.has(canonical)) {
+            warnings.push(`${filename}: group '${displayName}' uses reserved name '${canonical}' — skipped`);
+            continue;
+        }
+        if (groups.has(canonical)) {
+            warnings.push(`${filename}: group '${displayName}' canonicalises to '${canonical}', already declared as '${groups.get(canonical).displayName}' — skipped`);
+            continue;
+        }
+        if (value !== null && !Array.isArray(value)) {
+            warnings.push(`${filename}: group '${displayName}' must be a list of emails — skipped`);
+            continue;
+        }
+        const emails = new Set();
+        for (const raw of value ?? []) {
+            if (typeof raw !== 'string') {
+                warnings.push(`${filename}: group '${displayName}' has a non-string entry — entry skipped`);
+                continue;
+            }
+            const email = canonicalEmail(raw);
+            // The reserved `group:` prefix would PASS the email regex
+            // (`group:lee@x.io` shapes like an email) but it is the roles.yaml
+            // group-reference token, not an address — groups contain emails, never
+            // other groups. Skip it with its own warning so the write gate refuses
+            // it and the resolver never grants a colon-bearing "email".
+            if (email.startsWith(GROUP_REF_PREFIX)) {
+                warnings.push(`${filename}: group '${displayName}' has a '${GROUP_REF_PREFIX}'-prefixed entry ${JSON.stringify(raw)} — groups contain emails, not group references; entry skipped`);
+                continue;
+            }
+            if (!EMAIL_REGEX.test(email)) {
+                warnings.push(`${filename}: group '${displayName}' has malformed email '${raw}' — entry skipped`);
+                continue;
+            }
+            emails.add(email);
+        }
+        groups.set(canonical, { displayName: displayName.trim(), emails });
+    }
+    return { ok: true, groups, warnings };
+}
+/**
+ * Write-gate twin of {@link parseGroupsFile}: strict — structural errors AND
+ * entry-level warnings both refuse the candidate, so a UI write can never land
+ * a group the resolver would silently skip.
+ */
+export function validateGroupsFile(text, filename) {
+    // Strict PARSE first (no empty-key tolerance): the read side forgives a
+    // blank key entry-level so other groups keep resolving, but a WRITE that
+    // contains one — anywhere, including outside the `groups:` mapping — must
+    // refuse rather than land bytes the tolerant reader silently drops.
+    const strict = parseYamlSubset(text.trim() ? text : 'groups:');
+    if (!strict.ok)
+        return { ok: false, errors: [`${filename}: ${strict.error}`] };
+    const parsed = parseGroupsFile(text, filename);
+    if (!parsed.ok)
+        return { ok: false, errors: parsed.errors };
+    if (parsed.warnings.length > 0)
+        return { ok: false, errors: parsed.warnings };
+    return { ok: true };
+}
+//# sourceMappingURL=group-files.js.map

package/dist/modules/access/group-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-files.js","sourceRoot":"","sources":["../../../src/modules/access/group-files.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,YAAY,CAAC;IAClC,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,gCAAgC,CAAC;IACpE,4CAA4C;IAC5C,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,6BAA6B,CAAC;IACtE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACtD,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC7D,OAAO,6BAA6B,iBAAiB,sDAAsD,CAAC;IAC9G,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAuBD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,QAAgB;IAEhB,oEAAoE;IACpE,0EAA0E;IAC1E,wEAAwE;IACxE,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;IAE/E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC;IAC1B,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,+BAA+B,CAAC,EAAE,CAAC;IAC7E,CAAC;IAED,MAAM,UAAU,GAAI,IAAgC,CAAC,MAAM,CAAC;IAC5D,0EAA0E;IAC1E,oDAAoD;IACpD,IAAI,UAAU,IAAI,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC7E,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,8BAA8B,CAAC,EAAE,CAAC;IAC5E,CAAC;IAED,MAAM,MAAM,GAAgB,IAAI,GAAG,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAqC,CAAC,EAAE,CAAC;QACzF,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,8BAA8B,CAAC,CAAC;YACzD,SAAS;QACX,CAAC;QACD,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,wEAAwE;QACxE,oEAAoE;QACpE,+BAA+B;QAC/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,MAAM,EAAE,CAAC;YACX,QAAQ,CAAC,IAAI,CACX,GAAG,QAAQ,WAAW,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,MAAM,YAAY,CACxE,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CACX,GAAG,QAAQ,YAAY,WAAW,yBAAyB,SAAS,aAAa,CAClF,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CACX,GAAG,QAAQ,YAAY,WAAW,uBAAuB,SAAS,2BAA2B,MAAM,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,WAAW,aAAa,CAC7I,CAAC;YACF,SAAS;QACX,CAAC;QACD,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,YAAY,WAAW,sCAAsC,CAAC,CAAC;YACxF,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;YAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,YAAY,WAAW,0CAA0C,CAAC,CAAC;gBAC5F,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;YAClC,0DAA0D;YAC1D,mEAAmE;YACnE,uEAAuE;YACvE,uEAAuE;YACvE,4DAA4D;YAC5D,IAAI,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;gBACvC,QAAQ,CAAC,IAAI,CACX,GAAG,QAAQ,YAAY,WAAW,YAAY,gBAAgB,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,+DAA+D,CACrK,CAAC;gBACF,SAAS;YACX,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,QAAQ,CAAC,IAAI,CACX,GAAG,QAAQ,YAAY,WAAW,0BAA0B,GAAG,mBAAmB,CACnF,CAAC;gBACF,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,WAAW,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,QAAgB;IAEhB,wEAAwE;IACxE,yEAAyE;IACzE,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;IAC/E,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IAC5D,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC9E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/modules/access/groups-admin.routes.d.ts

@@ -0,0 +1,19 @@
+import express from 'express';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { GroupsAdminService } from './groups-admin.service.js';
+import '../auth/auth.middleware.js';
+/**
+ * Admin surface for GROUPS — the "who you are" half of the roles/groups
+ * split. Manual-mode CRUD on `groups.yaml`; in IdP mode the service refuses
+ * mutations with a typed 409 (`kind: 'idp-mode'`) and this router simply
+ * relays it. Admin-gated like the other admin routers: the roster is the org
+ * chart, not something every signed-in user may enumerate.
+ */
+export declare function createGroupsAdminRoutes(deps: {
+    groupsAdmin: GroupsAdminService;
+    adminAccess: IAdminAccessService;
+    /** Resolve the acting user for commit attribution. */
+    getUserById: (id: string) => Promise<AuthUser | null>;
+}): express.Router;
+//# sourceMappingURL=groups-admin.routes.d.ts.map

package/dist/modules/access/groups-admin.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-admin.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/access/groups-admin.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,4BAA4B,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,mBAAmB,CAAC;IACjC,sDAAsD;IACtD,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACvD,GAAG,OAAO,CAAC,MAAM,CA4FjB"}

package/dist/modules/access/groups-admin.routes.js

@@ -0,0 +1,98 @@
+import express from 'express';
+import { canonicalRoleName } from './access-control.service.js';
+import { sendError as sharedSendError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+/**
+ * Admin surface for GROUPS — the "who you are" half of the roles/groups
+ * split. Manual-mode CRUD on `groups.yaml`; in IdP mode the service refuses
+ * mutations with a typed 409 (`kind: 'idp-mode'`) and this router simply
+ * relays it. Admin-gated like the other admin routers: the roster is the org
+ * chart, not something every signed-in user may enumerate.
+ */
+export function createGroupsAdminRoutes(deps) {
+    const { groupsAdmin, adminAccess, getUserById } = deps;
+    const router = express.Router();
+    const requireAdmin = async (req, res, next) => {
+        if (!(await adminAccess.isAdmin(req.userEmail))) {
+            res.status(403).json({ error: 'Admins only' });
+            return;
+        }
+        next();
+    };
+    const actorOf = async (req) => {
+        const user = req.userId ? await getUserById(req.userId) : null;
+        if (user)
+            return user;
+        // The JWT authenticated but the row is gone (erased mid-session) — the
+        // identity claims are still the honest attribution we hold.
+        return { id: req.userId ?? 'unknown', email: req.userEmail ?? 'unknown', name: req.userEmail ?? 'unknown' };
+    };
+    // Shared access-family error shape + input coercion (admin-route-helpers):
+    // typed domain errors (incl. the roster's broken-groups 422) render
+    // themselves; anything else logs server-side and answers generically.
+    const sendError = (res, err) => sharedSendError(res, err, 'groups');
+    const requireNonEmptyString = (value, field) => sharedRequireNonEmptyString(value, field, { trim: true });
+    // GET /api/admin/groups — mode + roster (groups with grant references and
+    // role assignments) + `groupsHealth` (the broken-source banner marker; a
+    // broken MANUAL groups.yaml instead answers 422 with the parse message so
+    // the operator sees what to fix).
+    router.get('/admin/groups', requireAdmin, async (_req, res) => {
+        try {
+            res.json(await groupsAdmin.getRoster());
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.post('/admin/groups', requireAdmin, async (req, res) => {
+        try {
+            const displayName = requireNonEmptyString((req.body ?? {}).displayName, 'displayName');
+            res.json(await groupsAdmin.createGroup(await actorOf(req), displayName));
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.delete('/admin/groups/:canonical', requireAdmin, async (req, res) => {
+        try {
+            const canonical = canonicalRoleName(String(req.params.canonical));
+            res.json(await groupsAdmin.deleteGroup(await actorOf(req), canonical));
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    // PATCH /api/admin/groups/:canonical { newDisplayName } — rename;
+    // canonical-changing renames rewrite grant references atomically.
+    router.patch('/admin/groups/:canonical', requireAdmin, async (req, res) => {
+        try {
+            const canonical = canonicalRoleName(String(req.params.canonical));
+            const newDisplayName = requireNonEmptyString((req.body ?? {}).newDisplayName, 'newDisplayName');
+            res.json(await groupsAdmin.renameGroup(await actorOf(req), canonical, newDisplayName));
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.post('/admin/groups/:canonical/members', requireAdmin, async (req, res) => {
+        try {
+            const canonical = canonicalRoleName(String(req.params.canonical));
+            const email = requireNonEmptyString((req.body ?? {}).email, 'email');
+            res.json(await groupsAdmin.addMember(await actorOf(req), canonical, email));
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.delete('/admin/groups/:canonical/members/:email', requireAdmin, async (req, res) => {
+        try {
+            const canonical = canonicalRoleName(String(req.params.canonical));
+            res.json(await groupsAdmin.removeMember(await actorOf(req), canonical, String(req.params.email)));
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=groups-admin.routes.js.map

package/dist/modules/access/groups-admin.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-admin.routes.js","sourceRoot":"","sources":["../../../src/modules/access/groups-admin.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,SAAS,IAAI,eAAe,EAAE,qBAAqB,IAAI,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAE9H,OAAO,4BAA4B,CAAC,CAAC,+BAA+B;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAKvC;IACC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,YAAY,GAA2B,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACpE,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,EAAE,GAAoB,EAAqB,EAAE;QAChE,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/D,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QACtB,uEAAuE;QACvE,4DAA4D;QAC5D,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,IAAI,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;IAC9G,CAAC,CAAC;IAEF,2EAA2E;IAC3E,oEAAoE;IACpE,sEAAsE;IACtE,MAAM,SAAS,GAAG,CAAC,GAAqB,EAAE,GAAY,EAAQ,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IAErG,MAAM,qBAAqB,GAAG,CAAC,KAAc,EAAE,KAAa,EAAU,EAAE,CACtE,2BAA2B,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5D,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,kCAAkC;IAClC,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC5D,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC5D,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,qBAAqB,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;YACvF,GAAG,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;QAC3E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,0BAA0B,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACzE,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAClE,GAAG,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,kEAAkE;IAClE,kEAAkE;IAClE,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxE,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAClE,MAAM,cAAc,GAAG,qBAAqB,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;YAChG,GAAG,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;QACzF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/E,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAClE,MAAM,KAAK,GAAG,qBAAqB,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACrE,GAAG,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,yCAAyC,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAClE,GAAG,CAAC,IAAI,CACN,MAAM,WAAW,CAAC,YAAY,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACxF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modules/access/groups-admin.service.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Admin Groups service — CRUD on the default-branch `groups.yaml` (manual
+ * mode), the mode probe, and the connect-time retirement of manual groups.
+ *
+ * Shares `RolesAdminService`'s write pipeline via the SHARED
+ * `AdminLockedCommits` helper (one lock/commit implementation — the twin
+ * copies diverged once into a real bug) with the policy differences the
+ * roles/groups split defines:
+ *
+ *   - MODE GATE: every mutation refuses in IdP mode (`synced-groups.yaml`
+ *     exists on the default branch). Groups are managed in the identity
+ *     provider then; a second write surface would fragment org management —
+ *     which is the thing the mode model exists to prevent.
+ *   - COLLISION GATE: create/rename refuse a name whose canonical form is a
+ *     roles.yaml role. Bare-name precedence would let the group win, but a
+ *     deliberately-created shadow of a capability role is far more likely a
+ *     mistake than an intent — the IdP can still produce collisions, which
+ *     precedence then resolves (group first, `role/<name>` for the role).
+ *   - DEGRADE LOUDLY: a broken groups source never fails access resolution
+ *     closed — groups contribute nothing and the model carries a
+ *     `groupsHealth` marker, which the roster exposes so the Groups page can
+ *     banner it. A broken MANUAL groups.yaml additionally makes the roster
+ *     answer 422 with the parse message (the operator must see what to fix —
+ *     never a dead Groups page, never a silent empty roster they might
+ *     "repair" by re-creating groups over live bytes).
+ */
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import { WorkflowDomainError } from '../workflow/workflow.errors.js';
+import type { IAccessControl } from './access-control.interface.js';
+import { type GroupsHealth } from './access-control.service.js';
+/** A group mutation that cannot proceed. `payload.kind` distinguishes the
+ *  mode refusal (`'idp-mode'`) for the UI. */
+export declare class GroupsAdminError extends WorkflowDomainError {
+    constructor(message: string, status?: number, payload?: Record<string, unknown>);
+}
+export type GroupsMode = 'manual' | 'idp';
+export interface GroupRosterEntry {
+    canonical: string;
+    displayName: string;
+    members: string[];
+    /** Every access rule referencing this group — same scan the rename uses. */
+    referencedBy: {
+        path: string;
+        verb: string;
+    }[];
+    /**
+     * Canonical names of roles carrying a `group:<canonical>` assignment to
+     * this group — so the delete confirm can warn that those roles will lose
+     * the members they inherit through it (deleteGroup unassigns them
+     * atomically).
+     */
+    assignedToRoles: string[];
+}
+export interface GroupsRoster {
+    mode: GroupsMode;
+    groups: GroupRosterEntry[];
+    /**
+     * Health of the active groups source — `ok: false` when the source exists
+     * but is unreadable/unparseable (resolution degrades: groups contribute
+     * nothing). Shipped for the Groups page banner (frontend increment).
+     */
+    groupsHealth: GroupsHealth;
+}
+export declare class GroupsAdminService {
+    private readonly workspaceService;
+    private readonly workflowService;
+    private readonly accessControl;
+    private readonly kbDirName;
+    /** Live-binding thunk — see RolesAdminService's identical note. */
+    private readonly defaultBranchOf;
+    private readonly eventBus?;
+    /** Shared lock/commit plumbing — see module doc. */
+    private readonly locked;
+    /** Shared cached reference scanner. */
+    private readonly references;
+    constructor(workspaceService: IWorkspaceService, workflowService: IWorkflowService, accessControl: IAccessControl, kbDirName: string, 
+    /** Live-binding thunk — see RolesAdminService's identical note. */
+    defaultBranchOf: () => string, eventBus?: WorkflowEventBus | undefined);
+    private get defaultBranch();
+    private get workspaceId();
+    private ensureWorkspace;
+    /**
+     * IdP mode iff `synced-groups.yaml` exists — same rule the resolver applies.
+     *
+     * KNOWN GAP, deliberate: this cannot see the connect WINDOW — a directory
+     * connection that is configured but whose first provisioning push has not
+     * landed the synced file yet. Core's `SyncedGroupsSource` seam exposes only
+     * `listGroups()` (the overlay owns the connection), so "connected but not
+     * yet materialized" is not cheaply knowable server-side; the UI keeps its
+     * own suppression for that window.
+     */
+    getMode(): Promise<GroupsMode>;
+    /**
+     * Mode + roster + source health. Reads the ACTIVE source through the same
+     * `loadActiveGroups` rule the resolver applies, so mode, health, and the
+     * group set can never disagree with resolution:
+     *
+     *   - IdP mode (synced file present, even broken): the roster IS the synced
+     *     file — read-only in the UI; the manual file is retired and showing it
+     *     would misreport who has access. A broken synced file yields an EMPTY
+     *     roster with the `groupsHealth` marker (mode stays 'idp' — no
+     *     fallback to manual, which would resurrect retired groups).
+     *   - Manual mode, broken groups.yaml: 422 with the parse message — the
+     *     repair path must show the operator what to fix, never a dead page.
+     */
+    getRoster(): Promise<GroupsRoster>;
+    /**
+     * Display names from the ACTIVE group source (synced in IdP mode, manual
+     * otherwise). Malformed files degrade to an empty list, matching the
+     * resolver's degrade rule.
+     */
+    listActiveGroupNames(): Promise<string[]>;
+    /** Manual group display names — what the connect-time warning dialog lists. */
+    listManualGroupNames(): Promise<string[]>;
+    createGroup(actor: AuthUser, displayName: string): Promise<GroupsRoster>;
+    /**
+     * Delete a group AND unassign it from every role — the `group:<canonical>`
+     * members in roles.yaml — in the SAME atomic locked commit (mirror of the
+     * rename's ref rewrite): a delete that left the refs would silently shrink
+     * each assigned role's membership behind a mere log warning. Grant
+     * references in access.md are NOT touched — a dangling grant resolves to
+     * nothing by design (and the roster's `referencedBy` fed the confirm
+     * dialog's warning).
+     */
+    deleteGroup(actor: AuthUser, canonical: string): Promise<GroupsRoster>;
+    addMember(actor: AuthUser, canonical: string, email: string): Promise<GroupsRoster>;
+    removeMember(actor: AuthUser, canonical: string, email: string): Promise<GroupsRoster>;
+    /**
+     * Rename — canonical-changing renames rewrite every grant reference in ONE
+     * atomic commit (same machinery, same reasoning as ref unassignment on
+     * delete: a partial rewrite is a silent access drop).
+     */
+    renameGroup(actor: AuthUser, canonical: string, newDisplayName: string): Promise<GroupsRoster>;
+    private renameGroupLocked;
+    /**
+     * Connect-time retirement: delete `groups.yaml` in one commit. Called by the
+     * SCIM connect flow AFTER the admin confirmed the warning dialog ("groups
+     * you don't recreate in the IdP will be lost"). Recovery is a git revert —
+     * the file's history keeps every retired group. No-op when the file is
+     * already absent.
+     */
+    retireManualGroups(actor: AuthUser): Promise<boolean>;
+    private guardEdit;
+    private assertLoadable;
+    private assertManualMode;
+    /**
+     * Refuse a group name that IS a role. Bare-name precedence (group-first)
+     * would make the group win resolution, so this is deliberate FRICTION, not
+     * a correctness need: an admin naming a group after a capability role is
+     * far more likely shadowing by accident than by intent. IdP-sourced
+     * collisions still happen (the sync writer doesn't consult roles.yaml) and
+     * precedence resolves them.
+     */
+    private assertRoleNameFree;
+    /**
+     * Which roles carry a `group:<canonical>` assignment, per group canonical.
+     * Advisory (feeds the roster's `assignedToRoles` warning field): a broken
+     * roles.yaml yields an empty map rather than failing the roster.
+     */
+    private rolesReferencingGroups;
+    private runEdit;
+    private runEditLocked;
+    private afterWrite;
+}
+//# sourceMappingURL=groups-admin.service.d.ts.map

package/dist/modules/access/groups-admin.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-admin.service.d.ts","sourceRoot":"","sources":["../../../src/modules/access/groups-admin.service.ts"],"names":[],"mappings":"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"}