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

package/src/shared/logging.ts

@@ -0,0 +1,96 @@
+// This file IS the console sink; every other file logs through it. The lint
+// rule that forbids `console` elsewhere in the backend exempts exactly this
+// file (see eslint.config.js).
+import { oneLine, oneLineError, type ILogger, type LogFields } from './logger.contract.js';
+
+/**
+ * Where the backend's logging goes, and how a module gets a logger.
+ *
+ * ONE SLOT, INSTALLED ONCE. The composition root — or a shell before it —
+ * calls {@link setLogger} with the implementation the process runs on, and
+ * every module obtains a tagged child through {@link logger}. The slot is
+ * process-wide on purpose: the `console` it replaces was, and threading a
+ * logger through some sixty constructors (and the several hundred places
+ * tests construct them) would spend a great deal to make a cross-cutting
+ * concern look like a per-object dependency. It remains injectable: a suite
+ * that wants to see what was logged installs a capturing logger through the
+ * same setter.
+ *
+ * CHILDREN RESOLVE LATE. `logger('tag')` is called at module load, before any
+ * root has run, so what it returns is a handle that looks the slot up on
+ * every call rather than a child of whatever happened to be installed then.
+ * Installing pino after a module loaded therefore still routes that module's
+ * lines through pino.
+ */
+
+let current: ILogger = createConsoleLogger();
+
+/** Install the process's logger. Returns the previous one, for a suite to restore. */
+export function setLogger(impl: ILogger): ILogger {
+  const previous = current;
+  current = impl;
+  return previous;
+}
+
+/**
+ * The logger a module logs through, carrying `module: tag` on every line — the
+ * `[tag]` every call used to spell by hand.
+ */
+export function logger(tag: string): ILogger {
+  return lateBound({ module: tag });
+}
+
+function lateBound(bindings: LogFields): ILogger {
+  return {
+    debug: (message, fields) => current.child(bindings).debug(message, fields),
+    info: (message, fields) => current.child(bindings).info(message, fields),
+    warn: (message, fields) => current.child(bindings).warn(message, fields),
+    error: (message, fields) => current.child(bindings).error(message, fields),
+    child: (more) => lateBound({ ...bindings, ...more }),
+  };
+}
+
+/**
+ * The default sink: `console`, in the shape the backend has always written —
+ * `[module] message`, and the fields after it. Dependency-free, so the
+ * published package logs sensibly with nothing installed, and human-shaped,
+ * because a terminal is where that case is read. A deployment that wants
+ * machine-shaped lines installs a sink that emits them; the server shell
+ * installs pino.
+ *
+ * Fields are passed to `console` as a second argument rather than folded into
+ * the string, so an object stays inspectable and an error keeps its stack.
+ * When `err` is the only field it is passed bare: that is the shape a person
+ * at a terminal wants, and the shape the suites that watch the console have
+ * always asserted on.
+ *
+ * An error field is passed as a copy whose message is one line (see
+ * `oneLineError`): the stack the console prints is the process's own text,
+ * but the message at its head is very often not — it quotes git's stderr, a
+ * path, a request's branch name — and unescaped it would forge a line or
+ * paint the terminal exactly as a string field would. Every call site that
+ * logs `{ err }` is covered here, so none of them has to remember it.
+ */
+export function createConsoleLogger(bindings: LogFields = {}): ILogger {
+  // The tag is a binding like any other and goes through the same rule: a
+  // module name is the code's own today, but the contract lets a caller bind
+  // one, and a tag is written at the head of every line it tags.
+  const prefix = typeof bindings.module === 'string' ? `[${oneLine(bindings.module)}] ` : '';
+  const rest = Object.fromEntries(Object.entries(bindings).filter(([k]) => k !== 'module'));
+  const safe = (v: unknown): unknown => (typeof v === 'string' ? oneLine(v) : v instanceof Error ? oneLineError(v) : v);
+  const extra = (fields: LogFields | undefined): unknown[] => {
+    const merged = Object.fromEntries(Object.entries({ ...rest, ...fields }).map(([k, v]) => [k, safe(v)]));
+    const keys = Object.keys(merged);
+    if (keys.length === 0) return [];
+    if (keys.length === 1 && keys[0] === 'err') return [merged.err];
+    return [merged];
+  };
+  return {
+    debug: (message, fields) => console.debug(`${prefix}${oneLine(message)}`, ...extra(fields)),
+    info: (message, fields) => console.log(`${prefix}${oneLine(message)}`, ...extra(fields)),
+    warn: (message, fields) => console.warn(`${prefix}${oneLine(message)}`, ...extra(fields)),
+    error: (message, fields) => console.error(`${prefix}${oneLine(message)}`, ...extra(fields)),
+    child: (more) => createConsoleLogger({ ...bindings, ...more }),
+  };
+}
+

package/src/shared/path-containment.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { PathTraversalError } from './domain-errors.js';
+
+/**
+ * THE containment check for ABSOLUTE paths: is `absolutePath` the directory
+ * `dir`, or something under it?
+ *
+ * Three surfaces carried a copy of this — the workspace service, the diff
+ * ledger and the delete route — and each threw a bare `Error` whose MESSAGE
+ * five catch sites then matched to decide on a 403. A reworded message would
+ * have turned every one of those into a 500, which is to say into a silently
+ * unblocked traversal in the log. So the refusal is a TYPE now
+ * ({@link PathTraversalError}, 403 with a `path-traversal` payload), and the
+ * route layers read the status off the class like every other domain error.
+ *
+ * LEXICAL, deliberately: it compares resolved spellings and follows no links,
+ * so it is safe to call before anything touches the disk. It is therefore not
+ * the whole rule — a path may be contained by its spelling and still reach
+ * outside through a symlink, which is `assertNotThroughLink`'s job, and a
+ * workspace-RELATIVE spelling is `canonicalFileIdentity`'s. This is the first
+ * of those three, and the only one every caller needs.
+ */
+export function assertWithinDirectory(absolutePath: string, dir: string): void {
+  const resolved = path.resolve(absolutePath);
+  const root = path.resolve(dir);
+  // The separator is what makes this a containment check rather than a prefix
+  // match — without it `/srv/ws-backup` passes as "inside" `/srv/ws`. A root
+  // that already ends in one (the filesystem root, `/` or `C:\`) must not get
+  // a second, or every descendant fails to match the doubled prefix.
+  const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+  if (resolved !== root && !resolved.startsWith(prefix)) {
+    throw new PathTraversalError();
+  }
+}

package/src/shared/path-order.ts

@@ -0,0 +1,33 @@
+/**
+ * The ONE ordering of repository paths: component by component, each
+ * component by `localeCompare`, a shorter path before its extensions. It is
+ * exactly the order a directory walk that sorts each level's entries visits
+ * them in — so a consumer that must agree with the walk on "first by path"
+ * (plugin discovery keeps the first of two folders sharing a slug; principal
+ * synthesis must pick the same one) sorts with this and nothing else. A
+ * whole-string `localeCompare` does not agree: it weighs the separator
+ * against the next character (`a-b/x` before `a/b/x`), the walk never does.
+ *
+ * TOTAL over distinct paths: two components the collation cannot tell apart
+ * (a precomposed `é` and its decomposed spelling) fall through to code-unit
+ * order, so no pair of distinct paths ever compares equal — an equal pair
+ * would leave "first" to whichever enumeration happened to run, and the two
+ * consumers could then pick different folders for one slug.
+ */
+export function comparePathComponents(a: string, b: string): number {
+  const as = a.split('/');
+  const bs = b.split('/');
+  const n = Math.min(as.length, bs.length);
+  for (let i = 0; i < n; i++) {
+    const order = compareComponent(as[i]!, bs[i]!);
+    if (order !== 0) return order;
+  }
+  return as.length - bs.length;
+}
+
+/** One component against another: collation first, code units to break a tie. */
+function compareComponent(a: string, b: string): number {
+  const order = a.localeCompare(b);
+  if (order !== 0) return order;
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/shared/pending-proposals.ts

@@ -0,0 +1,161 @@
+import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { workspaceIdForBranch } from './workspace-id.js';
+import type { IAccessControl } from '../modules/access/access-control.interface.js';
+import { canonicalEmail, hashEmail } from './email-identity.js';
+import { printable } from './printable.js';
+import { logger } from './logging.js';
+
+const log = logger('pending-proposals');
+
+/**
+ * The mechanics every "proposed, not released" surface shares.
+ *
+ * Skills and tools both have a half of their catalog that is NOT on the default
+ * branch: a change request that ADDS a declaration has nothing on the default
+ * branch to hang itself off, so until it merged the proposal was invisible to
+ * its author and to the people who had to approve it. Both surfaces answer that
+ * the same way — walk the OPEN change requests, keep the touched paths that
+ * look like the declaration in question, decide who may see each one, and read
+ * the file at the request's own branch — and only the "looks like" predicate and
+ * the parsing differ.
+ *
+ * Kept in one place so the two cannot drift on the part that matters most: WHO
+ * MAY SEE A PROPOSAL. It is narrower than who may see the catalog — the author,
+ * and whoever could approve it. "Could approve it" is not re-stated as an
+ * admin check; it is `canWrite` on the very path the request would create,
+ * resolved on the DEFAULT branch. The new file carries no `access.md` of its
+ * own, so that verdict inherits from the plugin folder, which IS the plugin's
+ * admin; asking the access tree keeps these surfaces and the merge gate
+ * answering with one voice. The branch's own copy of the tree is written by the
+ * proposer and must not get a say in who reviews them.
+ */
+export interface ProposalSources {
+  workspaceService: Pick<WorkspaceService, 'ensureRemotesFetched' | 'readFileAtRef'>;
+  accessControl: Pick<IAccessControl, 'canWriteBatch'>;
+  workflow: Pick<IWorkflowService, 'listChangeRequests'>;
+}
+
+/** One file an open change request proposes, already read at that request's branch. */
+export interface ProposedFile {
+  /** The open change request that would release it. */
+  cr: ChangeRequest;
+  /** Repo-root-relative path of the proposed file. */
+  path: string;
+  /** The file's content at the request's branch. */
+  content: string;
+  /** True when the caller opened the request themselves. */
+  isAuthor: boolean;
+}
+
+/**
+ * Every file matching `matches` that an OPEN change request proposes and this
+ * caller is entitled to see, with its branch content in hand.
+ *
+ * Never throws: these surfaces hang off the library's list load, and a review
+ * shelf that cannot answer must not take the shelf down with it. Everything
+ * degrades to "nothing pending".
+ *
+ * `matches` is where a surface states what it is looking for — and, because it
+ * runs BEFORE the access batch, also where it drops what it already serves from
+ * the default branch, so the batch stays as small as the answer.
+ *
+ * Order follows the change requests as the workflow service listed them; a
+ * caller that wants a stable reading order sorts the result itself.
+ */
+export async function visibleProposedFiles(
+  sources: ProposalSources,
+  userEmail: string,
+  matches: (repoRelPath: string) => boolean,
+): Promise<ProposedFile[]> {
+  const email = canonicalEmail(userEmail);
+  if (!email) return [];
+
+  let crs: ChangeRequest[];
+  try {
+    // Open, and aimed at the DEFAULT BRANCH. Everything downstream is written
+    // in terms of that branch — the released set that decides "added", and the
+    // access tree that decides who may review — so a request targeting some
+    // other branch is not a proposal these surfaces can speak about: merging it
+    // puts nothing in the catalog, and the card would never resolve.
+    crs = (await sources.workflow.listChangeRequests()).filter(
+      (c) => c.state === 'open' && c.base === DEFAULT_BRANCH,
+    );
+  } catch {
+    return [];
+  }
+  if (crs.length === 0) return [];
+
+  const candidates = crs.flatMap((cr) =>
+    cr.touchedNodePaths.filter(matches).map((path) => ({ cr, path })),
+  );
+  if (candidates.length === 0) return [];
+
+  const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+  const authorHash = hashEmail(email);
+
+  // One access load for every candidate, resolved on the DEFAULT branch — see
+  // the note on {@link ProposalSources}.
+  const writable = await sources.accessControl
+    .canWriteBatch(
+      wsId,
+      email,
+      candidates.map((c) => c.path),
+    )
+    .catch(() => new Map<string, boolean>());
+
+  // The branch copies are read through the default branch's clone at
+  // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
+  // first, best-effort: a request pushed seconds ago is worth one fetch, and a
+  // failed fetch should degrade to "read what we have".
+  await sources.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
+
+  const out: ProposedFile[] = [];
+  for (const { cr, path } of candidates) {
+    const isAuthor = !!cr.authorId && cr.authorId === authorHash;
+    // Fail closed, matching the catalog: only an explicit `true` admits a
+    // reviewer. A missing entry (the batch skipped the path, the tree could not
+    // be read) means denied, never shown.
+    if (!isAuthor && writable.get(path) !== true) continue;
+
+    const content = await readAt(sources.workspaceService, wsId, cr.branch, path);
+    // Nothing to describe: the request touched the path but the file is gone at
+    // its head (proposed then withdrawn within the branch), or unreadable.
+    if (content === null) continue;
+    out.push({ cr, path, content, isAuthor });
+  }
+  return out;
+}
+
+/**
+ * The file at a branch, or null when it is not there.
+ *
+ * `readFileAtRef` ALREADY answers `null` for genuine absence (a `git show` that
+ * finds no such blob), so everything reaching the catch below is an infra
+ * failure instead — an unresolvable workspace, a rejected ref, a git call that
+ * timed out. The contract of this module is "never throws", so those still
+ * become `null` and the card still drops; what they must not do is drop
+ * SILENTLY, which is how a fetch problem reads as "the proposer withdrew it".
+ * The warning is the difference between a shelf that degraded and a shelf that
+ * lied.
+ */
+export async function readAt(
+  workspaceService: Pick<WorkspaceService, 'readFileAtRef'>,
+  wsId: string,
+  branch: string,
+  repoRelPath: string,
+): Promise<string | null> {
+  try {
+    return await workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
+  } catch (err) {
+    // Every interpolated value is attacker-shaped: the path and the branch come
+    // off a change request somebody else opened, and the reason comes off git.
+    // A raw newline or an escape sequence in any of them forges a log line or
+    // steers the operator's terminal, so all three go through `printable`.
+    log.warn(
+      `could not read ${printable(repoRelPath)} at origin/${printable(branch)} in ${printable(wsId)}; ` +
+        `dropping it from the review shelf: ${printable(err instanceof Error ? err.message : String(err))}`,
+    );
+    return null;
+  }
+}

package/src/shared/printable.ts

@@ -0,0 +1,68 @@
+/**
+ * Re-export, so this backend's ~20 call sites keep their short import while
+ * the function itself lives where BOTH MCP surfaces can reach it.
+ *
+ * The local server (`@bevel-software/hexis-mcp`) is published standalone and
+ * cannot import this package, but it logs the same kind of text — a reason
+ * string that came off the network — to the same kind of operator log. Two
+ * copies of an escaper is two escapers that drift, so it moved to the one
+ * package both already depend on. See `printable` there for what it escapes
+ * and why.
+ */
+export { printable } from '@bevel-software/platform-mcp-core';
+
+/**
+ * A path (or any short text) as it may be interpolated into a ONE-LINE
+ * message: every character a caller can put in a filename that RENDERS as a
+ * line break is escaped, so a refusal naming the path stays one line and
+ * cannot forge a second.
+ *
+ * That is every C0 and C1 control character — CR and LF, the other mandatory
+ * breaks (vertical tab, form feed, NEL), and the one-byte escapes a terminal
+ * obeys (U+009B starts an ANSI sequence on its own) — and the Unicode line
+ * separators U+2028/U+2029 with them: `JSON.stringify` leaves the C1 range
+ * and the separators raw, so a path that carries one survives being carried
+ * — in the `path` field of a not-found body, in a log line — and breaks or
+ * steers the line wherever it is finally rendered. {@link printable} escapes
+ * the same set for exactly that reason; the spelling is the same too (`\n`,
+ * `\t`, else `\uXXXX`), so a path reads alike in a refusal and in a log.
+ *
+ * Unquoted, unlike {@link printable}: this text is read by a person or an
+ * agent inside a sentence that already quotes it, not by an operator scanning
+ * a log. THE spelling for that job — `displayPath` in the file readers is this
+ * function, and the missing-path refusals use it too, so a path reads the same
+ * however it is refused.
+ */
+// The names JSON gives its escapes — and so what `printable`, which is
+// `JSON.stringify` underneath, writes for the same characters; every other
+// control is `\uXXXX` in both, so a path reads the same in a refusal and
+// in a log. (JSON has no name for vertical tab, so neither does this.)
+const NAMED_ESCAPES: ReadonlyMap<string, string> = new Map([
+  ['\b', '\\b'],
+  ['\t', '\\t'],
+  ['\n', '\\n'],
+  ['\f', '\\f'],
+  ['\r', '\\r'],
+]);
+// Built rather than written: the lint rule against control characters in a
+// regex literal guards against accidental ones, and these are the point.
+const CONTROL_OR_SEPARATOR = new RegExp(`[\\x00-\\x1F\\x7F-\\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+/** The characters `JSON.stringify` leaves raw: the C1 range and the two line separators. */
+const RAW_AFTER_JSON = new RegExp(`[\\x7F-\\x9F${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
+
+const uEscape = (c: string): string => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+
+export function sanitizedPath(text: string): string {
+  return text.replace(CONTROL_OR_SEPARATOR, (c) => NAMED_ESCAPES.get(c) ?? uEscape(c));
+}
+
+/**
+ * JSON text as a terminal can show it: `JSON.stringify` escapes the C0
+ * controls inside strings and leaves the C1 range and the line separators
+ * raw, so those are escaped here — still the same JSON to any reader of it,
+ * since they can only occur inside a string. For a document, not a path:
+ * the JSON's own line breaks (pretty-printing) are left alone.
+ */
+export function terminalSafeJson(json: string): string {
+  return json.replace(RAW_AFTER_JSON, uEscape);
+}

package/src/shared/redact-secret.ts

@@ -0,0 +1,118 @@
+/**
+ * Scrub credentials from anything that reaches a log or an error message:
+ * the token in effect wherever it appears, URL userinfo — a remote spelled
+ * `https://user:pass@host` would otherwise leak `pass` verbatim through every
+ * git failure that quotes the URL back — and URL query strings, where a
+ * presigned remote keeps its credential.
+ *
+ * "The token in effect" is every place one can come from: each environment
+ * spelling `CoreConfig` accepts (it normalises them onto `GITHUB_TOKEN` at
+ * boot, but a later write to one of them is not normalised), plus whatever the
+ * caller knows about — the settings-stored token, a token a request brought
+ * along, or a remote's query values ({@link urlQuerySecrets}). Longest first,
+ * so a secret that contains another is not half-scrubbed.
+ *
+ * Shared, not a module's own: the KB startup phase and the setup routes both
+ * log git's words, and one scrub is the only way they cannot disagree about
+ * what a secret is.
+ */
+export function redactSecret(text: string, secrets: readonly (string | null | undefined)[] = []): string {
+  const tokens = [
+    process.env.GITHUB_TOKEN,
+    process.env.GIT_TOKEN,
+    process.env.GH_TOKEN,
+    ...secrets,
+  ]
+    .map((t) => t?.trim())
+    .filter((t): t is string => !!t);
+  let scrubbed = text;
+  const ordered = [...new Set(tokens)].sort((a, b) => b.length - a.length);
+  // Every whole value first, then every echoed PREFIX. Git and the providers
+  // elide the middle of a token they quote back (`ghp_abcdef…`), and an exact
+  // match would leave that head on screen — enough of a secret to be one.
+  // Both can be in one text (the value in a URL, the elided form in the
+  // host's reply), so the prefix pass runs whether or not the whole was
+  // found — but only once every whole value is gone, or the head two tokens
+  // share (`ghp_from…`) would garble the second before its own turn came.
+  // Down to a floor, so a short common head (`ghp_`) does not garble every
+  // other token in the log.
+  for (const token of ordered) scrubbed = scrubbed.replaceAll(token, '***');
+  // Every echoed prefix of every token, LONGEST FIRST ACROSS TOKENS — not
+  // token by token: two tokens can share a head longer than the floor
+  // (`ghp_abcdefgh…`), and one token's shorter prefix, taken first, would
+  // scrub that head out of the other's echo and leave the rest of it on
+  // screen (`***Y123…`). Longest first, the longer echo goes whole.
+  const prefixes = ordered.flatMap((token) =>
+    Array.from({ length: Math.max(0, token.length - MIN_ECHOED_PREFIX_LENGTH) }, (_, i) => token.slice(0, token.length - 1 - i)),
+  );
+  for (const prefix of [...new Set(prefixes)].sort((a, b) => b.length - a.length)) {
+    if (scrubbed.includes(prefix)) scrubbed = scrubbed.replaceAll(prefix, '***');
+  }
+  return (
+    scrubbed
+      // Through the LAST `@` before the path: a password can carry an
+      // unencoded `@` of its own (`https://user:p@ss@host`), and stopping at
+      // the first would leave the rest of it in the log.
+      .replace(/:\/\/[^/\s]*@/g, '://***@')
+      // A presigned remote carries its credential in the query instead
+      // (`?X-Amz-Signature=…`, `?access_token=…`). A git remote has no query
+      // worth keeping in a log, so the whole of it goes — up to whitespace or
+      // a fragment, not to the first quote: a credential can carry a quote
+      // of its own, and stopping there would leave the rest of it in the log.
+      // When git quoted the URL, the LAST quote of that kind before the next
+      // space is the one closing it, and what follows it (`': 403`) is kept.
+      .replace(
+        /(\bhttps?:\/\/[^\s?#'"]+)\?([^\s#]*)/gi,
+        (_m, url: string, query: string, offset: number, whole: string) => {
+          const opener = whole[offset - 1];
+          const closing = opener === "'" || opener === '"' ? query.lastIndexOf(opener) : -1;
+          return `${url}?***${closing === -1 ? '' : query.slice(closing)}`;
+        },
+      )
+  );
+}
+
+/** Shorter than this, a query value is not a credential (`X-Amz-Expires=3600`). */
+const MIN_SECRET_LENGTH = 8;
+
+/**
+ * The shortest head of a token that is still scrubbed when only a prefix of
+ * it was echoed — the same floor the connection probe's redactor uses. Below
+ * it a head is a vendor's common prefix, not a secret.
+ */
+const MIN_ECHOED_PREFIX_LENGTH = 8;
+
+/**
+ * A remote's query, named as literal secrets for {@link redactSecret}: the
+ * query as written and each value in it, raw and percent-decoded.
+ *
+ * `redactSecret` drops a query that FOLLOWS a URL. Naming the values as well
+ * scrubs them wherever else they turn up — decoded, or on their own — where no
+ * URL pattern can see them. Values too short to be a credential are left alone,
+ * so a `3600` in the query does not garble every number in the log.
+ */
+export function urlQuerySecrets(url: string | null | undefined): string[] {
+  let query: string;
+  try {
+    query = url ? new URL(url.trim()).search.slice(1) : '';
+  } catch {
+    return [];
+  }
+  const secrets = new Set<string>();
+  if (query.length >= MIN_SECRET_LENGTH) secrets.add(query);
+  for (const part of query.split('&')) {
+    const raw = part.slice(part.indexOf('=') + 1);
+    for (const value of [raw, decoded(raw)]) {
+      if (value.length >= MIN_SECRET_LENGTH) secrets.add(value);
+    }
+  }
+  return [...secrets];
+}
+
+function decoded(value: string): string {
+  try {
+    return decodeURIComponent(value.replace(/\+/g, ' '));
+  } catch {
+    return value;
+  }
+}