@rubytech/create-maxy-code 0.1.458 → 0.1.460

package/payload/platform/plugins/cloudflare/skills/data-portal/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: data-portal
+description: Stand up a per-account gated file-drop portal on its own custom domain, where named people each sign in with their own passcode and can upload, list, download and delete only their own files. Files land in one R2 bucket under a per-person prefix and every upload writes a D1 manifest row the agent later ingests. Use when an account needs somewhere for named people to drop photos, invoices or spreadsheets — "set up a file drop for <client>", "somewhere for <person> to send us their invoices", "a place clients can upload documents".
+---
+
+# Data portal
+
+Assemble and deploy one account's file-drop portal. This is an outcome contract, not a copy of the
+Pages mechanics. The deploy, custom-domain attach, token discipline, and live done-gate are owned by
+`site-deploy`; the R2 store rules are owned by `references/r2-object-storage.md`. Read those
+references with `plugin-read` before issuing their commands.
+
+## What this skill produces, and what it does not
+
+It produces a Pages project on a custom domain, an R2 bucket holding one prefix per enrolled person,
+and a D1 database holding the manifest, the enrolment records, and the sessions. It does not ingest
+the dropped files: a separate device-side sweep reads un-ingested manifest rows and pulls them into
+the graph. This skill delivers the manifest that sweep consumes.
+
+## Why the portal is on Pages and not the install
+
+Uploads must keep succeeding while the device is offline, which is the same reason the booking page
+went to Pages. The install's magic-link gate cannot be reused: it gates `/api/chat` on the install
+and its sessions live in memory, so it does not cross origins.
+
+## Provisioning is two sessions, and the order matters
+
+The storage broker registers a bucket to **whoever creates it**, and that ownership is set on create
+and never reassigned. There is no delegation.
+
+1. **In the client account's own session**, create the bucket with `storage-r2-bucket-create`, named
+   from `bin/cf-store-name.sh <accountId> <purpose>`. It registers to that account.
+2. **In the admin session**, do everything else: the D1 database, the assembly, and the deploy.
+
+If the admin creates the bucket instead, it registers to the house, and the client account's own
+ingestion sweep is denied `cross-account` against its own files — permanently, because ownership is
+never reassigned. The portal would appear to work while nothing on the client side could read what
+it stored.
+
+## Enrol the people first
+
+Collect from the operator the portal's custom domain and the list of people, then write
+`<accountDir>/data-portal.json` carrying `portalDomain`, `portalDbName`, `bucketName`, and a
+`people` array of `{ name, ownerId, prefix }`.
+
+For each person, generate a high-entropy passcode, print it to the operator **once**, and insert the
+person into D1 with only a PBKDF2 salt and hash. **A passcode is never stored in plaintext** — not
+in `data-portal.json`, not in a log line, nowhere on the device. The operator conveys it to the
+person out of band. Rotating a passcode is a re-run of this step for that person; there is no
+separate editor.
+
+Rotation also revokes: a session records a digest of the person's passcode hash at sign-in, and the
+session lookup requires it to still match, so re-running enrolment kills every live session for that
+person immediately. There is no cleanup step to remember and no window to wait out — which is the
+point, because a leaked passcode is exactly the case where a procedure you have to remember fails.
+Deleting the person's row revokes their sessions the same way.
+
+The `ownerId` must match `[a-z0-9-]+`. This is not cosmetic: the whole isolation rule is that a key
+starts with `<ownerId>/`, so an `ownerId` containing a separator would let one person read another's
+files. The gate enforces it too, but do not enrol a name it will reject.
+
+## Assemble the canonical tree
+
+Copy `template/` to `<accountDir>/pages/<project>/` and fill `wrangler.toml`'s `__PROJECT_NAME__`,
+`__D1_DATABASE_NAME__`, `__D1_DATABASE_ID__`, and `__R2_BUCKET_NAME__`. **Leave no `__...__`
+placeholder in the assembled tree.**
+
+Name the D1 database with the same `bin/cf-store-name.sh` scheme as the bucket, and apply
+`schema.sql` to the remote database. It is `IF NOT EXISTS` throughout, so re-applying is safe.
+
+## Deploy through site-deploy
+
+Hand the assembled tree to `cloudflare:site-deploy`. Both bindings — D1 and R2 — are declarative
+config in `wrangler.toml`, carried in the deploy payload under the Pages scope; the deploy needs no
+R2 token. Only the bucket *creation* in step 1 needs R2 write, and the broker holds that.
+
+## The portal needs a paid Cloudflare plan
+
+Check this before promising a date. Signing in costs one PBKDF2 derivation at the OWASP floor of
+600,000 iterations, measured at roughly 250ms of CPU. Workers Free allows **10ms of CPU per
+request**, so on a free plan authentication cannot succeed — and no OWASP-compliant setting fits
+either, since even 100,000 iterations costs about 40ms. Paid plans allow far more and are fine.
+
+The cost is tunable without a migration if it ever needs to be: `iterations` is stored per person
+row, so it is the enrolment-time value that binds, not a constant baked into the deployed code.
+
+## Done-gate
+
+The portal is not done until all five hold on the live domain:
+
+1. A cache-busted request to the portal domain returns `HTTP/2 200`.
+2. Signing in with the right passcode returns `200` **within the CPU budget** rather than timing
+   out — this is the check that catches a free-plan deployment, and it fails nowhere else.
+3. A wrong passcode returns `401`; the **sixth** rapid wrong passcode returns `429` (five are
+   allowed per fifteen minutes, per person, per IP).
+4. An upload as one person returns `200`, and the object is present in R2 under that person's
+   prefix with exactly one manifest row at `ingested=0`. Re-uploading the same filename also
+   returns `200`, replaces the object, and leaves exactly one row, now back at `ingested=0`.
+5. That person's browser cannot list, download, or delete another person's file.
+
+A `502` on `/api/upload` with `op=r2-put result=failed` on every attempt is the expected signature of
+an R2 binding that did not deploy — check `wrangler.toml` reached the tree with its placeholder
+filled. An auth request that hangs or 500s while everything else works is the free-plan signature
+above, not a code fault.
+
+Uploads are capped at 25 MiB and a larger one returns `413` with `result=too-large`.
+
+## Observability
+
+Every step of an upload emits one `[data-portal]` line correlated by `uploadId`, ending in
+`op=complete` with `objectPresent` and `rowPresent` **re-read** rather than assumed. Passcodes,
+hashes, and object bodies are never logged.
+
+Read one upload's full lifeline by filtering the brand journal on its `uploadId`.
+
+The standing audit that would reconcile R2 objects against manifest rows is not built yet. Until it
+is, an object with no manifest row and a row with no object are both invisible: neither emits an
+event at request time.
+
+## Tool discipline
+
+Never write a token into the tree, never commit one, never echo one. The bucket name and database
+name come from `bin/cf-store-name.sh`, never hand-built.

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/authorize.ts

@@ -0,0 +1,32 @@
+// The isolation rule.
+//
+// Every file op authorizes owner-vs-key here BEFORE any R2 call. The
+// per-person key prefix is a consequence of this check, never the check
+// itself: a caller could otherwise reach another person's files by naming
+// them, and prefix convention alone would not stop it.
+
+const SEP = '/'
+
+// The whole gate rests on an ownerId that cannot contain the separator. If two
+// people were ever enrolled as 'alice' and 'alice/2024', then
+// 'alice/2024/invoice.pdf' starts with 'alice/' and alice would read the other
+// person's files. Enrolment is an agent writing rows, so this invariant cannot
+// live only in the skill's prose — it is enforced here, where the decision is
+// actually made, and it fails closed.
+const OWNER_ID = /^[a-z0-9-]+$/
+
+export function ownerPrefix(ownerId: string): string {
+  return `${ownerId}${SEP}`
+}
+
+export function authorizeKey(ownerId: string, key: string): boolean {
+  if (!ownerId || !key) return false
+  if (!OWNER_ID.test(ownerId)) return false
+  // Reject traversal and absolute forms outright rather than normalising them:
+  // a normaliser is one more thing that can be wrong, and no legitimate key
+  // contains these.
+  if (key.includes('..') || key.startsWith(SEP)) return false
+  // startsWith(ownerId) alone would authorize 'alice-evil/...' for 'alice'.
+  // The separator is part of the rule.
+  return key.startsWith(ownerPrefix(ownerId))
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/log.ts

@@ -0,0 +1,12 @@
+// The log grammar is `[tag] op=<verb> key=value …`, space-separated. Any field
+// carrying free text has to be quoted, because the values here are not ours:
+// `ownerId` is unvalidated JSON off the wire at auth time, and `filename` comes
+// straight from a multipart part name. Unquoted, a newline forges whole log
+// lines and an embedded `result=ok` corrupts the line's parse — in a portal
+// where the lifeline IS the diagnostic contract, and whose deferred reconcile
+// audit is specified to read these lines back.
+
+/** Render a free-text value as a quoted, single-line log field. */
+export function q(value: string): string {
+  return `"${value.replace(/[\\"]/g, '\\$&').replace(/[\r\n\t]/g, ' ')}"`
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/passcode.ts

@@ -0,0 +1,73 @@
+// Passcode hashing for the data portal. PBKDF2-SHA256 via Web Crypto, which
+// exists identically in the Workers runtime and in Node's webcrypto, so these
+// functions are tested against real crypto rather than a fake.
+//
+// constantTimeEqual is hand-rolled deliberately: crypto.subtle.timingSafeEqual
+// is a Cloudflare extension with no Node equivalent, so depending on it would
+// make the comparison untestable here.
+
+export const PBKDF2_ITERATIONS = 600_000
+
+export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  // Length is not secret; an early return on it leaks nothing a caller cannot
+  // already see. The byte loop below never short-circuits.
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i]
+  return diff === 0
+}
+
+export function randomSaltHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+// Returns Uint8Array<ArrayBuffer>, not the bare Uint8Array: the bare form
+// widens to ArrayBufferLike, which Web Crypto will not accept as a BufferSource
+// because a SharedArrayBuffer could back it.
+function hexToBytes(hex: string): Uint8Array<ArrayBuffer> | null {
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(hex)) return null
+  const out = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return out
+}
+
+export async function hashPasscode(
+  passcode: string,
+  saltHex: string,
+  iterations: number,
+): Promise<string> {
+  const salt = hexToBytes(saltHex)
+  if (!salt) throw new Error('salt must be hex')
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(passcode),
+    'PBKDF2',
+    false,
+    ['deriveBits'],
+  )
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt, iterations, hash: 'SHA-256' },
+    key,
+    256,
+  )
+  return randomSaltHex(new Uint8Array(bits))
+}
+
+export async function verifyPasscode(
+  passcode: string,
+  saltHex: string,
+  expectedHashHex: string,
+  iterations: number,
+): Promise<boolean> {
+  const expected = hexToBytes(expectedHashHex)
+  if (!expected) return false
+  let actualHex: string
+  try {
+    actualHex = await hashPasscode(passcode, saltHex, iterations)
+  } catch {
+    return false
+  }
+  const actual = hexToBytes(actualHex)
+  if (!actual) return false
+  return constantTimeEqual(actual, expected)
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/ratelimit.ts

@@ -0,0 +1,55 @@
+import type { D1Database } from './types'
+
+// Fixed-window attempt counter in D1.
+//
+// Every rate limiter elsewhere in this platform is an in-memory Map in a
+// long-lived Node process (ui/server/routes/client-error.ts). None of that
+// ports here: Pages Functions are stateless and spread across edge locations,
+// so the counter must live in storage the whole edge shares.
+//
+// D1 has no atomic increment, so two concurrent requests can read the same
+// count and both be allowed. This is a speed bump against passcode guessing,
+// not a hard limit, and the docs say so rather than implying a guarantee.
+
+export const RATE_WINDOW_MS = 900_000 // 15 minutes
+export const RATE_MAX_ATTEMPTS = 5
+
+/** The counter's key. The client IP is part of it, not decoration: keyed on the
+ *  owner alone, the limiter is a weapon rather than a shield — six
+ *  unauthenticated requests naming a person lock that person out of their own
+ *  portal for the window, from anywhere, repeatably. Keyed on owner+IP, an
+ *  attacker throttles only themselves. The cost is that a distributed guesser
+ *  gets RATE_MAX_ATTEMPTS per address, which the passcodes' entropy carries. */
+export function rateScope(ownerId: string, clientIp: string): string {
+  return `${ownerId}|${clientIp}`
+}
+
+/** Clear a scope's counter. Called on a successful sign-in, so a person doing
+ *  ordinary work does not lock themselves out. */
+export async function clearAttempts(db: D1Database, scope: string): Promise<void> {
+  await db.prepare('DELETE FROM auth_attempts WHERE scope = ?').bind(scope).run()
+}
+
+export async function checkAndRecordAttempt(
+  db: D1Database,
+  scope: string,
+  nowMs: number,
+): Promise<{ allowed: boolean; count: number }> {
+  const windowStart = Math.floor(nowMs / RATE_WINDOW_MS) * RATE_WINDOW_MS
+
+  await db
+    .prepare(
+      `INSERT INTO auth_attempts (scope, windowStart, count) VALUES (?, ?, 1)
+         ON CONFLICT (scope, windowStart) DO UPDATE SET count = count + 1`,
+    )
+    .bind(scope, windowStart)
+    .run()
+
+  const row = await db
+    .prepare('SELECT count FROM auth_attempts WHERE scope = ? AND windowStart = ?')
+    .bind(scope, windowStart)
+    .first<{ count: number }>()
+
+  const count = typeof row?.count === 'number' ? row.count : 1
+  return { allowed: count <= RATE_MAX_ATTEMPTS, count }
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/session.ts

@@ -0,0 +1,85 @@
+import type { D1Database } from './types'
+
+// Server-side sessions in D1 rather than a signed stateless token: a signed
+// token needs a signing secret provisioned into the Pages env, a secret
+// lifecycle this plugin does not have. D1 needs no secret and is revocable.
+// The cost is one D1 read per request.
+//
+// "Revocable" is a claim this module has to actually honour, so revocation is
+// structural rather than procedural. Each session records `pcCheck`, a short
+// digest of the person's passcode hash at mint time, and resolveSession joins
+// `people` and requires it to still match. Rotating a passcode necessarily
+// changes the hash, so every session minted against the old one stops
+// resolving with no cleanup step to remember and no window to wait out.
+// Unenrolling a person kills their sessions by the same join.
+
+export const SESSION_TTL_MS = 43_200_000 // 12 hours
+
+// The __Host- prefix is the only thing a browser enforces against a cookie set
+// on a sibling subdomain with Domain=.example.com shadowing this one — which
+// would let an attacker fix a victim's session and receive their uploads. It
+// requires Secure, Path=/, and no Domain; the Set-Cookie in auth.ts meets all
+// three.
+export const SESSION_COOKIE = '__Host-__portal_session'
+
+/** The stored session-vs-passcode check. A prefix of an already-irreversible
+ *  hash, kept next to it in the same database — it exposes nothing new. */
+export function passcodeCheck(hash: string): string {
+  return hash.slice(0, 16)
+}
+
+export async function mintSession(
+  db: D1Database,
+  ownerId: string,
+  sessionId: string,
+  nowMs: number,
+  pcCheck: string,
+): Promise<string> {
+  await db
+    .prepare(
+      'INSERT INTO sessions (sessionId, ownerId, pcCheck, expiresAt, createdAt) VALUES (?, ?, ?, ?, ?)',
+    )
+    .bind(sessionId, ownerId, pcCheck, nowMs + SESSION_TTL_MS, new Date(nowMs).toISOString())
+    .run()
+  // Opportunistic GC: expired rows are dead weight and nothing else prunes
+  // them. Scoped to this owner so it stays a small, indexed delete.
+  await db
+    .prepare('DELETE FROM sessions WHERE ownerId = ? AND expiresAt <= ?')
+    .bind(ownerId, nowMs)
+    .run()
+  return sessionId
+}
+
+export async function resolveSession(
+  db: D1Database,
+  sessionId: string,
+  nowMs: number,
+): Promise<{ ownerId: string } | null> {
+  if (!sessionId) return null
+  const row = await db
+    .prepare(
+      `SELECT s.ownerId AS ownerId
+         FROM sessions s
+         JOIN people p ON p.ownerId = s.ownerId
+        WHERE s.sessionId = ?
+          AND s.expiresAt > ?
+          AND s.pcCheck = substr(p.hash, 1, 16)`,
+    )
+    .bind(sessionId, nowMs)
+    .first<{ ownerId: string }>()
+  return row && typeof row.ownerId === 'string' ? { ownerId: row.ownerId } : null
+}
+
+export function readSessionCookie(header: string | null): string | null {
+  if (!header) return null
+  for (const part of header.split(';')) {
+    const [name, ...rest] = part.trim().split('=')
+    if (name !== SESSION_COOKIE) continue
+    const value = rest.join('=')
+    // Keep scanning rather than returning on the first match: a planted
+    // valueless duplicate sorted first would otherwise blank the real session,
+    // which is a persistent logout denial-of-service.
+    if (value) return value
+  }
+  return null
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/types.ts

@@ -0,0 +1,44 @@
+// Structural interfaces for the Pages runtime bindings this portal uses.
+// Declared here rather than imported from @cloudflare/workers-types (not a
+// dependency in this repo) so every function below is testable with a
+// hand-rolled fake — the choice book.ts:12-24 already makes.
+
+export interface D1Result<T = Record<string, unknown>> {
+  results?: T[]
+  meta?: { changes?: number }
+}
+
+export interface D1PreparedStatement {
+  bind: (...values: unknown[]) => D1PreparedStatement
+  run: () => Promise<D1Result>
+  all: <T = Record<string, unknown>>() => Promise<D1Result<T>>
+  first: <T = Record<string, unknown>>() => Promise<T | null>
+}
+
+export interface D1Database {
+  prepare: (query: string) => D1PreparedStatement
+}
+
+export interface R2ObjectBody {
+  body: ReadableStream | null
+  size: number
+}
+
+export interface R2Bucket {
+  put: (key: string, value: ArrayBuffer | Uint8Array) => Promise<unknown>
+  get: (key: string) => Promise<R2ObjectBody | null>
+  delete: (key: string) => Promise<void>
+  head: (key: string) => Promise<{ size: number } | null>
+}
+
+export interface PortalEnv {
+  DB: D1Database
+  BUCKET: R2Bucket
+}
+
+export type Logger = (line: string) => void
+
+export interface Handler {
+  status: number
+  payload: Record<string, unknown>
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/auth.ts

@@ -0,0 +1,113 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { PBKDF2_ITERATIONS, verifyPasscode } from './_lib/passcode'
+import { checkAndRecordAttempt, clearAttempts, rateScope } from './_lib/ratelimit'
+import { SESSION_COOKIE, SESSION_TTL_MS, mintSession, passcodeCheck } from './_lib/session'
+import { q } from './_lib/log'
+
+export interface AuthBody {
+  ownerId?: unknown
+  passcode?: unknown
+}
+
+interface AuthResult extends Handler {
+  sessionId?: string
+}
+
+// Same denial payload for a wrong passcode and an unknown owner: distinguishing
+// them would enumerate who is enrolled.
+const DENIED: Handler = { status: 401, payload: { ok: false, error: 'denied' } }
+
+// A real-shaped salt and hash used only to burn the same PBKDF2 cost when the
+// owner does not exist. Without it, an unknown owner returns after one D1 read
+// (single-digit ms) while a known one spends ~250ms deriving — a timing oracle
+// three orders of magnitude wide, which enumerates the enrolled people outright
+// and makes the identical DENIED payload above cosmetic.
+const DUMMY_SALT = '00000000000000000000000000000000'
+const DUMMY_HASH = '0'.repeat(64)
+
+export async function processAuth(
+  body: AuthBody,
+  env: PortalEnv,
+  log: Logger,
+  newId: () => string,
+  nowMs: number,
+  clientIp: string,
+): Promise<AuthResult> {
+  const ownerId = typeof body?.ownerId === 'string' ? body.ownerId : ''
+  const passcode = typeof body?.passcode === 'string' ? body.passcode : ''
+  if (!ownerId || !passcode) {
+    log('[data-portal] op=auth owner=none result=malformed')
+    return { status: 400, payload: { ok: false, error: 'ownerId and passcode required' } }
+  }
+
+  // Rate-limit BEFORE any passcode comparison, so a guessing loop is throttled
+  // rather than merely logged. The scope carries the client IP as well as the
+  // owner: keyed on the owner alone, the counter is a weapon — six requests
+  // naming a person lock that person out of their own portal for the window,
+  // from anywhere, unauthenticated.
+  const scope = rateScope(ownerId, clientIp)
+  const rate = await checkAndRecordAttempt(env.DB, scope, nowMs)
+  if (!rate.allowed) {
+    log(`[data-portal] op=auth owner=${q(ownerId)} result=rate-limited attempts=${rate.count}`)
+    return { status: 429, payload: { ok: false, error: 'too many attempts' } }
+  }
+
+  const person = await env.DB.prepare(
+    'SELECT ownerId, salt, hash, iterations FROM people WHERE ownerId = ?',
+  )
+    .bind(ownerId)
+    .first<{ ownerId: string; salt: string; hash: string; iterations: number }>()
+
+  if (!person) {
+    // Burn the same work an enrolled owner would cost, then deny identically.
+    await verifyPasscode(passcode, DUMMY_SALT, DUMMY_HASH, PBKDF2_ITERATIONS)
+    log(`[data-portal] op=auth owner=${q(ownerId)} result=denied reason=no-such-owner`)
+    return DENIED
+  }
+
+  const ok = await verifyPasscode(passcode, person.salt, person.hash, person.iterations)
+  if (!ok) {
+    log(`[data-portal] op=auth owner=${q(ownerId)} result=denied reason=bad-passcode`)
+    return DENIED
+  }
+
+  // A successful sign-in clears the counter. Without this, six legitimate
+  // sign-ins inside one window lock the person out of their own files.
+  await clearAttempts(env.DB, scope)
+
+  const sessionId = newId()
+  await mintSession(env.DB, ownerId, sessionId, nowMs, passcodeCheck(person.hash))
+  log(`[data-portal] op=auth owner=${q(ownerId)} result=ok`)
+  return { status: 200, payload: { ok: true }, sessionId }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestPost(context: PagesContext): Promise<Response> {
+  let body: AuthBody
+  try {
+    body = (await context.request.json()) as AuthBody
+  } catch {
+    return Response.json({ ok: false, error: 'invalid JSON' }, { status: 400 })
+  }
+  const { status, payload, sessionId } = await processAuth(
+    body,
+    context.env,
+    (line) => console.log(line),
+    () => crypto.randomUUID(),
+    Date.now(),
+    context.request.headers.get('cf-connecting-ip') ?? 'unknown',
+  )
+  const res = Response.json(payload, { status })
+  if (sessionId) {
+    // Secure + Path=/ + no Domain are the __Host- prefix's preconditions.
+    res.headers.append(
+      'Set-Cookie',
+      `${SESSION_COOKIE}=${sessionId}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${SESSION_TTL_MS / 1000}`,
+    )
+  }
+  return res
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/delete.ts

@@ -0,0 +1,89 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+import { authorizeKey } from './_lib/authorize'
+
+export async function processDelete(
+  sessionId: string,
+  key: string,
+  env: PortalEnv,
+  log: Logger,
+  now: () => number,
+): Promise<Handler> {
+  const startedMs = now()
+  const session = await resolveSession(env.DB, sessionId, startedMs)
+  if (!session) {
+    log('[data-portal] op=delete owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+  if (!authorizeKey(session.ownerId, key)) {
+    log(`[data-portal] op=delete owner=${q(session.ownerId)} result=denied reason=not-owner`)
+    return { status: 403, payload: { ok: false, error: 'denied' } }
+  }
+  const owner = q(session.ownerId)
+
+  // Both writes are wrapped and each emits its own line, mirroring upload's
+  // steps 3-5. Unwrapped, a throw here escapes the handler, Pages returns a
+  // bare 500, and NOTHING is logged — and if the R2 delete succeeded before the
+  // D1 delete threw, that silently manufactures a phantom row, which is exactly
+  // the failure class the deferred reconcile audit exists to catch. The
+  // lifeline that should have caught it must not be the thing that goes quiet.
+  try {
+    await env.BUCKET.delete(key)
+    log(`[data-portal] op=r2-delete owner=${owner} key=${q(key)} result=ok`)
+  } catch (err) {
+    log(
+      `[data-portal] op=r2-delete owner=${owner} key=${q(key)} result=failed err="${(err as Error).message}"`,
+    )
+    return { status: 502, payload: { ok: false, error: 'delete failed' } }
+  }
+
+  try {
+    await env.DB.prepare('DELETE FROM manifest WHERE objectKey = ?').bind(key).run()
+    log(`[data-portal] op=manifest-delete owner=${owner} key=${q(key)} result=ok`)
+  } catch (err) {
+    log(
+      `[data-portal] op=manifest-delete owner=${owner} key=${q(key)} result=failed err="${(err as Error).message}"`,
+    )
+    return { status: 502, payload: { ok: false, error: 'manifest delete failed' } }
+  }
+
+  // The verified post-condition: both sides re-read, not "we called delete".
+  const objectPresent = (await env.BUCKET.head(key)) !== null
+  const rowPresent =
+    (await env.DB.prepare('SELECT fileId FROM manifest WHERE objectKey = ?').bind(key).first()) !==
+    null
+  // Derived, never hardcoded: a failed delete printing result=ok next to
+  // objectPresent=true is a self-contradicting line.
+  const result = !objectPresent && !rowPresent ? 'ok' : 'incomplete'
+  log(
+    `[data-portal] op=complete owner=${owner} key=${q(key)} op2=delete ms=${now() - startedMs} result=${result} objectPresent=${objectPresent} rowPresent=${rowPresent}`,
+  )
+  return {
+    status: result === 'ok' ? 200 : 500,
+    payload: { ok: result === 'ok', objectPresent, rowPresent },
+  }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestPost(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  let key = ''
+  try {
+    key = String(((await context.request.json()) as { key?: unknown }).key ?? '')
+  } catch {
+    return Response.json({ ok: false, error: 'invalid JSON' }, { status: 400 })
+  }
+  const { status, payload } = await processDelete(
+    sessionId,
+    key,
+    context.env,
+    (line) => console.log(line),
+    () => Date.now(),
+  )
+  return Response.json(payload, { status })
+}