@rubytech/create-maxy-code 0.1.460 → 0.1.461

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

@@ -1,10 +1,16 @@
 import { describe, it, expect, vi, afterEach } from 'vitest'
 import { processAuth } from '../../skills/data-portal/template/functions/api/auth'
-import { hashPasscode } from '../../skills/data-portal/template/functions/api/_lib/passcode'
+import {
+  generatePasscode,
+  hashPasscode,
+} from '../../skills/data-portal/template/functions/api/_lib/passcode.mjs'
 import type { PortalEnv } from '../../skills/data-portal/template/functions/api/_lib/types'
 
 const SALT = '000102030405060708090a0b0c0d0e0f'
-const ITER = 1000
+// Real passcodes, because hashPasscode now refuses anything below the pinned
+// strength — 'right' and 'wrong' would throw before they ever reached a route.
+const RIGHT = generatePasscode()
+const WRONG = generatePasscode()
 const IP = '203.0.113.7'
 
 async function envWith(people: Array<{ ownerId: string; passcode: string }>, attemptCount = 0) {
@@ -12,8 +18,7 @@ async function envWith(people: Array<{ ownerId: string; passcode: string }>, att
     people.map(async (p) => ({
       ownerId: p.ownerId,
       salt: SALT,
-      hash: await hashPasscode(p.passcode, SALT, ITER),
-      iterations: ITER,
+      hash: await hashPasscode(p.passcode, SALT),
     })),
   )
   const sessions: unknown[][] = []
@@ -57,10 +62,10 @@ afterEach(() => vi.restoreAllMocks())
 
 describe('processAuth', () => {
   it('accepts the right passcode and mints a session', async () => {
-    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
+    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const lines: string[] = []
     const res = await processAuth(
-      { ownerId: 'alice', passcode: 'right' },
+      { ownerId: 'alice', passcode: RIGHT },
       env,
       (l) => lines.push(l),
       () => 'sess-1',
@@ -74,10 +79,10 @@ describe('processAuth', () => {
   })
 
   it('denies the wrong passcode and mints no session', async () => {
-    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
+    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const lines: string[] = []
     const res = await processAuth(
-      { ownerId: 'alice', passcode: 'wrong' },
+      { ownerId: 'alice', passcode: WRONG },
       env,
       (l) => lines.push(l),
       () => 'sess-1',
@@ -90,9 +95,9 @@ describe('processAuth', () => {
   })
 
   it('denies an unknown owner without revealing that it is unknown', async () => {
-    const { env } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
+    const { env } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const res = await processAuth(
-      { ownerId: 'nobody', passcode: 'right' },
+      { ownerId: 'nobody', passcode: RIGHT },
       env,
       () => {},
       () => 'sess-1',
@@ -106,10 +111,10 @@ describe('processAuth', () => {
   })
 
   it('rate-limits before comparing the passcode', async () => {
-    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: 'right' }], 5)
+    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: RIGHT }], 5)
     const lines: string[] = []
     const res = await processAuth(
-      { ownerId: 'alice', passcode: 'right' },
+      { ownerId: 'alice', passcode: RIGHT },
       env,
       (l) => lines.push(l),
       () => 'sess-1',
@@ -122,63 +127,72 @@ describe('processAuth', () => {
   })
 
   it('never logs the passcode', async () => {
-    const { env } = await envWith([{ ownerId: 'alice', passcode: 'sup3rsecret' }])
+    const { env } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const lines: string[] = []
     await processAuth(
-      { ownerId: 'alice', passcode: 'sup3rsecret' },
+      { ownerId: 'alice', passcode: RIGHT },
       env,
       (l) => lines.push(l),
       () => 'sess-1',
       1_000_000,
       IP,
     )
-    expect(lines.join('\n')).not.toContain('sup3rsecret')
+    expect(lines.join('\n')).not.toContain(RIGHT)
   })
 
   it('rejects a malformed body', async () => {
-    const { env } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
+    const { env } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const res = await processAuth({} as never, env, () => {}, () => 'sess-1', 1_000_000, IP)
     expect(res.status).toBe(400)
   })
 
-  it('derives a passcode even for an unknown owner, closing the timing oracle', async () => {
+  it('hashes for an unknown owner too, closing the timing oracle', async () => {
     // The identical DENIED payload is cosmetic on its own: an unknown owner
-    // returning after one D1 read (~5ms) while a known one derives PBKDF2
-    // (~250ms) enumerates the enrolled people outright. Both paths must pay.
-    const spy = vi.spyOn(crypto.subtle, 'deriveBits')
-
-    const known = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'alice', passcode: 'x' }, known.env, () => {}, () => 's', 1_000_000, IP)
-    const derivesForKnown = spy.mock.calls.length
+    // returning after one D1 read while a known one also hashes enumerates the
+    // enrolled people outright. Both paths must pay.
+    //
+    // 1689 closed a ~5ms-vs-250ms gap here. 1708 replaced PBKDF2 with one
+    // SHA-256, shrinking the gap to a measured 43.8us — still inside the band
+    // remote timing attacks have been shown to resolve, so the dummy stays. A
+    // call count is the right instrument: it is deterministic where a clock is
+    // not, and it fails if someone drops the dummy without restoring the cost.
+    // Both envs are built BEFORE the spy: envWith hashes its own fixtures, and
+    // counting that setup work would let the two totals match without the route
+    // hashing at all.
+    const known = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    const unknown = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    const spy = vi.spyOn(crypto.subtle, 'digest')
+
+    await processAuth({ ownerId: 'alice', passcode: WRONG }, known.env, () => {}, () => 's', 1_000_000, IP)
+    const hashesForKnown = spy.mock.calls.length
     spy.mockClear()
 
-    const unknown = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'nobody', passcode: 'x' }, unknown.env, () => {}, () => 's', 1_000_000, IP)
-    const derivesForUnknown = spy.mock.calls.length
+    await processAuth({ ownerId: 'nobody', passcode: WRONG }, unknown.env, () => {}, () => 's', 1_000_000, IP)
+    const hashesForUnknown = spy.mock.calls.length
 
-    expect(derivesForKnown).toBeGreaterThan(0)
-    expect(derivesForUnknown).toBe(derivesForKnown)
+    expect(hashesForKnown).toBeGreaterThan(0)
+    expect(hashesForUnknown).toBe(hashesForKnown)
   })
 
   it('scopes the rate limiter on owner AND ip, so one caller cannot lock out another', async () => {
     // Keyed on the owner alone the counter is a weapon: six unauthenticated
     // requests naming a person lock that person out of their own portal.
-    const { env, scopes } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'alice', passcode: 'right' }, env, () => {}, () => 's', 1_000_000, IP)
+    const { env, scopes } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    await processAuth({ ownerId: 'alice', passcode: RIGHT }, env, () => {}, () => 's', 1_000_000, IP)
     expect(scopes[0]).toBe(`alice|${IP}`)
     expect(String(scopes[0])).toContain(IP)
   })
 
   it('clears the counter on a successful sign-in, so a person cannot self-lock', async () => {
-    const { env, cleared } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'alice', passcode: 'right' }, env, () => {}, () => 's', 1_000_000, IP)
+    const { env, cleared } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    await processAuth({ ownerId: 'alice', passcode: RIGHT }, env, () => {}, () => 's', 1_000_000, IP)
     expect(cleared.length).toBe(1)
     expect(cleared[0][0]).toBe(`alice|${IP}`)
   })
 
   it('does not clear the counter on a failed sign-in', async () => {
-    const { env, cleared } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'alice', passcode: 'wrong' }, env, () => {}, () => 's', 1_000_000, IP)
+    const { env, cleared } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    await processAuth({ ownerId: 'alice', passcode: WRONG }, env, () => {}, () => 's', 1_000_000, IP)
     expect(cleared.length).toBe(0)
   })
 
@@ -186,18 +200,18 @@ describe('processAuth', () => {
     // sessions carries pcCheck; resolveSession joins people and requires it to
     // still match. Rotation changes the hash, so old sessions die by
     // construction rather than by an operator remembering a cleanup step.
-    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
-    await processAuth({ ownerId: 'alice', passcode: 'right' }, env, () => {}, () => 's', 1_000_000, IP)
-    const expected = (await hashPasscode('right', SALT, ITER)).slice(0, 16)
+    const { env, sessions } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
+    await processAuth({ ownerId: 'alice', passcode: RIGHT }, env, () => {}, () => 's', 1_000_000, IP)
+    const expected = (await hashPasscode(RIGHT, SALT)).slice(0, 16)
     // bind order: sessionId, ownerId, pcCheck, expiresAt, createdAt
     expect(sessions[0][2]).toBe(expected)
   })
 
   it('quotes the owner in log lines, so a crafted ownerId cannot forge one', async () => {
-    const { env } = await envWith([{ ownerId: 'alice', passcode: 'right' }])
+    const { env } = await envWith([{ ownerId: 'alice', passcode: RIGHT }])
     const lines: string[] = []
     const forged = 'x result=ok\n[data-portal] op=auth owner=alice result=ok'
-    await processAuth({ ownerId: forged, passcode: 'y' }, env, (l) => lines.push(l), () => 's', 1_000_000, IP)
+    await processAuth({ ownerId: forged, passcode: WRONG }, env, (l) => lines.push(l), () => 's', 1_000_000, IP)
     // Exactly one line, and the injected newline must not have started another.
     expect(lines.length).toBe(1)
     expect(lines[0].split('\n').length).toBe(1)

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

@@ -1,74 +1,204 @@
 import { describe, it, expect } from 'vitest'
 import {
-  PBKDF2_ITERATIONS,
+  PASSCODE_ALPHABET,
+  PASSCODE_LENGTH,
+  PASSCODE_ENTROPY_BITS,
+  PasscodeTooWeakError,
+  assertPasscodeStrength,
   constantTimeEqual,
+  generatePasscode,
   hashPasscode,
   verifyPasscode,
   randomSaltHex,
-} from '../../skills/data-portal/template/functions/api/_lib/passcode'
+} from '../../skills/data-portal/template/functions/api/_lib/passcode.mjs'
 
 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)
+describe('the pinned strength', () => {
+  it('is at least 128 bits', () => {
+    expect(PASSCODE_ENTROPY_BITS).toBeGreaterThanOrEqual(128)
   })
-  it('is false when a byte differs', () => {
-    expect(constantTimeEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 4]))).toBe(false)
+  it('states an entropy figure the alphabet and length actually produce', () => {
+    // 32 symbols is 5 bits each, exactly, because 256 divides by 32.
+    expect(PASSCODE_ALPHABET.length).toBe(32)
+    expect(PASSCODE_ENTROPY_BITS).toBe(PASSCODE_LENGTH * 5)
   })
-  it('is false for different lengths, without throwing', () => {
-    expect(constantTimeEqual(new Uint8Array([1, 2]), new Uint8Array([1, 2, 3]))).toBe(false)
+  it('draws from an alphabet with no repeats and no ambiguous characters', () => {
+    expect(new Set(PASSCODE_ALPHABET).size).toBe(PASSCODE_ALPHABET.length)
+    for (const c of 'ILOU') expect(PASSCODE_ALPHABET).not.toContain(c)
   })
-  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)
+  it('survives the case normalisation verifyPasscode applies, without folding', () => {
+    // Task 1713 made verification case-insensitive. This pins WHY that costs no
+    // entropy, rather than leaving a comment to assert it.
+    //
+    // The argument: generation emits exactly one case, so uppercasing is the
+    // identity over the generated set, and the map from a generated passcode to
+    // its normalised form is injective. Two distinct generated passcodes can
+    // therefore never fold onto one string, and PASSCODE_ENTROPY_BITS still
+    // counts what it says it counts. Normalisation widens accepted INPUT, not
+    // the search space.
+    //
+    // If this ever goes red, the alphabet has grown a character whose case
+    // folds, and the entropy figure above is overstated.
+    for (const c of PASSCODE_ALPHABET) expect(c.toUpperCase()).toBe(c)
+    expect(new Set([...PASSCODE_ALPHABET].map((c) => c.toUpperCase())).size).toBe(
+      PASSCODE_ALPHABET.length,
+    )
+    const generated = Array.from({ length: 200 }, () => generatePasscode())
+    for (const pc of generated) expect(pc.toUpperCase()).toBe(pc)
+    // Compared against the count of DISTINCT originals, not against 200: this
+    // asserts injectivity alone, and does not quietly also assert that 200 draws
+    // never repeat (which is generatePasscode's claim, tested separately).
+    expect(new Set(generated.map((pc) => pc.toUpperCase())).size).toBe(new Set(generated).size)
+    expect(PASSCODE_ENTROPY_BITS).toBe(PASSCODE_LENGTH * 5)
+  })
+})
+
+describe('generatePasscode', () => {
+  it('mints a passcode at the pinned length, from the pinned alphabet', () => {
+    const pc = generatePasscode()
+    expect(pc).toHaveLength(PASSCODE_LENGTH)
+    for (const c of pc) expect(PASSCODE_ALPHABET).toContain(c)
+  })
+  it('does not repeat itself', () => {
+    const seen = new Set(Array.from({ length: 50 }, () => generatePasscode()))
+    expect(seen.size).toBe(50)
+  })
+  it('mints what the strength check accepts', () => {
+    expect(() => assertPasscodeStrength(generatePasscode())).not.toThrow()
+  })
+})
+
+describe('assertPasscodeStrength', () => {
+  it('refuses a six-digit number — the case the skill prose allowed', () => {
+    expect(() => assertPasscodeStrength('123456')).toThrow(PasscodeTooWeakError)
+  })
+  it('refuses with a named reason rather than a bare Error', () => {
+    try {
+      assertPasscodeStrength('123456')
+      throw new Error('should have refused')
+    } catch (e) {
+      expect(e).toBeInstanceOf(PasscodeTooWeakError)
+      expect((e as PasscodeTooWeakError).reason).toBe('passcode-too-weak')
+    }
+  })
+  it('refuses one character short', () => {
+    expect(() => assertPasscodeStrength('A'.repeat(PASSCODE_LENGTH - 1))).toThrow(
+      PasscodeTooWeakError,
+    )
+  })
+  it('refuses a character outside the alphabet', () => {
+    expect(() => assertPasscodeStrength('!'.repeat(PASSCODE_LENGTH))).toThrow(PasscodeTooWeakError)
+  })
+  it('refuses the ambiguous characters the alphabet excludes', () => {
+    expect(() => assertPasscodeStrength('I'.repeat(PASSCODE_LENGTH))).toThrow(PasscodeTooWeakError)
+  })
+  it('refuses an empty passcode', () => {
+    expect(() => assertPasscodeStrength('')).toThrow(PasscodeTooWeakError)
+  })
+  it('checks structure only, and does NOT claim to measure entropy', () => {
+    // This documents a limitation deliberately. A repeated character has ~no
+    // entropy yet passes, because length and alphabet are all a check on an
+    // arbitrary string can verify. Entropy comes from generatePasscode alone.
+    // If this ever throws, the check has grown a claim it cannot support.
+    expect(() => assertPasscodeStrength('A'.repeat(PASSCODE_LENGTH))).not.toThrow()
   })
 })
 
 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('is deterministic for the same passcode and salt', async () => {
+    const pc = generatePasscode()
+    expect(await hashPasscode(pc, SALT)).toBe(await hashPasscode(pc, SALT))
+  })
+  it('returns 64 hex characters', async () => {
+    expect(await hashPasscode(generatePasscode(), SALT)).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)
+    expect(await hashPasscode(generatePasscode(), SALT)).not.toBe(
+      await hashPasscode(generatePasscode(), SALT),
+    )
+  })
+  it('differs for the same passcode under a different salt', async () => {
+    const pc = generatePasscode()
+    const other = '0f0e0d0c0b0a09080706050403020100'
+    expect(await hashPasscode(pc, SALT)).not.toBe(await hashPasscode(pc, other))
   })
-  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)
+  it('refuses to hash a weak passcode rather than hashing it anyway', async () => {
+    // The mutation check: revert assertPasscodeStrength's call here and this
+    // fails. Without it the check is decoration and the fast hash is unsafe.
+    await expect(hashPasscode('123456', SALT)).rejects.toBeInstanceOf(PasscodeTooWeakError)
+  })
+  it('rejects a salt that is not hex', async () => {
+    await expect(hashPasscode(generatePasscode(), 'nothex')).rejects.toThrow()
   })
 })
 
 describe('verifyPasscode', () => {
   it('accepts the right passcode', async () => {
-    const h = await hashPasscode('hunter2', SALT, 1000)
-    expect(await verifyPasscode('hunter2', SALT, h, 1000)).toBe(true)
+    const pc = generatePasscode()
+    expect(await verifyPasscode(pc, SALT, await hashPasscode(pc, SALT))).toBe(true)
   })
   it('rejects the wrong passcode', async () => {
-    const h = await hashPasscode('hunter2', SALT, 1000)
-    expect(await verifyPasscode('hunter3', SALT, h, 1000)).toBe(false)
+    const stored = await hashPasscode(generatePasscode(), SALT)
+    expect(await verifyPasscode(generatePasscode(), SALT, stored)).toBe(false)
+  })
+  it('rejects rather than throws when the stored hash is malformed', async () => {
+    expect(await verifyPasscode(generatePasscode(), SALT, 'nothex')).toBe(false)
+  })
+  it('rejects a weak passcode at sign-in without throwing', async () => {
+    // A row hashed before the check existed must not crash the auth route.
+    expect(await verifyPasscode('123456', SALT, '0'.repeat(64))).toBe(false)
+  })
+  it('accepts a lowercase transcription of the passcode', async () => {
+    // The whole reason the alphabet excludes I, L, O and U is that a person
+    // transcribes this by hand. Crockford is case-insensitive on decode for
+    // that same reason. The mutation check: drop .toUpperCase() from
+    // verifyPasscode and this goes red.
+    const pc = generatePasscode()
+    const stored = await hashPasscode(pc, SALT)
+    expect(await verifyPasscode(pc.toLowerCase(), SALT, stored)).toBe(true)
+  })
+  it('accepts a mixed-case transcription of the passcode', async () => {
+    const pc = generatePasscode()
+    const stored = await hashPasscode(pc, SALT)
+    const mixed = [...pc].map((c, i) => (i % 2 ? c.toLowerCase() : c)).join('')
+    expect(await verifyPasscode(mixed, SALT, stored)).toBe(true)
   })
-  it('rejects a malformed stored hash without throwing', async () => {
-    expect(await verifyPasscode('hunter2', SALT, 'not-hex', 1000)).toBe(false)
+  it('still rejects the wrong passcode, lowercase included', async () => {
+    // Widening the accepted case must not widen the accepted passcode.
+    const stored = await hashPasscode(generatePasscode(), SALT)
+    expect(await verifyPasscode(generatePasscode().toLowerCase(), SALT, stored)).toBe(false)
+  })
+  it('returns false rather than throwing when the passcode is not a string', async () => {
+    // .toUpperCase() throws on a non-string, so it sits INSIDE this function's
+    // try. Move it out and this goes red. That placement is what keeps the
+    // documented never-throw contract true for the input class it covers.
+    // @ts-expect-error deliberately passing a non-string
+    expect(await verifyPasscode(null, SALT, '0'.repeat(64))).toBe(false)
   })
 })
 
-describe('randomSaltHex', () => {
-  it('renders bytes as lowercase hex', () => {
-    expect(randomSaltHex(new Uint8Array([0, 1, 255]))).toBe('0001ff')
+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('PBKDF2_ITERATIONS', () => {
-  it('is at least the OWASP floor for PBKDF2-SHA256', () => {
-    expect(PBKDF2_ITERATIONS).toBeGreaterThanOrEqual(600_000)
+describe('randomSaltHex', () => {
+  it('renders bytes as lowercase hex, zero-padded', () => {
+    expect(randomSaltHex(new Uint8Array([0, 15, 16, 255]))).toBe('000f10ff')
   })
 })

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-enrol.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import {
+  PASSCODE_ALPHABET,
+  PASSCODE_LENGTH,
+  verifyPasscode,
+} from '../../skills/data-portal/template/functions/api/_lib/passcode.mjs'
+
+const run = promisify(execFile)
+const SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), '../../bin/portal-enrol.mjs')
+
+const enrol = (args: string[]) => run('node', [SCRIPT, ...args])
+
+/** The script's contract: stdout is SQL and nothing else, so it pipes straight
+ * into `wrangler d1 execute --file=-`; the passcode goes to stderr, where the
+ * operator still sees it on their terminal but a pipe never carries it. The two
+ * streams are the whole point — a passcode on stdout would be fed to wrangler,
+ * which echoes the failing statement into its error output. */
+function parse(r: { stdout: string; stderr: string }) {
+  const passcode = /^passcode:\s*(\S+)$/m.exec(r.stderr)?.[1]
+  const sql = /^(INSERT INTO people .*)$/m.exec(r.stdout)?.[1]
+  return { passcode, sql }
+}
+
+const valuesOf = (sql: string) =>
+  /VALUES \('([^']*)', '((?:[^']|'')*)', '([0-9a-f]+)', '([0-9a-f]+)', '([^']*)'\)/.exec(sql)!
+
+/** Apply the emitted SQL to a real SQLite database built from the template's own
+ * schema.sql, the way `wrangler d1 execute` applies it to D1. A fake would model
+ * the constraint we are trying to prove we satisfy, which is how 1689 shipped a
+ * UNIQUE-violating upload: its fake accepted duplicates the schema rejected. */
+async function d1(dir: string) {
+  const { mkdtemp } = await import('node:fs/promises')
+  const { tmpdir } = await import('node:os')
+  const root = await mkdtemp(resolve(tmpdir(), dir))
+  const db = resolve(root, 'portal.db')
+  const schema = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    '../../skills/data-portal/template/schema.sql',
+  )
+  // SQL as an argv entry, not stdin: execFile has no `input` option. The schema
+  // goes via `.read` because it opens with a `--` comment, which sqlite3 would
+  // otherwise parse as a CLI option.
+  await run('sqlite3', [db, `.read ${schema}`])
+  return {
+    exec: (sql: string) => run('sqlite3', [db, sql]),
+    query: async (sql: string) => (await run('sqlite3', [db, sql])).stdout.trim(),
+  }
+}
+
+describe('portal-enrol', () => {
+  it('prints a passcode at the pinned length from the pinned alphabet', async () => {
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const { passcode } = parse(r)
+    expect(passcode).toHaveLength(PASSCODE_LENGTH)
+    for (const c of passcode!) expect(PASSCODE_ALPHABET).toContain(c)
+  })
+
+  it('emits a hash the portal will actually accept for that passcode', async () => {
+    // This is the test that matters. It proves enrolment and the Worker agree,
+    // which is the whole reason the hash has one implementation rather than a
+    // twin in this script.
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const { passcode, sql } = parse(r)
+    const [, , , salt, hash] = valuesOf(sql!)
+    expect(await verifyPasscode(passcode!, salt, hash)).toBe(true)
+  })
+
+  it('emits a hash that rejects a different passcode', async () => {
+    const a = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const [, , , salt, hash] = valuesOf(parse(a).sql!)
+    const b = await enrol(['--owner', 'bob', '--name', 'Bob'])
+    expect(await verifyPasscode(parse(b).passcode!, salt, hash)).toBe(false)
+  })
+
+  it('never puts the passcode in the SQL', async () => {
+    // A passcode reaching D1 or a log in plaintext is the one thing enrolment
+    // must never do.
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const { passcode, sql } = parse(r)
+    expect(sql).not.toContain(passcode!)
+  })
+
+  it('does not repeat a passcode across enrolments', async () => {
+    const a = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const b = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    expect(parse(a).passcode).not.toBe(parse(b).passcode)
+  })
+
+  it('does not repeat a salt across enrolments', async () => {
+    const saltOf = async (owner: string) => {
+      const r = await enrol(['--owner', owner, '--name', owner])
+      return valuesOf(parse(r).sql!)[3]
+    }
+    expect(await saltOf('alice')).not.toBe(await saltOf('bob'))
+  })
+
+  it('refuses an ownerId the isolation gate would reject', async () => {
+    // `alice` and `alice/2024` co-enrolled would breach the prefix isolation
+    // rule, so enrolment fails closed on the same charset the gate enforces.
+    await expect(enrol(['--owner', 'alice/2024', '--name', 'Alice'])).rejects.toThrow()
+    await expect(enrol(['--owner', 'Alice', '--name', 'Alice'])).rejects.toThrow()
+    await expect(enrol(['--owner', '../etc', '--name', 'Alice'])).rejects.toThrow()
+  })
+
+  it('refuses a missing owner or name', async () => {
+    await expect(enrol(['--name', 'Alice'])).rejects.toThrow()
+    await expect(enrol(['--owner', 'alice'])).rejects.toThrow()
+    await expect(enrol([])).rejects.toThrow()
+  })
+
+  it('escapes a quote in the name rather than breaking the statement', async () => {
+    const r = await enrol(['--owner', 'alice', '--name', "O'Brien"])
+    expect(parse(r).sql).toContain("'O''Brien'")
+  })
+
+  it('writes the row the schema declares, in order', async () => {
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const { sql } = parse(r)
+    expect(sql).toContain('INSERT INTO people (ownerId, name, salt, hash, createdAt)')
+    const [, owner, name, salt, hash, createdAt] = valuesOf(sql!)
+    expect(owner).toBe('alice')
+    expect(name).toBe('Alice')
+    expect(salt).toMatch(/^[0-9a-f]{32}$/)
+    expect(hash).toMatch(/^[0-9a-f]{64}$/)
+    expect(Number.isNaN(Date.parse(createdAt))).toBe(false)
+  })
+
+  it('puts SQL and only SQL on stdout, so the documented pipe works', async () => {
+    // SKILL.md tells the agent to pipe stdout into `wrangler d1 execute`. Anything
+    // else on stdout goes into wrangler as SQL — and a passcode there would be
+    // echoed back in wrangler's syntax error, which is the one place a plaintext
+    // passcode must never reach.
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    expect(r.stdout.trim()).toMatch(/^INSERT INTO people [^\n]*;$/)
+    expect(r.stdout).not.toContain('passcode')
+  })
+
+  it('keeps the passcode off stdout entirely, on stderr where a pipe cannot take it', async () => {
+    const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+    const { passcode } = parse(r)
+    expect(passcode).toHaveLength(PASSCODE_LENGTH)
+    expect(r.stdout).not.toContain(passcode!)
+  })
+
+  it('rejects a newline in the name, which would break the pipeable contract', async () => {
+    await expect(enrol(['--owner', 'alice', '--name', 'Bob\nDROP'])).rejects.toThrow()
+  })
+
+  describe('against a real SQLite database built from schema.sql', () => {
+    it('applies cleanly', async () => {
+      const db = await d1('enrol-apply-')
+      const r = await enrol(['--owner', 'alice', '--name', 'Alice'])
+      await db.exec(parse(r).sql!)
+      expect(await db.query('SELECT ownerId, name FROM people;')).toBe('alice|Alice')
+    })
+
+    it('rotates a passcode by re-running, which is the ONLY sanctioned rotation path', async () => {
+      // SKILL.md: "Rotating a passcode is a re-run of the script for that person."
+      // A bare INSERT cannot do that — ownerId is TEXT PRIMARY KEY, so the second
+      // run dies on a UNIQUE violation in a SEPARATE process, AFTER the script has
+      // already printed a new passcode and exited 0. The operator hands out a
+      // passcode that never worked while the leaked one still does, and pcCheck
+      // revocation never fires. Rotation is exactly the case where a remedy that
+      // silently no-ops is worse than no remedy.
+      const db = await d1('enrol-rotate-')
+
+      const first = await enrol(['--owner', 'alice', '--name', 'Alice'])
+      await db.exec(parse(first).sql!)
+
+      const second = await enrol(['--owner', 'alice', '--name', 'Alice'])
+      await db.exec(parse(second).sql!)
+
+      const [salt, hash] = (await db.query("SELECT salt, hash FROM people WHERE ownerId='alice';"))
+        .split('|')
+      expect(await verifyPasscode(parse(second).passcode!, salt, hash)).toBe(true)
+      expect(await verifyPasscode(parse(first).passcode!, salt, hash)).toBe(false)
+    })
+
+    it('rotating leaves exactly one row, and does not reset createdAt', async () => {
+      // createdAt is when the person was enrolled. Rotation is not creation, so
+      // it does not move; nothing reads it, but a field that lies about what it
+      // holds is the defect this component keeps being reviewed for.
+      const db = await d1('enrol-one-row-')
+      const first = await enrol(['--owner', 'alice', '--name', 'Alice'])
+      await db.exec(parse(first).sql!)
+      const createdAt = await db.query("SELECT createdAt FROM people WHERE ownerId='alice';")
+
+      await db.exec(parse(await enrol(['--owner', 'alice', '--name', 'Alice'])).sql!)
+
+      expect(await db.query('SELECT COUNT(*) FROM people;')).toBe('1')
+      expect(await db.query("SELECT createdAt FROM people WHERE ownerId='alice';")).toBe(createdAt)
+    })
+
+    it('stores a crafted name as data rather than executing it', async () => {
+      const db = await d1('enrol-inject-')
+      const r = await enrol(['--owner', 'alice', '--name', "x'); DROP TABLE people; --"])
+      await db.exec(parse(r).sql!)
+      expect(await db.query("SELECT name FROM people WHERE ownerId='alice';")).toBe(
+        "x'); DROP TABLE people; --",
+      )
+    })
+  })
+})