@caelo-cms/provisioning 0.10.44 → 0.10.47

package/dist/release-manifest.d.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { RELEASE_OIDC_ISSUER } from "./upgrade/release-images.js";
+/** Release channels. Pre-release versions name theirs (`0.11.0-rc.1` → `rc`). */
+export declare const RELEASE_CHANNELS: readonly ["stable", "rc", "beta", "alpha"];
+export type ReleaseChannel = (typeof RELEASE_CHANNELS)[number];
+/** The services a release ships images for. */
+export declare const RELEASE_IMAGES: readonly ["admin", "gateway", "ops"];
+export type ReleaseImage = (typeof RELEASE_IMAGES)[number];
+/** Zod schema of `release-manifest.json` (manifestVersion 1). */
+export declare const ReleaseManifestSchema: z.ZodObject<{
+    manifestVersion: z.ZodLiteral<1>;
+    version: z.ZodString;
+    channel: z.ZodEnum<{
+        beta: "beta";
+        stable: "stable";
+        rc: "rc";
+        alpha: "alpha";
+    }>;
+    digests: z.ZodObject<{
+        admin: z.ZodString;
+        gateway: z.ZodString;
+        ops: z.ZodString;
+    }, z.core.$strip>;
+    minFromVersion: z.ZodString;
+    infraContractVersion: z.ZodNumber;
+    migrations: z.ZodObject<{
+        contract: z.ZodBoolean;
+        lastContractVersion: z.ZodNullable<z.ZodString>;
+        head: z.ZodString;
+    }, z.core.$strip>;
+    security: z.ZodBoolean;
+    advisories: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
+/** Registry the upgrader reads manifests from — the public AR mirror Cloud Run pulls from. */
+export declare const RELEASE_MANIFEST_REGISTRY = "europe-west1-docker.pkg.dev";
+/** Repository path of the manifest artifact inside {@link RELEASE_MANIFEST_REGISTRY}. */
+export declare const RELEASE_MANIFEST_REPOSITORY = "caelo-website/caelo-cms-images/release-manifest";
+/** OCI artifact type + layer media types of the pushed manifest. */
+export declare const RELEASE_MANIFEST_ARTIFACT_TYPE = "application/vnd.caelo.release-manifest.v1";
+export declare const RELEASE_MANIFEST_MEDIA_TYPE = "application/vnd.caelo.release-manifest.v1+json";
+export declare const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v0.3+json";
+export { RELEASE_OIDC_ISSUER };
+/**
+ * The only identity allowed to sign the manifest of `version`: release.yml
+ * of caelo-cms/caelo-cms running on that exact tag. Exact, not a regex —
+ * a manifest signed on another ref (a branch, another tag) is refused.
+ */
+export declare function releaseManifestSignerIdentity(version: string): string;
+/**
+ * Compare two SemVer strings: negative when `a < b`, 0 when equal,
+ * positive when `a > b`. A pre-release sorts below its release; two
+ * pre-release tags compare by SemVer identifier rules.
+ *
+ * @throws Error when either argument is not SemVer.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * The channel a version ships on.
+ *
+ * @returns null for a pre-release whose identifier names no known channel.
+ */
+export declare function channelForVersion(version: string): ReleaseChannel | null;
+/** Why fetching or verifying a manifest failed. */
+export type ReleaseManifestErrorCode = "registry" | "artifact-shape" | "blob-digest" | "signature" | "schema" | "version-mismatch";
+export interface ReleaseManifestError {
+    readonly code: ReleaseManifestErrorCode;
+    readonly message: string;
+}
+export type ReleaseManifestResult = {
+    readonly ok: true;
+    readonly manifest: ReleaseManifest;
+} | {
+    readonly ok: false;
+    readonly error: ReleaseManifestError;
+};
+/** Side effects of {@link fetchVerifiedReleaseManifest}, injectable for tests. */
+export interface ReleaseManifestDeps {
+    readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Runs `cosign` with `args`; resolves with its exit code + stderr. */
+    readonly cosign: (args: readonly string[]) => Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+    /** Registry host + repository; defaults to the fixed public mirror. */
+    readonly registry?: string;
+    readonly repository?: string;
+}
+/**
+ * Fetch the manifest of `version` from the fixed registry, verify its
+ * Sigstore bundle against the release workflow identity for that exact
+ * tag, schema-validate it, and check it describes `version`.
+ *
+ * @param version - SemVer without a leading `v`.
+ * @param deps - injected fetch + cosign runner (tests); defaults to the real ones.
+ */
+export declare function fetchVerifiedReleaseManifest(version: string, deps?: ReleaseManifestDeps): Promise<ReleaseManifestResult>;
+/** One image whose resolved digest differs from the manifest's. */
+export interface DigestMismatch {
+    readonly image: ReleaseImage;
+    readonly expected: string;
+    readonly actual: string | null;
+}
+/**
+ * Compare the digests a registry resolved for the release's tags with the
+ * signed manifest. Only images present in `resolved` are compared, except
+ * that an explicitly `null` entry (tag did not resolve) is a mismatch.
+ *
+ * @returns every mismatch; empty means the registry serves the signed images.
+ */
+export declare function compareImageDigests(manifest: ReleaseManifest, resolved: Partial<Record<ReleaseImage, string | null>>): DigestMismatch[];
+/** What the installed system looks like, for {@link assessAutoInstall}. */
+export interface InstalledRelease {
+    readonly version: string;
+    readonly infraContractVersion: number;
+}
+/**
+ * How an upgrader may treat a release:
+ *  - `auto`    — may install unattended (if the Owner's policy allows the kind).
+ *  - `manual`  — installable only with the operator's own identity
+ *                ("Run in Cloud Shell"); never unattended.
+ *  - `refused` — not installable onto this install at all.
+ */
+export type InstallMode = "auto" | "manual" | "refused";
+export interface InstallAssessment {
+    readonly mode: InstallMode;
+    /** `security` only when the manifest says so AND the release is otherwise auto-installable. */
+    readonly kind: "security" | "normal";
+    readonly reasons: readonly string[];
+}
+/**
+ * Decide whether `manifest` can be installed on `installed`, and how.
+ *
+ * A security release is NOT exempt: if it carries contract migrations
+ * (or skips a release that did) or raises the infra contract, it is `manual` like any other release — the
+ * manifest still says `security`, but `kind` drops to `normal` so an
+ * "auto-install security fixes" policy never applies it unattended.
+ */
+export declare function assessAutoInstall(manifest: ReleaseManifest, installed: InstalledRelease): InstallAssessment;
+//# sourceMappingURL=release-manifest.d.ts.map

package/dist/release-manifest.d.ts.map

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

package/dist/release-manifest.js

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The signed release manifest (epic #696): one JSON document per release
+ * that names the exact image digests plus the facts an upgrader needs to
+ * decide whether it may install the release on its own.
+ *
+ * Trust model. `release.yml` generates the manifest on the release tag,
+ * signs it with `cosign sign-blob` (keyless, the workflow's GitHub OIDC
+ * identity) and pushes it as an OCI artifact holding two layers — the
+ * manifest and its Sigstore bundle. Verification pins the signer to
+ * `release.yml` running on the tag `v<version>` of caelo-cms/caelo-cms,
+ * so neither a compromised admin nor a registry mirror can mint, alter or
+ * replay a manifest: changing a digest, flipping `security`, or serving
+ * v0.9's manifest as v0.10's all fail the signature or the version check.
+ * The signature rides inside the artifact (not as an OCI referrer), so
+ * any plain registry copy keeps it — the failure mode that left mirrored
+ * images unsigned (see release-images.yml, "oras copy -r") cannot apply.
+ *
+ * Errors are values: every failure carries a code plus a message that
+ * says what to check next.
+ */
+import { createHash } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { IMAGE_DIGEST, RELEASE_OIDC_ISSUER, RELEASE_WORKFLOWS_URL, } from "./upgrade/release-images.js";
+/** Release channels. Pre-release versions name theirs (`0.11.0-rc.1` → `rc`). */
+export const RELEASE_CHANNELS = ["stable", "rc", "beta", "alpha"];
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const GHSA_ID = /^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$/;
+/** The services a release ships images for. */
+export const RELEASE_IMAGES = ["admin", "gateway", "ops"];
+const digest = z.string().regex(IMAGE_DIGEST, "expected sha256:<64 hex>");
+/** Zod schema of `release-manifest.json` (manifestVersion 1). */
+export const ReleaseManifestSchema = z.object({
+    manifestVersion: z.literal(1),
+    version: z.string().regex(SEMVER, "expected a SemVer version without a leading v"),
+    channel: z.enum(RELEASE_CHANNELS),
+    digests: z.object({ admin: digest, gateway: digest, ops: digest }),
+    minFromVersion: z.string().regex(SEMVER),
+    infraContractVersion: z.number().int().positive(),
+    migrations: z.object({
+        /** True when the release carries destructive (contract) migrations. */
+        contract: z.boolean(),
+        /**
+         * Newest release up to and including this one that carried contract
+         * migrations (null: none known). An install below it that jumps
+         * straight here would run those destructive steps while its old image
+         * still serves — so it is manual too, even when `contract` is false.
+         */
+        lastContractVersion: z.string().regex(SEMVER).nullable(),
+        /** Newest cms_admin migration in the release, e.g. `0262_tool_approval_branch`. */
+        head: z.string().min(1),
+    }),
+    /** Set only via the release-cut input, backed by published GitHub Security Advisories. */
+    security: z.boolean(),
+    advisories: z.array(z.string().regex(GHSA_ID, "expected a GHSA id")),
+});
+/** Registry the upgrader reads manifests from — the public AR mirror Cloud Run pulls from. */
+export const RELEASE_MANIFEST_REGISTRY = "europe-west1-docker.pkg.dev";
+/** Repository path of the manifest artifact inside {@link RELEASE_MANIFEST_REGISTRY}. */
+export const RELEASE_MANIFEST_REPOSITORY = "caelo-website/caelo-cms-images/release-manifest";
+/** OCI artifact type + layer media types of the pushed manifest. */
+export const RELEASE_MANIFEST_ARTIFACT_TYPE = "application/vnd.caelo.release-manifest.v1";
+export const RELEASE_MANIFEST_MEDIA_TYPE = "application/vnd.caelo.release-manifest.v1+json";
+export const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v0.3+json";
+// The signer constants are shared with the image verification (one source).
+export { RELEASE_OIDC_ISSUER };
+/**
+ * The only identity allowed to sign the manifest of `version`: release.yml
+ * of caelo-cms/caelo-cms running on that exact tag. Exact, not a regex —
+ * a manifest signed on another ref (a branch, another tag) is refused.
+ */
+export function releaseManifestSignerIdentity(version) {
+    return `${RELEASE_WORKFLOWS_URL}/release.yml@refs/tags/v${version}`;
+}
+/**
+ * Compare two SemVer strings: negative when `a < b`, 0 when equal,
+ * positive when `a > b`. A pre-release sorts below its release; two
+ * pre-release tags compare by SemVer identifier rules.
+ *
+ * @throws Error when either argument is not SemVer.
+ */
+export function compareSemver(a, b) {
+    const ma = SEMVER.exec(a);
+    const mb = SEMVER.exec(b);
+    if (!ma || !mb)
+        throw new Error(`not a SemVer version: ${ma ? b : a}`);
+    for (let i = 1; i <= 3; i++) {
+        const d = Number(ma[i]) - Number(mb[i]);
+        if (d !== 0)
+            return d;
+    }
+    const pa = ma[4];
+    const pb = mb[4];
+    if (pa === undefined || pb === undefined) {
+        return pa === pb ? 0 : pa === undefined ? 1 : -1;
+    }
+    const ia = pa.split(".");
+    const ib = pb.split(".");
+    for (let i = 0; i < Math.max(ia.length, ib.length); i++) {
+        const x = ia[i];
+        const y = ib[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn && Number(x) !== Number(y))
+            return Number(x) - Number(y);
+        if (xn !== yn)
+            return xn ? -1 : 1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * The channel a version ships on.
+ *
+ * @returns null for a pre-release whose identifier names no known channel.
+ */
+export function channelForVersion(version) {
+    const m = SEMVER.exec(version);
+    if (!m)
+        return null;
+    if (m[4] === undefined)
+        return "stable";
+    const id = m[4].split(".")[0];
+    return RELEASE_CHANNELS.includes(id ?? "") ? id : null;
+}
+/** `cosign` from PATH. Missing binary → exit code 127 with a hint. */
+async function runCosign(args) {
+    try {
+        const proc = Bun.spawn(["cosign", ...args], { stdout: "ignore", stderr: "pipe" });
+        const stderr = await new Response(proc.stderr).text();
+        return { exitCode: await proc.exited, stderr };
+    }
+    catch (e) {
+        return {
+            exitCode: 127,
+            stderr: `cosign could not be started (${e instanceof Error ? e.message : String(e)}) — install cosign (it ships in the caelo-ops image)`,
+        };
+    }
+}
+const defaultDeps = {
+    fetch: (url, init) => fetch(url, init),
+    cosign: runCosign,
+};
+const OciManifestSchema = z.object({
+    artifactType: z.string().optional(),
+    layers: z.array(z.object({ mediaType: z.string(), digest: z.string().regex(IMAGE_DIGEST) })),
+});
+function fail(code, message) {
+    return { ok: false, error: { code, message } };
+}
+async function fetchBlob(deps, base, layer) {
+    const res = await deps.fetch(`${base}/blobs/${layer.digest}`);
+    if (!res.ok) {
+        return { code: "registry", message: `blob ${layer.digest}: HTTP ${res.status}` };
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const actual = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    if (actual !== layer.digest) {
+        return {
+            code: "blob-digest",
+            message: `blob content does not match its digest (${layer.digest} expected, ${actual} served) — the registry or a proxy altered it`,
+        };
+    }
+    return bytes;
+}
+/**
+ * Fetch the manifest of `version` from the fixed registry, verify its
+ * Sigstore bundle against the release workflow identity for that exact
+ * tag, schema-validate it, and check it describes `version`.
+ *
+ * @param version - SemVer without a leading `v`.
+ * @param deps - injected fetch + cosign runner (tests); defaults to the real ones.
+ */
+export async function fetchVerifiedReleaseManifest(version, deps = defaultDeps) {
+    if (!SEMVER.test(version))
+        return fail("schema", `"${version}" is not a SemVer version`);
+    const base = `https://${deps.registry ?? RELEASE_MANIFEST_REGISTRY}/v2/${deps.repository ?? RELEASE_MANIFEST_REPOSITORY}`;
+    let artifact;
+    try {
+        const res = await deps.fetch(`${base}/manifests/${version}`, {
+            headers: { Accept: "application/vnd.oci.image.manifest.v1+json" },
+        });
+        if (!res.ok) {
+            return fail("registry", `no release manifest for v${version} at ${base} (HTTP ${res.status}). Releases before the signed manifest (epic #696) have none; otherwise check the version exists.`);
+        }
+        const parsed = OciManifestSchema.safeParse(await res.json());
+        if (!parsed.success)
+            return fail("artifact-shape", `not an OCI manifest: ${parsed.error.message}`);
+        artifact = parsed.data;
+    }
+    catch (e) {
+        return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (artifact.artifactType !== RELEASE_MANIFEST_ARTIFACT_TYPE) {
+        return fail("artifact-shape", `artifactType is ${artifact.artifactType ?? "(none)"}, expected ${RELEASE_MANIFEST_ARTIFACT_TYPE}`);
+    }
+    const manifestLayers = artifact.layers.filter((l) => l.mediaType === RELEASE_MANIFEST_MEDIA_TYPE);
+    const bundleLayers = artifact.layers.filter((l) => l.mediaType === SIGSTORE_BUNDLE_MEDIA_TYPE);
+    const [manifestLayer] = manifestLayers;
+    const [bundleLayer] = bundleLayers;
+    if (manifestLayers.length !== 1 || bundleLayers.length !== 1 || !manifestLayer || !bundleLayer) {
+        return fail("artifact-shape", "the artifact must hold exactly one release-manifest layer and one Sigstore bundle layer");
+    }
+    let manifestBytes;
+    let bundleBytes;
+    try {
+        const m = await fetchBlob(deps, base, manifestLayer);
+        if (!(m instanceof Uint8Array))
+            return { ok: false, error: m };
+        const b = await fetchBlob(deps, base, bundleLayer);
+        if (!(b instanceof Uint8Array))
+            return { ok: false, error: b };
+        manifestBytes = m;
+        bundleBytes = b;
+    }
+    catch (e) {
+        return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // cosign verifies files, so the exact bytes go to a private temp dir.
+    const dir = await mkdtemp(join(tmpdir(), "caelo-release-manifest-"));
+    try {
+        const manifestPath = join(dir, "release-manifest.json");
+        const bundlePath = join(dir, "release-manifest.json.sigstore.json");
+        await writeFile(manifestPath, manifestBytes, { mode: 0o600 });
+        await writeFile(bundlePath, bundleBytes, { mode: 0o600 });
+        const verify = await deps.cosign([
+            "verify-blob",
+            "--bundle",
+            bundlePath,
+            "--certificate-identity",
+            releaseManifestSignerIdentity(version),
+            "--certificate-oidc-issuer",
+            RELEASE_OIDC_ISSUER,
+            manifestPath,
+        ]);
+        if (verify.exitCode !== 0) {
+            return fail("signature", `the manifest of v${version} is not signed by ${releaseManifestSignerIdentity(version)} — refuse to install. cosign: ${verify.stderr.trim().slice(0, 500)}`);
+        }
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder().decode(manifestBytes));
+    }
+    catch {
+        return fail("schema", "the signed manifest is not valid JSON");
+    }
+    const parsed = ReleaseManifestSchema.safeParse(json);
+    if (!parsed.success) {
+        return fail("schema", `the signed manifest does not match manifestVersion 1 — this CLI may be too old to read it: ${parsed.error.message}`);
+    }
+    if (parsed.data.version !== version) {
+        return fail("version-mismatch", `asked for v${version} but the signed manifest describes v${parsed.data.version}`);
+    }
+    return { ok: true, manifest: parsed.data };
+}
+/**
+ * Compare the digests a registry resolved for the release's tags with the
+ * signed manifest. Only images present in `resolved` are compared, except
+ * that an explicitly `null` entry (tag did not resolve) is a mismatch.
+ *
+ * @returns every mismatch; empty means the registry serves the signed images.
+ */
+export function compareImageDigests(manifest, resolved) {
+    const out = [];
+    for (const image of RELEASE_IMAGES) {
+        if (!(image in resolved))
+            continue;
+        const actual = resolved[image] ?? null;
+        if (actual !== manifest.digests[image]) {
+            out.push({ image, expected: manifest.digests[image], actual });
+        }
+    }
+    return out;
+}
+/**
+ * Decide whether `manifest` can be installed on `installed`, and how.
+ *
+ * A security release is NOT exempt: if it carries contract migrations
+ * (or skips a release that did) or raises the infra contract, it is `manual` like any other release — the
+ * manifest still says `security`, but `kind` drops to `normal` so an
+ * "auto-install security fixes" policy never applies it unattended.
+ */
+export function assessAutoInstall(manifest, installed) {
+    const refused = [];
+    if (compareSemver(manifest.version, installed.version) <= 0) {
+        refused.push(`v${manifest.version} is not newer than the installed v${installed.version}`);
+    }
+    if (compareSemver(installed.version, manifest.minFromVersion) < 0) {
+        refused.push(`v${manifest.version} needs at least v${manifest.minFromVersion} installed first (installed: v${installed.version})`);
+    }
+    if (refused.length > 0)
+        return { mode: "refused", kind: "normal", reasons: refused };
+    const manual = [];
+    if (manifest.infraContractVersion > installed.infraContractVersion) {
+        manual.push(`the release changes the infrastructure contract (${installed.infraContractVersion} → ${manifest.infraContractVersion}); it must run with the operator's own identity`);
+    }
+    const lastContract = manifest.migrations.lastContractVersion;
+    if (manifest.migrations.contract) {
+        manual.push("the release carries contract (destructive) migrations");
+    }
+    else if (lastContract !== null && compareSemver(installed.version, lastContract) < 0) {
+        manual.push(`the upgrade skips v${lastContract}, whose contract (destructive) migrations would run while v${installed.version}'s image still serves`);
+    }
+    if (manual.length > 0)
+        return { mode: "manual", kind: "normal", reasons: manual };
+    return { mode: "auto", kind: manifest.security ? "security" : "normal", reasons: [] };
+}
+//# sourceMappingURL=release-manifest.js.map

package/dist/release-manifest.js.map

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

package/dist/self-command.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A command line for this CLI, pinned to the version that is running
+ * (#696): `bunx @caelo-cms/provisioning@<this version> <args>`. Hints the
+ * CLI prints — resume the wizard, rotate a secret, check status — then
+ * run the same release the operator is using now, instead of whatever
+ * copy `bunx` cached for the bare package name.
+ *
+ * Not for upgrades: an upgrade must run as the *target* release, so
+ * `status` and the admin's Settings → Updates page build that command
+ * with the target version (`provisioningUpgradeCommand` in @caelo-cms/shared).
+ *
+ * @example selfCommand("rotate-secret", "internal-secret")
+ *   // → "bunx @caelo-cms/provisioning@0.10.43 rotate-secret internal-secret"
+ */
+export declare function selfCommand(...args: string[]): string;
+//# sourceMappingURL=self-command.d.ts.map

package/dist/self-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-command.d.ts","sourceRoot":"","sources":["../src/self-command.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAErD"}

package/dist/self-command.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MPL-2.0
+import { CAELO_VERSION, provisioningCommand } from "@caelo-cms/shared";
+/**
+ * A command line for this CLI, pinned to the version that is running
+ * (#696): `bunx @caelo-cms/provisioning@<this version> <args>`. Hints the
+ * CLI prints — resume the wizard, rotate a secret, check status — then
+ * run the same release the operator is using now, instead of whatever
+ * copy `bunx` cached for the bare package name.
+ *
+ * Not for upgrades: an upgrade must run as the *target* release, so
+ * `status` and the admin's Settings → Updates page build that command
+ * with the target version (`provisioningUpgradeCommand` in @caelo-cms/shared).
+ *
+ * @example selfCommand("rotate-secret", "internal-secret")
+ *   // → "bunx @caelo-cms/provisioning@0.10.43 rotate-secret internal-secret"
+ */
+export function selfCommand(...args) {
+    return provisioningCommand(CAELO_VERSION, args);
+}
+//# sourceMappingURL=self-command.js.map

package/dist/self-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-command.js","sourceRoot":"","sources":["../src/self-command.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,IAAc;IAC3C,OAAO,mBAAmB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/self-hosted-release.d.ts

@@ -0,0 +1,81 @@
+import { type ReleaseImages } from "./compose.js";
+/** What a host command returned. */
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Runs `docker` / `cosign` on the install's host. A seam so the install and
+ * upgrade orchestration is unit-testable with a fake (no real containers).
+ */
+export interface HostRunner {
+    /**
+     * Run `argv` to completion. With `stdoutPath`, stdout streams into that
+     * file (mode 600) instead of being captured — used for database dumps.
+     */
+    run(argv: readonly string[], opts?: {
+        readonly stdoutPath?: string;
+    }): Promise<CommandResult>;
+}
+/** The real runner: Bun.spawn; a missing binary is exit code 127, not a throw. */
+export declare const bunHostRunner: HostRunner;
+/** One install / upgrade / rollback of a self-hosted install. */
+export interface ReleaseHistoryEntry {
+    readonly at: string;
+    readonly from: string | null;
+    readonly to: string;
+    readonly outcome: "installed" | "upgraded" | "rolled-back";
+    readonly detail?: string;
+}
+/** `.caelo/release.json`. */
+export interface SelfHostedRelease {
+    /** The release tag the images were resolved from (e.g. `0.10.43`). */
+    readonly version: string;
+    readonly images: {
+        readonly admin: string;
+        readonly gateway: string;
+    };
+    readonly installedAt: string;
+    /** Newest last; capped at {@link HISTORY_LIMIT}. */
+    readonly history: readonly ReleaseHistoryEntry[];
+}
+export declare function releasePath(caeloDir: string): string;
+/** The images of a recorded release, as the Compose generator takes them. */
+export declare function releaseImages(release: SelfHostedRelease): ReleaseImages;
+/**
+ * The install's recorded release, or null when none is recorded (a dev-mode
+ * install, or one created before #696 that still runs the repo bind mount).
+ * Throws on a malformed record rather than running a guessed image.
+ */
+export declare function readRelease(caeloDir: string): SelfHostedRelease | null;
+/**
+ * Record that the install now runs `images` of `version` (or, for a
+ * rollback, keeps running the previous ones), appending to the history.
+ */
+export declare function recordRelease(caeloDir: string, next: {
+    version: string;
+    images: ReleaseImages;
+}, entry: Omit<ReleaseHistoryEntry, "at">, now?: Date): SelfHostedRelease;
+/** Record a failed-and-rolled-back upgrade without changing the running release. */
+export declare function recordRollback(caeloDir: string, current: SelfHostedRelease, attempted: string, detail: string, now?: Date): void;
+export type VerifiedRelease = {
+    readonly ok: true;
+    readonly images: ReleaseImages;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Resolve the admin + gateway images of release `tag` in GHCR to digests,
+ * then cosign-verify each digest against the Caelo release workflow
+ * identity (unless `skipVerify`, the escape hatch for forks). The returned
+ * references are digest-pinned, so what was verified is exactly what runs.
+ */
+export declare function resolveVerifiedRelease(tag: string, deps: {
+    readonly runner: HostRunner;
+    readonly skipVerify?: boolean;
+    readonly fetchImpl?: typeof fetch;
+    readonly onProgress?: (message: string) => void;
+}): Promise<VerifiedRelease>;
+//# sourceMappingURL=self-hosted-release.d.ts.map

package/dist/self-hosted-release.d.ts.map

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