@rubytech/create-maxy-code 0.1.459 → 0.1.461

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

@@ -0,0 +1,193 @@
+// Passcode generation, strength and hashing for the data portal.
+//
+// This module is JavaScript, not TypeScript, and that is deliberate: it has two
+// consumers on two runtimes. The Worker imports it (wrangler bundles JS), and
+// enrolment imports it from bare node on-device, which cannot load .ts. A second
+// copy of the hash for the enrolment side would drift, and the failure mode of
+// drift is that enrolment writes hashes the Worker rejects. JSDoc plus
+// `typecheck:templates --checkJs` keeps the type cover 1689 added.
+//
+// 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.
+
+/** Crockford base32: digits and letters minus I, L, O and U, which are the ones
+ * misread when the operator conveys a passcode to a person out of band. 32
+ * symbols is exactly 5 bits, and 256 divides by 32, so a masked random byte is
+ * an unbiased draw with no rejection sampling.
+ *
+ * How much of Crockford this portal takes, stated so nobody has to infer it
+ * from behaviour again (Task 1713):
+ *
+ *   ADOPTED  — the excluded letters, above, and case-insensitivity on decode.
+ *              The alphabet is uppercase and so is everything stored;
+ *              verifyPasscode uppercases what it is given, so a person may type
+ *              either case. That is the one normalisation point.
+ *   DECLINED — the letter-to-digit decode (I and L to 1, O to 0), check
+ *              symbols, and hyphen tolerance. None are implemented.
+ *
+ * So "Crockford" here means this alphabet plus the case rule, and nothing
+ * further. 1708 shipped the first half without the second, which is the gap
+ * 1713 closed; a future reader adding the rest should treat it as a new
+ * decision, not as finishing this one.
+ */
+export const PASSCODE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+/** 26 x 5 bits = 130, which clears the 128-bit floor this portal's security
+ * rests on. Changing this constant changes that guarantee: see the note at
+ * hashPasscode before touching it. */
+export const PASSCODE_LENGTH = 26
+
+/** What PASSCODE_LENGTH and PASSCODE_ALPHABET buy, stated once so a test can
+ * pin it rather than a comment asserting it. */
+export const PASSCODE_ENTROPY_BITS = PASSCODE_LENGTH * 5
+
+/** Enrolment refused a passcode below the pinned strength. Named rather than a
+ * bare Error so a caller can tell a weak passcode from a broken salt. */
+export class PasscodeTooWeakError extends Error {
+  /** @param {string} detail */
+  constructor(detail) {
+    super(`passcode too weak: ${detail}`)
+    this.name = 'PasscodeTooWeakError'
+    /** @type {'passcode-too-weak'} */
+    this.reason = 'passcode-too-weak'
+  }
+}
+
+/** Mint a passcode. This is the ONLY source of passcode entropy in the portal —
+ * assertPasscodeStrength below cannot supply it, only check the shape.
+ * @returns {string} */
+export function generatePasscode() {
+  const bytes = new Uint8Array(PASSCODE_LENGTH)
+  crypto.getRandomValues(bytes)
+  let out = ''
+  // & 31 is unbiased here precisely because the alphabet is 32 long.
+  for (const b of bytes) out += PASSCODE_ALPHABET[b & 31]
+  return out
+}
+
+/** Refuse a passcode that is not the pinned length drawn from the pinned
+ * alphabet.
+ *
+ * This is a STRUCTURAL check and nothing more. It cannot measure entropy: a
+ * 26-character run of 'A' passes it. Do not describe it as enforcing
+ * PASSCODE_ENTROPY_BITS — an arbitrary string's entropy is not a computable
+ * property of the string. What it does buy is the case that motivated it: an
+ * enrolling agent satisfying "high-entropy passcode" with a six-digit number
+ * can no longer store one. Entropy itself comes from generatePasscode.
+ * @param {string} passcode
+ * @returns {void} */
+export function assertPasscodeStrength(passcode) {
+  if (typeof passcode !== 'string' || passcode.length !== PASSCODE_LENGTH) {
+    throw new PasscodeTooWeakError(`expected ${PASSCODE_LENGTH} characters`)
+  }
+  for (const c of passcode) {
+    if (!PASSCODE_ALPHABET.includes(c)) {
+      throw new PasscodeTooWeakError('character outside the pinned alphabet')
+    }
+  }
+}
+
+/** @param {Uint8Array} bytes @returns {string} */
+export function randomSaltHex(bytes) {
+  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.
+ * @param {string} hex
+ * @returns {Uint8Array<ArrayBuffer> | null} */
+function hexToBytes(hex) {
+  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
+}
+
+/** Hash a passcode for storage: one SHA-256 over salt || passcode.
+ *
+ * ONE fast hash, no key stretching, and that is safe ONLY because passcodes are
+ * machine-generated by generatePasscode at PASSCODE_LENGTH. Stretching exists to
+ * make guessing a HUMAN-CHOSEN password expensive; 130 random bits are
+ * unguessable however fast the hash is, which is why nobody stretches a
+ * magic-link token either.
+ *
+ * So: if anyone ever lets an operator choose a memorable passcode, key
+ * stretching must come back in the SAME change. The danger here is not the fast
+ * hash. It is a later relaxation of generated-only while the fast hash stays.
+ *
+ * The salt earns its keep even without stretching: two people holding the same
+ * passcode still get different stored hashes, and no precomputed table over the
+ * alphabet is reusable across rows.
+ * @param {string} passcode
+ * @param {string} saltHex
+ * @returns {Promise<string>} */
+export async function hashPasscode(passcode, saltHex) {
+  assertPasscodeStrength(passcode)
+  const salt = hexToBytes(saltHex)
+  if (!salt) throw new Error('salt must be hex')
+  const encoded = new TextEncoder().encode(passcode)
+  const message = new Uint8Array(salt.length + encoded.length)
+  message.set(salt, 0)
+  message.set(encoded, salt.length)
+  const digest = await crypto.subtle.digest('SHA-256', message)
+  return randomSaltHex(new Uint8Array(digest))
+}
+
+/** Verify a passcode against a stored salt and hash. Returns false rather than
+ * throwing on any malformed input, including a passcode that would not pass
+ * enrolment: sign-in is not the place to crash over a bad row.
+ * @param {string} passcode
+ * @param {string} saltHex
+ * @param {string} expectedHashHex
+ * @returns {Promise<boolean>} */
+export async function verifyPasscode(passcode, saltHex, expectedHashHex) {
+  const expected = hexToBytes(expectedHashHex)
+  if (!expected) return false
+  /** @type {string} */
+  let actualHex
+  try {
+    // Crockford is case-insensitive on decode, and 1708 chose this alphabet for
+    // the very reason that rule exists: a person transcribes the passcode by
+    // hand. Uppercasing here is the second half of that choice (Task 1713), so
+    // the case someone types stops being something they can get wrong.
+    //
+    // This is the ONE normalisation point. hashPasscode and
+    // assertPasscodeStrength stay strict on the canonical uppercase form, so
+    // what enrolment stores is unchanged and only accepted INPUT widens.
+    //
+    // Inside the try deliberately: a malformed PASSCODE must return false rather
+    // than throw, and .toUpperCase() throws on a non-string. Outside the try,
+    // that would break for exactly the input class it exists to cover.
+    // (Scoped to the passcode on purpose. The docblock above says "any
+    // malformed input", which is not quite true of expectedHashHex — a null one
+    // throws out of hexToBytes before this try is entered. Unreachable today,
+    // since schema.sql pins hash TEXT NOT NULL; tracked in Task 1718 rather
+    // than restated here as though it held.)
+    //
+    // The strength gate therefore applies to the normalised form: verification
+    // accepts any string whose uppercase form is a valid passcode. One
+    // consequence, left unguarded on purpose — 'ß' uppercases to 'SS', so a
+    // 25-character string containing it can normalise onto a 26-character
+    // passcode. Building one requires already knowing the passcode, so it costs
+    // nothing an attacker could spend, and a fourth check to close it would buy
+    // no security.
+    actualHex = await hashPasscode(passcode.toUpperCase(), saltHex)
+  } catch {
+    return false
+  }
+  const actual = hexToBytes(actualHex)
+  if (!actual) return false
+  return constantTimeEqual(actual, expected)
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b @returns {boolean} */
+export function constantTimeEqual(a, b) {
+  // 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
+}

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,119 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { verifyPasscode } from './_lib/passcode.mjs'
+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 hash when the owner
+// does not exist, so the two paths cost the same and the identical DENIED
+// payload above is not merely cosmetic.
+//
+// Task 1708 re-measured this after replacing PBKDF2 with one SHA-256, because
+// the gap it closes shrank by four orders of magnitude and the dummy might have
+// stopped earning its place. It did not. Without it the delta is one hash —
+// measured at 43.8us (dev Mac, off-platform) — and published remote-timing work
+// resolves roughly 15-20us on a LAN and ~100us over the internet, so 43.8us sits
+// inside the demonstrated-resolvable band, and an attacker gets to pick a
+// Cloudflare PoP near the target. Keeping it costs 43.8us against a 10ms CPU
+// budget, which is 0.4% of it. Cheap enough not to think about; measurable
+// enough not to remove.
+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 FROM people WHERE ownerId = ?')
+    .bind(ownerId)
+    .first<{ ownerId: string; salt: string; hash: string }>()
+
+  if (!person) {
+    // Burn the same work an enrolled owner would cost, then deny identically.
+    await verifyPasscode(passcode, DUMMY_SALT, DUMMY_HASH)
+    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)
+  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 })
+}

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

@@ -0,0 +1,70 @@
+import type { Handler, Logger, PortalEnv, R2ObjectBody } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+import { authorizeKey } from './_lib/authorize'
+
+interface DownloadResult extends Handler {
+  body?: R2ObjectBody | null
+}
+
+export async function processDownload(
+  sessionId: string,
+  key: string,
+  env: PortalEnv,
+  log: Logger,
+  nowMs: number,
+): Promise<DownloadResult> {
+  const session = await resolveSession(env.DB, sessionId, nowMs)
+  if (!session) {
+    log('[data-portal] op=download owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+  // Authorize BEFORE any R2 call, so a denied caller cannot cause a fetch.
+  if (!authorizeKey(session.ownerId, key)) {
+    log(`[data-portal] op=download owner=${q(session.ownerId)} result=denied reason=not-owner`)
+    return { status: 403, payload: { ok: false, error: 'denied' } }
+  }
+  const obj = await env.BUCKET.get(key)
+  if (!obj) {
+    log(`[data-portal] op=download owner=${q(session.ownerId)} result=absent`)
+    return { status: 404, payload: { ok: false, error: 'not found' } }
+  }
+  log(`[data-portal] op=download owner=${q(session.ownerId)} result=ok bytes=${obj.size ?? 'na'}`)
+  return { status: 200, payload: { ok: true }, body: obj }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestGet(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  const key = new URL(context.request.url).searchParams.get('key') ?? ''
+  const { status, payload, body } = await processDownload(
+    sessionId,
+    key,
+    context.env,
+    (line) => console.log(line),
+    Date.now(),
+  )
+  if (status === 200 && body) {
+    return new Response(body.body, {
+      status: 200,
+      headers: {
+        // RFC 6266 filename*: percent-encoded, so a name containing a quote
+        // cannot break out of the quoted form, and CR/LF cannot reach the
+        // Headers constructor (which would throw and 500 the download).
+        'content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent(key.split('/').pop() ?? 'file')}`,
+        // `attachment` already stops inline rendering; nosniff is the belt to
+        // that braces, so an uploaded .html can never be sniffed and executed
+        // on the portal's own origin.
+        'x-content-type-options': 'nosniff',
+        // These are private client documents. Without this a browser or an
+        // intermediary proxy may cache one person's invoice.
+        'cache-control': 'private, no-store',
+      },
+    })
+  }
+  return Response.json(payload, { status })
+}