@rubytech/create-maxy-code 0.1.459 → 0.1.461

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 --allowJs --checkJs --target es2022 --module esnext --moduleResolution bundler --lib es2022,dom ../skills/*/template/functions/api/*.ts ../skills/*/template/functions/api/_lib/*.ts ../skills/*/template/functions/api/_lib/*.mjs"
   },
   "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/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.

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

@@ -0,0 +1,125 @@
+---
+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:
+
+```bash
+node platform/plugins/cloudflare/bin/portal-enrol.mjs --owner <ownerId> --name <name> \
+  | npx wrangler d1 execute <portalDbName> --remote --file=-
+```
+
+The script mints the passcode and prints it **once to stderr**, so it reaches the operator's terminal
+and never the pipe; stdout carries the `INSERT` alone. Do not hand-roll this: the passcode's length
+and alphabet are pinned in `template/functions/api/_lib/passcode.mjs`, the script is what applies
+them, and a passcode minted any other way is unpinned by definition. The script refuses an `ownerId`
+the isolation gate would reject, so a bad name fails here rather than after the row lands.
+
+The statement is an upsert on `ownerId`, which is what makes rotation a re-run rather than a
+constraint error.
+
+**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
+the script 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.
+
+## 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`.
+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.
+
+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, ' ')}"`
+}