From 51bb41c7e334440566ecf63cfc96fc36da05d7d2 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 31 Jul 2026 11:46:34 -0700 Subject: [PATCH] Expose the running build commit on the unauthenticated health response (#10563) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Instances run self-hosted or under hosting/deploy tooling, and operators need to observe what build a server is actually running > - `/api/health` carries the git SHA only inside `serverInfo`, which is gated to board/agent actors — anonymous callers get a redacted body with no version signal at all > - Deploy tooling that manages instances from outside (fleet rollouts, hosting providers, upgrade scripts) therefore cannot ground-truth that a deploy actually shipped without holding credentials > - A build commit is a plain git SHA of this public repository — it is not a secret, and gating it buys no security while blocking legitimate verification > - This pull request surfaces the running build commit as a top-level `commit` field on every `/api/health` response, including the redacted anonymous one > - The benefit is credential-free deploy verification: any operator or tool can confirm which commit an instance serves, while the fuller `serverInfo` block stays access-controlled as before ## Linked Issues or Issue Description No existing public issue — inline description following the feature request template: **Subsystem affected** Server (API, runs, routes) **Problem or motivation** An anonymous `GET /api/health` returns a redacted body with no version information; the running git SHA exists only in `serverInfo.git.fullSha`, which requires a board/agent actor. External deploy tooling (fleet rollouts, hosting providers, upgrade scripts) therefore cannot verify that an instance is actually serving the build it was just upgraded to — a rollout that silently keeps running the old image is indistinguishable from a successful one at the health endpoint. **Proposed solution** Surface the running build commit as a top-level nullable `commit` field on every `/api/health` response shape, including the redacted anonymous one, while keeping the fuller `serverInfo` block access-controlled as before. A build commit is a plain git SHA of this public repository — exposing it costs nothing and enables credential-free deploy verification, like the `version` endpoints on most server software. **Alternatives considered** Authenticating deploy tooling as a board actor to read `serverInfo` — rejected: it forces credential plumbing into infrastructure that only needs a public SHA, and adds a whole class of auth-misconfiguration failure to deploy verification. **Roadmap alignment** Not on ROADMAP.md; a small operational observability improvement, no overlap with planned core work. ## What Changed - `server/src/routes/health.ts`: derive `commit` from the server info snapshot (`serverInfo.git.fullSha` when git metadata is available, else `null`) and include it as a top-level field on every `/api/health` response shape — the redacted anonymous body, the full-details body, the no-db body, and the 503 database-unreachable body. - `serverInfo` itself remains gated to full-details responses exactly as before; only the bare commit is newly public. - `server/src/__tests__/health.test.ts`: updated exact-shape assertions to include `commit`, and added an assertion that `commit` is `null` (not omitted) when git metadata is unavailable. The redacted-response tests now pin that anonymous callers receive the commit. ## Verification - `pnpm vitest run src/__tests__/health.test.ts` in `server/` — 13 tests pass, including the redacted-anonymous shapes (which now pin the `commit` field) and the git-unavailable `null` case. - `tsc -p server/tsconfig.json --noEmit` — clean. - Manual: `curl -s https:///api/health` as an anonymous caller returns `"commit": ""` alongside the existing redacted fields. ## Risks - **Version disclosure:** anonymous callers can now fingerprint the exact running commit. This is a deliberate trade-off: the builds are of a public repository (the SHA reveals no private code), the endpoint already responds to anonymous callers, and the operational value — verifying deploys actually shipped — outweighs the marginal fingerprinting surface. Operators who consider this sensitive are typically fronting `/api` with their own access controls already. - Otherwise low risk: no behavioral change to any gated field, no schema or API-surface removal; `commit: null` keeps the field shape stable when git metadata is absent (e.g. non-git installs). ## Model Used Claude Opus 4.8 (`claude-opus-4-8`, extended thinking, via Claude Code with tool use and code execution) authored the change and tests; finalized and PR'd under Claude Fable 5 (`claude-fable-5`). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes (none needed beyond code comments — health endpoint has no standalone doc) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --- .../__tests__/health-dev-server-token.test.ts | 7 ++ server/src/__tests__/health.test.ts | 8 +- server/src/routes/health.ts | 12 ++- server/src/routes/openapi.ts | 86 ++++++++++++------- 4 files changed, 79 insertions(+), 34 deletions(-) diff --git a/server/src/__tests__/health-dev-server-token.test.ts b/server/src/__tests__/health-dev-server-token.test.ts index e50b0930f1..c62a76489d 100644 --- a/server/src/__tests__/health-dev-server-token.test.ts +++ b/server/src/__tests__/health-dev-server-token.test.ts @@ -85,6 +85,12 @@ describe("GET /health dev-server supervisor access", () => { deploymentExposure: "private", authReady: true, companyDeletionEnabled: true, + // Pin server info so the commit field is deterministic (null) + // instead of picking up the checkout's real git metadata. + serverInfo: { + processStartedAt: "2026-03-20T11:00:00.000Z", + git: { available: false, unavailableReason: "git_unavailable" }, + }, }), ); @@ -97,6 +103,7 @@ describe("GET /health dev-server supervisor access", () => { status: "ok", deploymentMode: "authenticated", deploymentExposure: "private", + commit: null, bootstrapStatus: "ready", bootstrapInviteActive: false, devServer: { diff --git a/server/src/__tests__/health.test.ts b/server/src/__tests__/health.test.ts index ed95872338..eabeca9711 100644 --- a/server/src/__tests__/health.test.ts +++ b/server/src/__tests__/health.test.ts @@ -74,7 +74,7 @@ describe("GET /health", () => { const app = createApp(); const res = await request(app).get("/health"); expect(res.status).toBe(200); - expect(res.body).toEqual({ status: "ok", version: serverVersion, serverVersion: serverVersion, serverInfo: testServerInfo }); + expect(res.body).toEqual({ status: "ok", version: serverVersion, serverVersion: serverVersion, commit: testServerInfo.git.fullSha, serverInfo: testServerInfo }); }, 15_000); it("returns 200 when the database probe succeeds", async () => { @@ -107,6 +107,7 @@ describe("GET /health", () => { status: "unhealthy", version: serverVersion, serverVersion, + commit: testServerInfo.git.fullSha, error: "database_unreachable", serverInfo: testServerInfo, }); @@ -131,6 +132,8 @@ describe("GET /health", () => { unavailableReason: "git_unavailable", }, }); + // With no git metadata baked in, the exposed commit is null (not omitted). + expect(res.body.commit).toBeNull(); }); it("surfaces a stale database backup warning in full health details", async () => { @@ -281,6 +284,7 @@ describe("GET /health", () => { status: "ok", deploymentMode: "authenticated", deploymentExposure: "public", + commit: testServerInfo.git.fullSha, bootstrapStatus: "ready", bootstrapInviteActive: false, databaseBackup: { @@ -337,6 +341,7 @@ describe("GET /health", () => { status: "ok", deploymentMode: "authenticated", deploymentExposure: "public", + commit: testServerInfo.git.fullSha, bootstrapStatus: "ready", bootstrapInviteActive: false, }); @@ -374,6 +379,7 @@ describe("GET /health", () => { status: "ok", deploymentMode: "authenticated", deploymentExposure: "public", + commit: testServerInfo.git.fullSha, bootstrapStatus: "ready", bootstrapInviteActive: false, }); diff --git a/server/src/routes/health.ts b/server/src/routes/health.ts index 760e3e11da..c7ac588407 100644 --- a/server/src/routes/health.ts +++ b/server/src/routes/health.ts @@ -121,14 +121,19 @@ export function healthRoutes( // enableServerInfoDebugView experimental flag gates the UI surface, not this // already access-controlled field. const serverInfo = opts.serverInfo ?? getServerInfoSnapshot(); + // The build commit is a plain git SHA of a public repository — not a + // secret — so it is surfaced on every response, including the redacted + // one, unlike the fuller `serverInfo` block. Deploy tooling (and anyone) + // can read which commit this server is running without authenticating. + const commit = serverInfo.git.available ? serverInfo.git.fullSha : null; const exposeDevServerDetails = exposeFullDetails || hasDevServerStatusToken(req.get("x-paperclip-dev-server-status-token")); if (!db) { res.json( exposeFullDetails - ? { status: "ok", version: serverVersion, serverVersion: serverVersion, serverInfo } - : { status: "ok", deploymentMode: opts.deploymentMode }, + ? { status: "ok", version: serverVersion, serverVersion: serverVersion, commit, serverInfo } + : { status: "ok", deploymentMode: opts.deploymentMode, commit }, ); return; } @@ -141,6 +146,7 @@ export function healthRoutes( status: "unhealthy", version: serverVersion, serverVersion, + commit, error: "database_unreachable", ...(exposeFullDetails ? { serverInfo } : {}), }); @@ -210,6 +216,7 @@ export function healthRoutes( status: "ok", deploymentMode: opts.deploymentMode, deploymentExposure: opts.deploymentExposure, + commit, bootstrapStatus, bootstrapInviteActive, ...(redactedDatabaseBackup ? { databaseBackup: redactedDatabaseBackup } : {}), @@ -223,6 +230,7 @@ export function healthRoutes( status: "ok", version: serverVersion, serverVersion, + commit, deploymentMode: opts.deploymentMode, deploymentExposure: opts.deploymentExposure, authReady: opts.authReady, diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index 9129f96fd8..43fd6a4fe4 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -1054,6 +1054,39 @@ function applyDocumentFixups(document: any): any { // ─── Health ────────────────────────────────────────────────────────────────── +// Shared by the healthy and database-unreachable responses: full details +// (including serverInfo) ride only on board/agent-actor responses. +const healthServerInfoSchema = z.object({ + processStartedAt: z.string().datetime(), + git: z.union([ + z.object({ + available: z.literal(true), + fullSha: z.string(), + shortSha: z.string(), + branchName: z.string().nullable(), + subject: z.string(), + committedAt: z.string().datetime().nullable(), + localChanges: z.union([ + z.object({ + available: z.literal(true), + hasLocalChanges: z.boolean(), + stagedFileCount: z.number().int().nonnegative(), + unstagedFileCount: z.number().int().nonnegative(), + untrackedFileCount: z.number().int().nonnegative(), + }).strict(), + z.object({ + available: z.literal(false), + unavailableReason: z.enum(["git_status_unavailable"]), + }).strict(), + ]), + }).strict(), + z.object({ + available: z.literal(false), + unavailableReason: z.enum(["git_unavailable", "invalid_git_metadata"]), + }).strict(), + ]), +}).strict(); + registry.registerPath({ method: "get", path: "/api/health", @@ -1063,6 +1096,9 @@ registry.registerPath({ 200: r.ok(z.object({ status: z.enum(["ok", "unhealthy"]), version: z.string().optional(), + // Running build commit (full git SHA), or null when git metadata is + // unavailable. Present on every response shape, including redacted ones. + commit: z.string().nullable(), deploymentMode: z.string().optional(), bootstrapStatus: z.enum(["ready", "bootstrap_pending"]).optional(), bootstrapInviteActive: z.boolean().optional(), @@ -1097,38 +1133,26 @@ registry.registerPath({ code: z.string(), message: z.string(), })).optional(), - serverInfo: z.object({ - processStartedAt: z.string().datetime(), - git: z.union([ - z.object({ - available: z.literal(true), - fullSha: z.string(), - shortSha: z.string(), - branchName: z.string().nullable(), - subject: z.string(), - committedAt: z.string().datetime().nullable(), - localChanges: z.union([ - z.object({ - available: z.literal(true), - hasLocalChanges: z.boolean(), - stagedFileCount: z.number().int().nonnegative(), - unstagedFileCount: z.number().int().nonnegative(), - untrackedFileCount: z.number().int().nonnegative(), - }).strict(), - z.object({ - available: z.literal(false), - unavailableReason: z.enum(["git_status_unavailable"]), - }).strict(), - ]), - }).strict(), - z.object({ - available: z.literal(false), - unavailableReason: z.enum(["git_unavailable", "invalid_git_metadata"]), - }).strict(), - ]), - }).strict().optional(), + serverInfo: healthServerInfoSchema.optional(), })), - 503: { description: "Service unavailable", content: { "application/json": { schema: ErrorSchema } } }, + // The database-unreachable body still carries version and commit so + // deployment tooling can verify the running build during an outage; + // serverInfo rides only on full-details (board/agent) responses. + 503: { + description: "Service unavailable", + content: { + "application/json": { + schema: z.object({ + status: z.literal("unhealthy"), + version: z.string(), + serverVersion: z.string(), + commit: z.string().nullable(), + error: z.literal("database_unreachable"), + serverInfo: healthServerInfoSchema.optional(), + }), + }, + }, + }, }, });