Add authenticated provisioning artifact staging

Author: chubes4

docs/cloudflare-provisioning-api.md

@@ -14,6 +14,7 @@ The Worker compares SHA-256 token digests and never accepts plaintext API creden
 
 ## Resources
 
+- `PUT /v1/artifacts/{sha256}` requires `Authorization: Bearer ...` with `sites:create`. Its body is the canonical `blocks-engine/php-transformer/site-artifact/v1` JSON artifact. The Worker enforces the artifact byte, file, path, encoding, and digest bounds before an immutable conditional write, then returns the exact reference accepted by site creation. Replays of identical bytes converge; conflicting content at the digest-addressed key fails closed.
 - `POST /v1/sites` requires `Authorization: Bearer ...` with `sites:create` and `Idempotency-Key`. Its body is `wp-codebox/provisioning-create-request/v1`; it references an immutable staged artifact at `sites/provisioning/import-artifacts/<sha256>.json`. The Worker verifies the bounded artifact before allocating a site, then copies it immutably to the selected site namespace.
 - `GET /v1/sites/{siteId}` requires `sites:read`.
 - `POST /v1/sites/{siteId}/imports` requires `sites:import` and uses the existing bounded static-artifact request.

packages/runtime-cloudflare/src/provisioning-api.ts

@@ -6,6 +6,7 @@ import { deriveSiteCredential } from "./wordpress-auth.js"
 export const PROVISIONING_API_SCHEMA = "wp-codebox/provisioning-api/v1"
 export const PROVISIONING_CREATE_REQUEST_SCHEMA = "wp-codebox/provisioning-create-request/v1"
 export const PROVISIONING_SITE_RESOURCE_SCHEMA = "wp-codebox/provisioning-site/v1"
+export const PROVISIONING_ARTIFACT_RESOURCE_SCHEMA = "wp-codebox/provisioning-artifact/v1"
 export const PROVISIONING_ERROR_SCHEMA = "wp-codebox/provisioning-error/v1"
 const SCOPES = new Set(["sites:create", "sites:read", "sites:import", "operations:read"])
 
@@ -21,6 +22,7 @@ export async function routeProvisioningApi(request: Request, env: ProvisioningEn
   const parts = new URL(request.url).pathname.split("/").filter(Boolean)
   const method = request.method
   if (parts[0] !== "v1") return notFound()
+  if (parts.length === 3 && parts[1] === "artifacts" && /^[a-f0-9]{64}$/.test(parts[2])) return method === "PUT" ? stageArtifact(request, env, parts[2]) : methodNotAllowed("PUT")
   if (parts.length === 2 && parts[1] === "sites") return method === "POST" ? create(request, env, operations) : methodNotAllowed("POST")
   if (parts.length < 3 || parts[1] !== "sites" || !validSiteId(parts[2])) return notFound()
   const siteId = parts[2]
@@ -32,6 +34,35 @@ export async function routeProvisioningApi(request: Request, env: ProvisioningEn
   return notFound()
 }
 
+async function stageArtifact(request: Request, env: ProvisioningEnv, expectedSha256: string): Promise<Response> {
+  const token = await authenticate(request, env, "sites:create"); if (token instanceof Response) return token
+  const declaredLength = request.headers.get("content-length")
+  if (declaredLength && (!/^\d+$/.test(declaredLength) || Number(declaredLength) < 1 || Number(declaredLength) > MAX_STATIC_ARTIFACT_BYTES)) return apiError(413, "invalid_artifact", "Provisioning artifact exceeds its byte budget.")
+  let bytes: Uint8Array
+  try { bytes = await readBoundedRequestBytes(request, MAX_STATIC_ARTIFACT_BYTES) } catch (error) { return importError(error) }
+  if (!bytes.byteLength) return apiError(400, "invalid_artifact", "Provisioning artifact is required.")
+  if (await sha(bytes) !== expectedSha256) return apiError(409, "artifact_digest_mismatch", "Provisioning artifact does not match its digest.")
+  try { await validateArtifact(bytes) } catch (error) { return importError(error) }
+  const key = stagedKey(expectedSha256)
+  const verify = async () => {
+    const object = await env.WORDPRESS_STATE_BUCKET.get(key)
+    if (!object) return false
+    const stored = new Uint8Array(await object.arrayBuffer())
+    if (object.size !== bytes.byteLength || stored.byteLength !== bytes.byteLength || await sha(stored) !== expectedSha256) throw new OperationConflict("Provisioning artifact staging conflicts with existing content.")
+    return true
+  }
+  try {
+    if (!await verify()) {
+      await env.WORDPRESS_STATE_BUCKET.put(key, bytes, { onlyIf: { etagDoesNotMatch: "*" }, httpMetadata: { contentType: "application/json" } })
+      if (!await verify()) throw new OperationConflict("Provisioning artifact staging did not produce a verified object.")
+    }
+  } catch (error) {
+    if (error instanceof OperationConflict) return apiError(409, "artifact_conflict", error.message)
+    throw error
+  }
+  return Response.json({ schema: PROVISIONING_ARTIFACT_RESOURCE_SCHEMA, artifact: { sha256: expectedSha256, size: bytes.byteLength, r2Key: key } }, { status: 200 })
+}
+
 async function create(request: Request, env: ProvisioningEnv, operations: D1OperationRepository): Promise<Response> {
   const token = await authenticate(request, env, "sites:create"); if (token instanceof Response) return token
   const key = idempotencyKey(request); if (key instanceof Response) return key

packages/runtime-cloudflare/src/static-artifact-import.ts

@@ -77,7 +77,7 @@ export class StaticArtifactImportError extends Error {
   }
 }
 
-export async function readBoundedRequestBytes(request: Request): Promise<Uint8Array> {
+export async function readBoundedRequestBytes(request: Request, maxBytes = MAX_STATIC_ARTIFACT_REQUEST_BYTES): Promise<Uint8Array> {
   if (!request.body) return new Uint8Array()
   const reader = request.body.getReader()
   const chunks: Uint8Array[] = []
@@ -86,7 +86,7 @@ export async function readBoundedRequestBytes(request: Request): Promise<Uint8Ar
     const { done, value } = await reader.read()
     if (done) break
     total += value.byteLength
-    if (total > MAX_STATIC_ARTIFACT_REQUEST_BYTES) {
+    if (total > maxBytes) {
       await reader.cancel()
       throw new StaticArtifactImportError("Static artifact import request exceeds its byte budget.", 413)
     }

tests/cloudflare-provisioning-api.test.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto"
 import { DatabaseSync } from "node:sqlite"
 import test from "node:test"
 import { D1OperationRepository } from "../packages/runtime-cloudflare/src/d1-operation-repository.js"
-import { PROVISIONING_CREATE_REQUEST_SCHEMA, resumeProvisioningAllocation, routeProvisioningApi } from "../packages/runtime-cloudflare/src/provisioning-api.js"
+import { PROVISIONING_ARTIFACT_RESOURCE_SCHEMA, PROVISIONING_CREATE_REQUEST_SCHEMA, resumeProvisioningAllocation, routeProvisioningApi } from "../packages/runtime-cloudflare/src/provisioning-api.js"
 import { STATIC_ARTIFACT_IMPORT_REQUEST_SCHEMA } from "../packages/runtime-cloudflare/src/static-artifact-import.js"
 
 const hash = (value: string | Uint8Array) => createHash("sha256").update(value).digest("hex")
@@ -28,6 +28,7 @@ function createRequest(key = "create-1", change: Partial<{ sha256: string; size:
   const sha256 = change.sha256 ?? digest; const size = change.size ?? artifact.byteLength
   return new Request("https://control.invalid/v1/sites", { method: "POST", headers: { authorization: `Bearer ${token}`, "idempotency-key": key }, body: JSON.stringify({ schema: PROVISIONING_CREATE_REQUEST_SCHEMA, idempotencyKey: key, artifact: { sha256, size, r2Key: change.r2Key ?? `sites/provisioning/import-artifacts/${sha256}.json` }, import: { slug: "site", name: "Site", siteTitle: change.title ?? "Site" } }) })
 }
+function stageRequest(body: Uint8Array = artifact, sha256 = digest, token = "good") { return new Request(`https://control.invalid/v1/artifacts/${sha256}`, { method: "PUT", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body }) }
 async function create(runtime: ReturnType<typeof runtime>, key = "create-1") { return routeProvisioningApi(createRequest(key), runtime.env, runtime.operations) }
 function count(db: Db, table: string) { const exists = db.sqlite.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table); return exists ? Number((db.sqlite.prepare(`SELECT COUNT(*) AS count FROM ${table}`).get() as { count: number }).count) : 0 }
 
@@ -39,6 +40,33 @@ test("auth failures, malformed config, expiry, and scope stop before body and R2
 test("invalid, missing, and oversized artifacts create zero allocations", async () => {
   for (const change of [{ sha256: "bad" }, { sha256: "f".repeat(64) }, { size: 5 * 1024 * 1024 }]) { const r = runtime(); assert.ok((await routeProvisioningApi(createRequest("key", change), r.env, r.operations)).status >= 400); assert.equal(count(r.db, "wp_codebox_api_sites"), 0) }
 })
+test("authenticated artifact staging validates and converges immutable canonical bytes", async () => {
+  const r = runtime(); r.bucket.objects.clear()
+  const first = await routeProvisioningApi(stageRequest(), r.env, r.operations)
+  assert.equal(first.status, 200)
+  assert.deepEqual(await first.json(), { schema: PROVISIONING_ARTIFACT_RESOURCE_SCHEMA, artifact: { sha256: digest, size: artifact.byteLength, r2Key: `sites/provisioning/import-artifacts/${digest}.json` } })
+  assert.equal((await routeProvisioningApi(stageRequest(), r.env, r.operations)).status, 200)
+  assert.equal(r.bucket.puts, 1)
+  assert.equal((await create(r)).status, 202)
+})
+test("artifact staging authenticates before reads and rejects mismatched or noncanonical bytes", async () => {
+  const unauthorized = runtime(); unauthorized.bucket.objects.clear()
+  assert.equal((await routeProvisioningApi(stageRequest(artifact, digest, "bad"), unauthorized.env, unauthorized.operations)).status, 401)
+  assert.equal(unauthorized.bucket.puts, 0)
+  const mismatch = runtime(); mismatch.bucket.objects.clear()
+  assert.equal((await routeProvisioningApi(stageRequest(new TextEncoder().encode("{}")), mismatch.env, mismatch.operations)).status, 409)
+  assert.equal(mismatch.bucket.puts, 0)
+  const invalid = new TextEncoder().encode(JSON.stringify({ schema: "wp-build/website-artifact-bundle/v1", root: "website/", entrypoint: "website/index.html", files: [{ path: "website/index.html", content: "ok" }] }))
+  const rejected = runtime(); rejected.bucket.objects.clear()
+  assert.equal((await routeProvisioningApi(stageRequest(invalid, hash(invalid)), rejected.env, rejected.operations)).status, 422)
+  assert.equal(rejected.bucket.puts, 0)
+})
+test("artifact staging verifies the winner of a conditional R2 race", async () => {
+  const same = runtime(); same.bucket.objects.clear(); same.bucket.race = artifact
+  assert.equal((await routeProvisioningApi(stageRequest(), same.env, same.operations)).status, 200)
+  const conflicting = runtime(); conflicting.bucket.objects.clear(); conflicting.bucket.race = new TextEncoder().encode("bad")
+  assert.equal((await routeProvisioningApi(stageRequest(), conflicting.env, conflicting.operations)).status, 409)
+})
 test("registered active contexts are excluded", async () => { const r = runtime(); await r.operations.createOrConverge({ id: "alpha", hostname: "alpha.example", origin: "https://alpha.example" }, { idempotencyKey: "legacy", fingerprint: "x", artifact: { r2Key: "x", sha256: digest, size: artifact.byteLength }, options: { slug: "x", name: "x", siteTitle: "x" } }); const body = await (await create(r)).json() as { site: { id: string } }; assert.equal(body.site.id, "beta") })
 test("exact and concurrent same-key creates converge", async () => { const r = runtime(); const [one, two] = await Promise.all([create(r), create(r)]); assert.equal(one.status, 202); assert.deepEqual(await one.json(), await two.json()); assert.equal(count(r.db, "wp_codebox_api_sites"), 1) })
 test("changed fingerprints conflict without another allocation", async () => { const r = runtime(); await create(r); const response = await routeProvisioningApi(createRequest("create-1", { title: "Changed" }), r.env, r.operations); assert.equal(response.status, 409); assert.equal(count(r.db, "wp_codebox_api_sites"), 1) })
@@ -51,7 +79,7 @@ test("cross-principal and site-restricted reads and imports fail closed", async
 test("not-ready import is rejected and ready exact replay converges with an API link", async () => { const r = runtime(); const body = await (await create(r)).json() as { site: { id: string; operation: string } }; const url = `https://control.invalid/v1/sites/${body.site.id}/imports`; const importBody = { schema: STATIC_ARTIFACT_IMPORT_REQUEST_SCHEMA, idempotencyKey: "import-1", artifact: { r2Key: `sites/${body.site.id}/import-artifacts/${digest}.json`, sha256: digest, size: artifact.byteLength }, import: { slug: "import", name: "Import", siteTitle: "Import" } }; const pending = await routeProvisioningApi(new Request(url, { method: "POST", headers: { authorization: "Bearer good", "idempotency-key": "import-1" }, body: JSON.stringify(importBody) }), r.env, r.operations); assert.equal(pending.status, 409); r.db.sqlite.prepare("UPDATE wp_codebox_operations SET state = 'succeeded' WHERE site_id = ?").run(body.site.id); const one = await routeProvisioningApi(new Request(url, { method: "POST", headers: { authorization: "Bearer good", "idempotency-key": "import-1" }, body: JSON.stringify(importBody) }), r.env, r.operations); const two = await routeProvisioningApi(new Request(url, { method: "POST", headers: { authorization: "Bearer good", "idempotency-key": "import-1" }, body: JSON.stringify(importBody) }), r.env, r.operations); assert.deepEqual(await one.json(), await two.json()); assert.equal(count(r.db, "wp_codebox_api_operation_links"), 2) })
 test("unlinked same-site legacy operations return 404", async () => { const r = runtime(); const body = await (await create(r)).json() as { site: { id: string } }; r.db.sqlite.prepare("UPDATE wp_codebox_operations SET state = 'succeeded' WHERE site_id = ?").run(body.site.id); const legacy = await r.operations.createOrConverge({ id: body.site.id, hostname: `${body.site.id}.example`, origin: `https://${body.site.id}.example` }, { idempotencyKey: "legacy", fingerprint: "legacy", artifact: { r2Key: "legacy", sha256: digest, size: artifact.byteLength }, options: { slug: "legacy", name: "Legacy", siteTitle: "Legacy" } }); const response = await routeProvisioningApi(new Request(`https://control.invalid/v1/sites/${body.site.id}/operations/${legacy.operation.operationId}`, { headers: { authorization: "Bearer good" } }), r.env, r.operations); assert.equal(response.status, 404) })
 test("operation resources expose retry, error, and receipt without ownership tokens", async () => { const r = runtime(); const body = await (await create(r)).json() as { site: { id: string; operation: string } }; const id = body.site.operation.split("/").at(-1)!; r.db.sqlite.prepare("UPDATE wp_codebox_operations SET state='retryable', retry_at=1, error_code='x', error_message='y' WHERE site_id=? AND operation_id=?").run(body.site.id, id); const value = await (await routeProvisioningApi(new Request(`https://control.invalid/v1/sites/${body.site.id}/operations/${id}`, { headers: { authorization: "Bearer good" } }), r.env, r.operations)).text(); assert.match(value, /retryAt/); assert.match(value, /"error"/); assert.doesNotMatch(value, /claimToken|principal/) })
-test("route, method, Allow, and /v1 precedence behavior is explicit", async () => { const r = runtime(); assert.equal((await routeProvisioningApi(new Request("https://x.invalid/v1/wordpress"), r.env, r.operations)).status, 404); const response = await routeProvisioningApi(new Request("https://x.invalid/v1/sites", { method: "GET" }), r.env, r.operations); assert.equal(response.status, 405); assert.equal(response.headers.get("allow"), "POST"); const claim = await routeProvisioningApi(new Request("https://x.invalid/v1/sites/alpha/administrator-claim", { method: "GET" }), r.env, r.operations); assert.equal(claim.status, 405); assert.equal(claim.headers.get("allow"), "POST"); assert.equal((await routeProvisioningApi(new Request("https://x.invalid/not-v1"), r.env, r.operations)).status, 404) })
+test("route, method, Allow, and /v1 precedence behavior is explicit", async () => { const r = runtime(); assert.equal((await routeProvisioningApi(new Request("https://x.invalid/v1/wordpress"), r.env, r.operations)).status, 404); const response = await routeProvisioningApi(new Request("https://x.invalid/v1/sites", { method: "GET" }), r.env, r.operations); assert.equal(response.status, 405); assert.equal(response.headers.get("allow"), "POST"); const artifactMethod = await routeProvisioningApi(new Request(`https://x.invalid/v1/artifacts/${digest}`, { method: "POST" }), r.env, r.operations); assert.equal(artifactMethod.status, 405); assert.equal(artifactMethod.headers.get("allow"), "PUT"); const claim = await routeProvisioningApi(new Request("https://x.invalid/v1/sites/alpha/administrator-claim", { method: "GET" }), r.env, r.operations); assert.equal(claim.status, 405); assert.equal(claim.headers.get("allow"), "POST"); assert.equal((await routeProvisioningApi(new Request("https://x.invalid/not-v1"), r.env, r.operations)).status, 404) })
 test("administrator claims validate roots before allocation and persist only a digest", async () => {
   for (const key of ["WORDPRESS_ADMIN_CLAIM_SECRET", "WORDPRESS_ADMIN_PASSWORD"] as const) { const r = runtime(); delete r.env[key]; assert.equal((await create(r)).status, 503); assert.equal(count(r.db, "wp_codebox_api_sites"), 0) }
   const r = runtime(); const body = await (await create(r)).json() as { site: { administratorClaim: { token: string } } }; assert.match(body.site.administratorClaim.token, /^[a-f0-9]{64}$/)