@cardinali-studio/adminkit 2.1.0 → 2.2.1

package/dist/deployment.js

@@ -0,0 +1,180 @@
+import { sha256Hex } from "./persistence.js";
+export const deploymentPhases = [
+    "waiting", "validating", "materializing", "building", "deploying",
+    "verifying_deployment_url", "verifying_canonical", "succeeded", "failed", "ambiguous", "superseded",
+];
+const terminal = new Set(["succeeded", "failed", "ambiguous", "superseded"]);
+const next = {
+    waiting: ["validating", "failed", "ambiguous", "superseded"],
+    validating: ["materializing", "failed", "ambiguous", "superseded"],
+    materializing: ["building", "failed", "ambiguous", "superseded"],
+    building: ["deploying", "failed", "ambiguous", "superseded"],
+    deploying: ["verifying_deployment_url", "failed", "ambiguous", "superseded"],
+    verifying_deployment_url: ["verifying_canonical", "failed", "ambiguous", "superseded"],
+    verifying_canonical: ["succeeded", "failed", "ambiguous", "superseded"],
+};
+export function isTerminalDeploymentPhase(phase) {
+    return terminal.has(phase);
+}
+export function assertDeploymentTransition(from, to) {
+    if (!next[from]?.includes(to))
+        throw new Error("invalid_attempt_transition");
+}
+/** A claim is a single-use, short-lived capability. The CI shared credential
+ * authenticates the caller; the claim token binds its later calls to one exact
+ * attempt so a captured request cannot be replayed against another release. */
+export async function claimTokenChecksum(token) {
+    if (!/^[0-9a-f]{32,128}$/i.test(token))
+        throw new Error("invalid_claim_token");
+    return sha256Hex(`content-ci-claim:v1:${token}`);
+}
+export async function constantTimeSecretEqual(expected, provided) {
+    /* Hash both inputs before a fixed-length comparison. This works in Workers
+     * without Node's timingSafeEqual and never retains the supplied secret. */
+    const [left, right] = await Promise.all([sha256Hex(expected), sha256Hex(provided)]);
+    let difference = left.length ^ right.length;
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        difference |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+    }
+    return difference === 0;
+}
+/** Pure state model used both to pin the allowed lifecycle in tests and to
+ * keep the SQL repository from growing an implicit transition graph. */
+export class DeploymentAttemptKernel {
+    attempts = new Map();
+    claim(attemptId, releaseId, tokenChecksum, expiresAt, now) {
+        const attempt = this.required(attemptId, releaseId);
+        if (attempt.phase !== "waiting" || attempt.claimTokenChecksum || expiresAt <= now)
+            throw new Error("attempt_unavailable");
+        const claimed = { ...attempt, claimTokenChecksum: tokenChecksum, claimExpiresAt: expiresAt };
+        this.attempts.set(attemptId, claimed);
+        return claimed;
+    }
+    advance(attemptId, releaseId, tokenChecksum, to, now) {
+        const attempt = this.authorized(attemptId, releaseId, tokenChecksum, now);
+        assertDeploymentTransition(attempt.phase, to);
+        const advanced = { ...attempt, phase: to };
+        this.attempts.set(attemptId, advanced);
+        return advanced;
+    }
+    authorized(attemptId, releaseId, tokenChecksum, now) {
+        const attempt = this.required(attemptId, releaseId);
+        if (isTerminalDeploymentPhase(attempt.phase) || attempt.claimTokenChecksum !== tokenChecksum || !attempt.claimExpiresAt || attempt.claimExpiresAt <= now) {
+            throw new Error("attempt_unavailable");
+        }
+        return attempt;
+    }
+    required(attemptId, releaseId) {
+        const attempt = this.attempts.get(attemptId);
+        if (!attempt || attempt.releaseId !== releaseId)
+            throw new Error("attempt_not_found");
+        return attempt;
+    }
+}
+function asAttempt(row) {
+    if (!row?.releaseId)
+        return null;
+    return {
+        attemptId: row.attemptId, intentKind: row.intentKind, releaseId: row.releaseId, codeSha: row.codeSha,
+        phase: row.phase, claimTokenChecksum: row.claimTokenChecksum, claimExpiresAt: row.claimExpiresAt,
+    };
+}
+/** D1 adapter for the CI-only surface. It deliberately has no query that can
+ * select a "latest" release or an attempt from another site binding. */
+export class D1DeploymentAttemptRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async get(attemptId) {
+        const row = await this.db.prepare(`SELECT attempt_id AS attemptId, intent_kind AS intentKind, release_id AS releaseId,
+      code_sha AS codeSha, phase, ci_claim_token_checksum AS claimTokenChecksum, ci_claim_expires_at AS claimExpiresAt
+      FROM production_deployment_attempts WHERE attempt_id = ?`).bind(attemptId).first();
+        return asAttempt(row);
+    }
+    /** Registers the exact code/content pair before a workflow is dispatched.
+     * `active_slot` is the shared lane lock: code and content cannot overtake
+     * one another by merely reaching GitHub in a different queue order. */
+    async register(input) {
+        const existing = await this.db.prepare(`SELECT attempt_id AS attemptId, intent_kind AS intentKind,
+      requested_release_id AS requestedReleaseId, requested_code_sha AS requestedCodeSha, release_id AS releaseId,
+      code_sha AS codeSha, expected_fingerprint AS expectedFingerprint
+      FROM production_deployment_attempts WHERE attempt_id = ?`).bind(input.attemptId).first();
+        if (existing) {
+            if (existing.intentKind === input.intentKind && existing.requestedReleaseId === input.requestedReleaseId
+                && existing.requestedCodeSha === input.requestedCodeSha && existing.releaseId === input.releaseId
+                && existing.codeSha === input.codeSha && existing.expectedFingerprint === input.expectedFingerprint)
+                return "repeated";
+            throw new Error("duplicate_attempt");
+        }
+        const result = await this.db.prepare(`INSERT INTO production_deployment_attempts
+      (attempt_id, intent_kind, requested_release_id, requested_code_sha, code_sha, release_id, expected_fingerprint,
+       phase, active_slot, created_at, updated_at)
+      SELECT ?, ?, ?, ?, ?, ?, ?, 'waiting', 1, ?, ?
+      WHERE NOT EXISTS (SELECT 1 FROM production_deployment_attempts WHERE active_slot = 1)
+        AND EXISTS (SELECT 1 FROM content_releases WHERE release_id = ? AND status IN ('publishing', 'published'))`)
+            .bind(input.attemptId, input.intentKind, input.requestedReleaseId, input.requestedCodeSha, input.codeSha, input.releaseId, input.expectedFingerprint, input.now, input.now, input.releaseId).run();
+        if (result.meta?.changes !== 1)
+            throw new Error("deployment_lane_busy");
+        return "created";
+    }
+    async claim(input) {
+        const result = await this.db.prepare(`UPDATE production_deployment_attempts
+      SET ci_claim_token_checksum = ?, ci_claimed_at = ?, ci_claim_expires_at = ?, updated_at = ?
+      WHERE attempt_id = ? AND release_id = ? AND phase = 'waiting'
+        AND ci_claim_token_checksum IS NULL AND ci_claim_expires_at IS NULL`)
+            .bind(input.tokenChecksum, input.now, input.expiresAt, input.now, input.attemptId, input.releaseId).run();
+        if (result.meta?.changes !== 1)
+            throw new Error("attempt_unavailable");
+    }
+    async advance(input) {
+        assertDeploymentTransition(input.from, input.to);
+        const result = await this.db.prepare(`UPDATE production_deployment_attempts SET phase = ?, updated_at = ?,
+      active_slot = CASE WHEN ? IN ('succeeded', 'failed', 'ambiguous', 'superseded') THEN NULL ELSE 1 END,
+      finished_at = CASE WHEN ? IN ('succeeded', 'failed', 'ambiguous', 'superseded') THEN ? ELSE NULL END
+      WHERE attempt_id = ? AND release_id = ? AND phase = ? AND ci_claim_token_checksum = ?
+        AND ci_claim_expires_at > ?`)
+            .bind(input.to, input.now, input.to, input.to, input.now, input.attemptId, input.releaseId, input.from, input.tokenChecksum, input.now).run();
+        if (result.meta?.changes !== 1)
+            throw new Error("attempt_unavailable");
+    }
+    async fail(input) {
+        if (isTerminalDeploymentPhase(input.phase))
+            throw new Error("invalid_attempt_transition");
+        const result = await this.db.prepare(`UPDATE production_deployment_attempts
+      SET phase = 'failed', active_slot = NULL, error_code = ?, error_stage = ?, safe_message = ?, updated_at = ?, finished_at = ?
+      WHERE attempt_id = ? AND release_id = ? AND phase = ? AND ci_claim_token_checksum = ? AND ci_claim_expires_at > ?`)
+            .bind(input.code, input.stage, input.message, input.now, input.now, input.attemptId, input.releaseId, input.phase, input.tokenChecksum, input.now).run();
+        if (result.meta?.changes !== 1)
+            throw new Error("attempt_unavailable");
+    }
+    /** Promotes the release and succeeds the exact verified attempt in one D1
+     * batch. Every mutating statement repeats the capability guard, so a stale
+     * claim cannot publish content even if a prior read was valid. */
+    async finalize(input) {
+        const guard = `EXISTS (SELECT 1 FROM production_deployment_attempts WHERE attempt_id = ? AND release_id = ?
+      AND phase = 'verifying_canonical' AND ci_claim_token_checksum = ? AND ci_claim_expires_at > ?)`;
+        const statements = [
+            this.db.prepare(`UPDATE content_releases SET status = 'published', active_slot = NULL, finished_at = ?
+        WHERE release_id = ? AND status = 'publishing' AND base_release_id IS
+          (SELECT current_release_id FROM content_site_state WHERE singleton = 1) AND ${guard}`)
+                .bind(input.now, input.releaseId, input.attemptId, input.releaseId, input.tokenChecksum, input.now),
+            this.db.prepare(`UPDATE content_site_state SET current_release_id = ?, updated_at = ? WHERE singleton = 1
+        AND current_release_id IS (SELECT base_release_id FROM content_releases WHERE release_id = ?)
+        AND EXISTS (SELECT 1 FROM content_releases WHERE release_id = ? AND status = 'published') AND ${guard}`)
+                .bind(input.releaseId, input.now, input.releaseId, input.releaseId, input.attemptId, input.releaseId, input.tokenChecksum, input.now),
+            this.db.prepare(`UPDATE content_documents SET draft_revision_id = NULL, updated_at = ?
+        WHERE draft_revision_id IN (SELECT revision_id FROM content_release_entries WHERE release_id = ?)
+          AND document_id IN (SELECT document_id FROM content_release_entries WHERE release_id = ?) AND ${guard}`)
+                .bind(input.now, input.releaseId, input.releaseId, input.attemptId, input.releaseId, input.tokenChecksum, input.now),
+            this.db.prepare(`UPDATE production_deployment_attempts SET phase = 'succeeded', active_slot = NULL, updated_at = ?, finished_at = ?
+        WHERE attempt_id = ? AND release_id = ? AND phase = 'verifying_canonical' AND ci_claim_token_checksum = ?
+          AND ci_claim_expires_at > ? AND EXISTS (SELECT 1 FROM content_site_state WHERE singleton = 1 AND current_release_id = ?)`)
+                .bind(input.now, input.now, input.attemptId, input.releaseId, input.tokenChecksum, input.now, input.releaseId),
+        ];
+        const results = await this.db.batch(statements);
+        if (results[0]?.meta?.changes !== 1 || results[1]?.meta?.changes !== 1 || results[3]?.meta?.changes !== 1) {
+            throw new Error("attempt_unavailable");
+        }
+    }
+}

package/dist/functions/api/content-ci.js

@@ -0,0 +1,141 @@
+import { json } from "../_shared/assets.js";
+import { D1ContentRepository } from "../../persistence.js";
+import {
+  D1DeploymentAttemptRepository, claimTokenChecksum, constantTimeSecretEqual,
+  isTerminalDeploymentPhase,
+} from "../../deployment.js";
+import { releaseExportFromStored } from "../../release.js";
+
+const MAX_BODY_BYTES = 8_000;
+const claimLifetimeMs = 20 * 60 * 1_000;
+const id = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const phases = new Set(["validating", "materializing", "building", "deploying", "verifying_deployment_url", "verifying_canonical"]);
+const failure = {
+  materialization_failed: { stage: "materializing", message: "La generazione del sito non è riuscita." },
+  build_failed: { stage: "building", message: "La compilazione del sito non è riuscita." },
+  deployment_failed: { stage: "deploying", message: "La distribuzione non è riuscita." },
+  verification_failed: { stage: "verifying", message: "La verifica della pubblicazione non è riuscita." },
+};
+
+function response(data, status = 200) {
+  const result = json(data, status);
+  result.headers.set("Cache-Control", "no-store");
+  result.headers.set("Pragma", "no-cache");
+  return result;
+}
+
+function diagnosticId() {
+  return `diag_${crypto.randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+
+function safeError(code, stage, status = 400) {
+  const message = code === "ci_unauthorized" ? "Credenziale CI non valida."
+    : code === "attempt_not_available" ? "Tentativo di pubblicazione non disponibile."
+      : code === "invalid_request" ? "Richiesta CI non valida."
+        : "Esportazione contenuti non disponibile.";
+  return response({ ok: false, code, stage, error: message, diagnosticId: diagnosticId(), retryable: status >= 500 }, status);
+}
+
+function hasBrowserSession(request) {
+  return Boolean(request.headers.get("Cookie") || request.headers.get("CF-Access-Jwt-Assertion") || request.headers.get("Origin"));
+}
+
+async function authorize(request, env) {
+  const configured = typeof env.CONTENT_CI_TOKEN === "string" ? env.CONTENT_CI_TOKEN : "";
+  const match = /^Bearer ([^\s]+)$/.exec(request.headers.get("Authorization") || "");
+  if (!configured || !match || hasBrowserSession(request) || !await constantTimeSecretEqual(configured, match[1])) {
+    throw new Error("ci_unauthorized");
+  }
+}
+
+function requiredIdentity(value) {
+  if (!value || typeof value !== "object" || !id.test(value.attemptId || "") || !id.test(value.releaseId || "")) {
+    throw new Error("invalid_request");
+  }
+  return { attemptId: value.attemptId, releaseId: value.releaseId };
+}
+
+async function body(request) {
+  if (Number(request.headers.get("Content-Length") || 0) > MAX_BODY_BYTES) throw new Error("invalid_request");
+  const raw = await request.text();
+  if (new TextEncoder().encode(raw).byteLength > MAX_BODY_BYTES) throw new Error("invalid_request");
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid_request");
+    return parsed;
+  } catch { throw new Error("invalid_request"); }
+}
+
+function repositories(env) {
+  if (!env.CONTENT_DB) throw new Error("content_unavailable");
+  return { attempts: new D1DeploymentAttemptRepository(env.CONTENT_DB), content: new D1ContentRepository(env.CONTENT_DB) };
+}
+
+async function claimedAttempt(request, attempts, identity, now) {
+  const token = request.headers.get("X-Content-CI-Claim") || "";
+  let checksum;
+  try { checksum = await claimTokenChecksum(token); } catch { throw new Error("attempt_not_available"); }
+  const attempt = await attempts.get(identity.attemptId);
+  if (!attempt || attempt.releaseId !== identity.releaseId || isTerminalDeploymentPhase(attempt.phase)
+    || attempt.claimTokenChecksum !== checksum || !attempt.claimExpiresAt || attempt.claimExpiresAt <= now) {
+    throw new Error("attempt_not_available");
+  }
+  return { attempt, checksum };
+}
+
+/** Site-owned Pages Functions intentionally call this directly from their
+ * `/internal/[[path]].js` file. It is not registered in the Access-protected
+ * admin router, so browser sessions cannot accidentally reach a CI route. */
+export async function handleInternalContentCi({ request, env }) {
+  try {
+    await authorize(request, env);
+    const url = new URL(request.url);
+    const path = url.pathname;
+    const now = Date.now();
+    const { attempts, content } = repositories(env);
+
+    if (path === "/internal/deployment/claim" && request.method === "POST") {
+      const identity = requiredIdentity(await body(request));
+      const attempt = await attempts.get(identity.attemptId);
+      if (!attempt || attempt.releaseId !== identity.releaseId || attempt.phase !== "waiting" || attempt.claimTokenChecksum) throw new Error("attempt_not_available");
+      const token = crypto.randomUUID().replaceAll("-", "");
+      const expiresAt = now + claimLifetimeMs;
+      await attempts.claim({ ...identity, tokenChecksum: await claimTokenChecksum(token), now, expiresAt });
+      return response({ ok: true, attempt: { ...identity, phase: "waiting", expiresAt }, claimToken: token });
+    }
+
+    if (path === "/internal/release/export" && request.method === "GET") {
+      const identity = requiredIdentity({ attemptId: url.searchParams.get("attemptId"), releaseId: url.searchParams.get("releaseId") });
+      const { attempt } = await claimedAttempt(request, attempts, identity, now);
+      const snapshot = await content.getReleaseExport(attempt.releaseId);
+      if (!snapshot) throw new Error("attempt_not_available");
+      return response({ ok: true, attempt: { attemptId: attempt.attemptId, releaseId: attempt.releaseId, phase: attempt.phase }, release: await releaseExportFromStored(snapshot) });
+    }
+
+    const input = await body(request);
+    const identity = requiredIdentity(input);
+    const { attempt, checksum } = await claimedAttempt(request, attempts, identity, now);
+    if (path === "/internal/deployment/phase" && request.method === "POST") {
+      if (!phases.has(input.phase)) throw new Error("invalid_request");
+      await attempts.advance({ ...identity, tokenChecksum: checksum, from: attempt.phase, to: input.phase, now });
+      return response({ ok: true, attempt: { ...identity, phase: input.phase } });
+    }
+    if (path === "/internal/deployment/finalize" && request.method === "POST") {
+      await attempts.finalize({ ...identity, tokenChecksum: checksum, now });
+      return response({ ok: true, attempt: { ...identity, phase: "succeeded" } });
+    }
+    if (path === "/internal/deployment/fail" && request.method === "POST") {
+      const detail = failure[input.code];
+      if (!detail) throw new Error("invalid_request");
+      await attempts.fail({ ...identity, tokenChecksum: checksum, phase: attempt.phase, now, code: input.code, ...detail });
+      return response({ ok: true, attempt: { ...identity, phase: "failed" } });
+    }
+    return safeError("invalid_request", "routing", 405);
+  } catch (error) {
+    const code = error?.message;
+    if (code === "ci_unauthorized") return safeError(code, "authorization", 401);
+    if (code === "invalid_request" || code === "invalid_attempt_transition") return safeError("invalid_request", "validation", 400);
+    if (code === "attempt_not_available" || code === "attempt_unavailable") return safeError("attempt_not_available", "attempt", 409);
+    return safeError("content_unavailable", "persistence", 503);
+  }
+}

package/dist/functions/api/content.js

@@ -0,0 +1,140 @@
+import { json } from "../_shared/assets.js";
+import { D1ContentRepository, canonicalChecksum, contentSaveRequestChecksum } from "../../persistence.js";
+import { presentContentConflict, validateContentDocument } from "../site.js";
+
+const MAX_BODY_BYTES = 512_000;
+const id = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const checksum = /^[0-9a-f]{64}$/;
+
+function response(data, status = 200) {
+  const result = json(data, status);
+  result.headers.set("Cache-Control", "no-store");
+  return result;
+}
+
+function diagnosticId() {
+  return `diag_${crypto.randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+
+function repository(env) {
+  if (!env.CONTENT_DB) throw new Error("content_unavailable");
+  return new D1ContentRepository(env.CONTENT_DB);
+}
+
+function safeError(error, stage) {
+  const code = error?.message;
+  const safeCode = ["content_unavailable", "unauthenticated", "invalid_request", "invalid_document", "stale_revision", "duplicate_request"].includes(code)
+    ? code : "content_unavailable";
+  const status = safeCode === "unauthenticated" ? 401
+    : safeCode === "stale_revision" || safeCode === "duplicate_request" ? 409
+      : safeCode === "invalid_request" || safeCode === "invalid_document" ? 400 : 503;
+  const message = safeCode === "unauthenticated" ? "Sessione non valida: ricarica la pagina per rientrare."
+    : safeCode === "stale_revision" ? "Questo contenuto è stato modificato altrove: ricarica e risolvi il conflitto."
+    : code === "duplicate_request" ? "Questo identificatore di salvataggio è già associato a dati diversi."
+      : safeCode === "invalid_request" || safeCode === "invalid_document" ? "Il documento non è valido."
+        : "La persistenza contenuti non è disponibile.";
+  return response({ ok: false, code: safeCode, stage, error: message, diagnosticId: diagnosticId(), retryable: status >= 500 }, status);
+}
+
+function author(data) {
+  const payload = data?.cloudflareAccess?.JWT?.payload;
+  if (!payload?.sub) throw new Error("unauthenticated");
+  return { subject: String(payload.sub), label: String(payload.email || payload.name || "Admin").slice(0, 200) };
+}
+
+function parseStoredRevision(revision) {
+  if (!revision) return null;
+  return {
+    revisionId: revision.revisionId,
+    schemaVersion: revision.schemaVersion,
+    tombstone: Boolean(revision.tombstone),
+    payload: revision.payload === null ? null : JSON.parse(revision.payload),
+  };
+}
+
+async function conflict(repo, { documentId, baseRevisionId, mine }) {
+  const currentDocument = await repo.getEffectiveDocument(documentId);
+  const current = currentDocument?.draftRevisionId ? await repo.getRevision(currentDocument.draftRevisionId) : null;
+  const base = baseRevisionId ? await repo.getRevision(baseRevisionId) : null;
+  return presentContentConflict({
+    base: parseStoredRevision(base),
+    current: parseStoredRevision(current),
+    mine,
+  });
+}
+
+export async function onRequestGet({ request, env }) {
+  try {
+    const repo = repository(env);
+    const url = new URL(request.url);
+    if (url.pathname.endsWith("/state")) {
+      const state = await env.CONTENT_DB.prepare("SELECT current_release_id, current_code_sha, current_pages_deployment_id, current_fingerprint, schema_generation, updated_at FROM content_site_state WHERE singleton = 1").first();
+      return response({ ok: true, state: state || null });
+    }
+    const documentId = url.searchParams.get("id") || "";
+    if (!url.pathname.endsWith("/document")) return response({ ok: false, code: "invalid_request", stage: "validation", error: "Metodo non ammesso.", diagnosticId: diagnosticId(), retryable: false }, 405);
+    if (!id.test(documentId)) return response({ ok: false, code: "invalid_request", stage: "validation", error: "Identificatore documento non valido.", diagnosticId: diagnosticId(), retryable: false }, 400);
+    const document = await repo.getEffectiveDocument(documentId);
+    return document ? response({ ok: true, document }) : response({ ok: false, code: "not_found", stage: "validation", error: "Documento non trovato.", diagnosticId: diagnosticId(), retryable: false }, 404);
+  } catch (error) { return safeError(error, "validation"); }
+}
+
+export async function onRequestPost({ request, env, data }) {
+  if (Number(request.headers.get("Content-Length") || 0) > MAX_BODY_BYTES) return response({ ok: false, code: "invalid_request", stage: "validation", error: "Richiesta troppo grande.", diagnosticId: diagnosticId(), retryable: false }, 413);
+  let body;
+  try {
+    const raw = await request.text();
+    if (new TextEncoder().encode(raw).byteLength > MAX_BODY_BYTES) throw new Error("too_large");
+    body = JSON.parse(raw);
+  } catch (error) {
+    const tooLarge = error?.message === "too_large";
+    return response({ ok: false, code: "invalid_request", stage: "validation", error: tooLarge ? "Richiesta troppo grande." : "JSON non valido.", diagnosticId: diagnosticId(), retryable: false }, tooLarge ? 413 : 400);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return response({ ok: false, code: "invalid_request", stage: "validation", error: "JSON non valido.", diagnosticId: diagnosticId(), retryable: false }, 400);
+  }
+  try {
+    const now = Date.now();
+    if (new URL(request.url).pathname.endsWith("/discard")) {
+      author(data);
+      if (!id.test(body.documentId) || (body.expectedDraftRevisionId !== null && !id.test(body.expectedDraftRevisionId)) || (body.baselineRevisionId !== null && !id.test(body.baselineRevisionId))) throw new Error("invalid_request");
+      const repo = repository(env);
+      try {
+        await repo.discard(body.documentId, body.expectedDraftRevisionId, body.baselineRevisionId, now);
+        return response({ ok: true, discarded: true });
+      } catch (error) {
+        if (error?.message !== "stale_revision") throw error;
+        return response({
+          ok: false, code: "stale_revision", stage: "discard",
+          error: "Questo contenuto è stato modificato altrove: ricarica e risolvi il conflitto.",
+          diagnosticId: diagnosticId(), retryable: false,
+          conflict: await conflict(repo, {
+            documentId: body.documentId, baseRevisionId: body.baselineRevisionId,
+            mine: { action: "discard", expectedDraftRevisionId: body.expectedDraftRevisionId, baselineRevisionId: body.baselineRevisionId },
+          }),
+        }, 409);
+      }
+    }
+    if (!new URL(request.url).pathname.endsWith("/save")) return response({ ok: false, code: "invalid_request", stage: "validation", error: "Metodo non ammesso.", diagnosticId: diagnosticId(), retryable: false }, 405);
+    const editor = author(data);
+    if (!id.test(body.revisionId) || !id.test(body.documentId) || (body.baseRevisionId !== null && !id.test(body.baseRevisionId)) || (body.expectedDraftRevisionId !== undefined && body.expectedDraftRevisionId !== null && !id.test(body.expectedDraftRevisionId)) || (body.translationGroupId !== null && body.translationGroupId !== undefined && !id.test(body.translationGroupId)) || !checksum.test(body.requestChecksum || "") || !Number.isInteger(body.schemaVersion) || body.schemaVersion < 1 || typeof body.kind !== "string" || body.kind.length > 120 || typeof body.locale !== "string" || body.locale.length > 35 || (body.payload !== null && (typeof body.payload !== "object" || Array.isArray(body.payload)))) throw new Error("invalid_request");
+    const document = validateContentDocument({ documentId: body.documentId, kind: body.kind, locale: body.locale, translationGroupId: body.translationGroupId ?? null, payload: body.payload, tombstone: body.tombstone === true, schemaVersion: body.schemaVersion });
+    if (document.documentId !== body.documentId || document.kind !== body.kind || document.locale !== body.locale || document.schemaVersion !== body.schemaVersion || document.tombstone !== (body.tombstone === true)) throw new Error("invalid_document");
+    const expectedPayloadChecksum = await canonicalChecksum(document.tombstone ? null : document.payload);
+    if (body.payloadChecksum !== expectedPayloadChecksum) throw new Error("invalid_document");
+    const normalized = { ...body, ...document, expectedDraftRevisionId: body.expectedDraftRevisionId === undefined ? body.baseRevisionId : body.expectedDraftRevisionId, payloadChecksum: expectedPayloadChecksum };
+    const expectedRequestChecksum = await contentSaveRequestChecksum(normalized);
+    if (body.requestChecksum !== expectedRequestChecksum) throw new Error("invalid_document");
+    const repo = repository(env);
+    try {
+      const outcome = await repo.save({ ...normalized, now, authorSubject: editor.subject, authorLabel: editor.label });
+      return response({ ok: true, saved: true, repeated: outcome === "repeated", revisionId: body.revisionId });
+    } catch (error) {
+      if (error?.message !== "stale_revision") throw error;
+      return response({ ok: false, code: "stale_revision", stage: "save", error: "Questo contenuto è stato modificato altrove: ricarica e risolvi il conflitto.", diagnosticId: diagnosticId(), retryable: false, conflict: await conflict(repo, {
+        documentId: normalized.documentId, baseRevisionId: normalized.baseRevisionId,
+        mine: { revisionId: normalized.revisionId, schemaVersion: normalized.schemaVersion, tombstone: normalized.tombstone === true, payload: normalized.payload },
+      }) }, 409);
+    }
+  } catch (error) { return safeError(error, "save"); }
+}

package/dist/functions/index.js

@@ -22,7 +22,7 @@
  * sull'acchiappatutto (verificato, non dedotto). È il motivo per cui Prenotazioni può restare
  * dov'è senza inventare nessun punto di innesto.
  */
-import { setServerConfig, moduleEnabled } from "./site.js";
+import { setServerConfig, moduleEnabled, contentPersistenceMode } from "./site.js";
 
 import * as analytics from "./api/analytics.js";
 import * as assets from "./api/assets.js";
@@ -48,6 +48,7 @@ import * as requests from "./api/requests.js";
 import * as settings from "./api/settings.js";
 import * as singleton from "./api/singleton.js";
 import * as storage from "./api/storage.js";
+import * as content from "./api/content.js";
 
 export { adminAccess } from "./_middleware.js";
 export { setServerConfig } from "./site.js";
@@ -83,6 +84,10 @@ const ROUTES = {
   "settings": { mod: null, h: settings },
   "singleton": { mod: null, h: singleton },
   "storage": { mod: null, h: storage },
+  "content/state": { mod: null, h: content },
+  "content/document": { mod: null, h: content },
+  "content/save": { mod: null, h: content },
+  "content/discard": { mod: null, h: content },
 };
 
 const PREFIX = "/admin/api/";
@@ -105,6 +110,9 @@ export async function handleAdminApi(context, config) {
   const path = url.pathname.slice(PREFIX.length).split("/").filter(Boolean).join("/");
   const route = ROUTES[path];
   if (!route) return json({ ok: false, error: "rotta sconosciuta" }, 404);
+  if (path.startsWith("content/") && contentPersistenceMode() !== "d1") {
+    return json({ ok: false, code: "feature_inactive", error: "Persistenza D1 non attiva per questo sito." }, 404);
+  }
 
   /* Un modulo spento risponde 404, non 403: dall'esterno quella funzione non esiste, e un 403
    * racconterebbe che esiste ma è vietata. */

package/dist/functions/site.js

@@ -51,3 +51,31 @@ export function languages() {
   const available = [...new Set(config.available.filter((language) => typeof language === "string" && language))];
   return available.includes(config.default) ? { default: config.default, available } : null;
 }
+
+/** Git remains the compatibility default. D1 is opt-in per site and fails
+ * closed when its dedicated binding is absent. */
+export function contentPersistenceMode() {
+  return current?.contentPersistence === "d1" ? "d1" : "github";
+}
+
+/** D1 owns persistence, never a site's editorial meaning. A site explicitly
+ * supplies both functions before its D1 mode can accept a write: one validates
+ * (and may normalize) the complete document and the other produces the
+ * intentionally displayable side of a three-way conflict. */
+export function validateContentDocument(document) {
+  const validate = current?.content?.validateDocument;
+  if (typeof validate !== "function") throw new Error("content_unavailable");
+  const result = validate(document);
+  if (!result || result.ok !== true || !result.document || typeof result.document !== "object") {
+    throw new Error("invalid_document");
+  }
+  return result.document;
+}
+
+export function presentContentConflict(comparison) {
+  const present = current?.content?.presentConflict;
+  if (typeof present !== "function") throw new Error("content_unavailable");
+  const result = present(comparison);
+  if (!result || typeof result !== "object") throw new Error("content_unavailable");
+  return result;
+}

package/dist/index.d.ts

@@ -9,3 +9,8 @@ export * from "./prose.js";
 export * from "./gallery.js";
 export * from "./normalize.js";
 export * from "./i18n.js";
+export * from "./persistence.js";
+export * from "./conflict.js";
+export * from "./release.js";
+export * from "./deployment.js";
+export * from "./media.js";

package/dist/index.js

@@ -9,3 +9,8 @@ export * from "./prose.js";
 export * from "./gallery.js";
 export * from "./normalize.js";
 export * from "./i18n.js";
+export * from "./persistence.js";
+export * from "./conflict.js";
+export * from "./release.js";
+export * from "./deployment.js";
+export * from "./media.js";

package/dist/materializer.d.ts

@@ -0,0 +1,20 @@
+import type { ImmutableReleaseExport, ReleaseExportEntry } from "./release.js";
+export type MaterializedFile = {
+    path: string;
+    content: string;
+};
+export type ReleaseMaterializer = {
+    /** Site-wide validation happens before generating any file. This is where a
+     * site rejects collisions that are meaningful to Hugo (URLs, menus, etc.)
+     * but cannot be inferred from one document in isolation. */
+    validate?(entries: readonly ReleaseExportEntry[]): void;
+    materialize(entry: ReleaseExportEntry): readonly MaterializedFile[];
+};
+/** Pure materialization planning. The CI driver owns the disposable directory
+ * and writes these files there; keeping filesystem effects out of this module
+ * makes it impossible for a package consumer to accidentally rewrite tracked
+ * content while preparing a release. */
+export declare function materializeRelease(release: ImmutableReleaseExport, adapter: ReleaseMaterializer, fingerprint: {
+    version: 1;
+    fingerprint: string;
+}): readonly MaterializedFile[];

package/dist/materializer.js

@@ -0,0 +1,27 @@
+import { deploymentFingerprintJson } from "./release.js";
+const SAFE_OUTPUT_PATH = /^(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+/** Pure materialization planning. The CI driver owns the disposable directory
+ * and writes these files there; keeping filesystem effects out of this module
+ * makes it impossible for a package consumer to accidentally rewrite tracked
+ * content while preparing a release. */
+export function materializeRelease(release, adapter, fingerprint) {
+    adapter.validate?.(release.entries);
+    const files = [];
+    for (const entry of release.entries) {
+        if (entry.tombstone)
+            continue;
+        for (const file of adapter.materialize(entry)) {
+            if (!SAFE_OUTPUT_PATH.test(file.path) || file.path.startsWith(".") || typeof file.content !== "string")
+                throw new Error("invalid_materialized_file");
+            files.push(file);
+        }
+    }
+    files.push({ path: ".well-known/adminkit-deployment.json", content: deploymentFingerprintJson(fingerprint) });
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.path))
+            throw new Error("duplicate_materialized_file");
+        seen.add(file.path);
+    }
+    return files.sort((left, right) => left.path.localeCompare(right.path));
+}