@bevel-software/platform-core-backend 0.19.0 → 0.20.0

package/dist/modules/groups/group-provision.service.js

@@ -1,288 +0,0 @@
-/**
- * Group provisioning — the ONE privileged door for bringing a `Groups/<name>/`
- * folder into existence, and (via {@link GroupProvisionService.deleteGroup})
- * for taking one back out of it.
- *
- * Creating a group is the single operation the access model cannot govern
- * from inside: the folder that will carry the rules does not exist yet, and
- * the root's own rule (`write: Admin`) says no. The old answer was a
- * carve-out inside the generic write gate — every write path could claim an
- * unused name under `Groups/`, and the gate had to re-derive "is this that
- * one blessed case?" on every check. This service replaces that: the generic
- * gate is uniformly strict again, and the privilege lives here, named,
- * behind its own endpoint.
- *
- * What a provision IS: one exclusive write of the new folder's `access.md`
- * (flag `wx`, so two concurrent creators race for the fs, not for the
- * overwrite), then one SYNCHRONOUS commit+push. Synchronous on purpose — the
- * write gate reads rules at HEAD, so a creation whose access.md were still
- * sitting in the async commit queue would 403 the very next thing its
- * creator does (writing the first skill into it).
- *
- * Two shapes, two templates:
- *
- *   - A NAMED group: discoverable by design. The access.md's own frontmatter
- *     reads `everyone` — anyone may open the FILE, see the group listed, and
- *     ask to join — while the BODY (the folder's actual rules) names only
- *     the creator under read, write and owner.
- *   - A PERSONAL folder (`personal-<user-id>`): private by design. No
- *     frontmatter grant at all, so nobody else can even see it exists; the
- *     body names its owner. Created lazily (ensure semantics) on the first
- *     personal skill.
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { DEFAULT_BRANCH, GROUPS_DIR, PERSONAL_GROUP_PREFIX, isPersonalGroupFolder, personalGroupFolderName, } from '@bevel-software/platform-shared';
-import { creatorPrincipal } from '../access/creator-access.js';
-import { spliceGrant } from '../access/access-splice.js';
-import { WorkspaceMutex } from '../workflow/git/mutex.js';
-/** A refusal the route can pass through: message + HTTP status. */
-export class GroupProvisionError extends Error {
-    status;
-    constructor(message, status) {
-        super(message);
-        this.status = status;
-        this.name = 'GroupProvisionError';
-    }
-}
-export class GroupProvisionService {
-    workspaceService;
-    commits;
-    accessControl;
-    kbDirName;
-    events;
-    /**
-     * Serialises creations by NORMALIZED (lowercased) folder name. The wx write
-     * arbitrates same-path races, but on a case-sensitive filesystem `GTM` and
-     * `gtm` are different paths — without this lock two concurrent requests
-     * could both pass the collision check and both land, breaking the
-     * case-insensitive uniqueness the check promises.
-     */
-    creations = new WorkspaceMutex();
-    constructor(workspaceService, commits, accessControl, kbDirName, events) {
-        this.workspaceService = workspaceService;
-        this.commits = commits;
-        this.accessControl = accessControl;
-        this.kbDirName = kbDirName;
-        this.events = events;
-    }
-    /**
-     * Create `Groups/<name>/` for `user`. Throws `GroupProvisionError` 422 on a
-     * name the filesystem or the model cannot carry, 409 when the name is taken
-     * (case-insensitively — the workspaces live on case-insensitive
-     * filesystems too, where `GTM` and `gtm` are one folder).
-     */
-    async createGroup(user, rawName) {
-        const name = rawName.trim();
-        if (!name)
-            throw new GroupProvisionError('A group needs a name.', 422);
-        // eslint-disable-next-line no-control-regex -- NUL and control chars are
-        // exactly what a filesystem path cannot carry; refusing them here keeps
-        // the refusal a 422 instead of the fs layer's 500.
-        if (/[/\\\u0000-\u001f\u007f]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
-            throw new GroupProvisionError('A group name can\'t contain / or \\ or control characters, or start with a dot.', 422);
-        }
-        if (name.toLowerCase().startsWith(PERSONAL_GROUP_PREFIX)) {
-            // Reserved: the personal-folder namespace. A group squatting there
-            // would collide with somebody's future personal folder.
-            throw new GroupProvisionError(`Group names starting with "${PERSONAL_GROUP_PREFIX}" are reserved.`, 422);
-        }
-        return this.creations.run(`group:${name.toLowerCase()}`, async () => {
-            const existing = await this.existingFolder(name);
-            if (existing !== null) {
-                throw new GroupProvisionError(`A group named "${existing}" already exists.`, 409);
-            }
-            await this.provision(user, name, groupAccessMd(user));
-            return { folder: name, created: true };
-        });
-    }
-    /**
-     * Ensure the caller's personal folder exists — idempotent, keyed to the
-     * stable user id. Returns `created: false` when it is already there.
-     */
-    async ensurePersonalGroup(user) {
-        const folder = personalGroupFolderName(user.id);
-        return this.creations.run(`group:${folder.toLowerCase()}`, async () => {
-            if ((await this.existingFolder(folder)) !== null) {
-                return { folder, created: false };
-            }
-            try {
-                await this.provision(user, folder, personalAccessMd(user));
-            }
-            catch (err) {
-                // ENSURE semantics even under a race the lock cannot see (another
-                // process, a checkout that appeared between check and write): the
-                // folder existing is this method's success case, never its error.
-                if (err instanceof GroupProvisionError && err.status === 409) {
-                    return { folder, created: false };
-                }
-                throw err;
-            }
-            return { folder, created: true };
-        });
-    }
-    /**
-     * Delete `Groups/<name>/` — the whole folder, its skills and tools
-     * included, in ONE commit. MECHANISM only: the route owns the
-     * authorization (the caller must hold the `owner` verb on the folder;
-     * this service never re-derives it), exactly as `createGroup` leaves
-     * "any signed-in user" to its endpoint.
-     *
-     * Shape mirrors a provision run in reverse, with the same failure
-     * contract: the folder is PARKED (renamed to a dot-prefixed sibling the
-     * scanners ignore) rather than removed, the deletion is committed
-     * synchronously, and only a landed commit lets the parked bytes go. A
-     * refused commit renames the folder back, so a failed delete leaves the
-     * group exactly as it was — never half-gone on disk while origin still
-     * carries it.
-     *
-     * Serialised on the same per-name lock creations use, so a delete can
-     * never interleave with a re-creation of the same name.
-     */
-    async deleteGroup(user, rawName) {
-        const name = rawName.trim();
-        if (!name)
-            throw new GroupProvisionError('A group needs a name.', 422);
-        if (isPersonalGroupFolder(name)) {
-            // Personal folders are not groups (the catalog never lists them), and
-            // nobody deletes somebody's private shelf through the group door.
-            throw new GroupProvisionError('Unknown group', 404);
-        }
-        return this.creations.run(`group:${name.toLowerCase()}`, async () => {
-            const existing = await this.existingFolder(name);
-            // Exact match only — the catalog hands the route the on-disk casing,
-            // so a mismatch means the group is gone (or was never there).
-            if (existing !== name)
-                throw new GroupProvisionError('Unknown group', 404);
-            const wsId = await this.readyWorkspaceId();
-            const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-            const groupsDir = path.join(wsDir, this.kbDirName, GROUPS_DIR);
-            const folderDir = path.join(groupsDir, name);
-            // Dot-prefixed ⇒ invisible to the group scanner and the collision
-            // check for the whole window the commit is in flight.
-            const parkedDir = path.join(groupsDir, `.${name}.deleting`);
-            await fs.rm(parkedDir, { recursive: true, force: true }); // a stale park from a crashed run
-            await fs.rename(folderDir, parkedDir);
-            try {
-                // Inline and `systemAuthorized`, for `provision`'s reasons in
-                // reverse: the gate reads rules at HEAD, and the endpoint has
-                // already authorized the delete (owner verdict), so the per-user
-                // push gate — which would re-read an access.md this very commit
-                // removes — is skipped for exactly this commit. `commitFile` is
-                // path-scoped (`git add -- <path>`), and a folder path stages every
-                // deletion under it: one commit, one removed group.
-                await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${GROUPS_DIR}/${name}`, user, { systemAuthorized: true });
-            }
-            catch (err) {
-                // The commit did not land: put the folder back, so a failed delete
-                // is a no-op rather than a group that exists at origin but not here.
-                try {
-                    await fs.rename(parkedDir, folderDir);
-                }
-                catch {
-                    /* the park survives for the next attempt — better than masking the real error */
-                }
-                throw err;
-            }
-            await fs.rm(parkedDir, { recursive: true, force: true }).catch(() => { });
-            // The folder's rules left the access model — drop the resolver cache
-            // so the very next check runs against a tree without them.
-            this.accessControl.invalidate(wsId);
-            this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
-        });
-    }
-    /** The taken name (in its on-disk casing) colliding with `name`, or null. */
-    async existingFolder(name) {
-        const wsId = await this.readyWorkspaceId();
-        const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-        let children;
-        try {
-            children = await fs.readdir(path.join(wsDir, this.kbDirName, GROUPS_DIR));
-        }
-        catch {
-            return null; // no Groups/ root yet — nothing can collide
-        }
-        const lower = name.toLowerCase();
-        return children.find((c) => c.toLowerCase() === lower) ?? null;
-    }
-    async provision(user, folder, accessMd) {
-        const wsId = await this.readyWorkspaceId();
-        const wsRelPath = `${this.kbDirName}/${GROUPS_DIR}/${folder}/access.md`;
-        try {
-            // Exclusive create — the fs is the arbiter of a same-name race, not
-            // the (stale-able) existence check above.
-            await this.workspaceService.writeFile(wsId, wsRelPath, accessMd, { failIfExists: true });
-        }
-        catch (err) {
-            if (err.status === 409) {
-                throw new GroupProvisionError(`A group named "${folder}" already exists.`, 409);
-            }
-            throw err;
-        }
-        try {
-            // Inline, not enqueued: the gate reads rules at HEAD, so the folder is
-            // only real once this commit lands. `runPendingCommit` is the same
-            // commit+push (with pull-rebase recovery) the queue worker runs.
-            // `systemAuthorized`: the push gate reads access at origin, where this
-            // folder does not exist yet and the root says `write: Admin` — the very
-            // rule this endpoint exists to carve through. The endpoint has already
-            // authorized the write (any signed-in user, unused name, exclusive
-            // create), so the per-user gate is skipped for exactly this commit.
-            await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, wsRelPath, user, {
-                systemAuthorized: true,
-            });
-        }
-        catch (err) {
-            // The commit did not land: roll the seeded file back off the disk,
-            // best-effort, so a retry doesn't find a half-made group and report
-            // "already exists" for something that never got committed. Only OUR
-            // file and — when that leaves it empty — the folder; never recursive,
-            // so a concurrent writer's bytes can't be collateral.
-            try {
-                const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-                const folderDir = path.join(wsDir, this.kbDirName, GROUPS_DIR, folder);
-                await fs.rm(path.join(folderDir, 'access.md'), { force: true });
-                await fs.rmdir(folderDir).catch(() => { });
-            }
-            catch {
-                /* leave it for the next attempt's wx conflict — better than masking the real error */
-            }
-            throw err;
-        }
-        // The folder's rules changed the access model — drop the resolver cache
-        // so the very next check (the creator's first skill write) sees them.
-        this.accessControl.invalidate(wsId);
-        this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
-    }
-    async readyWorkspaceId() {
-        const ws = await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-        return ws.id;
-    }
-}
-/**
- * A named group's access.md: discoverable file (frontmatter `read: everyone`
- * — anyone may see the group listed and ask to join), creator-run folder
- * (body read/write/owner name the creator). The `read: []` placeholder makes
- * the body parse as rules from the first byte, so every later splice targets
- * the body rather than the frontmatter.
- */
-export function groupAccessMd(creator) {
-    return withCreatorGrants('---\nread:\n  - everyone\n---\nread: []\n', creator);
-}
-/**
- * A personal folder's access.md: PRIVATE — no frontmatter grant, so the
- * folder is invisible to everyone but its owner; the body names the owner
- * under read, write and owner.
- */
-export function personalAccessMd(creator) {
-    return withCreatorGrants('read: []\n', creator);
-}
-function withCreatorGrants(base, creator) {
-    const principal = creatorPrincipal(creator);
-    let out = base;
-    for (const verb of ['read', 'write', 'owner']) {
-        out = spliceGrant(out, verb, principal, { allowScalar: false, target: 'folder' }).text;
-    }
-    return out;
-}
-//# sourceMappingURL=group-provision.service.js.map

package/dist/modules/groups/group-provision.service.js.map

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

package/dist/modules/groups/groups.contract.d.ts

@@ -1,106 +0,0 @@
-/**
- * Groups — the folders under `Groups/` that carry a team's skills and the
- * tools those skills need. A group is a FOLDER, never a role: one access
- * boundary, one place, derived from the path exactly the way `groupOfPath`
- * derives it.
- *
- * A group EXISTS exactly when its folder carries an `access.md` — the file
- * the provisioning endpoint seeds. A bare directory under `Groups/` is not a
- * group (git cannot record an empty folder, so deleted groups leave ghost
- * directories on live checkouts).
- *
- * Enumeration then follows the KB's read model with NO special cases: an
- * existing group appears for a caller exactly when the access resolution says
- * something about it —
- *
- *   - MEMBER: the caller can read the folder itself (`canRead`).
- *   - MANAGER: the caller can write the folder's `access.md` (`canWrite`,
- *     admin-rescued).
- *   - DISCOVERABLE: the caller can read the `access.md` FILE — which, in the
- *     new body-governed format, is granted by the file's own
- *     `read: everyone` frontmatter (see `accessMdSelfEntries`). The group
- *     shows locked, and the caller may ask to join.
- *
- * A group where all three verdicts are false is ABSENT from the response —
- * name, counts and principals never leave the backend. Making a group secret
- * is therefore an ordinary access edit: drop the `everyone` grant from its
- * access.md frontmatter.
- *
- * Requesting access is a CHANGE REQUEST, not a bespoke system: the join
- * route commits "add me to the body's `read:` list" on a draft branch and
- * opens a CR that the folder's writers approve by merging (or by granting
- * via Manage access, which makes the CR moot). To agents these are plain
- * change requests; only the UI dresses them up.
- */
-/** Access-rule principals as the resolver hands them back. */
-export interface ResolvedPrincipals {
-    roles: string[];
-    users: {
-        name: string;
-        email: string;
-    }[];
-}
-export interface ResolvedReaders extends ResolvedPrincipals {
-    restricted: boolean;
-}
-/** One group as `GET /api/groups` reports it, resolved for ONE caller. */
-export interface GroupSummary {
-    /** Group folder name, e.g. `GTM`. */
-    name: string;
-    /** Repo-relative constituent folders, e.g. `['Groups/GTM']`. */
-    folders: string[];
-    /**
-     * Per-caller: the caller can read the FOLDER (membership). Every returned
-     * group has at least one of `canRead` / `canWrite` / discoverability; a
-     * group with none is not returned at all.
-     */
-    canRead: boolean;
-    /**
-     * Per-caller; true ⇒ may manage access. Resolved as write on the folder's
-     * `access.md`, which admin-rescues — so a platform Admin locked OUT of
-     * reading still sees the group and gets the self-service way back in.
-     */
-    canWrite: boolean;
-    /**
-     * Per-caller: the caller holds the `owner` verb on the FOLDER — resolved
-     * from the `owner:` lists alone, no admin rescue. Deleting the group is the
-     * owner's verb (the DELETE route enforces the same verdict); managers who
-     * merely write the access.md do not get it.
-     */
-    isOwner: boolean;
-    /** Caller-INDEPENDENT total (the group's whole content, not the caller's slice). */
-    skillCount: number;
-    toolCount: number;
-    /** For display: "Run by …" (fallback chain: owners → writers → 'the workspace admins'). */
-    owners: ResolvedPrincipals;
-    writers: ResolvedPrincipals;
-    readers: ResolvedReaders;
-    /**
-     * The caller has an OPEN join change request for this group (their
-     * deterministic join branch has an open CR). Always false for a member.
-     */
-    hasRequested: boolean;
-    /** The open join CR's number when `hasRequested` (deep-links the UI). */
-    requestNumber: number | null;
-}
-/**
- * The caller-INDEPENDENT slice of a group — what `catalog()` computes once and
- * caches. The per-caller verdicts (`canRead`/`canWrite`, and whether the group
- * appears at all) are resolved per request in the route.
- */
-export interface GroupCatalogEntry {
-    name: string;
-    folders: string[];
-    skillCount: number;
-    toolCount: number;
-    owners: ResolvedPrincipals;
-    writers: ResolvedPrincipals;
-    readers: ResolvedReaders;
-}
-export interface IGroupIndexService {
-    /** Caller-independent catalog part (folders, counts, principals) — cached 60s. */
-    catalog(): Promise<GroupCatalogEntry[]>;
-    /** Drop the cached catalog (call after a default-branch change under a group root). */
-    invalidate(): void;
-}
-//# sourceMappingURL=groups.contract.d.ts.map

package/dist/modules/groups/groups.contract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"groups.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/groups/groups.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,OAAO,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,uFAAuF;IACvF,UAAU,IAAI,IAAI,CAAC;CACpB"}

package/dist/modules/groups/groups.contract.js

@@ -1,36 +0,0 @@
-/**
- * Groups — the folders under `Groups/` that carry a team's skills and the
- * tools those skills need. A group is a FOLDER, never a role: one access
- * boundary, one place, derived from the path exactly the way `groupOfPath`
- * derives it.
- *
- * A group EXISTS exactly when its folder carries an `access.md` — the file
- * the provisioning endpoint seeds. A bare directory under `Groups/` is not a
- * group (git cannot record an empty folder, so deleted groups leave ghost
- * directories on live checkouts).
- *
- * Enumeration then follows the KB's read model with NO special cases: an
- * existing group appears for a caller exactly when the access resolution says
- * something about it —
- *
- *   - MEMBER: the caller can read the folder itself (`canRead`).
- *   - MANAGER: the caller can write the folder's `access.md` (`canWrite`,
- *     admin-rescued).
- *   - DISCOVERABLE: the caller can read the `access.md` FILE — which, in the
- *     new body-governed format, is granted by the file's own
- *     `read: everyone` frontmatter (see `accessMdSelfEntries`). The group
- *     shows locked, and the caller may ask to join.
- *
- * A group where all three verdicts are false is ABSENT from the response —
- * name, counts and principals never leave the backend. Making a group secret
- * is therefore an ordinary access edit: drop the `everyone` grant from its
- * access.md frontmatter.
- *
- * Requesting access is a CHANGE REQUEST, not a bespoke system: the join
- * route commits "add me to the body's `read:` list" on a draft branch and
- * opens a CR that the folder's writers approve by merging (or by granting
- * via Manage access, which makes the CR moot). To agents these are plain
- * change requests; only the UI dresses them up.
- */
-export {};
-//# sourceMappingURL=groups.contract.js.map

package/dist/modules/groups/groups.contract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"groups.contract.js","sourceRoot":"","sources":["../../../src/modules/groups/groups.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG"}

package/dist/modules/groups/groups.routes.d.ts

@@ -1,42 +0,0 @@
-import express from 'express';
-import '../auth/auth.middleware.js';
-import { type AuthUser, type IWorkflowService } from '@bevel-software/platform-shared';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { type GroupProvisionService } from './group-provision.service.js';
-import type { JoinRequestsService } from './join-requests.service.js';
-import type { IGroupIndexService } from './groups.contract.js';
-/**
- * Browser-facing (JWT) group routes, mounted behind `authMiddleware`:
- *
- *   GET    /api/groups                            → { groups: GroupSummary[] }
- *   DELETE /api/groups/:name                      → { ok }          (owners)
- *   POST   /api/groups/:name/join-request         → { ok, number }  (opens a CR)
- *   GET    /api/groups/:name/join-requests        → { requests }    (managers)
- *   POST   /api/groups/:name/join-requests/:n/reconcile → { closed }
- *
- * Enumeration is three verdicts per (caller, group), all of them ordinary
- * access resolution — no special cases, no side tables:
- *
- *   member       canRead on the group FOLDER
- *   manager      canWrite on the folder's access.md (admin-rescued)
- *   discoverable canRead on the access.md FILE — in the body-governed format
- *                its own `read: everyone` frontmatter grants this
- *
- * All three false ⇒ the group is absent from the response entirely.
- *
- * A join request is a plain change request whose branch edits the group's
- * `access.md`. Managers do NOT merge it: they read its individual proposals
- * (see `join-proposals.ts`), grant the ones they accept through the ordinary
- * access path, and the request retires itself once its rules are a subset of
- * the default branch's — reconciled here, lazily on listing and eagerly right
- * after a grant. Nothing about the lifecycle is stored; it is derived from
- * two copies of one file.
- *
- * Auth gating is explicit and uniform: `authMiddleware` at the mount, PLUS a
- * `req.userEmail` check in every handler (the skills-routes pattern) so a
- * middleware change can never silently un-gate one. Nothing here is reachable
- * with an agent connection key or a manual-auth bearer.
- */
-export declare function createGroupsRoutes(groupIndex: IGroupIndexService, accessControl: IAccessControl, workflow: IWorkflowService, workspaceService: WorkspaceService, joinRequests: JoinRequestsService, provision: GroupProvisionService, kbDirName: string, resolveUser: (req: express.Request) => Promise<AuthUser | null>): express.Router;
-//# sourceMappingURL=groups.routes.d.ts.map

package/dist/modules/groups/groups.routes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"groups.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/groups/groups.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,QAAQ,EAEb,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAG5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAuB,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAGV,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,kBAAkB,EAC9B,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,mBAAmB,EACjC,SAAS,EAAE,qBAAqB,EAChC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAC9D,OAAO,CAAC,MAAM,CAiXhB"}