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

package/dist/modules/kb-sync/kb-sync.routes.d.ts

@@ -0,0 +1,70 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IKbSyncService, SyncResult } from './kb-sync.interface.js';
+/**
+ * Remote sync — a git host or a pipeline tells Hexis the repository changed.
+ *
+ *   POST /api/sync/<branch>   sync that one branch — the branch whose change
+ *                             made the call. What a GitHub Action or a
+ *                             pipeline step uses: the branch name goes in the
+ *                             URL, the body is ignored for branch selection.
+ *   POST /api/sync            the branches named by the body — an Azure
+ *                             DevOps service hook or a GitHub/GitLab webhook
+ *                             payload (they cannot template the URL), an
+ *                             explicit `{ "branches": [...] }`, or nothing,
+ *                             which syncs every clone Hexis holds.
+ *
+ * Mounted BEFORE every JWT-protected `/api` mount: the caller is a machine
+ * holding the deployment's sync secret, not a browser session, and Express 5
+ * would otherwise 401 it in the first protected mount. The route parses its
+ * own body as raw bytes (the global JSON parser skips this path) because the
+ * GitHub-style credential is an HMAC over exactly the bytes that arrived.
+ *
+ * Status codes are chosen for the two kinds of caller. A pipeline's
+ * `curl --fail` must fail exactly when Hexis is not in sync; a webhook host
+ * retries 5xx and gives up on 4xx:
+ *
+ *   200  every branch updated, already current, or not cloned here
+ *   409  a branch has a CONFLICT: Hexis-side commits clash with the host.
+ *        Automatic recovery is queued, but the branch is not in sync at the
+ *        time of the answer; the body's `error` names the files. A retry
+ *        answers 200 once recovery (or a person) has cleared it.
+ *   503  a branch could not be pulled (origin unreachable, credential
+ *        refused) — retriable. Also: no sync secret configured.
+ *   401  missing or wrong credential
+ *   400  a branch name git would refuse, or a body that is not JSON
+ */
+export interface KbSyncRouteDeps {
+    kbSync: IKbSyncService;
+    /** The configured secret, read per request so a setup-screen save applies at once. */
+    syncSecret: () => string;
+    authService: {
+        verifyToken(token: string): {
+            userId: string;
+            email: string;
+        };
+    };
+    adminAccess: IAdminAccessService;
+}
+/**
+ * Stamped on EVERY response this router writes. The endpoint answers 503 for
+ * an ordinary result (a branch could not be pulled), and a reverse proxy
+ * answers 503 when the backend is down; by status alone the browser cannot
+ * tell them apart, and it must — one is a line on the page, the other the
+ * maintenance overlay. A proxy standing in for a dead upstream never sets
+ * this header. Exposed to cross-origin callers in `create-core-server.ts`.
+ */
+export declare const SYNC_RESPONSE_HEADER = "X-Hexis-Sync";
+export declare const SYNC_RESPONSE_MARKER = "result";
+/**
+ * Whether a request path belongs to this router and must reach it with its
+ * body UNPARSED. The server's global JSON parser consults this: once that
+ * parser has read the stream, `express.raw` below sees nothing and the
+ * signature credential has no bytes to verify. Both routes share the check,
+ * so the branch form (`/api/sync/<branch>`) is covered as well as the bare
+ * one — an exact-path exemption used to protect only the latter.
+ */
+export declare function isSyncRawBodyPath(path: string): boolean;
+export declare function httpStatusFor(result: SyncResult): 200 | 409 | 503;
+export declare function createKbSyncRoutes(deps: KbSyncRouteDeps): express.Router;
+//# sourceMappingURL=kb-sync.routes.d.ts.map

package/dist/modules/kb-sync/kb-sync.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,sFAAsF;IACtF,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,WAAW,EAAE;QAAE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC/E,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAKD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AACnD,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASvD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAIjE;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAsGxE"}

package/dist/modules/kb-sync/kb-sync.routes.js

@@ -0,0 +1,135 @@
+import express from 'express';
+import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { parseSyncPayload } from './sync-payload.js';
+import { verifySyncCredential } from './sync-auth.js';
+/** Cap on a webhook body. ADO's PR payloads run to a few hundred KB. */
+const BODY_LIMIT = '2mb';
+/**
+ * Stamped on EVERY response this router writes. The endpoint answers 503 for
+ * an ordinary result (a branch could not be pulled), and a reverse proxy
+ * answers 503 when the backend is down; by status alone the browser cannot
+ * tell them apart, and it must — one is a line on the page, the other the
+ * maintenance overlay. A proxy standing in for a dead upstream never sets
+ * this header. Exposed to cross-origin callers in `create-core-server.ts`.
+ */
+export const SYNC_RESPONSE_HEADER = 'X-Hexis-Sync';
+export const SYNC_RESPONSE_MARKER = 'result';
+/**
+ * Whether a request path belongs to this router and must reach it with its
+ * body UNPARSED. The server's global JSON parser consults this: once that
+ * parser has read the stream, `express.raw` below sees nothing and the
+ * signature credential has no bytes to verify. Both routes share the check,
+ * so the branch form (`/api/sync/<branch>`) is covered as well as the bare
+ * one — an exact-path exemption used to protect only the latter.
+ */
+export function isSyncRawBodyPath(path) {
+    // Case-insensitive, because Express routing is: `/api/Sync` reaches this
+    // router, and if this check said no the global parser would eat the body
+    // first. On either form a signed call would then 401 (no bytes to verify).
+    // On the bare form a bearer call would silently sync every clone, since a
+    // body that is no longer a Buffer parses as "no body"; the branch form is
+    // unaffected there, its branch comes from the URL.
+    const lower = path.toLowerCase();
+    return lower === '/api/sync' || lower.startsWith('/api/sync/');
+}
+export function httpStatusFor(result) {
+    if (result.results.some((r) => r.outcome === 'conflict'))
+        return 409;
+    if (result.results.some((r) => r.outcome === 'error'))
+        return 503;
+    return 200;
+}
+export function createKbSyncRoutes(deps) {
+    const router = express.Router();
+    const rawBody = express.raw({ type: () => true, limit: BODY_LIMIT });
+    /**
+     * Everything both routes share: the credential check, then the sync and
+     * its answer. `select` turns the request into the branches to sync, or
+     * sends its own 400 and returns null.
+     */
+    async function handle(req, res, select) {
+        res.setHeader(SYNC_RESPONSE_HEADER, SYNC_RESPONSE_MARKER);
+        const raw = Buffer.isBuffer(req.body) ? req.body : undefined;
+        const auth = await verifySyncCredential({
+            secret: deps.syncSecret(),
+            authorization: header(req, 'authorization'),
+            gitlabToken: header(req, 'x-gitlab-token'),
+            hubSignature: header(req, 'x-hub-signature-256'),
+            rawBody: raw,
+        }, {
+            verifyJwt: (token) => {
+                try {
+                    return { email: deps.authService.verifyToken(token).email };
+                }
+                catch {
+                    return null;
+                }
+            },
+            isAdmin: (email) => deps.adminAccess.isAdmin(email),
+        });
+        if (!auth.ok) {
+            if (auth.status === 401)
+                res.setHeader('WWW-Authenticate', 'Bearer realm="hexis-sync"');
+            res.status(auth.status).json({ error: auth.message });
+            return;
+        }
+        const selection = select();
+        if (!selection)
+            return;
+        const who = auth.credential.kind === 'admin-session' ? auth.credential.email : auth.credential.kind;
+        const asked = selection.branches === 'all' ? 'all cloned branches' : selection.branches.join(', ') || '(none)';
+        try {
+            const result = await deps.kbSync.sync({ branches: selection.branches, by: who });
+            const summary = result.results.map((r) => `${r.branch}=${r.outcome}`).join(' ');
+            console.log(`[sync] by ${who} via ${selection.source} for ${asked}: ${result.status} ${summary}`);
+            res.status(httpStatusFor(result)).json(result);
+        }
+        catch (err) {
+            console.error('[sync] unhandled error:', err);
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+    // The branch in the URL. A wildcard rather than `:branch` so a branch with
+    // slashes (`ali/new-skill`) works spelled either way — as segments or
+    // percent-encoded as one.
+    router.post('/sync/*branch', rawBody, (req, res) => handle(req, res, () => {
+        const param = req.params.branch;
+        const branch = (Array.isArray(param) ? param.join('/') : String(param ?? '')).trim();
+        try {
+            assertValidBranchName(branch);
+        }
+        catch {
+            res.status(400).json({ error: `Not a valid branch name: ${branch}` });
+            return null;
+        }
+        return { source: 'path', branches: [branch] };
+    }));
+    router.post('/sync', rawBody, (req, res) => handle(req, res, () => {
+        const raw = Buffer.isBuffer(req.body) ? req.body : undefined;
+        let body = undefined;
+        if (raw && raw.length > 0) {
+            try {
+                body = JSON.parse(raw.toString('utf8'));
+            }
+            catch {
+                res.status(400).json({ error: 'The request body is not valid JSON.' });
+                return null;
+            }
+        }
+        const parsed = parseSyncPayload(body);
+        if (parsed.invalid.length > 0) {
+            res.status(400).json({
+                error: `Not a valid branch name: ${parsed.invalid.join(', ')}`,
+                invalid: parsed.invalid,
+            });
+            return null;
+        }
+        return { source: parsed.source, branches: parsed.branches };
+    }));
+    return router;
+}
+function header(req, name) {
+    const v = req.headers[name];
+    return typeof v === 'string' ? v : undefined;
+}
+//# sourceMappingURL=kb-sync.routes.js.map

package/dist/modules/kb-sync/kb-sync.routes.js.map

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

package/dist/modules/kb-sync/kb-sync.service.d.ts

@@ -0,0 +1,45 @@
+import type { IKbSyncService, LastSync, SyncRequest, SyncResult, SyncWorkflowPort, SyncWorkspacePort } from './kb-sync.interface.js';
+/**
+ * Runs remote syncs one at a time and folds everything that arrives
+ * mid-run into ONE follow-up.
+ *
+ * Why coalesce: a git host fires several hooks for one event — Azure DevOps
+ * sends a push, a PR-updated and a PR-merged within a second of each other —
+ * and each would otherwise queue behind the workspace mutex to pull the same
+ * tree again. The follow-up pulls the union of every request that arrived
+ * during the run (an "all" absorbs the rest).
+ *
+ * But each caller is answered for the branches IT asked about. The endpoint
+ * promises to fail exactly when the caller's branch is not in sync; a hook
+ * for branch A answered with branch B's conflict would fail the wrong
+ * subscription — and a host that disables subscriptions after repeated
+ * failures would disable the wrong one.
+ *
+ * Branches are pulled sequentially. N is small (only cloned branches count),
+ * the per-clone mutex serialises them anyway, and one slow origin round-trip
+ * at a time keeps the process calm during a burst.
+ */
+export declare class KbSyncService implements IKbSyncService {
+    private readonly workflow;
+    private readonly workspaces;
+    private readonly now;
+    private inFlight;
+    /** Everyone who arrived mid-run, each with what they asked for. */
+    private waiters;
+    private last;
+    constructor(workflow: SyncWorkflowPort, workspaces: SyncWorkspacePort, now?: () => number);
+    lastSync(): LastSync | null;
+    sync(request: SyncRequest): Promise<SyncResult>;
+    private start;
+    /**
+     * Run ONE follow-up for everyone who arrived during the last run: the union
+     * of their branches, then each waiter answered from its own share of the
+     * result — never from another caller's branches.
+     */
+    private drain;
+    /** The part of a union run that answers one caller: its branches, and its status over them. */
+    private static subsetFor;
+    private static statusOf;
+    private run;
+}
+//# sourceMappingURL=kb-sync.service.d.ts.map

package/dist/modules/kb-sync/kb-sync.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-sync.service.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/kb-sync.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAYhD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAbtB,OAAO,CAAC,QAAQ,CAAiC;IACjD,mEAAmE;IACnE,OAAO,CAAC,OAAO,CAKP;IACR,OAAO,CAAC,IAAI,CAAyB;gBAGlB,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,GAAE,MAAM,MAAyB;IAGvD,QAAQ,IAAI,QAAQ,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAW/C,OAAO,CAAC,KAAK;IASb;;;;OAIG;IACH,OAAO,CAAC,KAAK;IA2Bb,+FAA+F;IAC/F,OAAO,CAAC,MAAM,CAAC,SAAS;IAWxB,OAAO,CAAC,MAAM,CAAC,QAAQ;YAWT,GAAG;CAyElB"}

package/dist/modules/kb-sync/kb-sync.service.js

@@ -0,0 +1,183 @@
+import { sanitizeError } from '../workflow/sanitize-error.js';
+/**
+ * Runs remote syncs one at a time and folds everything that arrives
+ * mid-run into ONE follow-up.
+ *
+ * Why coalesce: a git host fires several hooks for one event — Azure DevOps
+ * sends a push, a PR-updated and a PR-merged within a second of each other —
+ * and each would otherwise queue behind the workspace mutex to pull the same
+ * tree again. The follow-up pulls the union of every request that arrived
+ * during the run (an "all" absorbs the rest).
+ *
+ * But each caller is answered for the branches IT asked about. The endpoint
+ * promises to fail exactly when the caller's branch is not in sync; a hook
+ * for branch A answered with branch B's conflict would fail the wrong
+ * subscription — and a host that disables subscriptions after repeated
+ * failures would disable the wrong one.
+ *
+ * Branches are pulled sequentially. N is small (only cloned branches count),
+ * the per-clone mutex serialises them anyway, and one slow origin round-trip
+ * at a time keeps the process calm during a burst.
+ */
+export class KbSyncService {
+    workflow;
+    workspaces;
+    now;
+    inFlight = null;
+    /** Everyone who arrived mid-run, each with what they asked for. */
+    waiters = [];
+    last = null;
+    constructor(workflow, workspaces, now = () => Date.now()) {
+        this.workflow = workflow;
+        this.workspaces = workspaces;
+        this.now = now;
+    }
+    lastSync() {
+        return this.last;
+    }
+    sync(request) {
+        if (!this.inFlight)
+            return this.start(request);
+        return new Promise((resolve, reject) => {
+            // Copied on entry: the caller keeps its array, and a caller that reuses
+            // or edits it before the follow-up runs must not change what is pulled
+            // or what it is answered for.
+            const branches = request.branches === 'all' ? 'all' : [...request.branches];
+            this.waiters.push({ branches, by: request.by, resolve, reject });
+        });
+    }
+    start(request) {
+        const run = this.run(request);
+        this.inFlight = run.catch(() => undefined).finally(() => {
+            this.inFlight = null;
+            this.drain();
+        });
+        return run;
+    }
+    /**
+     * Run ONE follow-up for everyone who arrived during the last run: the union
+     * of their branches, then each waiter answered from its own share of the
+     * result — never from another caller's branches.
+     */
+    drain() {
+        if (this.waiters.length === 0)
+            return;
+        const waiters = this.waiters;
+        this.waiters = [];
+        const union = new Set();
+        let all = false;
+        const by = new Set();
+        for (const w of waiters) {
+            if (w.branches === 'all')
+                all = true;
+            else
+                for (const b of w.branches)
+                    union.add(b);
+            if (w.by)
+                by.add(w.by);
+        }
+        const request = {
+            branches: all ? 'all' : [...union],
+            by: by.size > 0 ? [...by].join(', ') : undefined,
+        };
+        this.start(request).then((result) => {
+            for (const w of waiters)
+                w.resolve(KbSyncService.subsetFor(result, w.branches));
+        }, (err) => {
+            for (const w of waiters)
+                w.reject(err);
+        });
+    }
+    /** The part of a union run that answers one caller: its branches, and its status over them. */
+    static subsetFor(result, branches) {
+        if (branches === 'all')
+            return result;
+        const wanted = new Set(branches);
+        const results = result.results.filter((r) => wanted.has(r.branch));
+        return {
+            status: KbSyncService.statusOf(results),
+            results,
+            changeRequests: result.changeRequests,
+        };
+    }
+    static statusOf(results) {
+        const clean = results.every((r) => r.outcome === 'updated' ||
+            r.outcome === 'up-to-date' ||
+            r.outcome === 'not-cloned' ||
+            r.outcome === 'remote-gone');
+        return clean ? 'synced' : 'partial';
+    }
+    async run(request) {
+        const known = await this.workspaces.listClonedWorkspaces();
+        const byBranch = new Map(known.map((w) => [w.branch, w.id]));
+        const targets = request.branches === 'all'
+            ? known.map((w) => ({ branch: w.branch, id: w.id }))
+            : request.branches.map((branch) => ({ branch, id: byBranch.get(branch) ?? null }));
+        const unreadable = new Map(known.filter((w) => w.unreadable).map((w) => [w.branch, w.unreadable]));
+        const results = [];
+        for (const { branch, id } of targets) {
+            if (id === null) {
+                results.push({ branch, outcome: 'not-cloned' });
+                continue;
+            }
+            const cannotRead = unreadable.get(branch);
+            if (cannotRead) {
+                results.push({ branch, outcome: 'error', error: cannotRead });
+                continue;
+            }
+            let outcome;
+            try {
+                outcome = await this.workflow.syncWorkspaceFromRemote(id);
+            }
+            catch (err) {
+                // The workflow step promises outcomes, not throws — but one broken
+                // clone must never take the other branches, the sweep, or every
+                // coalesced caller down with it, so the promise is enforced here too.
+                const message = sanitizeError(err);
+                console.error(`[sync] unexpected failure syncing "${branch}": ${message}`);
+                outcome = { branch, outcome: 'error', error: message };
+            }
+            results.push(outcome);
+            if (outcome.outcome === 'remote-gone') {
+                // The host deleted the branch. Left in place, the stale clone would
+                // fail its fetch on every following full sync — and a webhook host
+                // disables a subscription that keeps failing. The workflow retires it
+                // under the branch-lifecycle lock, after asking origin again, so a
+                // branch recreated since the pull keeps its clone. Best-effort.
+                try {
+                    const removed = await this.workflow.retireRemoteGoneClone(id);
+                    if (removed)
+                        console.log(`[sync] removed the clone of "${branch}" — deleted on the host`);
+                    else
+                        console.log(`[sync] kept the clone of "${branch}" — it is back on the host, or already gone`);
+                }
+                catch (err) {
+                    console.warn(`[sync] could not remove the clone of "${branch}":`, sanitizeError(err));
+                }
+            }
+        }
+        // The host may have deleted a branch (an ADO PR completed with "delete
+        // source branch"); the existing sweep closes the Hexis request that
+        // pointed at it. Best-effort — it fails safe by closing nothing.
+        let closedDeletedBranch = 0;
+        try {
+            closedDeletedBranch = await this.workflow.closeChangeRequestsWithDeletedBranches();
+        }
+        catch (err) {
+            console.warn('[sync] deleted-branch sweep failed:', err instanceof Error ? err.message : err);
+        }
+        const result = {
+            status: KbSyncService.statusOf(results),
+            results,
+            changeRequests: { closedDeletedBranch },
+        };
+        this.last = {
+            at: this.now(),
+            by: request.by ?? 'unknown',
+            status: result.status,
+            results: [...results],
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=kb-sync.service.js.map

package/dist/modules/kb-sync/kb-sync.service.js.map

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

package/dist/modules/kb-sync/sync-auth.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Who may call `POST /api/sync`, decided from the request's credentials.
+ *
+ * Framework-agnostic on purpose (the route hands in plain strings and the
+ * raw body) so the rule is one function with one test, not something spread
+ * across middleware.
+ *
+ * Four credentials are accepted, because the callers cannot all speak the
+ * same one:
+ *
+ *   bearer            `Authorization: Bearer <secret>` — ADO Web Hooks and
+ *                     any pipeline can set a header.
+ *   gitlab-token      `X-Gitlab-Token: <secret>` — what GitLab sends.
+ *   github-signature  `X-Hub-Signature-256: sha256=<hmac of the raw body>` —
+ *                     GitHub and Gitea cannot set headers, only sign.
+ *   admin-session     a browser JWT whose user is an admin, so a "Sync now"
+ *                     button and a curl with your own session both work while
+ *                     the hook is being wired up.
+ *
+ * Every comparison is constant-time. The secret never travels in the URL.
+ */
+export type SyncCredential = {
+    kind: 'bearer' | 'gitlab-token' | 'github-signature';
+} | {
+    kind: 'admin-session';
+    email: string;
+};
+export type SyncAuthResult = {
+    ok: true;
+    credential: SyncCredential;
+} | {
+    ok: false;
+    status: 401 | 503;
+    message: string;
+};
+export interface SyncAuthInput {
+    /** The configured secret, or empty when none is set. */
+    secret: string;
+    authorization?: string;
+    gitlabToken?: string;
+    hubSignature?: string;
+    /** The request body exactly as received — the HMAC is over these bytes. */
+    rawBody?: Buffer;
+}
+export interface SyncSessionVerifier {
+    /** Resolve a browser JWT to its email, or null when it is not one. */
+    verifyJwt(token: string): {
+        email: string;
+    } | null;
+    isAdmin(email: string): Promise<boolean>;
+}
+/**
+ * Shortest secret the endpoint will honour. The setup screen enforces the
+ * same floor on save; this is the boundary that also covers a secret set
+ * through the environment, which no validator ever sees.
+ */
+export declare const MIN_SYNC_SECRET_LENGTH = 16;
+export declare function verifySyncCredential(input: SyncAuthInput, session: SyncSessionVerifier): Promise<SyncAuthResult>;
+//# sourceMappingURL=sync-auth.d.ts.map

package/dist/modules/kb-sync/sync-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-auth.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/sync-auth.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,GAAG,kBAAkB,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,cAAc,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAMD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAazC,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CA4CzB"}

package/dist/modules/kb-sync/sync-auth.js

@@ -0,0 +1,62 @@
+import { createHmac } from 'node:crypto';
+import { timingSafeStringEqual } from '../auth/password-hash.js';
+const NO_SECRET = 'No sync secret is configured. Set KB_SYNC_SECRET (or the setup screen’s sync secret), ' +
+    'or call this endpoint with an administrator session.';
+/**
+ * Shortest secret the endpoint will honour. The setup screen enforces the
+ * same floor on save; this is the boundary that also covers a secret set
+ * through the environment, which no validator ever sees.
+ */
+export const MIN_SYNC_SECRET_LENGTH = 16;
+const SECRET_TOO_SHORT = `The configured sync secret is shorter than ${MIN_SYNC_SECRET_LENGTH} characters and is not ` +
+    'accepted. Set a longer KB_SYNC_SECRET, or call this endpoint with an administrator session.';
+function signatureMatches(secret, rawBody, header) {
+    const [scheme, hex] = header.split('=', 2);
+    if (scheme !== 'sha256' || !hex)
+        return false;
+    const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+    return timingSafeStringEqual(expected, hex.toLowerCase());
+}
+export async function verifySyncCredential(input, session) {
+    const configured = input.secret.trim();
+    // A too-short secret is treated as absent for matching purposes and named
+    // as the problem below, so a one-character deployment secret can never be
+    // what lets a caller in.
+    const usable = configured.length >= MIN_SYNC_SECRET_LENGTH;
+    const secret = usable ? configured : '';
+    const bearer = input.authorization?.startsWith('Bearer ')
+        ? input.authorization.slice('Bearer '.length).trim()
+        : '';
+    // A shared secret presented in any of its three shapes.
+    if (secret) {
+        if (bearer && timingSafeStringEqual(bearer, secret)) {
+            return { ok: true, credential: { kind: 'bearer' } };
+        }
+        if (input.gitlabToken && timingSafeStringEqual(input.gitlabToken.trim(), secret)) {
+            return { ok: true, credential: { kind: 'gitlab-token' } };
+        }
+        if (input.hubSignature && input.rawBody && signatureMatches(secret, input.rawBody, input.hubSignature.trim())) {
+            return { ok: true, credential: { kind: 'github-signature' } };
+        }
+    }
+    // An admin's own session, carried as the bearer. Checked after the secret
+    // so a secret that happens to parse as a JWT is never mistaken for one.
+    if (bearer) {
+        const claim = session.verifyJwt(bearer);
+        if (claim && (await session.isAdmin(claim.email))) {
+            return { ok: true, credential: { kind: 'admin-session', email: claim.email } };
+        }
+    }
+    // Nothing matched. Say WHY when the reason is the deployment's, not the
+    // caller's: a hook pointed at an unconfigured endpoint should read "set
+    // the secret", not "wrong secret".
+    if (!secret && (bearer || input.gitlabToken || input.hubSignature)) {
+        return { ok: false, status: 503, message: configured ? SECRET_TOO_SHORT : NO_SECRET };
+    }
+    return {
+        ok: false,
+        status: 401,
+        message: 'A valid sync secret or an administrator session is required.',
+    };
+}
+//# sourceMappingURL=sync-auth.js.map

package/dist/modules/kb-sync/sync-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-auth.js","sourceRoot":"","sources":["../../../src/modules/kb-sync/sync-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AA+CjE,MAAM,SAAS,GACb,wFAAwF;IACxF,sDAAsD,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,MAAM,gBAAgB,GACpB,8CAA8C,sBAAsB,yBAAyB;IAC7F,6FAA6F,CAAC;AAEhG,SAAS,gBAAgB,CAAC,MAAc,EAAE,OAAe,EAAE,MAAc;IACvE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,QAAQ,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5E,OAAO,qBAAqB,CAAC,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAoB,EACpB,OAA4B;IAE5B,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACvC,0EAA0E;IAC1E,0EAA0E;IAC1E,yBAAyB;IACzB,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,IAAI,sBAAsB,CAAC;IAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,EAAE,UAAU,CAAC,SAAS,CAAC;QACvD,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QACpD,CAAC,CAAC,EAAE,CAAC;IAEP,wDAAwD;IACxD,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,IAAI,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;YACpD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;QACtD,CAAC;QACD,IAAI,KAAK,CAAC,WAAW,IAAI,qBAAqB,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;YACjF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,CAAC;QAC5D,CAAC;QACD,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,CAAC;QAChE,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,wEAAwE;IACxE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,KAAK,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAClD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACjF,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,wEAAwE;IACxE,mCAAmC;IACnC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACnE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;IACxF,CAAC;IACD,OAAO;QACL,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,8DAA8D;KACxE,CAAC;AACJ,CAAC"}

package/dist/modules/kb-sync/sync-payload.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turn whatever a caller POSTed to `/api/sync` into the branches to sync.
+ *
+ * Pure: no IO, no throwing on foreign shapes. The endpoint is meant to be
+ * pointed at by a webhook subscription whose payload the operator does not
+ * control, so an unrecognised body must degrade to "sync everything" — the
+ * safe answer, and the one an empty pipeline call gets too — never to a 400
+ * that makes the host disable the subscription.
+ *
+ * Recognised shapes:
+ *
+ *   explicit      `{ "branches": ["main", "ali/x"] }`
+ *   azure-devops  `eventType: git.push` → `resource.refUpdates[].name`
+ *                 `eventType: git.pullrequest.*` → `resource.targetRefName`
+ *                 and `resource.sourceRefName`
+ *   github/gitea  `{ "ref": "refs/heads/main" }` (push)
+ *   gitlab        `{ "object_kind": "push", "ref": "refs/heads/main" }`
+ *
+ * Only `refs/heads/*` refs count; a tag push names nothing to sync. A branch
+ * name git would refuse is dropped from a provider payload (the host
+ * produced it, nothing we can do) but reported for an explicit body, where
+ * it is the caller's mistake to fix.
+ */
+export type SyncPayloadSource = 'explicit' | 'azure-devops' | 'github' | 'gitlab' | 'none';
+export interface ParsedSyncPayload {
+    source: SyncPayloadSource;
+    branches: string[] | 'all';
+    /** Explicit-body names git would refuse. Empty for every other source. */
+    invalid: string[];
+}
+export declare function parseSyncPayload(body: unknown): ParsedSyncPayload;
+//# sourceMappingURL=sync-payload.d.ts.map

package/dist/modules/kb-sync/sync-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-payload.d.ts","sourceRoot":"","sources":["../../../src/modules/kb-sync/sync-payload.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3F,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC3B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA+CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,CA+DjE"}