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

package/src/shared/git-internals.ts

@@ -107,7 +107,13 @@ async function resolvedRealPath(absolutePath: string): Promise<string | null> {
  * Refuse a path under `rootDir` that names the git folder or resolves into it.
  *
  * `inputPath` is the caller's own spelling (checked lexically, encoded forms
- * included); `absolutePath` is where it lands on disk. Only the part below
+ * included, and probed on disk every way it could land — see
+ * {@link candidateTargets}); `absolutePath`, when a layer has already
+ * decided where the path goes, is that place, judged AS WELL. Both in one
+ * call, because the two answer different questions — a link reached by a
+ * reading this layer does not use is caught only by the spelling, a link the
+ * layer's own resolution follows only by the place — and one call walks the
+ * root once and probes a place that both name once. Only the part below
  * `rootDir` is judged, so a workspaces root that itself sits under some
  * `.git` directory does not refuse everything. A link that leaves the root
  * is judged on its target's path relative to the root, so a link into
@@ -116,9 +122,58 @@ async function resolvedRealPath(absolutePath: string): Promise<string | null> {
  */
 export async function assertNotGitInternals(rootDir: string, inputPath: string, absolutePath?: string): Promise<void> {
   assertNoGitInternalsSegment(inputPath);
-  const target = absolutePath ?? path.resolve(rootDir, inputPath.replace(/^[\\/]+/, ''));
-  if (hasGitInternalsSegment(path.relative(path.resolve(rootDir), target))) throw new GitInternalsError();
-  const [realTarget, realRoot] = await Promise.all([resolvedRealPath(target), resolvedRealPath(path.resolve(rootDir))]);
-  if (realTarget === null || realRoot === null) return;
-  if (hasGitInternalsSegment(path.relative(realRoot, realTarget))) throw new GitInternalsError();
+  const root = path.resolve(rootDir);
+  const realRoot = await resolvedRealPath(root);
+  // Each place once, remembering whether a layer resolved it (probed as
+  // given) or only a spelling named it (probed only inside the root).
+  const targets = new Map<string, boolean>();
+  for (const target of candidateTargets(root, inputPath)) targets.set(target, false);
+  if (absolutePath !== undefined) targets.set(absolutePath, true);
+  for (const [target, resolved] of targets) {
+    const relative = path.relative(root, target);
+    if (hasGitInternalsSegment(relative)) throw new GitInternalsError();
+    if (realRoot === null) continue;
+    // A raw spelling fans out into candidates, and one of them can name a
+    // place outside the workspace entirely — `/etc/…`, a deep climb. Such a
+    // candidate is judged by the lexical reading above (a link into another
+    // checkout's `.git` is named there) but NOT probed on disk: probing it
+    // would let an unreadable external directory answer with its own
+    // `EACCES` instead of the path rule's typed refusal for a spelling that
+    // was never a workspace path. A path a layer already resolved is the one
+    // place it is, so it is probed as given.
+    // `..` and `../…` are the climbs; `..link` is an ordinary name that merely
+    // starts with those characters, and a link by that name can point into the
+    // folder — so it is probed like any other entry under the root.
+    const climbsOut = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (!resolved && (relative === '' || climbsOut)) continue;
+    const realTarget = await resolvedRealPath(target);
+    if (realTarget !== null && hasGitInternalsSegment(path.relative(realRoot, realTarget))) throw new GitInternalsError();
+  }
+}
+
+/**
+ * Every place one raw spelling could LAND, because a spelling is not yet a
+ * path until something decides how to read it.
+ *
+ * A backslash separates segments on Windows and is an ordinary character in a
+ * filename here, so `kb\\Notes\\..\\link` is read BOTH ways; an absolute path
+ * is both the path it names and — as every workspace caller reads it — that
+ * path with its leading slashes dropped, under the workspace; and a leading
+ * climb (`../kb/link`) is both the climb it spells and the path left when the
+ * climb is dropped, which is how a lenient reader takes it. The spelling is
+ * refused when ANY reading lands in the git folder: which reading a later
+ * layer picks is not something this rule should have to predict.
+ *
+ * This is what a CALLER's own spelling needs. A path some layer has already
+ * resolved arrives as `absolutePath` and is judged as the one place it is.
+ */
+function candidateTargets(root: string, inputPath: string): string[] {
+  const targets = new Set<string>();
+  for (const spelling of new Set([inputPath, inputPath.replace(/\\/g, '/')])) {
+    const anchored = spelling.replace(/^[\\/]+/, '');
+    targets.add(path.resolve(root, anchored));
+    targets.add(path.resolve(root, anchored.replace(/^(\.\.?[\\/])+/, '')));
+    if (/^[\\/]/.test(spelling)) targets.add(path.resolve(spelling));
+  }
+  return [...targets];
 }

package/dist/modules/access/access-errors.d.ts

@@ -1,34 +0,0 @@
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
-export interface AccessDeniedDetails {
-    /** repo-relative POSIX path the caller tried to write */
-    path: string;
-    /** Display names of roles that would grant write at this path. */
-    eligibleRoles: string[];
-    /** Direct user grants at this path, in `{name, email}` form. */
-    eligibleUsers: {
-        name: string;
-        email: string;
-    }[];
-}
-/**
- * Thrown when a user lacks the `write` permission on a path under the
- * access-control rules in `roles.yaml` + `access.md`.
- *
- * Carries enough detail in the JSON payload for the frontend to render
- * "you don't have permission to write to <path>; eligible: <roles + users>"
- * without a follow-up roundtrip.
- */
-export declare class AccessDeniedError extends WorkflowDomainError {
-    readonly access: AccessDeniedDetails;
-    constructor(details: AccessDeniedDetails);
-}
-/**
- * Thrown when the access-control config (roles.yaml or access.md) is missing
- * or malformed at runtime — distinct from AccessDeniedError because the cause
- * is a config bug, not a permission decision.
- */
-export declare class AccessConfigError extends WorkflowDomainError {
-    readonly errors: string[];
-    constructor(errors: string[]);
-}
-//# sourceMappingURL=access-errors.d.ts.map

package/dist/modules/access/access-errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"access-errors.d.ts","sourceRoot":"","sources":["../../../src/modules/access/access-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gEAAgE;IAChE,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,mBAAmB;IACxD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;gBAEzB,OAAO,EAAE,mBAAmB;CAkBzC;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,mBAAmB;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAS7B"}

package/dist/modules/access/access-errors.js

@@ -1,40 +0,0 @@
-import { WorkflowDomainError } from '../workflow/workflow.errors.js';
-/**
- * Thrown when a user lacks the `write` permission on a path under the
- * access-control rules in `roles.yaml` + `access.md`.
- *
- * Carries enough detail in the JSON payload for the frontend to render
- * "you don't have permission to write to <path>; eligible: <roles + users>"
- * without a follow-up roundtrip.
- */
-export class AccessDeniedError extends WorkflowDomainError {
-    access;
-    constructor(details) {
-        const rolesPart = details.eligibleRoles.length
-            ? details.eligibleRoles.join(', ')
-            : 'none';
-        const usersPart = details.eligibleUsers.length
-            ? details.eligibleUsers
-                .map((u) => (u.name ? `${u.name} <${u.email}>` : u.email))
-                .join(', ')
-            : '';
-        const eligible = [rolesPart, usersPart].filter(Boolean).join('; ');
-        super(`You don't have permission to write to "${details.path}". Eligible: ${eligible}.`, 403, { access: details });
-        this.name = 'AccessDeniedError';
-        this.access = details;
-    }
-}
-/**
- * Thrown when the access-control config (roles.yaml or access.md) is missing
- * or malformed at runtime — distinct from AccessDeniedError because the cause
- * is a config bug, not a permission decision.
- */
-export class AccessConfigError extends WorkflowDomainError {
-    errors;
-    constructor(errors) {
-        super(`Access-control config is invalid: ${errors.join('; ')}`, 500, { accessConfigErrors: errors });
-        this.name = 'AccessConfigError';
-        this.errors = errors;
-    }
-}
-//# sourceMappingURL=access-errors.js.map

package/dist/modules/access/access-errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"access-errors.js","sourceRoot":"","sources":["../../../src/modules/access/access-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAWrE;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAAmB;IAC/C,MAAM,CAAsB;IAErC,YAAY,OAA4B;QACtC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM;YAC5C,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;YAClC,CAAC,CAAC,MAAM,CAAC;QACX,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM;YAC5C,CAAC,CAAC,OAAO,CAAC,aAAa;iBAClB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;iBACzD,IAAI,CAAC,IAAI,CAAC;YACf,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,KAAK,CACH,0CAA0C,OAAO,CAAC,IAAI,gBAAgB,QAAQ,GAAG,EACjF,GAAG,EACH,EAAE,MAAM,EAAE,OAAO,EAAE,CACpB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;IACxB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,mBAAmB;IAC/C,MAAM,CAAW;IAE1B,YAAY,MAAgB;QAC1B,KAAK,CACH,qCAAqC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACxD,GAAG,EACH,EAAE,kBAAkB,EAAE,MAAM,EAAE,CAC/B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/modules/access/access-splice.d.ts

@@ -1,140 +0,0 @@
-/**
- * Surgical text-splice editor for `access.md` frontmatter and node-frontmatter
- * access verbs.
- *
- * WHY a splice and not parse→model→emit: the resolver's parser
- * (`parseYamlSubset` / `extractFrontmatter` / `stripComment`) deliberately
- * throws away comments, blank lines, key order, AND the markdown body below the
- * closing `---`. Re-serialising from the parsed model would silently DELETE the
- * prose bodies the real `access.md` files carry (the repo-root one is a whole
- * README) — and a `parse(emit(x))` round-trip test would PASS anyway because
- * parse ignores the body. So every mutation here edits the RAW text: we locate
- * the verb's block, splice exactly one list line in or out, and leave every
- * other byte — comments, ordering, blank lines, the body — untouched.
- *
- *   ---
- *   write:                 (verb key line, indent 0)
- *     - Admin              (list item, indent 2)  <- splice point
- *     - Felix <f@x.eu>     (list item)
- *   # a comment            (preserved verbatim)
- *   owner: []              (inline-empty list)
- *   ---
- *   # Body prose           (preserved verbatim)
- *
- * The same engine serves node-frontmatter, which additionally accepts a scalar
- * form (`owner: Felix <f@x.eu>`). Adding a second principal to a scalar verb
- * normalises it to the block-list form.
- */
-import { type Verb } from './access-control.service.js';
-/**
- * Which rule block a mutation edits.
- *
- *  - `'node'` (default): the file's YAML frontmatter — node files, and every
- *    call that predates the two-format `access.md` story.
- *  - `'folder'`: the block that governs the CONTAINING FOLDER of an
- *    `access.md` — the body when the file is in the new (body-governed)
- *    format, the frontmatter otherwise. Callers mutating folder rules pass
- *    this so a grant can never land in a new-format file's frontmatter
- *    (which governs the FILE itself, not the folder).
- */
-export type SpliceTarget = 'node' | 'folder';
-/** A principal to grant/revoke, in the resolver's canonical terms. */
-export type Principal = {
-    kind: 'user';
-    email: string;
-    displayName: string;
-} | {
-    kind: 'role';
-    role: string;
-};
-/** Result of a splice — the new full file text and whether anything changed. */
-export interface SpliceResult {
-    text: string;
-    changed: boolean;
-}
-/** Thrown when the input can't be spliced safely (malformed frontmatter, etc.). */
-export declare class AccessSpliceError extends Error {
-    constructor(message: string);
-}
-/**
- * Render a principal as the canonical access-entry line value the parser reads
- * back (`Name <email>` or a bare role display name). The caller is responsible
- * for having validated the principal first (see `validatePrincipal`).
- *
- * `deny` prefixes the entry with `deny ` so the resolver reads it as a denial
- * (the `deny-here` per-item override) — same line shape, opposite verdict.
- */
-export declare function renderEntry(p: Principal, deny?: boolean): string;
-/**
- * Validate a principal before it is spliced into a file. Rejects anything that
- * could break frontmatter or smuggle in extra YAML — newlines, control chars,
- * and emails / names that don't match the resolver's own regexes. This is the
- * injection guard: a principal that survives this is safe to render verbatim
- * into a `  - ` list line.
- *
- * Returns the canonical principal (lowercased email / canonical role) on
- * success, or throws `AccessSpliceError`.
- */
-export declare function validatePrincipal(p: Principal): Principal;
-/**
- * How a role-shaped principal's TOKEN is compared against a file entry:
- *
- *  - `'exact'`: the entry must carry the SAME spelling — a bare token and a
- *    `role/<name>` token are DIFFERENT principals (bare = whoever owns the
- *    bare key under group-first precedence, `role/` = the role). Grants
- *    always use this: granting the group `X` while `role/X` is present (or
- *    vice versa) must NOT be treated as already-granted, or the other
- *    principal silently never receives the grant.
- *  - `'name'`: both spellings of the name match. Revokes use this ONLY when
- *    no group shadows the bare name — then both spellings resolve to the
- *    role, and revoking the role must also remove legacy bare spellings.
- */
-export type TokenMatch = 'exact' | 'name';
-/**
- * Add `principal` under `verb`. Idempotent: if an entry with the EXACT same
- * token spelling already exists with the SAME deny-ness (a grant when
- * granting, a deny when denying), returns `changed: false`. Idempotency is
- * deliberately exact-token, never name-level: a bare token and a `role/`
- * token are different principals (group-first precedence gives the bare key
- * to a same-named group), so a bare-`X` GROUP grant must go through even when
- * `role/X` is present, and vice versa. Creates the verb key (and the
- * frontmatter fence, for a fresh file) as needed. Preserves everything else
- * byte-for-byte.
- *
- * `allowScalar` controls whether a fresh single-entry verb may be written in
- * the node-frontmatter scalar form (`owner: Name <email>`). access.md always
- * uses the block-list form; node frontmatter prefers scalar for a lone entry.
- *
- * `deny` writes the entry as a `deny <principal>` denial instead of a grant
- * (the `deny-here` per-item override). The block/scalar/empty-list handling is
- * identical — only the rendered line and the idempotency check differ — so the
- * deny path reuses this engine rather than a parallel `spliceDeny`. NOTE: the
- * resolver lets a same-scope grant override a same-scope deny of the same
- * principal, so a caller adding a deny where a grant already exists must strip
- * that grant first (see `AccessMutationService`); this function only writes the
- * one entry it's asked to.
- */
-export declare function spliceGrant(text: string, verb: Verb, rawPrincipal: Principal, opts?: {
-    allowScalar?: boolean;
-    deny?: boolean;
-    target?: SpliceTarget;
-}): SpliceResult;
-/**
- * Remove every entry naming `principal` under `verb` (grant or deny). Idempotent:
- * returns `changed: false` when the principal isn't present. If removing the
- * last item empties the verb, the `verb:` key is collapsed to `verb: []` so the
- * file still parses cleanly (the resolver reads `[]` as an empty list).
- * Preserves everything else.
- *
- * Token matching for role-shaped principals is `tokenMatch` (default `'name'`:
- * BOTH spellings — revoking the role removes legacy bare spellings too).
- * Callers pass `'exact'` when a GROUP shadows the principal's bare name: the
- * bare token then belongs to the group and the `role/` token to the role, so a
- * revoke of one must never strip the other (see AccessMutationService, which
- * derives the flag from the merged principal index).
- */
-export declare function spliceRevoke(text: string, verb: Verb, rawPrincipal: Principal, opts?: {
-    target?: SpliceTarget;
-    tokenMatch?: TokenMatch;
-}): SpliceResult;
-//# sourceMappingURL=access-splice.d.ts.map

package/dist/modules/access/access-splice.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"access-splice.d.ts","sourceRoot":"","sources":["../../../src/modules/access/access-splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,IAAI,EAMV,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C,sEAAsE;AACtE,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,mFAAmF;AACnF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,UAAQ,GAAG,MAAM,CAG9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAgDzD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AA+L1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,SAAS,EACvB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC1E,YAAY,CA0Dd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,SAAS,EACvB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAAO,GAC5D,YAAY,CAkCd"}