@rubytech/create-maxy-code 0.1.458 → 0.1.460

package/payload/platform/plugins/cloudflare/mcp/__tests__/passcode.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest'
+import {
+  PBKDF2_ITERATIONS,
+  constantTimeEqual,
+  hashPasscode,
+  verifyPasscode,
+  randomSaltHex,
+} from '../../skills/data-portal/template/functions/api/_lib/passcode'
+
+const SALT = '000102030405060708090a0b0c0d0e0f'
+
+describe('constantTimeEqual', () => {
+  it('is true for identical arrays', () => {
+    expect(constantTimeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]))).toBe(true)
+  })
+  it('is false when a byte differs', () => {
+    expect(constantTimeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 4]))).toBe(false)
+  })
+  it('is false for different lengths, without throwing', () => {
+    expect(constantTimeEqual(new Uint8Array([1, 2]), new Uint8Array([1, 2, 3]))).toBe(false)
+  })
+  it('compares every byte even after a mismatch (no early return)', () => {
+    // A first-byte mismatch and a last-byte mismatch must both be false.
+    // This does not measure timing; it pins that the function does not
+    // short-circuit in a way a rewrite could reintroduce.
+    expect(constantTimeEqual(new Uint8Array([9, 2, 3]), new Uint8Array([1, 2, 3]))).toBe(false)
+    expect(constantTimeEqual(new Uint8Array([1, 2, 9]), new Uint8Array([1, 2, 3]))).toBe(false)
+  })
+})
+
+describe('hashPasscode', () => {
+  it('is deterministic for the same passcode, salt and iterations', async () => {
+    const a = await hashPasscode('hunter2', SALT, 1000)
+    const b = await hashPasscode('hunter2', SALT, 1000)
+    expect(a).toBe(b)
+    expect(a).toMatch(/^[0-9a-f]{64}$/)
+  })
+  it('differs for a different passcode', async () => {
+    const a = await hashPasscode('hunter2', SALT, 1000)
+    const b = await hashPasscode('hunter3', SALT, 1000)
+    expect(a).not.toBe(b)
+  })
+  it('differs for a different salt', async () => {
+    const a = await hashPasscode('hunter2', SALT, 1000)
+    const b = await hashPasscode('hunter2', 'ffffffffffffffffffffffffffffffff', 1000)
+    expect(a).not.toBe(b)
+  })
+})
+
+describe('verifyPasscode', () => {
+  it('accepts the right passcode', async () => {
+    const h = await hashPasscode('hunter2', SALT, 1000)
+    expect(await verifyPasscode('hunter2', SALT, h, 1000)).toBe(true)
+  })
+  it('rejects the wrong passcode', async () => {
+    const h = await hashPasscode('hunter2', SALT, 1000)
+    expect(await verifyPasscode('hunter3', SALT, h, 1000)).toBe(false)
+  })
+  it('rejects a malformed stored hash without throwing', async () => {
+    expect(await verifyPasscode('hunter2', SALT, 'not-hex', 1000)).toBe(false)
+  })
+})
+
+describe('randomSaltHex', () => {
+  it('renders bytes as lowercase hex', () => {
+    expect(randomSaltHex(new Uint8Array([0, 1, 255]))).toBe('0001ff')
+  })
+})
+
+describe('PBKDF2_ITERATIONS', () => {
+  it('is at least the OWASP floor for PBKDF2-SHA256', () => {
+    expect(PBKDF2_ITERATIONS).toBeGreaterThanOrEqual(600_000)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/ratelimit.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import {
+  RATE_WINDOW_MS,
+  RATE_MAX_ATTEMPTS,
+  checkAndRecordAttempt,
+} from '../../skills/data-portal/template/functions/api/_lib/ratelimit'
+import type { D1Database } from '../../skills/data-portal/template/functions/api/_lib/types'
+
+// Minimal D1 fake: one row per (scope, windowStart), matching the schema's
+// unique index. The INSERT ... ON CONFLICT DO UPDATE is modelled as an upsert.
+function fakeDb(seed: Array<{ scope: string; windowStart: number; count: number }> = []) {
+  const rows = [...seed]
+  const db: D1Database = {
+    prepare(query: string) {
+      let bound: unknown[] = []
+      const stmt = {
+        bind(...v: unknown[]) {
+          bound = v
+          return stmt
+        },
+        async run() {
+          if (/INSERT/i.test(query)) {
+            const [scope, windowStart] = bound as [string, number]
+            const hit = rows.find((r) => r.scope === scope && r.windowStart === windowStart)
+            if (hit) hit.count++
+            else rows.push({ scope, windowStart, count: 1 })
+          }
+          return { meta: { changes: 1 } }
+        },
+        async all() {
+          return { results: [] }
+        },
+        async first<T>() {
+          const [scope, windowStart] = bound as [string, number]
+          const hit = rows.find((r) => r.scope === scope && r.windowStart === windowStart)
+          return (hit ? { count: hit.count } : null) as T | null
+        },
+      }
+      return stmt
+    },
+  }
+  return { db, rows }
+}
+
+describe('checkAndRecordAttempt', () => {
+  it('allows the first attempt in a window', async () => {
+    const { db } = fakeDb()
+    expect(await checkAndRecordAttempt(db, 'alice', 1_000_000)).toEqual({ allowed: true, count: 1 })
+  })
+
+  it('allows up to the cap', async () => {
+    const w = Math.floor(1_000_000 / RATE_WINDOW_MS) * RATE_WINDOW_MS
+    const { db } = fakeDb([{ scope: 'alice', windowStart: w, count: RATE_MAX_ATTEMPTS - 1 }])
+    expect((await checkAndRecordAttempt(db, 'alice', 1_000_000)).allowed).toBe(true)
+  })
+
+  it('denies past the cap', async () => {
+    const w = Math.floor(1_000_000 / RATE_WINDOW_MS) * RATE_WINDOW_MS
+    const { db } = fakeDb([{ scope: 'alice', windowStart: w, count: RATE_MAX_ATTEMPTS }])
+    const res = await checkAndRecordAttempt(db, 'alice', 1_000_000)
+    expect(res.allowed).toBe(false)
+    expect(res.count).toBeGreaterThan(RATE_MAX_ATTEMPTS)
+  })
+
+  it('starts a fresh count in the next window', async () => {
+    const w = Math.floor(1_000_000 / RATE_WINDOW_MS) * RATE_WINDOW_MS
+    const { db } = fakeDb([{ scope: 'alice', windowStart: w, count: RATE_MAX_ATTEMPTS }])
+    const later = 1_000_000 + RATE_WINDOW_MS
+    expect((await checkAndRecordAttempt(db, 'alice', later)).allowed).toBe(true)
+  })
+
+  it('scopes counts independently per person', async () => {
+    const w = Math.floor(1_000_000 / RATE_WINDOW_MS) * RATE_WINDOW_MS
+    const { db } = fakeDb([{ scope: 'alice', windowStart: w, count: RATE_MAX_ATTEMPTS }])
+    expect((await checkAndRecordAttempt(db, 'bob', 1_000_000)).allowed).toBe(true)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/skill-contract.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const skill = () => readFileSync(join(__dirname, '../../skills/data-portal/SKILL.md'), 'utf8')
+
+describe('data-portal SKILL.md', () => {
+  it('opens with frontmatter carrying name and description', () => {
+    // Without these the skill is invisible to the available-skills reminder and
+    // to skill-search. The defect is silent: no error, no log line.
+    const text = skill()
+    expect(text.startsWith('---\n')).toBe(true)
+    const fm = text.slice(4, text.indexOf('\n---', 4))
+    expect(fm).toMatch(/^name:\s*data-portal\s*$/m)
+    expect(fm).toMatch(/^description:\s*\S/m)
+  })
+
+  it('declares the plugin-read convention (check-plugin-references.mjs)', () => {
+    expect(skill()).toMatch(/plugin-read/)
+  })
+
+  it('records the two-session provisioning sequence', () => {
+    // The load-bearing sequencing decision: the broker registers a bucket to
+    // whoever creates it, ON CREATE and never reassigned, so the client
+    // account must create its own or its ingestion sweep is denied forever.
+    const text = skill()
+    expect(text).toMatch(/storage-r2-bucket-create/)
+    expect(text).toMatch(/client|sub-account/i)
+  })
+
+  it('names the passcode discipline', () => {
+    expect(skill()).toMatch(/once/i)
+    expect(skill()).toMatch(/never.*plaintext|plaintext.*never/i)
+  })
+
+  it('routes store naming through cf-store-name.sh rather than hand-building', () => {
+    // The script is already tested (bin/__tests__/cf-store-name.test.sh). What
+    // is untested is that this skill defers to it — a hand-built name would
+    // break the "name identifies owner and purpose" contract silently.
+    expect(skill()).toMatch(/cf-store-name\.sh/)
+  })
+
+  it('leaves no unfilled placeholder marker in its own prose', () => {
+    expect(skill()).not.toMatch(/\bTBD\b|\bTODO\b/)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/template-config.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const TEMPLATE = join(__dirname, '../../skills/data-portal/template')
+const wrangler = () => readFileSync(join(TEMPLATE, 'wrangler.toml'), 'utf8')
+const schema = () => readFileSync(join(TEMPLATE, 'schema.sql'), 'utf8')
+
+describe('wrangler.toml', () => {
+  it('binds D1 as DB', () => {
+    expect(wrangler()).toMatch(/\[\[d1_databases\]\]/)
+    expect(wrangler()).toMatch(/binding\s*=\s*"DB"/)
+  })
+
+  it('binds R2 as BUCKET — the resource class the plugin has never bound', () => {
+    expect(wrangler()).toMatch(/\[\[r2_buckets\]\]/)
+    expect(wrangler()).toMatch(/binding\s*=\s*"BUCKET"/)
+    expect(wrangler()).toMatch(/bucket_name\s*=\s*"__R2_BUCKET_NAME__"/)
+  })
+
+  it('declares every placeholder it uses in its header comment', () => {
+    const text = wrangler()
+    const used = [...text.matchAll(/__[A-Z0-9_]+__/g)].map((m) => m[0])
+    for (const p of new Set(used)) {
+      // Each placeholder appears at least twice: once documented, once used.
+      expect(text.split(p).length - 1).toBeGreaterThanOrEqual(2)
+    }
+  })
+})
+
+describe('schema.sql', () => {
+  it('is re-appliable — every create is IF NOT EXISTS', () => {
+    const creates = [...schema().matchAll(/CREATE (TABLE|INDEX|UNIQUE INDEX)/gi)]
+    expect(creates.length).toBeGreaterThan(0)
+    expect(schema()).not.toMatch(/CREATE TABLE (?!IF NOT EXISTS)/i)
+  })
+
+  it('has the four tables the portal needs', () => {
+    for (const t of ['people', 'sessions', 'manifest', 'auth_attempts']) {
+      expect(schema()).toMatch(new RegExp(`CREATE TABLE IF NOT EXISTS ${t}`, 'i'))
+    }
+  })
+
+  it('defaults manifest.ingested to 0', () => {
+    expect(schema()).toMatch(/ingested\s+INTEGER\s+NOT NULL\s+DEFAULT 0/i)
+  })
+
+  it('stores no plaintext passcode column', () => {
+    expect(schema()).not.toMatch(/passcode\s+TEXT/i)
+  })
+
+  it('enforces one attempt row per (scope, window)', () => {
+    expect(schema()).toMatch(/CREATE UNIQUE INDEX IF NOT EXISTS auth_attempts_scope_window/i)
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/__tests__/upload-route.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect } from 'vitest'
+import { processUpload } from '../../skills/data-portal/template/functions/api/upload'
+import type { PortalEnv } from '../../skills/data-portal/template/functions/api/_lib/types'
+
+// The fake must model the constraints the schema actually declares, not just
+// the happy path. `objectKey TEXT UNIQUE` is what makes a re-upload an upsert
+// rather than a second row; a fake that accepts duplicates would let the
+// "exactly one manifest row" assertion pass while the real D1 threw.
+function makeEnv() {
+  const manifestRows: unknown[][] = []
+  const objects = new Map<string, Uint8Array>()
+  const env = {
+    DB: {
+      prepare(query: string) {
+        let bound: unknown[] = []
+        const stmt = {
+          bind(...v: unknown[]) {
+            bound = v
+            return stmt
+          },
+          async run() {
+            if (/INSERT INTO manifest/i.test(query)) {
+              const objectKey = bound[3] as string
+              const existing = manifestRows.findIndex((r) => r[3] === objectKey)
+              if (existing >= 0) {
+                if (!/ON CONFLICT\s*\(\s*objectKey\s*\)\s*DO UPDATE/i.test(query)) {
+                  throw new Error('UNIQUE constraint failed: manifest.objectKey')
+                }
+                manifestRows[existing] = bound
+              } else {
+                manifestRows.push(bound)
+              }
+            }
+            return { meta: { changes: 1 } }
+          },
+          async all() {
+            return { results: [] }
+          },
+          async first<T>() {
+            if (/FROM sessions/i.test(query)) {
+              return (bound[0] === 'sess-a' ? { ownerId: 'alice' } : null) as T | null
+            }
+            if (/FROM manifest/i.test(query)) {
+              const key = bound[0] as string
+              return (objects.has(key) ? { fileId: 'x' } : null) as T | null
+            }
+            return null as T | null
+          },
+        }
+        return stmt
+      },
+    },
+    BUCKET: {
+      async put(key: string, body: Uint8Array) {
+        objects.set(key, body)
+        return {}
+      },
+      async get(key: string) {
+        const v = objects.get(key)
+        return v ? { body: null, size: v.length } : null
+      },
+      async head(key: string) {
+        const v = objects.get(key)
+        return v ? { size: v.length } : null
+      },
+      async delete(key: string) {
+        objects.delete(key)
+      },
+    },
+  } as unknown as PortalEnv
+  return { env, manifestRows, objects }
+}
+
+describe('processUpload', () => {
+  it('writes the object under the owner prefix and exactly one manifest row', async () => {
+    const { env, manifestRows, objects } = makeEnv()
+    const lines: string[] = []
+    const res = await processUpload(
+      'sess-a',
+      'invoice.pdf',
+      new Uint8Array([1, 2, 3]),
+      env,
+      (l) => lines.push(l),
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    expect(res.status).toBe(200)
+    expect([...objects.keys()]).toEqual(['alice/invoice.pdf'])
+    expect(manifestRows.length).toBe(1)
+  })
+
+  it('writes the manifest row with ingested=0', async () => {
+    const { env, manifestRows } = makeEnv()
+    await processUpload(
+      'sess-a',
+      'invoice.pdf',
+      new Uint8Array([1]),
+      env,
+      () => {},
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    // Column order: fileId, ownerId, filename, objectKey, size, uploadedAt, ingested
+    expect(manifestRows[0][6]).toBe(0)
+  })
+
+  it('emits the full lifeline correlated by uploadId, ending in a verified post-condition', async () => {
+    const { env } = makeEnv()
+    const lines: string[] = []
+    await processUpload(
+      'sess-a',
+      'invoice.pdf',
+      new Uint8Array([1]),
+      env,
+      (l) => lines.push(l),
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    const joined = lines.join('\n')
+    expect(joined).toContain('op=request uploadId=up-1')
+    expect(joined).toContain('op=r2-put uploadId=up-1')
+    expect(joined).toContain('op=manifest-write uploadId=up-1')
+    expect(joined).toMatch(/op=complete uploadId=up-1 .*objectPresent=true rowPresent=true/)
+  })
+
+  it('denies an unauthenticated caller and writes nothing', async () => {
+    const { env, manifestRows, objects } = makeEnv()
+    const res = await processUpload(
+      '',
+      'invoice.pdf',
+      new Uint8Array([1]),
+      env,
+      () => {},
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    expect(res.status).toBe(401)
+    expect(objects.size).toBe(0)
+    expect(manifestRows.length).toBe(0)
+  })
+
+  it('rejects a filename that escapes the owner prefix, and writes nothing', async () => {
+    const { env, objects, manifestRows } = makeEnv()
+    const res = await processUpload(
+      'sess-a',
+      '../bob/evil.pdf',
+      new Uint8Array([1]),
+      env,
+      () => {},
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    expect(res.status).toBe(400)
+    expect(objects.size).toBe(0)
+    expect(manifestRows.length).toBe(0)
+  })
+
+  it('rejects an empty filename', async () => {
+    const { env } = makeEnv()
+    expect(
+      (
+        await processUpload(
+          'sess-a',
+          '',
+          new Uint8Array([1]),
+          env,
+          () => {},
+          () => 'up-1',
+          () => 1_000_000,
+        )
+      ).status,
+    ).toBe(400)
+  })
+
+  it('caps the upload size and says so, rather than OOMing the isolate silently', async () => {
+    const { env, objects, manifestRows } = makeEnv()
+    const lines: string[] = []
+    const tooBig = new Uint8Array(25 * 1024 * 1024 + 1)
+    const res = await processUpload(
+      'sess-a',
+      'huge.bin',
+      tooBig,
+      env,
+      (l) => lines.push(l),
+      () => 'up-1',
+      () => 1_000_000,
+    )
+    expect(res.status).toBe(413)
+    expect(objects.size).toBe(0)
+    expect(manifestRows.length).toBe(0)
+    expect(lines.join('\n')).toContain('result=too-large')
+  })
+
+  it('measures elapsed time rather than printing a fabricated zero', async () => {
+    const { env } = makeEnv()
+    const lines: string[] = []
+    let t = 1_000_000
+    await processUpload(
+      'sess-a',
+      'invoice.pdf',
+      new Uint8Array([1]),
+      env,
+      (l) => lines.push(l),
+      () => 'up-1',
+      () => (t += 5),
+    )
+    // A hardcoded ms=0 reads to an operator as "took no time", not "was never
+    // measured". With a real clock the value moves.
+    expect(lines.join('\n')).toMatch(/op=complete uploadId=up-1 ms=([1-9]\d*)/)
+  })
+
+  // R2 overwrites an existing key unconditionally, so a re-upload of the same
+  // filename REPLACES the object whatever the manifest does. The manifest must
+  // therefore replace its row too, or it ends up describing a file that no
+  // longer exists. Re-sending a corrected invoice.pdf is the single most
+  // ordinary thing this portal will ever be asked to do.
+  describe('re-uploading the same filename', () => {
+    it('replaces the object, keeps exactly one row, and succeeds', async () => {
+      const { env, manifestRows, objects } = makeEnv()
+      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      const second = await processUpload(
+        'sess-a',
+        'invoice.pdf',
+        new Uint8Array([9, 9, 9]),
+        env,
+        () => {},
+        () => 'up-2',
+        () => 2_000,
+      )
+      expect(second.status).toBe(200)
+      expect(manifestRows.length).toBe(1)
+      expect(objects.get('alice/invoice.pdf')?.length).toBe(3)
+    })
+
+    it('updates the row to describe the new object, not the old one', async () => {
+      const { env, manifestRows } = makeEnv()
+      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
+      // Column order: fileId, ownerId, filename, objectKey, size, uploadedAt, ingested
+      expect(manifestRows[0][4]).toBe(3)
+      expect(manifestRows[0][5]).toBe(new Date(2_000).toISOString())
+    })
+
+    it('re-arms ingestion by resetting ingested to 0', async () => {
+      // The load-bearing part. If the first file was already swept to
+      // ingested=1, a replacement that left the flag set would never be
+      // ingested, and nothing would ever say so.
+      const { env, manifestRows } = makeEnv()
+      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([1]), env, () => {}, () => 'up-1', () => 1_000)
+      manifestRows[0][6] = 1 // the device-side sweep marks it ingested
+      await processUpload('sess-a', 'invoice.pdf', new Uint8Array([9, 9, 9]), env, () => {}, () => 'up-2', () => 2_000)
+      expect(manifestRows[0][6]).toBe(0)
+    })
+  })
+})

package/payload/platform/plugins/cloudflare/mcp/package.json

@@ -6,13 +6,16 @@
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck:templates": "tsc --noEmit --strict --target es2022 --module esnext --moduleResolution bundler --lib es2022,dom ../skills/*/template/functions/api/*.ts ../skills/*/template/functions/api/_lib/*.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
   }
 }

package/payload/platform/plugins/cloudflare/references/api.md

@@ -53,7 +53,7 @@ chmod 600 "${SECRETS_DIR}/cloudflare.env"
 
 ### Multi-tenant installs — the master lives house-only
 
-The account-scoped storage above is correct for a single-tenant install (one Cloudflare account, one client). On a **multi-client install** (many client sub-accounts sharing one Cloudflare account, for example SiteDesk), an account-wide token in a sub-account's `cloudflare.env` lets that sub-account reach every other client's D1 and R2. There, the master lives house-only at `${PLATFORM_ROOT}/config/cloudflare-house.env` (a location no sub-account spawn sources), per-account `cloudflare.env` files carry no account-wide token, and a sub-account reaches D1/R2 only through the storage broker, which scopes every operation to the caller's account. See [`../../../../.docs/cloudflare-storage-isolation.md`](../../../../.docs/cloudflare-storage-isolation.md). The per-scope DNS/Pages/Access minting below stays admin-run, and its mint-or-reuse mechanism is unchanged; the one difference on a multi-tenant install is the source file. Because the per-account `cloudflare.env` no longer carries the master, `cf-token.sh` falls back to the house credential (`${PLATFORM_ROOT}/config/cloudflare-house.env`) for these scopes, mints and persists the scope token there, and reports `src=house` on its `[cf-token]` lifeline. `cf-token.sh` gates that fallback on the caller being the house account (its `account.json` carries `role:"house"`, or it is the sole account), so the sanctioned path never mints a hosting token for a client sub-account; a denied caller gets an `action=deny` lifeline naming the reason. This gate is a boundary of intent, not of permission: every account's session runs as the same unix user and the house env path is deterministic, so an agent holding `Bash` can read the master directly or export a false `ACCOUNT_ID`. Do not cite the gate as proof a sub-account cannot reach the master. OS user separation is tracked separately.
+The account-scoped storage above is correct for a single-tenant install (one Cloudflare account, one client). On a **multi-client install** (many client sub-accounts sharing one Cloudflare account, for example SiteDesk), an account-wide token in a sub-account's `cloudflare.env` lets that sub-account reach every other client's D1 and R2. There, the master lives house-only at `${PLATFORM_ROOT}/config/cloudflare-house.env` (a location no sub-account spawn sources), per-account `cloudflare.env` files carry no account-wide token, and a sub-account reaches D1/R2 only through the storage broker, which scopes every operation to the caller's account. See [`../../../../.docs/cloudflare-storage-isolation.md`](../../../../.docs/cloudflare-storage-isolation.md). The per-scope DNS/Pages/Access minting below stays admin-run, and its mint-or-reuse mechanism is unchanged; the one difference on a multi-tenant install is the source file. Because the per-account `cloudflare.env` no longer carries the master, `cf-token.sh` falls back to the house credential (`${PLATFORM_ROOT}/config/cloudflare-house.env`) for these scopes, mints and persists the scope token there, and reports `src=house` on its `[cf-token]` lifeline. `cf-token.sh` gates that fallback on the caller being the house account (its `account.json` carries `role:"house"`, or it is the sole account), so the sanctioned path never mints a hosting token for a client sub-account; a denied caller gets an `action=deny` lifeline naming the reason. This gate is a boundary of intent, not of permission: every account's session runs as the same unix user and the house env path is deterministic, so an agent holding `Bash` can read the master directly or export a false `ACCOUNT_ID`. Do not cite the gate as proof a sub-account cannot reach the master. This is permanent, not pending: OS user separation was costed and declined as disproportionate, so nothing tracks closing it.
 
 Load the master for a mint call:
 

package/payload/platform/plugins/cloudflare/references/r2-object-storage.md

@@ -37,3 +37,49 @@ When a bucket is created or reused, log the establishment decision so a reuse is
 ```
 op=storage-provision resource=r2 purpose=<purpose> account=<accountId> name=<canonical-name> action=create|reuse
 ```
+
+## Bind the bucket in wrangler.toml
+
+The binding name (`BUCKET` below) is the variable the Pages Function reads off `env`. Keep `wrangler.toml` in the site's project root; it carries no secret, only the bucket's name.
+
+```toml
+name = "<project>"
+pages_build_output_dir = "public"
+
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "<accountId>-<purpose>"    # from bin/cf-store-name.sh
+```
+
+**R2 binds by name and has no `database_id` analogue.** That is the one asymmetry with the `[[d1_databases]]` block in `d1-data-capture.md` § Bind the database, where a `database_id` from `wrangler d1 create` must also be recorded. An R2 bucket needs no id, so there is no second value to carry into the tree.
+
+The deploy-time token needs **no** R2 scope: the binding is declarative config carried in the deploy payload, covered by Pages Write. `wrangler r2 bucket create` **does** need `Workers R2 Storage Write` — the `storage` scope from `bin/cf-token.sh`. Reaching for an R2 token at deploy time is a sign the binding is being confused with the provision.
+
+## The Pages Function
+
+The bound bucket arrives on `env` and exposes `put` / `get` / `delete` / `head`. Keep the handler a thin wrapper over a pure function taking the env injected, so the logic is verifiable without the Pages runtime — the shape `d1-data-capture.md` § The Pages Function prescribes for D1.
+
+```ts
+interface R2Bucket {
+  put: (key: string, value: ArrayBuffer | Uint8Array) => Promise<unknown>
+  get: (key: string) => Promise<{ body: ReadableStream | null; size: number } | null>
+  delete: (key: string) => Promise<void>
+  head: (key: string) => Promise<{ size: number } | null>
+}
+
+export async function storeObject(
+  env: { BUCKET: R2Bucket },
+  key: string,
+  bytes: Uint8Array,
+  log: (line: string) => void,
+): Promise<boolean> {
+  await env.BUCKET.put(key, bytes)
+  // Re-read rather than assume: a put that stored nothing emits no error, and
+  // an object with no manifest row is invisible to whatever later reads it.
+  const present = (await env.BUCKET.head(key)) !== null
+  log(`[r2-store] op=put key=${key} present=${present}`)
+  return present
+}
+```
+
+Declaring the interface structurally, rather than importing `@cloudflare/workers-types`, is what lets a test inject a fake bucket. No Workers-specific test tooling ships in this repo and none is needed for a Function shaped this way.