@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/dist/modules/github-app/github-app.routes.js

@@ -0,0 +1,323 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+import { GitHubAppClient, GitHubAppError } from './github-app.client.js';
+import { repositoriesAsSetting } from './github-app.connection.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+const log = logger('github-app');
+const STATE_COOKIE = 'hexis_github_state';
+const STATE_MAX_AGE_S = 15 * 60;
+/** A GitHub organisation's name, as it appears in an address. */
+const ORGANIZATION_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+/** GitHub refuses an app name longer than this. */
+const MAX_APP_NAME = 34;
+/** The address GitHub is told to send the browser back to once the app is installed. */
+export function githubAppCallbackUrl(publicBackendUrl) {
+    return `${publicBackendUrl}/api/setup/github-app/callback`;
+}
+/**
+ * The manifest a deployment's own GitHub App is created from. It asks for
+ * what the deployment does and nothing else: read and write the contents of
+ * the repositories it is installed on. No webhook, no events, not public:
+ * the app is this deployment's, installed by its owner on the one
+ * repository the knowledge base lives in.
+ */
+export function githubAppManifest(publicBackendUrl, publicFrontendUrl) {
+    const host = new URL(publicFrontendUrl).host;
+    return {
+        name: `Hexis ${host}`.slice(0, MAX_APP_NAME),
+        url: publicFrontendUrl,
+        description: `Lets the Hexis deployment at ${host} read and write the repository its knowledge base lives in.`,
+        redirect_url: `${publicBackendUrl}/api/setup/github-app/registered`,
+        callback_urls: [githubAppCallbackUrl(publicBackendUrl)],
+        // GitHub then sends the person back signed in, which is what lets the
+        // deployment check that the installation they name is one they hold.
+        request_oauth_on_install: true,
+        public: false,
+        default_permissions: { contents: 'write', metadata: 'read' },
+        default_events: [],
+    };
+}
+function readCookie(req, name) {
+    for (const segment of (req.headers.cookie ?? '').split(';')) {
+        const trimmed = segment.trim();
+        if (!trimmed.startsWith(`${name}=`))
+            continue;
+        try {
+            return decodeURIComponent(trimmed.slice(name.length + 1)) || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function same(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/**
+ * Connecting a repository on GitHub through a GitHub App, from the setup
+ * screen. Mounted behind the deployment's sign-in; every route is an
+ * admin's.
+ *
+ *   GET  /setup/github-app               where the connection stands
+ *   POST /setup/github-app/manifest      start registering this deployment's own app
+ *   GET  /setup/github-app/registered    GitHub sends the browser back: the app exists
+ *   POST /setup/github-app/install       where on GitHub the app is installed
+ *   POST /setup/github-app/refresh       where to sign in, to read again what may be connected
+ *   GET  /setup/github-app/callback      GitHub sends the browser back: the app is installed
+ *   GET  /setup/github-app/repositories  what the deployment may be pointed at
+ *
+ * A ROUND TRIP IS STARTED BY A POST AND ENDED BY A GET. The two routes
+ * GitHub sends the browser to are ordinary navigations, authenticated by
+ * the session cookie; each checks a state this browser was given when the
+ * round trip started, and spends it. Nothing that starts one is a link, so
+ * a link somebody was sent starts nothing.
+ *
+ * WHAT THE DEPLOYMENT MAY REACH is never taken from the address the browser
+ * came back on. GitHub puts an installation's number there and anyone can
+ * write another: with one app serving many deployments, that number is the
+ * only thing between a deployment and another organisation's repositories.
+ * GitHub sends the person back signed in, and the deployment asks GitHub
+ * two things about THAT PERSON: which installations they reach, and which
+ * repositories of the one they named they can push to with their own
+ * account. The first alone is not enough, since read access to one
+ * repository puts an installation on that list. Only the second is what
+ * the deployment may be pointed at.
+ */
+export function createGitHubAppRoutes(deps) {
+    const router = express.Router();
+    const client = deps.client ?? new GitHubAppClient();
+    const { settings, connection } = deps;
+    const secure = deps.publicBackendUrl.startsWith('https');
+    const requireAdmin = async (req, res, next) => {
+        if (!(await deps.adminAccess.isAdmin(req.userEmail))) {
+            res.status(403).json({ error: 'Admins only' });
+            return;
+        }
+        next();
+    };
+    /** A state for one round trip, kept in this browser until it comes back. */
+    const beginRoundTrip = (res) => {
+        const tag = settings.resolve('githubAppStateTag');
+        const state = `${tag ? `${tag}.` : ''}${randomBytes(24).toString('base64url')}`;
+        res.cookie(STATE_COOKIE, state, { httpOnly: true, sameSite: 'lax', secure, maxAge: STATE_MAX_AGE_S * 1000, path: '/' });
+        return state;
+    };
+    /** Whether the browser that came back is the one that was sent. */
+    const cameBack = (req) => {
+        const kept = readCookie(req, STATE_COOKIE);
+        const given = typeof req.query.state === 'string' ? req.query.state : '';
+        return Boolean(kept && given && same(kept, given));
+    };
+    /** Back to the setup screen, saying how the round trip ended. */
+    const finish = (res, outcome) => {
+        const page = deps.isComplete() ? '/deployment' : '/';
+        res.redirect(`${deps.publicFrontendUrl}${page}?github=${encodeURIComponent(outcome)}`);
+    };
+    const installUrl = (slug, state) => `https://github.com/apps/${encodeURIComponent(slug)}/installations/new?state=${encodeURIComponent(state)}`;
+    const outcomeOf = (err) => err instanceof GitHubAppError && err.kind === 'unreachable' ? 'unreachable' : 'refused';
+    router.get('/setup/github-app', requireAdmin, (_req, res) => {
+        const credentials = connection.credentials();
+        res.json({
+            // Who supplied the app. Null: this deployment has none yet, and can register its own.
+            registeredBy: connection.registeredBy(),
+            app: credentials ? { slug: credentials.slug, url: `https://github.com/apps/${credentials.slug}` } : null,
+            installation: connection.installationId()
+                ? { id: connection.installationId(), account: settings.resolve('githubInstallationAccount') }
+                : null,
+            repository: settings.resolve('githubRepository') || null,
+        });
+    });
+    router.post('/setup/github-app/manifest', requireAdmin, (req, res) => {
+        if (connection.credentials()) {
+            res.status(409).json({ error: 'This deployment already has a GitHub App.' });
+            return;
+        }
+        const organization = req.body?.organization;
+        const org = typeof organization === 'string' ? organization.trim() : '';
+        if (org && !ORGANIZATION_PATTERN.test(org)) {
+            res.status(400).json({ error: 'Enter the organisation’s name as it appears in its GitHub address.' });
+            return;
+        }
+        const state = beginRoundTrip(res);
+        const base = org ? `https://github.com/organizations/${org}/settings/apps/new` : 'https://github.com/settings/apps/new';
+        // The browser posts the manifest to GitHub itself: a form, not a request of ours.
+        res.json({
+            action: `${base}?state=${encodeURIComponent(state)}`,
+            manifest: githubAppManifest(deps.publicBackendUrl, deps.publicFrontendUrl),
+        });
+    });
+    router.get('/setup/github-app/registered', requireAdmin, async (req, res) => {
+        // Spent on return, however the return ends.
+        const returned = cameBack(req);
+        res.clearCookie(STATE_COOKIE, { path: '/' });
+        if (!returned) {
+            finish(res, 'state');
+            return;
+        }
+        const code = typeof req.query.code === 'string' ? req.query.code : '';
+        if (!code || connection.credentials()) {
+            finish(res, code ? 'already-registered' : 'refused');
+            return;
+        }
+        try {
+            const app = await client.convertManifest(code);
+            await settings.record({
+                githubAppId: app.appId,
+                githubAppSlug: app.slug,
+                githubAppPrivateKey: app.privateKey,
+                githubAppClientId: app.clientId,
+                githubAppClientSecret: app.clientSecret,
+            }, req.userId ?? null);
+            log.info(`GitHub App "${app.slug}" registered for this deployment`, { slug: app.slug, owner: app.owner });
+            // Straight on to installing it: the same round trip, the same state.
+            res.redirect(installUrl(app.slug, beginRoundTrip(res)));
+        }
+        catch (err) {
+            log.error('the GitHub App could not be registered:', { detail: err instanceof Error ? err.message : String(err) });
+            finish(res, outcomeOf(err));
+        }
+    });
+    /**
+     * A POST that answers with the address, and the page sends the browser
+     * there. As a link it was a round trip anyone could start in an admin's
+     * browser by getting them to follow it: the state would be set, and
+     * whatever they then installed would come back with a state that matched.
+     */
+    router.post('/setup/github-app/install', requireAdmin, (_req, res) => {
+        const credentials = connection.credentials();
+        if (!credentials) {
+            res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+            return;
+        }
+        res.json({ url: installUrl(credentials.slug, beginRoundTrip(res)) });
+    });
+    /**
+     * Ask GitHub again what the person may connect, WITHOUT installing
+     * anything: a sign-in with the app and nothing more, which comes back on
+     * the same callback with a code and no installation named.
+     *
+     * It exists because installing comes back only the first time. Once the
+     * app is installed, the address that installs it opens the installation's
+     * settings on GitHub, and GitHub sends nobody back from there: a
+     * repository added on that page was reached by the app and never offered
+     * here, since what is offered is what was recorded when the person
+     * connected. The same goes for an installation an organisation's owner
+     * approved later, in a browser of their own.
+     */
+    router.post('/setup/github-app/refresh', requireAdmin, (_req, res) => {
+        const credentials = connection.credentials();
+        if (!credentials) {
+            res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+            return;
+        }
+        const state = beginRoundTrip(res);
+        res.json({
+            url: `https://github.com/login/oauth/authorize?client_id=${encodeURIComponent(credentials.clientId)}&state=${encodeURIComponent(state)}`,
+        });
+    });
+    router.get('/setup/github-app/callback', requireAdmin, async (req, res) => {
+        const returned = cameBack(req);
+        res.clearCookie(STATE_COOKIE, { path: '/' });
+        if (!returned) {
+            finish(res, 'state');
+            return;
+        }
+        const credentials = connection.credentials();
+        if (!credentials) {
+            finish(res, 'not-registered');
+            return;
+        }
+        // Someone without the right to install asked their organisation's owner
+        // to: nothing is installed yet, and there is nothing to record.
+        if (req.query.setup_action === 'request') {
+            finish(res, 'requested');
+            return;
+        }
+        const code = typeof req.query.code === 'string' ? req.query.code : '';
+        const given = typeof req.query.installation_id === 'string' ? req.query.installation_id : '';
+        if (!code || (given !== '' && !/^\d+$/.test(given))) {
+            finish(res, 'refused');
+            return;
+        }
+        // Back from installing, GitHub names the installation. Back from a
+        // sign-in alone (see `refresh`) it names none, and the one in question
+        // is the one this deployment has. Either way it is only a name: what
+        // decides is what GitHub says the person reaches, below.
+        const refreshing = given === '';
+        const named = given || connection.installationId();
+        try {
+            const userToken = await client.exchangeUserCode(credentials, code);
+            const reached = await client.installationsOf(userToken);
+            let held = named ? reached.find((installation) => installation.id === named) : undefined;
+            if (!named) {
+                // No installation on record and none named: the app was installed
+                // where this browser never came back from (an owner approved it
+                // later). One the person reaches is the one; several are a choice
+                // only installing from here can make.
+                if (reached.length === 0) {
+                    finish(res, 'not-installed');
+                    return;
+                }
+                if (reached.length > 1) {
+                    finish(res, 'several');
+                    return;
+                }
+                held = reached[0];
+            }
+            if (!held) {
+                log.warn('an installation was named that the person who came back cannot reach', { installation: named });
+                finish(res, 'not-yours');
+                return;
+            }
+            // Reaching the installation is not holding it: read access to one
+            // repository it covers is enough for GitHub to list it. What the
+            // deployment may be pointed at is what THIS PERSON can push to.
+            const theirs = await client.repositoriesOf(userToken, held.id);
+            const writable = theirs.repositories.filter((repository) => repository.writable).map((r) => r.fullName);
+            if (writable.length === 0) {
+                log.warn('the person who came back can push to nothing the installation covers', { installation: held.id });
+                finish(res, 'nothing-to-write');
+                return;
+            }
+            await settings.record({
+                githubInstallationId: held.id,
+                githubRepositoriesPermitted: repositoriesAsSetting(writable),
+                ...(held.account ? { githubInstallationAccount: held.account } : {}),
+            }, req.userId ?? null);
+            // A token in hand was another installation's.
+            connection.forget();
+            log.info(refreshing
+                ? `what may be connected through the GitHub App on "${held.account}" was read again`
+                : `GitHub App installed on "${held.account}"`, { installation: held.id, account: held.account, repositories: writable.length });
+            finish(res, refreshing ? 'refreshed' : 'connected');
+        }
+        catch (err) {
+            log.error('the installation could not be confirmed:', { detail: err instanceof Error ? err.message : String(err) });
+            finish(res, outcomeOf(err));
+        }
+    });
+    router.get('/setup/github-app/repositories', requireAdmin, async (_req, res) => {
+        if (!connection.credentials() || !connection.installationId()) {
+            res.status(409).json({ error: 'Connect GitHub first.' });
+            return;
+        }
+        try {
+            res.json(await connection.repositories());
+        }
+        catch (err) {
+            log.error('the repositories could not be listed:', { detail: err instanceof Error ? err.message : String(err) });
+            const unreachable = err instanceof GitHubAppError && err.kind === 'unreachable';
+            res.status(502).json({
+                error: unreachable
+                    ? 'GitHub could not be reached. Try again shortly.'
+                    : 'GitHub would not list the repositories. The app may have been uninstalled: connect it again.',
+            });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=github-app.routes.js.map

package/dist/modules/github-app/github-app.routes.js.map

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

package/dist/modules/github-app/index.d.ts

@@ -0,0 +1,4 @@
+export { GitHubAppClient, GitHubAppError, appJwt, normalizePrivateKey, type GitHubAppCredentials, type GitHubFailureKind, type Installation, type InstallationRepository, type InstallationToken, type RegisteredApp, } from './github-app.client.js';
+export { GitHubAppConnection, repositoriesAsSetting, type GitHubAppConnectionOptions } from './github-app.connection.js';
+export { createGitHubAppRoutes, githubAppCallbackUrl, githubAppManifest, type GitHubAppRoutesDeps, } from './github-app.routes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/github-app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/github-app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,cAAc,EACd,MAAM,EACN,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACzH,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/modules/github-app/index.js

@@ -0,0 +1,4 @@
+export { GitHubAppClient, GitHubAppError, appJwt, normalizePrivateKey, } from './github-app.client.js';
+export { GitHubAppConnection, repositoriesAsSetting } from './github-app.connection.js';
+export { createGitHubAppRoutes, githubAppCallbackUrl, githubAppManifest, } from './github-app.routes.js';
+//# sourceMappingURL=index.js.map

package/dist/modules/github-app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/github-app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,cAAc,EACd,MAAM,EACN,mBAAmB,GAOpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAmC,MAAM,4BAA4B,CAAC;AACzH,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,GAElB,MAAM,wBAAwB,CAAC"}

package/dist/modules/kb-fs/branch-name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-name.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/branch-name.ts"],"names":[],"mappings":"AASA,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAIzC,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAwBxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAyBlE"}
+{"version":3,"file":"branch-name.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/branch-name.ts"],"names":[],"mappings":"AASA,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAIzC,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAwBxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAsClE"}

package/dist/modules/kb-fs/branch-name.js

@@ -49,8 +49,18 @@ export function assertValidRelativePath(relativePath) {
         throw new WorkflowValidationError('path is required');
     if (relativePath.length > 1024)
         throw new WorkflowValidationError('path too long');
-    if (relativePath.includes('\0'))
-        throw new WorkflowValidationError('path contains NUL');
+    // NUL, every other C0 control and DEL. A NUL is named on its own because it
+    // terminates a C string and git's `-z` output; the rest are refused with it
+    // because a LINE BREAK in a path is a separator in git's line-oriented stdin
+    // protocols — `cat-file --batch` reads one `<ref>:<path>` per line, so
+    // `Docs/secret.md\nzzz` is two object names while every gate upstream was
+    // asked about one string. See `CONTROL_CHARACTERS` in `repo-path.ts`, which
+    // refuses the same range at the normaliser; this is the same rule at the
+    // check every path handed to git as a pathspec passes through.
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1F\x7F]/.test(relativePath)) {
+        throw new WorkflowValidationError(relativePath.includes('\0') ? 'path contains NUL' : 'path contains a control character');
+    }
     if (relativePath.includes('\\')) {
         throw new WorkflowValidationError('path must use forward slashes only');
     }

package/dist/modules/kb-fs/branch-name.js.map

@@ -1 +1 @@
-{"version":3,"file":"branch-name.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/branch-name.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"branch-name.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/branch-name.ts"],"names":[],"mappings":"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"}

package/dist/modules/kb-fs/remote-url.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether two repository addresses name the same repository.
+ *
+ * The answer decides whether a working copy on disk is KEPT or DELETED, so it
+ * errs towards "same": only differences that cannot change which repository
+ * is meant are ignored, and they are ignored on both sides.
+ *
+ *  - a trailing slash, and a `.git` suffix — hosts serve both spellings;
+ *  - the letter case of the scheme and the host — DNS does not distinguish;
+ *  - userinfo (`user:token@`) — who asks does not change what is asked for,
+ *    and a credential must never decide, or appear in, a comparison.
+ *
+ * The PATH keeps its case: hosts that fold it and hosts that do not both
+ * exist, and treating `Org/Repo` and `org/repo` as one would keep a clone of
+ * the wrong repository on a host that tells them apart — but deleting a clone
+ * of the right one is the worse error, and an operator who only changed the
+ * case gets a re-clone, not a loss: the work on that clone was pushed to the
+ * same place.
+ */
+export declare function normalizeRepositoryAddress(address: string): string;
+export declare function sameRepository(a: string, b: string): boolean;
+//# sourceMappingURL=remote-url.d.ts.map

package/dist/modules/kb-fs/remote-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-url.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/remote-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWlE;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/modules/kb-fs/remote-url.js

@@ -0,0 +1,35 @@
+/**
+ * Whether two repository addresses name the same repository.
+ *
+ * The answer decides whether a working copy on disk is KEPT or DELETED, so it
+ * errs towards "same": only differences that cannot change which repository
+ * is meant are ignored, and they are ignored on both sides.
+ *
+ *  - a trailing slash, and a `.git` suffix — hosts serve both spellings;
+ *  - the letter case of the scheme and the host — DNS does not distinguish;
+ *  - userinfo (`user:token@`) — who asks does not change what is asked for,
+ *    and a credential must never decide, or appear in, a comparison.
+ *
+ * The PATH keeps its case: hosts that fold it and hosts that do not both
+ * exist, and treating `Org/Repo` and `org/repo` as one would keep a clone of
+ * the wrong repository on a host that tells them apart — but deleting a clone
+ * of the right one is the worse error, and an operator who only changed the
+ * case gets a re-clone, not a loss: the work on that clone was pushed to the
+ * same place.
+ */
+export function normalizeRepositoryAddress(address) {
+    let a = address.trim();
+    const url = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)(\/.*)?$/i.exec(a);
+    if (url) {
+        const host = url[2].replace(/^[^@]*@/, '').toLowerCase();
+        a = `${url[1].toLowerCase()}://${host}${url[3] ?? ''}`;
+    }
+    return a
+        .replace(/[\\/]+$/, '')
+        .replace(/\.git$/i, '')
+        .replace(/[\\/]+$/, '');
+}
+export function sameRepository(a, b) {
+    return normalizeRepositoryAddress(a) === normalizeRepositoryAddress(b);
+}
+//# sourceMappingURL=remote-url.js.map

package/dist/modules/kb-fs/remote-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-url.js","sourceRoot":"","sources":["../../../src/modules/kb-fs/remote-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAe;IACxD,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,2CAA2C,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChE,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1D,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC;SACL,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAS,EAAE,CAAS;IACjD,OAAO,0BAA0B,CAAC,CAAC,CAAC,KAAK,0BAA0B,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC"}

package/dist/modules/kb-fs/repo-path.d.ts

@@ -1,21 +1,16 @@
 /**
- * Workspace-relative paths and the repository folder.
- *
- * A workspace directory holds the git clone as `<kbDirName>/` (plus transient
- * scratch such as `tmp/`). The agent filesystem, the lock keys and the human
- * editor all speak WORKSPACE-relative paths, so a path reaches git only when
- * it starts with that folder — and `KnowledgeBase/Foo.md` on its own names a
- * location BESIDE the clone, that nothing commits and nothing pushes.
- *
- * Which is why nothing on this platform resolves a workspace path for itself.
- * Every accepted path goes through {@link normalizeWorkspacePath} first, which
- * places it inside the clone; {@link assertInsideRepo} is then the check that
- * what came out really is in there. A route or a tool that resolved a path of
- * its own would be the drift this file exists to prevent — a `KnowledgeBase/`
- * folder, a `Plugins/` folder and eight uploaded documents sitting beside a
- * staging checkout is what it looked like the last time two spellings of this
- * rule were allowed to exist.
+ * Whether `value` carries one of them — THE predicate, so the places that
+ * accept a NAME enforce the same rule as the normaliser that joins it into a
+ * path. The checkout folder name is the one that matters: it is not a caller's
+ * path, it is deployment configuration (`KB_DIR_NAME`, and the `kbDirName`
+ * setting), and it is PREFIXED onto every workspace-relative path. A name with
+ * a line break in it would therefore make the normaliser emit exactly the path
+ * this rule exists to exclude, from inputs that were each clean. Refused where
+ * the name is set — at boot in `core-config` and in the settings validator —
+ * so the deployment fails loudly instead of serving a path nothing downstream
+ * can safely read.
  */
+export declare function hasControlCharacter(value: string): boolean;
 /**
  * True when `wsPath` is the repository folder or lies under it.
  *

package/dist/modules/kb-fs/repo-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-path.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/repo-path.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAKvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAexE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAwChF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAY9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,IAAI,CAaN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC9F,IAAI,CAiBN;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}
+{"version":3,"file":"repo-path.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-fs/repo-path.ts"],"names":[],"mappings":"AAoDA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CASvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA+BxE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA2DhF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAY9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,IAAI,CAaN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC9F,IAAI,CAiBN;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}

package/dist/modules/kb-fs/repo-path.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
 /**
  * Workspace-relative paths and the repository folder.
  *
@@ -18,6 +19,49 @@ import { WorkflowValidationError } from '../../shared/domain-errors.js';
  * staging checkout is what it looked like the last time two spellings of this
  * rule were allowed to exist.
  */
+/**
+ * NUL, the C0 controls (a line break among them) and DEL — refused in a
+ * workspace path wherever one enters.
+ *
+ * Not merely hygiene about names nobody can type. A `\n` is a SEPARATOR in
+ * git's own line-oriented stdin protocols: `cat-file --batch` reads one
+ * `<ref>:<path>` object name per LINE, so `Docs/secret.md\nzzz` is TWO specs.
+ * Everything upstream — the read gate, the download gate, the not-a-directory
+ * check — is then asked about the whole string, which names nothing, while git
+ * answers about `Docs/secret.md` and hands over its bytes. A file denied by
+ * its own frontmatter inside a folder its reader may list would be readable
+ * that way, and in a batch of several specs the extra answer shifts every
+ * result after it, so the access resolver reads one directory's `access.md` as
+ * another's.
+ *
+ * Refused HERE, at the normaliser every accepted path goes through, rather
+ * than at each route: the fence has to be at the mechanism, because the next
+ * caller to assemble a git spec from a path will not remember this. The
+ * shared `validateFilename` has always refused the same range per segment, so
+ * no name any surface can create is lost — this closes the gap between it and
+ * the paths that reach git. U+2028/U+2029 are NOT in it: they are nothing to
+ * git's protocols (which read bytes, and a line break there is 0x0A), a name
+ * carrying one is creatable today, and refusing it here would make an existing
+ * file unreadable. They are escaped for display instead, which is what
+ * `sanitizedPath` is for.
+ */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\x00-\x1F\x7F]/;
+/**
+ * Whether `value` carries one of them — THE predicate, so the places that
+ * accept a NAME enforce the same rule as the normaliser that joins it into a
+ * path. The checkout folder name is the one that matters: it is not a caller's
+ * path, it is deployment configuration (`KB_DIR_NAME`, and the `kbDirName`
+ * setting), and it is PREFIXED onto every workspace-relative path. A name with
+ * a line break in it would therefore make the normaliser emit exactly the path
+ * this rule exists to exclude, from inputs that were each clean. Refused where
+ * the name is set — at boot in `core-config` and in the settings validator —
+ * so the deployment fails loudly instead of serving a path nothing downstream
+ * can safely read.
+ */
+export function hasControlCharacter(value) {
+    return CONTROL_CHARACTERS.test(value);
+}
 /**
  * True when `wsPath` is the repository folder or lies under it.
  *
@@ -32,6 +76,11 @@ import { WorkflowValidationError } from '../../shared/domain-errors.js';
 export function isInsideRepo(wsPath, kbDirName) {
     if (typeof wsPath !== 'string' || wsPath.includes('\\'))
         return false;
+    // A control character is not a spelling of any path under the repository —
+    // see {@link CONTROL_CHARACTERS}. Refused here too, so the check AFTER the
+    // normaliser cannot pass one that somehow skipped it.
+    if (CONTROL_CHARACTERS.test(wsPath))
+        return false;
     const segments = wsPath.replace(/\/$/, '').split('/');
     if (segments[0] !== kbDirName)
         return false;
@@ -52,6 +101,19 @@ export function isInsideRepo(wsPath, kbDirName) {
 export function assertInsideRepo(wsPath, kbDirName) {
     if (isInsideRepo(wsPath, kbDirName))
         return;
+    // Said as what it is, before the suggestion below: a control character is
+    // not a path that landed in the wrong place, and a "use this instead"
+    // carrying an invisible character back to the caller would be nonsense.
+    if (typeof wsPath === 'string' && CONTROL_CHARACTERS.test(wsPath)) {
+        // Through `sanitizedPath`, like every other refusal that names a path: the
+        // character that makes this path invalid is also the character that would
+        // forge a second line of the answer, in the message and in the `path` a
+        // JSON consumer reads.
+        const shown = sanitizedPath(wsPath);
+        throw new WorkflowValidationError(`"${shown}" contains a control character: a line break, a NUL or another invisible byte is not part of any ` +
+            'file name, and git reads a line break in a path as the end of one object name and the start of another. ' +
+            'Remove it and send the name as it is written.', { kind: 'path-control-character', path: shown, kbDirName });
+    }
     // The suggestion collapses what made the path wrong: backslashes, leading
     // `./` or `/`, and any `..` climbing back out (a bare `..` included, so the
     // suggestion is never itself a climb). The agent gets a path it can use.
@@ -101,6 +163,23 @@ export function normalizeWorkspacePath(wsPath, kbDirName) {
     // read. Refused before anything is collapsed, never rewritten to `/`.
     if (wsPath.includes('\\'))
         refuse();
+    // A line break (or any other control character) is a SEPARATOR to git, not
+    // part of a name — see {@link CONTROL_CHARACTERS}. Refused before the path
+    // is normalised, so no gate downstream is ever asked about a string that
+    // means one thing to it and two things to git.
+    if (CONTROL_CHARACTERS.test(wsPath))
+        refuse();
+    // …and the FOLDER NAME, which is prefixed onto the result rather than read
+    // from it: a clean path joined to `kb\nname` comes out carrying the line
+    // break, so the normaliser would itself emit what the check above refuses.
+    // Said as the configuration error it is — the caller's path is fine, and an
+    // operator reading a refusal about their own path would have nothing to fix.
+    // `core-config` and the `kbDirName` setting validator both refuse this at
+    // the point it is SET, so reaching here means the two drifted.
+    if (CONTROL_CHARACTERS.test(kbDirName)) {
+        throw new WorkflowValidationError(`the configured checkout folder name (kbDirName / KB_DIR_NAME) contains a control character: "${sanitizedPath(kbDirName)}". ` +
+            'Every workspace path is prefixed with it, so no path can be resolved until the setting is corrected.', { kind: 'kb-dir-name-control-character', kbDirName: sanitizedPath(kbDirName) });
+    }
     // The root-anchored form, and ONLY for the repository folder: `/<kbDirName>/…`
     // is what the app's Copy path gives (it is the form a Markdown link resolves
     // from) and names the same workspace path. `/tmp/x` and `//x` are not that