From 2f90e9fbed6162c7c6242da99104696cf0654ba8 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Wed, 28 Oct 2026 21:57:33 -0700 Subject: [PATCH] Serve /.well-known/source SOURCE_URL and the commit the build was made from, in the form https://coffeylabs.org/specs/well-known-source/ defines, at the host's root whatever the base path. The image build passes the commit as INBUXA_REVISION, like the version; a clean checkout asks git. A build that can't name its commit, or a checkout with uncommitted changes, answers 404. --- .gitea/workflows/ci.yml | 1 + .github/workflows/ci.yml | 4 ++- Dockerfile | 4 +++ deploy.example.sh | 4 +++ scripts/version.d.mts | 1 + scripts/version.mjs | 21 ++++++++++++++++ server/src/app.ts | 12 +++++++++ server/src/config.ts | 9 ++++++- server/src/source.test.ts | 53 +++++++++++++++++++++++++++++++++++++++ server/src/source.ts | 33 ++++++++++++++++++++++++ 10 files changed, 140 insertions(+), 2 deletions(-) create mode 100644 server/src/source.test.ts create mode 100644 server/src/source.ts diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 0ac3ab5..c2fa29d 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -175,6 +175,7 @@ jobs: docker buildx build \ --platform linux/amd64,linux/arm64 \ --build-arg IHASMAIL_VERSION="$VERSION" \ + --build-arg INBUXA_REVISION="${{ github.sha }}" \ --provenance=false --sbom=false \ $(for t in $TAGS; do printf '%s %s:%s ' --tag "$IMAGE" "$t"; done) \ --push . diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a1376a3..f33eeaf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -168,7 +168,9 @@ jobs: with: context: . platforms: ${{ matrix.platform }} - build-args: IHASMAIL_VERSION=${{ needs.version.outputs.version }} + build-args: | + IHASMAIL_VERSION=${{ needs.version.outputs.version }} + INBUXA_REVISION=${{ github.sha }} # Attestations add manifests of their own to the index, and # `imagetools create` below expects the two entries pushed here. provenance: false diff --git a/Dockerfile b/Dockerfile index fac6b91..6b047af 100644 --- a/Dockerfile +++ b/Dockerfile @@ -33,12 +33,16 @@ FROM mirror.gcr.io/library/node:26-alpine AS runtime # Re-declared: an ARG does not cross stages. ARG IHASMAIL_VERSION="" ARG BASE_PATH="" +# The commit being built, for /.well-known/source; passed like the version, +# for the same reason. Left empty, there is no source document. +ARG INBUXA_REVISION="" ENV NODE_ENV=production \ HOST=:: \ PORT=8080 \ STATIC_DIR=/app/web/dist \ SESSION_FILE=/data/sessions.json \ IHASMAIL_VERSION=$IHASMAIL_VERSION \ + INBUXA_REVISION=$INBUXA_REVISION \ BASE_PATH=$BASE_PATH WORKDIR /app COPY package.json package-lock.json* ./ diff --git a/deploy.example.sh b/deploy.example.sh index 49ed152..d60c12e 100755 --- a/deploy.example.sh +++ b/deploy.example.sh @@ -254,8 +254,12 @@ VERSION="${IHASMAIL_VERSION:-$(version_from_git)}" # correctly. TAG="${VERSION//+/-}" echo "==> building $(git log --oneline -1) as v$VERSION" +# The commit, for /.well-known/source; none for a tree with uncommitted changes. +REVISION="" +[ -z "$(git status --porcelain --untracked-files=no)" ] && REVISION="$(git rev-parse HEAD)" docker build \ --build-arg IHASMAIL_VERSION="$VERSION" \ + --build-arg INBUXA_REVISION="$REVISION" \ -t "$IMAGE_REPO:$TAG" \ -t "$IMAGE_REPO:current" \ . diff --git a/scripts/version.d.mts b/scripts/version.d.mts index 7f75820..e7740fd 100644 --- a/scripts/version.d.mts +++ b/scripts/version.d.mts @@ -4,3 +4,4 @@ export function readRelease(): string; export function formatVersion(commit: { release: string; tagged?: boolean; subject?: string; sha: string }): string; export function versionFromGit(release?: string): string | null; export function resolveVersion(): string; +export function resolveRevision(): string | null; diff --git a/scripts/version.mjs b/scripts/version.mjs index 4db7b37..d35a7c8 100644 --- a/scripts/version.mjs +++ b/scripts/version.mjs @@ -102,6 +102,27 @@ export function versionFromGit(release) { return formatVersion({ release, tagged: tags.includes(`inbuxa-v${release}`), subject, sha: head }); } +/** A full commit id: 40 hex digits (SHA-1) or 64 (SHA-256). */ +const COMMIT = /^([0-9a-f]{40}|[0-9a-f]{64})$/i; + +/** + * The commit this build was made from, for `/.well-known/source`: what the + * environment was told (INBUXA_REVISION, passed like IHASMAIL_VERSION), else + * git's HEAD in a checkout with nothing uncommitted. Null otherwise: a commit + * with local changes on top doesn't name what runs. + */ +export function resolveRevision() { + const fromEnv = process.env.INBUXA_REVISION?.trim(); + if (fromEnv) return COMMIT.test(fromEnv) ? fromEnv : null; + try { + if (git("status", "--porcelain", "--untracked-files=no")) return null; + const head = git("rev-parse", "HEAD"); + return COMMIT.test(head) ? head : null; + } catch { + return null; + } +} + /** Whatever the environment was told, else git, else an answer that looks wrong. */ export function resolveVersion() { const fromEnv = process.env.IHASMAIL_VERSION?.trim(); diff --git a/server/src/app.ts b/server/src/app.ts index 668a32a..ad525ab 100644 --- a/server/src/app.ts +++ b/server/src/app.ts @@ -9,6 +9,7 @@ import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response"; import { attach as pushAttach, attachRelay as pushAttachRelay, prepare as pushPrepare, receive as pushReceive, pushStatus } from "./push.js"; import { getConnInfo } from "@hono/node-server/conninfo"; import { config } from "./config.js"; +import { sourceDocument } from "./source.js"; import { fetchPermissions } from "./permissionSchema.js"; import { administrationAllowed, gateAdministration, grantsAdministration } from "./adminGate.js"; import { SessionStore, accountKey, type SessionBackend, type LiveSession } from "./sessions.js"; @@ -1369,6 +1370,17 @@ api.get("/ics", requireSession, apiRateLimited, icsProxyHandler); app.route(`${basePath}/api`, api); + // ihasmail-inbuxa: where this build's source is. At the host's root whatever + // the base path, since that's where the well-known address is; see source.ts. + app.on(["GET", "HEAD"], "/.well-known/source", (c) => { + const doc = sourceDocument({ version: config.version, repository: config.sourceUrl, revision: config.revision }); + if (!doc) return c.json({ error: "not_found" }, 404); + c.header("Content-Type", "application/json"); + c.header("Cache-Control", "no-cache"); + c.header("Access-Control-Allow-Origin", "*"); + return c.body(doc); + }); + // ---------- Static SPA ---------- app.get("*", staticHandler(config.staticDir, basePath)); return app; diff --git a/server/src/config.ts b/server/src/config.ts index 82ba221..21413e5 100644 --- a/server/src/config.ts +++ b/server/src/config.ts @@ -1,4 +1,4 @@ -import { resolveVersion } from "../../scripts/version.mjs"; +import { resolveRevision, resolveVersion } from "../../scripts/version.mjs"; import { normalizeBasePath } from "../../scripts/basePath.mjs"; import { randomBytes } from "node:crypto"; import { fileURLToPath } from "node:url"; @@ -296,6 +296,13 @@ export const config = { * such a tree, so the default is INBUXA's fork. */ sourceUrl: env("SOURCE_URL", "https://git.coffeylabs.org/inbuxa/inbuxa-webmail"), + /** + * ihasmail-inbuxa: the commit this build was made from, named beside + * `sourceUrl` in `/.well-known/source`. Set by the image build from + * `--build-arg INBUXA_REVISION`; a clean checkout asks git. Null when + * neither can say, and then there is no source document. See source.ts. + */ + revision: resolveRevision(), /** * ihasmail-inbuxa: this webmail's own name, shown in Settings > About next * to the mail node it talks to. Set per host by the deploy; empty means the diff --git a/server/src/source.test.ts b/server/src/source.test.ts new file mode 100644 index 0000000..d281724 --- /dev/null +++ b/server/src/source.test.ts @@ -0,0 +1,53 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +process.env.MAIL_SERVER_URL = "http://127.0.0.1:1"; +const { createApp } = await import("./app.js"); +const { config } = await import("./config.js"); +const { sourceDocument } = await import("./source.js"); + +const COMMIT = "e8249751c2a1d5e8b7f6a9c0d1e2f3a4b5c6d7e8"; +const REPOSITORY = "https://git.coffeylabs.org/inbuxa/inbuxa-webmail"; + +test("the document names the repository and the commit", () => { + const doc = JSON.parse(sourceDocument({ version: "27.1-rc.1", repository: REPOSITORY, revision: COMMIT })!); + assert.deepEqual(doc, { + version: 1, + software: [ + { name: "inbuxa Webmail", version: "27.1-rc.1", license: "AGPL-3.0-or-later", repository: REPOSITORY, revision: COMMIT }, + ], + }); +}); + +test("without a full commit id there is no document", () => { + for (const revision of [null, "", "e824975", "inbuxa-v27.1-rc.1", COMMIT.replace(/e/g, "x")]) { + assert.equal(sourceDocument({ version: "27.1-rc.1", repository: REPOSITORY, revision }), null, String(revision)); + } +}); + +test("served at the root, public and uncached", async (t) => { + const was = config.revision; + t.after(() => { + config.revision = was; + }); + config.revision = COMMIT; + for (const basePath of ["", "/mail"]) { + const res = await createApp(basePath).request("/.well-known/source"); + assert.equal(res.status, 200, basePath); + assert.match(res.headers.get("content-type") ?? "", /^application\/json/); + assert.equal(res.headers.get("access-control-allow-origin"), "*"); + assert.equal(res.headers.get("cache-control"), "no-cache"); + const doc = (await res.json()) as { software: Array<{ revision: string; repository: string }> }; + assert.equal(doc.software[0].revision, COMMIT); + assert.equal(doc.software[0].repository, config.sourceUrl); + } +}); + +test("a build without its commit answers 404, not the app", async (t) => { + const was = config.revision; + t.after(() => { + config.revision = was; + }); + config.revision = null; + const res = await createApp("").request("/.well-known/source"); + assert.equal(res.status, 404); +}); diff --git a/server/src/source.ts b/server/src/source.ts new file mode 100644 index 0000000..cc04018 --- /dev/null +++ b/server/src/source.ts @@ -0,0 +1,33 @@ +/** + * ihasmail-inbuxa: `/.well-known/source`, what this webmail runs and where its + * source is, in the form https://coffeylabs.org/specs/well-known-source/ + * gives it. + * + * It names SOURCE_URL as the repository and the commit the build was made + * from (`resolveRevision` in scripts/version.mjs). A build that doesn't know + * its commit says nothing and the address is a 404, since a repository without + * a revision doesn't name the build. So does a checkout with uncommitted + * changes: no public revision holds them. + */ + +/** A full commit id: 40 hex digits (SHA-1) or 64 (SHA-256). */ +export function isCommitId(revision: string | null | undefined): revision is string { + return typeof revision === "string" && /^([0-9a-f]{40}|[0-9a-f]{64})$/i.test(revision); +} + +/** The document for a build, or null when it can't name its commit. */ +export function sourceDocument(build: { version: string; repository: string; revision: string | null }): string | null { + if (!isCommitId(build.revision)) return null; + return JSON.stringify({ + version: 1, + software: [ + { + name: "inbuxa Webmail", + version: build.version, + license: "AGPL-3.0-or-later", + repository: build.repository, + revision: build.revision, + }, + ], + }); +} -- 2.54.0