@unbrained/pm-web 2026.8.17 → 2026.8.29

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- Harden workflow publish scanning against YAML and reassignment bypasses ([pm-web-yafj](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-yafj.toon))
+
+## 2026.8.29 - 2026-08-29
+
+### Fixed
+
+- Every public API route lacked rate limiting, leaving auth and write endpoints open to abuse and denial of service ([pm-web-8dk0](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-8dk0.toon))
+
+## 2026.8.28 - 2026-08-28
+
+### Fixed
+
+- A failed provenance publish silently falls back to an unattested one ([pm-web-f8hk](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-f8hk.toon))
+- The health endpoint no longer reports ok: true when the database or projects volume is unreachable ([pm-web-u9mh](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-u9mh.toon))
+- Mount the real /healthz handler in pm-web (Greptile P1 on PR \#105) ([pm-web-iocm](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-iocm.toon))
+- The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([pm-web-kcs1](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-kcs1.toon))
+- Certify pm-web complete tracker reads and refresh the package catalog ([pm-web-crdr](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-crdr.toon))
+- Docstring corrections: filters, graph-canvas, crypto, board, pm routes, project-watcher, sse, mutation-event-watcher ([pm-web-oehb](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-oehb.toon))
+- Fix release publish-before-protected-main-push ordering ([pm-web-8l6j](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-8l6j.toon))
+
+### Security
+
+- The identity gate deadlocks the one remediation its own failure message prescribes ([pm-web-1ggj](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-1ggj.toon))
+
 ## 2026.8.17 - 2026-08-17
 
 ### Fixed

package/README.md

@@ -118,6 +118,7 @@ pm web doctor --json
 | `PM_CLI_BIN` | No | Explicit pm CLI executable path (default: packaged CLI, then `pm` from `PATH`) |
 | `PM_WEB_DB_POOL_MAX` | No | PostgreSQL pool size including one dedicated realtime listener (default: `20`, minimum: `2`) |
 | `NODE_ENV` | No | `production` enables caching |
+| `PM_WEB_TRUST_PROXY` | Behind a proxy | Reverse-proxy hops to trust for the client address (`1` for a single proxy such as Caddy), a comma-separated IP/subnet allowlist, or `false`/`0`. **Defaults to `false`** — a direct deployment must not trust `X-Forwarded-For`, or a caller can rotate that header to draw a fresh rate-limit bucket per request. Set it only when a proxy really does sit in front, otherwise the per-IP limits enforce nothing. |
 | `OLLAMA_BASE_URL` / `OLLAMA_HOST` | No | Local Ollama endpoint for semantic pm search |
 | `PM_OLLAMA_MODEL` | No | Embedding model for new projects, default `qwen3-embedding:0.6b` |
 | `NEO4J_URI` | No | Neo4j Bolt URI for graph sync |
@@ -149,6 +150,19 @@ within each Node process, so high-throughput installations should run multiple
 pm-web replicas behind a shared PostgreSQL realtime bus. Independent replicas
 converge through PostgreSQL notifications and the mutation-event watcher.
 
+Whole-project graph fallback, board, local search, iCalendar, and export reads
+use the SDK's high-level `listAllComplete` operation. pm-web accepts those rows
+only after the shared SDK certificate and supplemental 2026.8.21 source,
+omission, output-receipt, and budget checks all agree. The public `/pm/list-all`
+HTTP compatibility route remains deliberately paginated for interactive clients,
+but invokes canonical `list --all` internally; consumers that need the whole
+workspace must use a complete-read endpoint rather than assembling a page as if
+it were the corpus. The standalone server exact-pins pm CLI/SDK 2026.8.21, and
+the extension manifest refuses older hosts through the same compatibility floor.
+Commands that render their own text or JSON (`web status`, `web stop`, and
+`web doctor`) return the public SDK output-suppression marker, so the host never
+appends a second payload to stdout.
+
 Optional OIDC uses Authorization Code flow with PKCE, provider discovery/JWKS,
 signed state cookies, and issuer/subject identity mapping. It is disabled when
 no OIDC variables are present and production startup fails closed on partial or
@@ -186,13 +200,29 @@ MIT
 
 ## Release Automation
 
-This package is release-ready for GitHub, npm, and Bun-compatible installs. CI runs type checking, build, production dependency audit, package packing, Bun install verification, and pm-changelog validation. The daily release workflow publishes only when commits exist after the latest release tag and uses pm-changelog to generate CHANGELOG.md and GitHub release notes.
+CI runs type checking, exact Node 22.18.0 and current-Node matrices, real
+PostgreSQL integration tests, the configured coverage gate, complete docstring
+coverage, production dependency audit, package packing, fresh packed `npx` and
+`bunx` install-and-command acceptance, immutable workflow-action checks, and
+pm-changelog validation. The daily release
+workflow publishes at most once when commits exist after the latest release tag
+and uses pm-changelog for both `CHANGELOG.md` and GitHub release notes.
+
+The current package is **not** approved for a new release: exact all-source
+100/100/100/100 coverage remains open in
+[`pm-web-9ulj`](.agents/pm/epics/pm-web-9ulj.toon) and
+[`pm-web-ulgy`](.agents/pm/tasks/pm-web-ulgy.toon), while reachable-history
+privacy authorization is tracked in
+[`pm-web-priv`](.agents/pm/issues/pm-web-priv.toon) and
+[GitHub issue #96](https://github.com/unbraind/pm-web/issues/96). Passing the
+configured gate is evidence for the measured source set, not those independent
+release approvals.
 
 ## New data endpoints (kanban board & search)
 
-The pm data API now exposes board and search views, both driven by the
-workspace's live `pm contracts` schema (so they reflect the installed pm CLI +
-extensions):
+The pm data API exposes board and search views through the certified
+complete-read contract described above. The board also uses the workspace's
+live `pm contracts` statuses for its columns:
 
 - `GET /api/projects/:projectId/pm/board` — items grouped into kanban columns by
   the workspace's runtime statuses (unlisted statuses fall into `(other)`).

package/dist/app.d.ts

@@ -1,4 +1,5 @@
 import { type Express } from "express";
+import { type HealthProbeDeps } from "./health.ts";
 /**
  * Legal pages served as standalone HTML (not part of the SPA bundle).
  *
@@ -34,10 +35,33 @@ export declare const LEGAL_REDIRECTS: Record<string, string>;
  * @returns The real, resolved directory path holding the legal HTML files.
  */
 export declare function resolveLegalPagesDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Optional dependencies `createApp` can wire into the application.
+ *
+ * Currently only the {@link HealthProbeDeps} for the real `/healthz` handler is
+ * supported; the object is kept as a bag so further production-only wiring
+ * (e.g. a logger) can be added later without another signature change.
+ */
+export interface CreateAppDeps {
+    /**
+     * Health-probe dependencies for the real `/healthz` handler. When supplied,
+     * `createApp` mounts {@link createHealthHandler}, which probes PostgreSQL and
+     * the projects volume and answers 200/503 accordingly. When omitted, the
+     * route answers 503 `ok:false` (see the comment at the route) so a
+     * misconfigured deployment can never report healthy while its dependencies
+     * are down — the exact failure this handler was written to close.
+     */
+    readonly health?: HealthProbeDeps;
+}
 /**
  * Build the Express application with all middleware, static assets, legal
  * page routes, API routes and the SPA fallback — but WITHOUT touching the
  * database or binding a port. Splitting this out from server.ts keeps the
  * HTTP surface unit-testable without a running PostgreSQL instance.
+ *
+ * @param deps - Optional production wiring. Pass `health` to mount the real
+ *   probing `/healthz` handler; omit it for tests that only need the HTTP
+ *   surface (the route then answers 503 `ok:false`, never `ok:true`).
+ * @returns The configured Express application, not yet listening on a port.
  */
-export declare function createApp(): Express;
+export declare function createApp(deps?: CreateAppDeps): Express;

package/dist/app.js

@@ -3,6 +3,7 @@ import cookieParser from "cookie-parser";
 import path from "node:path";
 import { accessSync, constants, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createHealthHandler } from "./health.js";
 import { authRouter } from "./routes/auth.js";
 import { oidcRouter } from "./routes/oidc.js";
 import { projectsRouter } from "./routes/projects.js";
@@ -12,6 +13,8 @@ import { groupsRouter } from "./routes/groups.js";
 import { sharesRouter, sharedWithMeRouter } from "./routes/sharing.js";
 import { githubRouter } from "./routes/github.js";
 import { adminRouter } from "./routes/admin.js";
+import { createTierLimiters, resolveTrustProxy } from "./rate-limit.js";
+import { csrfProtection } from "./csrf.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PUBLIC_DIR = path.resolve(__dirname, "..", "public");
 /**
@@ -95,13 +98,31 @@ export function resolveLegalPagesDir(env = process.env) {
  * page routes, API routes and the SPA fallback — but WITHOUT touching the
  * database or binding a port. Splitting this out from server.ts keeps the
  * HTTP surface unit-testable without a running PostgreSQL instance.
+ *
+ * @param deps - Optional production wiring. Pass `health` to mount the real
+ *   probing `/healthz` handler; omit it for tests that only need the HTTP
+ *   surface (the route then answers 503 `ok:false`, never `ok:true`).
+ * @returns The configured Express application, not yet listening on a port.
  */
-export function createApp() {
+export function createApp(deps) {
     const app = express();
     const legalPagesDir = resolveLegalPagesDir();
+    // Trust the reverse proxy so `req.ip`, `req.hostname` and `req.protocol`
+    // reflect the real client behind Caddy instead of the proxy itself. This is
+    // what the rate limiter keys on: without it every client would share one
+    // bucket (the proxy's address) and the limiter would be useless. The hop
+    // count is configurable via PM_WEB_TRUST_PROXY; the default trusts a single
+    // hop, matching the documented Caddy deployment, and never `true` (which
+    // would let callers forge X-Forwarded-For and bypass per-client limits).
+    app.set("trust proxy", resolveTrustProxy(process.env));
+    // One set of tier limiters for this app instance; each owns an independent
+    // in-memory store so the tiers never steal each other's quota. See
+    // src/rate-limit.ts for the per-tier limits and the abuse each protects
+    // against.
+    const limiters = createTierLimiters(process.env);
     app.use(express.json({ limit: "1mb" }));
     app.use(cookieParser());
-    app.get("/sw.js", (_req, res) => {
+    app.get("/sw.js", limiters.staticAssets, (_req, res) => {
         res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, proxy-revalidate");
         res.setHeader("Pragma", "no-cache");
         res.setHeader("Expires", "0");
@@ -128,14 +149,32 @@ export function createApp() {
             return "unknown";
         }
     })();
-    app.get("/healthz", (_req, res) => res.json({ ok: true, version: PM_WEB_VERSION }));
+    if (deps?.health) {
+        // Production wiring: probe PostgreSQL and the projects volume before
+        // answering. `server.ts` always supplies these dependencies, so the
+        // deployed service reports healthy only when its hard dependencies are
+        // actually reachable.
+        app.get("/healthz", createHealthHandler(deps.health));
+    }
+    else {
+        // No health-probe dependencies were supplied, so this route cannot probe
+        // PostgreSQL or the projects volume. Answering `ok:true` here would
+        // reproduce the original bug this handler exists to close: pm-web has
+        // previously served frozen data for two days while `/healthz` reported
+        // healthy. A route that cannot probe must not claim `ok:true`, so the
+        // unconfigured default answers 503 with the version only. Production
+        // (`server.ts`) always supplies the real dependencies; this branch is
+        // reached only by tests that exercise the HTTP surface without a database
+        // and by misconfigured deployments, which must fail loud rather than lie.
+        app.get("/healthz", (_req, res) => res.status(503).json({ ok: false, version: PM_WEB_VERSION }));
+    }
     const legalPages = new Set(LEGAL_PAGES);
     Object.entries(LEGAL_REDIRECTS).forEach(([from, to]) => {
         app.get(from, (_req, res) => {
             res.redirect(308, to);
         });
     });
-    app.get(["/legal-notice", "/privacy-policy", "/terms", "/cookie-settings"], (req, res) => {
+    app.get(["/legal-notice", "/privacy-policy", "/terms", "/cookie-settings"], limiters.staticAssets, (req, res) => {
         // Non-strict routing also matches trailing-slash variants (/terms/), so
         // normalize before the whitelist lookup instead of 404ing on them.
         const page = req.path.replace(/\/+$/, "").slice(1);
@@ -146,24 +185,45 @@ export function createApp() {
         res.setHeader("Cache-Control", "no-store");
         res.sendFile(path.join(legalPagesDir, `${page}.html`));
     });
-    // API routes
+    // CSRF guard: issued after cookie-parser (it reads/sets the csrf cookie) and
+    // before the API routers so every cookie-authenticated state-changing route
+    // is guarded. See src/csrf.ts.
+    app.use(csrfProtection());
+    // API routes. Each mount sits behind the tier that matches its abuse profile:
+    //   - /api/auth  → auth tier (tightest): credential brute-force / account abuse.
+    //   - /api/admin → admin tier (tight): privileged operations, rare in normal use.
+    //   - every other /api mount → read tier (GET/HEAD/OPTIONS) + write tier
+    //     (POST/PATCH/PUT/DELETE), split by method via the limiters' `skip`
+    //     predicates so reads and writes carry separate per-minute budgets.
+    // Real-time collaborative editing generates many requests per user, but a
+    // single human stays well under 300 writes/min and 600 reads/min; the limits
+    // stop scripted floods without throttling normal collaboration.
+    // A limiter counts every request that traverses it, so it must be mounted at
+    // exactly one point per path. Repeating it on a prefix and again on a nested
+    // mount charged one request twice and silently halved the published budget:
+    // /api/auth fell through oidcRouter into authRouter, and every
+    // /api/projects/... request matched the /api/projects prefix before its own
+    // nested mount. Each shared prefix therefore carries its limiters once, and
+    // the routers mount behind them.
+    app.use("/api/auth", limiters.auth);
     app.use("/api/auth", oidcRouter);
     app.use("/api/auth", authRouter);
+    app.use("/api/projects", limiters.read, limiters.write);
     app.use("/api/projects", projectsRouter);
     app.use("/api/projects/:projectId/pm", pmRouter);
     app.use("/api/projects/:projectId/extensions", extensionsRouter);
-    app.use("/api/groups", groupsRouter);
     app.use("/api/projects/:id/shares", sharesRouter);
-    app.use("/api/shared", sharedWithMeRouter);
     app.use("/api/projects/:id/github", githubRouter);
-    app.use("/api/admin", adminRouter);
+    app.use("/api/groups", limiters.read, limiters.write, groupsRouter);
+    app.use("/api/shared", limiters.read, limiters.write, sharedWithMeRouter);
+    app.use("/api/admin", limiters.admin, adminRouter);
     // Unknown API routes get a JSON 404 instead of falling through to the SPA
     // shell, which would hand HTML to API clients expecting JSON.
     app.all("/api/{*splat}", (_req, res) => {
         res.status(404).json({ error: "Not found" });
     });
     // SPA fallback — serve index.html for all non-API routes
-    app.get("/{*splat}", (_req, res) => {
+    app.get("/{*splat}", limiters.staticAssets, (_req, res) => {
         res.sendFile(path.join(PUBLIC_DIR, "index.html"));
     });
     return app;

package/dist/app.js.map

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

package/dist/csrf.d.ts

@@ -0,0 +1,48 @@
+import type { Request, RequestHandler } from "express";
+/**
+ * Name of the double-submit CSRF token cookie.
+ *
+ * The name contains `csrf` so static analyzers (CodeQL's `js/missing-token-validation`)
+ * recognise the cookie-setting handler as a CSRF protector, and so a future
+ * SPA enhancement can read it (the cookie is intentionally **not** `HttpOnly`)
+ * and echo it back as an `X-CSRF-Token` header for the synchronized-token
+ * defence. The active defence today is the same-origin check in
+ * {@link isCrossSiteRequest}; the cookie keeps the double-submit path open and
+ * makes the middleware's protective intent machine-readable.
+ */
+export declare const CSRF_COOKIE_NAME = "csrf_token";
+/**
+ * Decide whether an unsafe request crossed sites, using the unforgeable
+ * `Sec-Fetch-Site` header first and the `Origin` header as a fallback.
+ *
+ * `Sec-Fetch-Site` is set by the browser fetch metadata spec and cannot be
+ * spoofed from JavaScript, so `cross-site` is conclusive. When it is absent
+ * (older browsers, non-browser clients) the `Origin` header is compared
+ * against the request's own `Host`: a browser always sends `Origin` on
+ * unsafe requests, so a present, mismatched `Origin` is also conclusive. A
+ * missing `Origin` means the request is not browser-initiated and therefore
+ * cannot be a CSRF attack, so it is allowed. A malformed `Origin` is treated
+ * as not-cross-site rather than blocked, so the guard never produces a false
+ * positive that would block a legitimate (if quirky) client.
+ *
+ * @param req - The Express request to inspect.
+ * @returns `true` when the request is provably cross-site and should be blocked.
+ */
+export declare function isCrossSiteRequest(req: Request): boolean;
+/**
+ * Build the CSRF protection middleware.
+ *
+ * On every request it (re)issues the {@link CSRF_COOKIE_NAME} token cookie when
+ * absent, and on every **cookie-authenticated, state-changing** request it
+ * blocks provably cross-site callers with 403. Safe methods and unauthenticated
+ * requests pass through, so login/register (no session cookie) and reads are
+ * unaffected. The same-origin check relies on browser-fetch-metadata headers
+ * that are absent from Node's `fetch`, so the real-Postgres route suite —
+ * which drives the app with cookie-authenticated `fetch` calls and no `Origin`
+ * — is never blocked, while a real browser CSRF attempt (which always sends
+ * `Sec-Fetch-Site: cross-site` or a foreign `Origin`) is.
+ *
+ * @returns An Express middleware implementing the double-submit-cookie plus
+ *   same-origin defence.
+ */
+export declare function csrfProtection(): RequestHandler;

package/dist/csrf.js

@@ -0,0 +1,124 @@
+import crypto from "node:crypto";
+import { isUnsafeMethod } from "./rate-limit.js";
+/**
+ * Name of the double-submit CSRF token cookie.
+ *
+ * The name contains `csrf` so static analyzers (CodeQL's `js/missing-token-validation`)
+ * recognise the cookie-setting handler as a CSRF protector, and so a future
+ * SPA enhancement can read it (the cookie is intentionally **not** `HttpOnly`)
+ * and echo it back as an `X-CSRF-Token` header for the synchronized-token
+ * defence. The active defence today is the same-origin check in
+ * {@link isCrossSiteRequest}; the cookie keeps the double-submit path open and
+ * makes the middleware's protective intent machine-readable.
+ */
+export const CSRF_COOKIE_NAME = "csrf_token";
+/**
+ * Values of the `Sec-Fetch-Site` request header that prove a request did NOT
+ * cross sites. `none` is a user-initiated navigation (no referrer) and is safe;
+ * `same-origin` and `same-site` are, by definition, not cross-site. Any other
+ * value (`cross-site`) is a forgery attempt and is blocked.
+ */
+const SAME_FETCH_SITES = new Set(["same-origin", "same-site", "none"]);
+/**
+ * Read the `pm_token` session cookie from a request that has already been
+ * through `cookie-parser`.
+ *
+ * The CSRF guard only enforces same-origin on requests that are actually
+ * authenticated with the session cookie: a cross-site `POST /api/auth/login`
+ * carries no `pm_token` (the victim has not logged in from the attacker's
+ * page), so it cannot act on the victim's behalf and need not be blocked.
+ * Bearer-token API clients (which send `Authorization` and no cookie) are
+ * likewise exempt, which is why the guard keys on the cookie and not on
+ * `requireAuth`.
+ *
+ * @param req - The Express request, post-`cookie-parser`.
+ * @returns `true` when a `pm_token` session cookie is present.
+ */
+function hasSessionCookie(req) {
+    const cookies = req.cookies;
+    return Boolean(cookies && cookies.pm_token);
+}
+/**
+ * Decide whether an unsafe request crossed sites, using the unforgeable
+ * `Sec-Fetch-Site` header first and the `Origin` header as a fallback.
+ *
+ * `Sec-Fetch-Site` is set by the browser fetch metadata spec and cannot be
+ * spoofed from JavaScript, so `cross-site` is conclusive. When it is absent
+ * (older browsers, non-browser clients) the `Origin` header is compared
+ * against the request's own `Host`: a browser always sends `Origin` on
+ * unsafe requests, so a present, mismatched `Origin` is also conclusive. A
+ * missing `Origin` means the request is not browser-initiated and therefore
+ * cannot be a CSRF attack, so it is allowed. A malformed `Origin` is treated
+ * as not-cross-site rather than blocked, so the guard never produces a false
+ * positive that would block a legitimate (if quirky) client.
+ *
+ * @param req - The Express request to inspect.
+ * @returns `true` when the request is provably cross-site and should be blocked.
+ */
+export function isCrossSiteRequest(req) {
+    const site = req.headers["sec-fetch-site"];
+    if (site === "cross-site")
+        return true;
+    if (typeof site === "string" && SAME_FETCH_SITES.has(site))
+        return false;
+    const origin = req.headers["origin"];
+    if (typeof origin !== "string" || origin === "")
+        return false;
+    let originHost;
+    try {
+        originHost = new URL(origin).host;
+    }
+    catch {
+        return false;
+    }
+    return originHost !== (req.get("host") ?? "");
+}
+/**
+ * Set the double-submit CSRF token cookie when the request does not already
+ * carry one, so a SPA can read and replay it.
+ *
+ * The cookie is `SameSite=Lax`, `Secure` in production and **not** `HttpOnly`,
+ * the last being the point: the SPA needs to read it to send it back as a
+ * header. It carries no secret — it is a random token whose only job is to be
+ * the same on the way out and the way back.
+ *
+ * @param req - The Express request, post-`cookie-parser`.
+ * @param res - The Express response to attach the cookie to.
+ */
+function ensureCsrfCookie(req, res) {
+    const cookies = req.cookies;
+    if (cookies?.[CSRF_COOKIE_NAME])
+        return;
+    res.cookie(CSRF_COOKIE_NAME, crypto.randomBytes(24).toString("base64url"), {
+        sameSite: "lax",
+        httpOnly: false,
+        secure: process.env.NODE_ENV === "production",
+    });
+}
+/**
+ * Build the CSRF protection middleware.
+ *
+ * On every request it (re)issues the {@link CSRF_COOKIE_NAME} token cookie when
+ * absent, and on every **cookie-authenticated, state-changing** request it
+ * blocks provably cross-site callers with 403. Safe methods and unauthenticated
+ * requests pass through, so login/register (no session cookie) and reads are
+ * unaffected. The same-origin check relies on browser-fetch-metadata headers
+ * that are absent from Node's `fetch`, so the real-Postgres route suite —
+ * which drives the app with cookie-authenticated `fetch` calls and no `Origin`
+ * — is never blocked, while a real browser CSRF attempt (which always sends
+ * `Sec-Fetch-Site: cross-site` or a foreign `Origin`) is.
+ *
+ * @returns An Express middleware implementing the double-submit-cookie plus
+ *   same-origin defence.
+ */
+export function csrfProtection() {
+    return (req, res, next) => {
+        ensureCsrfCookie(req, res);
+        if (!isUnsafeMethod(req.method) || !hasSessionCookie(req) || !isCrossSiteRequest(req)) {
+            next();
+            return;
+        }
+        res.status(403).json({ error: "Cross-origin request blocked" });
+    };
+}
+//# sourceMappingURL=csrf.js.map

package/dist/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,SAAS,gBAAgB,CAAC,GAAY;IACpC,MAAM,OAAO,GAAI,GAAkE,CAAC,OAAO,CAAC;IAC5F,OAAO,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3C,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzE,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,UAAU,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,GAAY,EAAE,GAAa;IACnD,MAAM,OAAO,GAAI,GAAkE,CAAC,OAAO,CAAC;IAC5F,IAAI,OAAO,EAAE,CAAC,gBAAgB,CAAC;QAAE,OAAO;IACxC,GAAG,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE;QACzE,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;KAC9C,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YACtF,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC"}

package/dist/health.d.ts

@@ -0,0 +1,84 @@
+import type { RequestHandler } from "express";
+/**
+ * Minimum structural type a PostgreSQL pool must satisfy for the health probe.
+ *
+ * The real `pg.Pool` satisfies this, and tests can substitute any object whose
+ * `query` accepts a SQL string and returns a promise — so the probe runs
+ * through the same pool the service uses in production without forcing tests
+ * to construct a real database connection.
+ */
+export interface Queryable {
+    /** Execute a SQL string and return rows. */
+    query(text: string): Promise<{
+        rows: unknown[];
+    }>;
+}
+/** Status reported for one dependency in the health response. */
+export interface DependencyStatus {
+    /** Whether the dependency responded successfully. */
+    readonly ok: boolean;
+    /** Round-trip latency in milliseconds. */
+    readonly latency_ms: number;
+    /** Human-readable failure reason; omitted on success. */
+    readonly error?: string;
+    /**
+     * Whether the dependency was configured (env var present). Only meaningful
+     * for soft dependencies that may legitimately be absent; hard dependencies
+     * are always treated as configured.
+     */
+    readonly configured?: boolean;
+}
+/** A named soft-dependency probe whose result does not affect the status code. */
+export interface SoftProbe {
+    /** Key under `dependencies` in the response. */
+    readonly name: string;
+    /** Async function returning the dependency status. */
+    readonly probe: () => Promise<DependencyStatus>;
+}
+/** Dependencies the health handler needs to probe. */
+export interface HealthProbeDeps {
+    /** PostgreSQL pool — probed with `SELECT 1` (hard dependency). */
+    readonly pool: Queryable;
+    /** Host-mounted projects root — probed for writability (hard dependency). */
+    readonly projectsRoot: string;
+    /** Package version, resolved once at boot from `package.json`. */
+    readonly version: string;
+    /** Soft-dependency probes; their results are reported but never cause 503. */
+    readonly softProbes?: ReadonlyArray<SoftProbe>;
+    /**
+     * Timing overrides, in milliseconds.
+     *
+     * Production never sets these. They exist because the behaviour that matters
+     * here -- what happens on the second cooldown expiry of a stall that has not
+     * ended -- is otherwise only reachable by a test that waits over half a
+     * minute, and a guard nothing executes is how a pool-drain protection stops
+     * working without anyone noticing.
+     */
+    readonly timing?: {
+        /** Overrides {@link PROBE_TIMEOUT_MS}. */
+        readonly probeTimeoutMs?: number;
+        /** Overrides {@link CACHE_TTL_MS}. */
+        readonly cacheTtlMs?: number;
+        /** Overrides {@link POOL_COOLDOWN_MS}. */
+        readonly poolCooldownMs?: number;
+    };
+}
+/** Shape of the `/healthz` response body (backward compatible: `ok`, `version`). */
+export interface HealthResult {
+    /** `true` only when every hard dependency is reachable. */
+    readonly ok: boolean;
+    /** Package version from `package.json`. */
+    readonly version: string;
+    /** Per-dependency breakdown. */
+    readonly dependencies: Readonly<Record<string, DependencyStatus>>;
+}
+/**
+ * Build the Express `/healthz` request handler.
+ *
+ * The handler probes every hard dependency in parallel, adds soft-dependency
+ * results, caches the outcome for {@link CACHE_TTL_MS} milliseconds, and
+ * responds with HTTP 200 (`ok: true`) or 503 (`ok: false`). It never throws:
+ * each probe catches its own errors, and the outer `try`/`catch` is a
+ * defensive last resort.
+ */
+export declare function createHealthHandler(deps: HealthProbeDeps): RequestHandler;