@rubytech/create-maxy-code 0.1.458 → 0.1.460

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 })
+}

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

@@ -0,0 +1,41 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+
+export async function processFiles(
+  sessionId: string,
+  env: PortalEnv,
+  log: Logger,
+  nowMs: number,
+): Promise<Handler> {
+  const session = await resolveSession(env.DB, sessionId, nowMs)
+  if (!session) {
+    log('[data-portal] op=list owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+  // Scoped by ownerId, not by key prefix: the owner is the authority.
+  const rows = await env.DB.prepare(
+    'SELECT fileId, filename, objectKey, size, uploadedAt, ingested FROM manifest WHERE ownerId = ? ORDER BY uploadedAt DESC',
+  )
+    .bind(session.ownerId)
+    .all<Record<string, unknown>>()
+  const files = rows.results ?? []
+  log(`[data-portal] op=list owner=${q(session.ownerId)} result=ok files=${files.length}`)
+  return { status: 200, payload: { ok: true, files } }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestGet(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  const { status, payload } = await processFiles(
+    sessionId,
+    context.env,
+    (line) => console.log(line),
+    Date.now(),
+  )
+  return Response.json(payload, { status })
+}

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

@@ -0,0 +1,151 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+import { authorizeKey, ownerPrefix } from './_lib/authorize'
+
+const MAX_FILENAME = 200
+
+// An upload is read wholly into the Function's memory, so it needs a bound or a
+// large one OOMs the isolate — and an OOM emits no [data-portal] line at all,
+// making it exactly the unobservable failure this portal's lifeline exists to
+// prevent. 25 MiB is chosen for the documents this portal is for (invoices,
+// photos, spreadsheets) and is deliberately NOT the storage broker's 100 MiB
+// (task 1695): that one bounds a house-process spike, this one bounds an edge
+// isolate, and the two must move independently.
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+
+export async function processUpload(
+  sessionId: string,
+  filename: string,
+  bytes: Uint8Array,
+  env: PortalEnv,
+  log: Logger,
+  newId: () => string,
+  now: () => number,
+): Promise<Handler> {
+  // `now` is a clock, not a scalar: op=complete reports elapsed time, and a
+  // single injected instant cannot measure elapsed anything. It previously
+  // printed a hardcoded ms=0, which an operator reads as "took no time" rather
+  // than "was never measured".
+  const startedMs = now()
+  const session = await resolveSession(env.DB, sessionId, startedMs)
+  if (!session) {
+    log('[data-portal] op=upload owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+  const owner = session.ownerId
+  const uploadId = newId()
+
+  if (!filename || filename.length > MAX_FILENAME) {
+    log(`[data-portal] op=request uploadId=${uploadId} owner=${q(owner)} result=bad-filename`)
+    return { status: 400, payload: { ok: false, error: 'filename required' } }
+  }
+
+  const key = `${ownerPrefix(owner)}${filename}`
+  // The key is derived from the session owner, then re-checked through the same
+  // gate the other routes use — a filename carrying '..' must not escape.
+  if (!authorizeKey(owner, key)) {
+    log(`[data-portal] op=request uploadId=${uploadId} owner=${q(owner)} result=bad-filename`)
+    return { status: 400, payload: { ok: false, error: 'invalid filename' } }
+  }
+
+  if (bytes.byteLength > MAX_UPLOAD_BYTES) {
+    log(
+      `[data-portal] op=request uploadId=${uploadId} owner=${q(owner)} filename=${q(filename)} bytes=${bytes.byteLength} result=too-large limit=${MAX_UPLOAD_BYTES}`,
+    )
+    return {
+      status: 413,
+      payload: {
+        ok: false,
+        error: `file is ${bytes.byteLength} bytes, over the ${MAX_UPLOAD_BYTES}-byte limit`,
+      },
+    }
+  }
+
+  log(
+    `[data-portal] op=request uploadId=${uploadId} owner=${q(owner)} filename=${q(filename)} bytes=${bytes.byteLength}`,
+  )
+
+  try {
+    await env.BUCKET.put(key, bytes)
+    log(`[data-portal] op=r2-put uploadId=${uploadId} key=${q(key)} result=ok`)
+  } catch (err) {
+    log(
+      `[data-portal] op=r2-put uploadId=${uploadId} key=${q(key)} result=failed err="${(err as Error).message}"`,
+    )
+    return { status: 502, payload: { ok: false, error: 'store failed' } }
+  }
+
+  const fileId = newId()
+  try {
+    // Upsert, not insert. R2 overwrote the object above unconditionally, so a
+    // re-upload of the same filename has already replaced the file whatever the
+    // manifest does; a plain INSERT would hit `objectKey UNIQUE`, throw, and
+    // leave the row describing bytes that no longer exist while telling the
+    // person their upload failed. Resetting `ingested` is the load-bearing
+    // part: without it a replacement of an already-swept file would never be
+    // ingested, and nothing would ever say so.
+    await env.DB.prepare(
+      `INSERT INTO manifest (fileId, ownerId, filename, objectKey, size, uploadedAt, ingested)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (objectKey) DO UPDATE SET
+           fileId = excluded.fileId,
+           size = excluded.size,
+           uploadedAt = excluded.uploadedAt,
+           ingested = 0`,
+    )
+      .bind(fileId, owner, filename, key, bytes.byteLength, new Date(startedMs).toISOString(), 0)
+      .run()
+    log(`[data-portal] op=manifest-write uploadId=${uploadId} rowId=${fileId} result=ok`)
+  } catch (err) {
+    log(
+      `[data-portal] op=manifest-write uploadId=${uploadId} rowId=${fileId} result=failed err="${(err as Error).message}"`,
+    )
+    return { status: 502, payload: { ok: false, error: 'manifest failed' } }
+  }
+
+  // The verified post-condition: re-read both sides rather than assume the
+  // writes above landed. An orphan object or a phantom row emits no error at
+  // request time, which is why this line exists.
+  const objectPresent = (await env.BUCKET.head(key)) !== null
+  const rowPresent =
+    (await env.DB.prepare('SELECT fileId FROM manifest WHERE objectKey = ?').bind(key).first()) !==
+    null
+  log(
+    `[data-portal] op=complete uploadId=${uploadId} ms=${now() - startedMs} objectPresent=${objectPresent} rowPresent=${rowPresent}`,
+  )
+
+  return { status: 200, payload: { ok: true, fileId, 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 filename = ''
+  let bytes: Uint8Array
+  try {
+    const form = await context.request.formData()
+    const file = form.get('file')
+    if (!(file instanceof File)) {
+      return Response.json({ ok: false, error: 'file required' }, { status: 400 })
+    }
+    filename = file.name
+    bytes = new Uint8Array(await file.arrayBuffer())
+  } catch {
+    return Response.json({ ok: false, error: 'invalid form' }, { status: 400 })
+  }
+  const { status, payload } = await processUpload(
+    sessionId,
+    filename,
+    bytes,
+    context.env,
+    (line) => console.log(line),
+    () => crypto.randomUUID(),
+    () => Date.now(),
+  )
+  return Response.json(payload, { status })
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/public/index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>File drop</title>
+    <!-- Same-origin: the API is served by this project's own Pages Functions,
+         so api-base is deliberately empty (Task 1307's convention). -->
+    <meta name="api-base" content="" />
+    <link rel="stylesheet" href="/portal.css" />
+  </head>
+  <body>
+    <main class="dp-card">
+      <h1 class="dp-title">File drop</h1>
+      <p id="dp-status" class="dp-status" role="status"></p>
+
+      <form id="dp-login" class="dp-login">
+        <label class="dp-label" for="dp-owner">Your name</label>
+        <input class="dp-input" id="dp-owner" name="owner" autocomplete="username" required />
+        <label class="dp-label" for="dp-passcode">Passcode</label>
+        <input
+          class="dp-input"
+          id="dp-passcode"
+          name="passcode"
+          type="password"
+          autocomplete="current-password"
+          required
+        />
+        <button class="dp-btn" type="submit">Sign in</button>
+      </form>
+
+      <section id="dp-panel" class="dp-panel" hidden>
+        <form id="dp-upload" class="dp-upload">
+          <input class="dp-file" id="dp-file" type="file" required />
+          <button class="dp-btn" type="submit">Upload</button>
+        </form>
+        <ul id="dp-files" class="dp-files"></ul>
+      </section>
+    </main>
+    <script src="/portal.js"></script>
+  </body>
+</html>

package/payload/platform/plugins/cloudflare/skills/data-portal/template/public/portal.css

@@ -0,0 +1,113 @@
+/* Data portal styles. Plain CSS, dp- prefixed, themed off variables so a brand
+   can restyle without touching markup — the same shape as booking.css. */
+:root {
+  --dp-ink: #14181f;
+  --dp-muted: #667085;
+  --dp-paper: #ffffff;
+  --dp-rule: #e4e7ec;
+  --dp-accent: #1f6feb;
+  --dp-accent-ink: #ffffff;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  padding: 2rem 1rem;
+  background: var(--dp-paper);
+  color: var(--dp-ink);
+  font: 16px/1.5 system-ui, -apple-system, 'Segoe UI', sans-serif;
+}
+
+.dp-card {
+  max-width: 34rem;
+  margin: 0 auto;
+}
+
+.dp-title {
+  margin: 0 0 1rem;
+  font-size: 1.5rem;
+}
+
+.dp-status {
+  min-height: 1.5rem;
+  margin: 0 0 1rem;
+  color: var(--dp-muted);
+}
+
+.dp-login,
+.dp-upload {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.dp-label {
+  font-size: 0.875rem;
+  color: var(--dp-muted);
+}
+
+.dp-input,
+.dp-file {
+  padding: 0.625rem 0.75rem;
+  border: 1px solid var(--dp-rule);
+  border-radius: 0.375rem;
+  font: inherit;
+}
+
+.dp-btn {
+  margin-top: 0.5rem;
+  padding: 0.625rem 1rem;
+  border: 0;
+  border-radius: 0.375rem;
+  background: var(--dp-accent);
+  color: var(--dp-accent-ink);
+  font: inherit;
+  cursor: pointer;
+}
+
+.dp-upload {
+  margin-bottom: 1.5rem;
+}
+
+.dp-files {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.dp-file-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 0;
+  border-bottom: 1px solid var(--dp-rule);
+}
+
+.dp-file-name {
+  color: var(--dp-accent);
+  text-decoration: none;
+  word-break: break-all;
+}
+
+.dp-file-name:hover {
+  text-decoration: underline;
+}
+
+.dp-del {
+  border: 1px solid var(--dp-rule);
+  border-radius: 0.375rem;
+  background: transparent;
+  color: var(--dp-muted);
+  padding: 0.375rem 0.625rem;
+  font: inherit;
+  cursor: pointer;
+}
+
+.dp-empty {
+  color: var(--dp-muted);
+  padding: 0.75rem 0;
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/public/portal.js

@@ -0,0 +1,155 @@
+/* Data portal client. Dependency-free, no bundler, no framework — the same
+   shape as the booking page's booking.js.
+
+   Three steps: sign in with a passcode, list your own files, upload/delete.
+   The session cookie is HttpOnly, so this script never sees or stores it. */
+(function () {
+  'use strict';
+
+  function meta(name) {
+    var el = document.querySelector('meta[name="' + name + '"]');
+    return el ? el.getAttribute('content') || '' : '';
+  }
+
+  var API = meta('api-base');
+  var statusEl = document.getElementById('dp-status');
+  var loginEl = document.getElementById('dp-login');
+  var panelEl = document.getElementById('dp-panel');
+  var filesEl = document.getElementById('dp-files');
+
+  function say(msg) {
+    statusEl.textContent = msg;
+  }
+
+  function api(path, opts) {
+    return fetch(API + path, Object.assign({ credentials: 'same-origin' }, opts || {}));
+  }
+
+  function item(text) {
+    var li = document.createElement('li');
+    li.className = 'dp-empty';
+    li.textContent = text;
+    return li;
+  }
+
+  function render(files) {
+    // replaceChildren, not innerHTML: every filename below is set with
+    // textContent so a name like '<img onerror=…>' renders as text, and
+    // clearing the list should not go anywhere near HTML parsing either.
+    filesEl.replaceChildren();
+    if (!files.length) {
+      filesEl.appendChild(item('No files yet.'));
+      return;
+    }
+    files.forEach(function (f) {
+      var li = document.createElement('li');
+      li.className = 'dp-file-row';
+
+      var a = document.createElement('a');
+      a.className = 'dp-file-name';
+      a.href = API + '/api/download?key=' + encodeURIComponent(f.objectKey);
+      a.textContent = f.filename;
+      li.appendChild(a);
+
+      var del = document.createElement('button');
+      del.className = 'dp-del';
+      del.type = 'button';
+      del.textContent = 'Delete';
+      del.addEventListener('click', function () {
+        remove(f.objectKey);
+      });
+      li.appendChild(del);
+
+      filesEl.appendChild(li);
+    });
+  }
+
+  function refresh() {
+    return api('/api/files')
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (d) {
+        if (d.ok) render(d.files || []);
+      })
+      .catch(function () {
+        say('Could not load your files.');
+      });
+  }
+
+  function remove(key) {
+    say('Deleting…');
+    api('/api/delete', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key: key }),
+    })
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (d) {
+        say(d.ok ? 'Deleted.' : 'Could not delete that.');
+        return refresh();
+      })
+      .catch(function () {
+        say('Could not delete that.');
+      });
+  }
+
+  loginEl.addEventListener('submit', function (e) {
+    e.preventDefault();
+    say('Signing in…');
+    api('/api/auth', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        ownerId: document.getElementById('dp-owner').value.trim(),
+        passcode: document.getElementById('dp-passcode').value,
+      }),
+    })
+      .then(function (r) {
+        return r.json().then(function (d) {
+          return { s: r.status, d: d };
+        });
+      })
+      .then(function (res) {
+        if (res.s === 429) {
+          say('Too many attempts. Try again later.');
+          return;
+        }
+        if (!res.d.ok) {
+          say('That did not work.');
+          return;
+        }
+        document.getElementById('dp-passcode').value = '';
+        loginEl.hidden = true;
+        panelEl.hidden = false;
+        say('');
+        return refresh();
+      })
+      .catch(function () {
+        say('That did not work.');
+      });
+  });
+
+  document.getElementById('dp-upload').addEventListener('submit', function (e) {
+    e.preventDefault();
+    var input = document.getElementById('dp-file');
+    if (!input.files || !input.files[0]) return;
+    var fd = new FormData();
+    fd.append('file', input.files[0]);
+    say('Uploading…');
+    api('/api/upload', { method: 'POST', body: fd })
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (d) {
+        say(d.ok ? 'Uploaded.' : 'Upload failed.');
+        input.value = '';
+        return refresh();
+      })
+      .catch(function () {
+        say('Upload failed.');
+      });
+  });
+})();

package/payload/platform/plugins/cloudflare/skills/data-portal/template/schema.sql

@@ -0,0 +1,64 @@
+-- D1 schema for the data portal (data-portal skill).
+--
+-- Four tables: who may authenticate (people), who currently is (sessions),
+-- what they have dropped (manifest), and how hard they have been trying
+-- (auth_attempts). Everything is IF NOT EXISTS so re-applying is safe.
+
+-- One row per enrolled person. No plaintext passcode is ever stored: the skill
+-- generates the passcode, shows it to the operator once, and persists only the
+-- PBKDF2 salt and hash. `iterations` is stored per row so the cost can be
+-- raised later without invalidating existing rows.
+CREATE TABLE IF NOT EXISTS people (
+  ownerId    TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  salt       TEXT NOT NULL,
+  hash       TEXT NOT NULL,
+  iterations INTEGER NOT NULL,
+  createdAt  TEXT NOT NULL
+);
+
+-- `pcCheck` is a short digest of the person's passcode hash at mint time, and
+-- resolveSession requires it to still match `people.hash`. It is what makes
+-- revocation structural: rotating a passcode necessarily changes the hash, so
+-- every session minted against the old one stops resolving immediately, with
+-- no cleanup step for an operator to remember and no 12-hour window to wait
+-- out. A leaked passcode is exactly the case where a procedural remedy fails.
+CREATE TABLE IF NOT EXISTS sessions (
+  sessionId TEXT PRIMARY KEY,
+  ownerId   TEXT NOT NULL,
+  pcCheck   TEXT NOT NULL,
+  expiresAt INTEGER NOT NULL,
+  createdAt TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS sessions_owner ON sessions (ownerId);
+
+-- One row per stored object. `ingested` is the claim flag the device-side
+-- sweep (a separate task) reads and sets; a row stays 0 until its file has
+-- been pulled into the graph, so the backlog survives the device being offline.
+CREATE TABLE IF NOT EXISTS manifest (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  fileId     TEXT UNIQUE NOT NULL,
+  ownerId    TEXT NOT NULL,
+  filename   TEXT NOT NULL,
+  objectKey  TEXT UNIQUE NOT NULL,
+  size       INTEGER NOT NULL,
+  uploadedAt TEXT NOT NULL,
+  ingested   INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS manifest_uningested ON manifest (ingested);
+CREATE INDEX IF NOT EXISTS manifest_owner ON manifest (ownerId);
+
+-- Fixed-window auth attempt counter. Pages Functions are stateless, so the
+-- counter cannot live in process memory the way every other rate limiter in
+-- this platform does. The unique index is what makes the upsert in
+-- _lib/ratelimit.ts collapse onto one row per window.
+CREATE TABLE IF NOT EXISTS auth_attempts (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope       TEXT NOT NULL,
+  windowStart INTEGER NOT NULL,
+  count       INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS auth_attempts_scope_window ON auth_attempts (scope, windowStart);

package/payload/platform/plugins/cloudflare/skills/data-portal/template/wrangler.toml

@@ -0,0 +1,21 @@
+# Cloudflare Pages config for the data portal (data-portal skill).
+# The skill fills the placeholders at assemble time:
+#   __PROJECT_NAME__     the Pages project name
+#   __D1_DATABASE_NAME__ the D1 database name  (<accountId>-<purpose>)
+#   __D1_DATABASE_ID__   the id printed by `wrangler d1 create`
+#   __R2_BUCKET_NAME__   the R2 bucket name    (<accountId>-<purpose>)
+name = "__PROJECT_NAME__"
+pages_build_output_dir = "public"
+compatibility_date = "2024-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[d1_databases]]
+binding = "DB"
+database_name = "__D1_DATABASE_NAME__"
+database_id = "__D1_DATABASE_ID__"
+
+# R2 binds by NAME and has no database_id analogue — the one asymmetry with the
+# D1 block above. `binding` is the name the Pages Function reads off env.
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "__R2_BUCKET_NAME__"

package/payload/platform/plugins/cloudflare/skills/site-deploy/SKILL.md

@@ -61,6 +61,14 @@ When the canonical tree carries a contact or waitlist form, the deploy is not co
 
 Name the database with the canonical `<accountId>-<purpose>` scheme from `bin/cf-store-name.sh`, and keep one store per capture purpose: a new capture kind is a discriminator column, not a second database. A document-acceptance form (works agreement, quote signing) uses the canonical `acceptances` shape declared in `references/d1-data-capture.md`, not a per-build table, so the watcher reads one known store.
 
+## Bind the bucket when the tree binds one
+
+When the canonical tree carries an `[[r2_buckets]]` block, the deploy is not complete until a Function can reach the bucket off `env`. Follow `references/r2-object-storage.md`: the bucket is created once by its owning account through the storage broker — not here, and not by this skill's token — the binding is added to `wrangler.toml`, and the Function reads `env.<binding>`.
+
+The binding is declarative config carried in the deploy payload, so the Pages token from the auth step already covers it and no R2 scope is needed at deploy time. Only bucket *creation* needs `Workers R2 Storage Write`, which is the `storage` scope, and it happens outside this skill. An R2-bound Function that fails every store call with `result=failed` is the signature of a binding that did not deploy — check the block reached the tree with `bucket_name` filled, rather than reaching for a token the deploy never needed.
+
+Name the bucket with the canonical `<accountId>-<purpose>` scheme from `bin/cf-store-name.sh`, and keep one bucket per purpose, exactly as the D1 section above requires for databases. A tree with no `[[r2_buckets]]` block skips this section.
+
 ## Open Graph correctness
 
 The live page must carry brand-correct Open Graph metadata: `<meta property="og:title">`, `og:description`, `og:image`, and `og:url` reflecting this site and this brand, not a leftover from whatever the tree was cloned from. Stale OG (a live card still naming a previous brand) is a recorded failure mode of hand deployment. Confirm the `og:*` tags in the deployed HTML are correct before claiming done; if they are stale, fix them in the source tree, redeploy, and re-check.