@rubytech/create-maxy-code 0.1.459 → 0.1.460

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

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

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

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

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

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

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

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

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