@elytracms/studio 0.0.93 → 0.0.94

package/convex/ingest.test.ts

@@ -0,0 +1,326 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { z } from 'zod'
+import {
+  INGEST_MAX_BODY_BYTES,
+  INGEST_RECEIVER_PATH,
+  INGEST_SIGNATURE_HEADER,
+  signedIngestRequest,
+} from '@elytracms/core/ingest'
+import type { IngestHandlerResult, IngestPayload } from '@elytracms/core/ingest'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import schema from './schema'
+import { internalMutation } from './functions'
+import { defineStudioHttp } from './http'
+import { claimIngestUpload, ingestHandlerArgs, parseIngestPayload, recordIngestUpload, unclaimedIngestUploads } from './ingest'
+import type { IngestHandlerRef } from './ingest'
+import { saveRecord } from './record-functions'
+import { createIngestRoute } from '../../next/src/ingest'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2026-10-26T12:00:00.000Z'))
+})
+afterEach(() => {
+  vi.useRealTimers()
+  delete env()['ELYTRA_INGEST_SECRET']
+  delete env()['DRAFT_PREVIEW_TOKEN']
+})
+
+/**
+ * EC-617 — the ONE inbound receiver (`POST /elytra/ingest`, `defineStudioHttp`), on
+ * convex-test with a project-registered handler (a test module standing in for an addon's
+ * `./convex` entry): 401 unconfigured / unsigned / wrong secret, 413, 400, the probe, a
+ * kind with NO handler refused visibly (422 — EC-618's gate), a handler's write and its
+ * refusal relayed, the upload URL issued after the handler accepted, and the claim checks.
+ * Then the site's route (`createIngestRoute`) driven END TO END into this receiver.
+ *
+ * convex-test runs `crypto.subtle` under edge-runtime; that the Convex default runtime has
+ * it too is the operator's dev-deployment check (the revalidation signer already runs there).
+ */
+
+const SECRET = 'ec617-shared-secret'
+function env(): Record<string, string | undefined> {
+  return (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+}
+
+/** The submission an addon would declare (forms, EC-613) — here a test kind. */
+const testSubmissionKind = defineRecordKind({
+  kind: 'testSubmission',
+  module: 'testIngest',
+  keys: ['form'],
+  fields: {
+    form: z.string().min(1),
+    values: z.record(z.string(), z.unknown()),
+    files: z.array(z.string()).optional(),
+  },
+})
+
+/** The addon's handler module: one internal mutation, the shape `IngestHandlerRef` names. */
+const testIngestModule = {
+  handle: internalMutation({
+    args: ingestHandlerArgs,
+    handler: async (ctx, args): Promise<IngestHandlerResult> => {
+      const payload: IngestPayload = parseIngestPayload(args.payload)
+      if (payload.kind === 'upload') {
+        return recordIngestUpload(ctx, payload, args.receivedAt, { maxBytes: 1000, contentTypes: ['image/*'] })
+      }
+      if (payload.kind !== 'submission') return { ok: false, status: 422, message: 'Not a submission.' }
+      if (payload.target !== 'contact') return { ok: false, status: 404, message: `No form “${payload.target}”.` }
+      const files: string[] = []
+      for (const claim of payload.uploads ?? []) {
+        const claimed = await claimIngestUpload(ctx, claim, payload.target, args.receivedAt)
+        if (!claimed.ok) return claimed
+        files.push(claimed.storageId)
+      }
+      const id = `sub_${(await ctx.db.query('records').collect()).length + 1}`
+      await saveRecord(
+        ctx,
+        testSubmissionKind,
+        id,
+        { form: payload.target, values: payload.data, ...(files.length ? { files } : {}) },
+        { createdAt: args.receivedAt, updatedAt: args.receivedAt },
+      )
+      return { ok: true, id }
+    },
+  }),
+}
+
+const handle = makeFunctionReference<'mutation'>('testIngest:handle') as unknown as IngestHandlerRef
+const silentAuth = { addHttpRoutes: () => {} }
+
+function backend(handlers: Parameters<typeof defineStudioHttp>[0]['ingest'] = { submission: handle }) {
+  return convexTest(schema, {
+    ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+    './_generated/api.ts': async () => ({}),
+    './testIngest.ts': async () => testIngestModule,
+    './http.ts': async () => ({ default: defineStudioHttp({ auth: silentAuth, ingest: handlers }) }),
+  })
+}
+
+async function signedPost(t: ReturnType<typeof backend>, body: Parameters<typeof signedIngestRequest>[0], secret = SECRET) {
+  const signed = await signedIngestRequest(body, secret)
+  return t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', headers: signed.headers, body: signed.body })
+}
+
+const SUBMISSION = { kind: 'submission', target: 'contact', data: { email: 'ada@example.test' } } as const
+
+describe('the ingest receiver — refusals (EC-617)', () => {
+  it('401 { configured: false } while ELYTRA_INGEST_SECRET is unset — even for a signed body', async () => {
+    const t = backend()
+    const response = await signedPost(t, SUBMISSION)
+    expect(response.status).toBe(401)
+    expect(await response.json()).toMatchObject({ configured: false })
+  })
+
+  it('401 unsigned, or signed with another secret; control: the right secret is accepted', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const unsigned = await t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', body: JSON.stringify(SUBMISSION) })
+    expect(unsigned.status).toBe(401)
+    expect((await signedPost(t, SUBMISSION, 'wrong-secret')).status).toBe(401)
+    expect((await signedPost(t, SUBMISSION)).status).toBe(200)
+  })
+
+  it('413 over the body cap', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const big = JSON.stringify({ ...SUBMISSION, data: { note: 'x'.repeat(INGEST_MAX_BODY_BYTES) } })
+    const response = await t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', body: big })
+    expect(response.status).toBe(413)
+  })
+
+  it('400 for a signed body that is not an ingest payload', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const raw = JSON.stringify({ kind: 'submission' })
+    const { headers } = await signedIngestRequest({ kind: 'probe' }, SECRET) // headers for another body…
+    const badShape = await t.fetch(INGEST_RECEIVER_PATH, {
+      method: 'POST',
+      headers: { ...headers, [INGEST_SIGNATURE_HEADER]: (await signedIngestRequestRaw(raw)) },
+      body: raw,
+    })
+    expect(badShape.status).toBe(400)
+  })
+
+  it('the doctor’s signed probe answers 200 and dispatches nothing', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await signedPost(t, { kind: 'probe' })
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true, probe: true })
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
+
+  it('a kind with NO registered handler is refused visibly (422), never dropped — an event without analytics', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await signedPost(t, { kind: 'event', data: { page: '/' } })
+    expect(response.status).toBe(422)
+    expect(await response.json()).toMatchObject({ kind: 'event', handled: false })
+    // …and with NO handlers at all, a submission is refused the same way.
+    const bare = backend({})
+    expect((await signedPost(bare, SUBMISSION)).status).toBe(422)
+  })
+})
+
+/**
+ * Store a file as an upload URL would: Convex records the uploader's Content-Type on the
+ * `_storage` row; convex-test 0.0.54's `storage.store` records only size + sha256, so the
+ * harness sets the type the real upload would have carried.
+ */
+async function storeFile(t: ReturnType<typeof backend>, bytes: number, contentType: string) {
+  return t.run(async (ctx) => {
+    const id = await ctx.storage.store(new Blob([new Uint8Array(bytes)], { type: contentType }))
+    await (ctx.db as unknown as { patch(id: unknown, value: unknown): Promise<void> }).patch(id, { contentType })
+    return id
+  })
+}
+
+/** Sign an arbitrary raw body (for the invalid-shape case the typed builder refuses to build). */
+async function signedIngestRequestRaw(raw: string): Promise<string> {
+  const { signRevalidationBody } = await import('@elytracms/core/revalidation')
+  return signRevalidationBody(raw, SECRET)
+}
+
+describe('the key rule: a payload Convex cannot carry is a 400, never a failed mutation (EC-617)', () => {
+  /** POST a raw body signed with the right secret (the typed builder would refuse it). */
+  async function postRaw(t: ReturnType<typeof backend>, payload: unknown) {
+    const raw = JSON.stringify(payload)
+    return t.fetch(INGEST_RECEIVER_PATH, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', [INGEST_SIGNATURE_HEADER]: await signedIngestRequestRaw(raw) },
+      body: raw,
+    })
+  }
+
+  it('refuses a `$`-led key, a non-ASCII key and a nested one with 400 naming the key; nothing is dispatched', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    for (const data of [{ $honeypot: '' }, { straße: 'Hauptstraße 1' }, { address: { 'straße': 'x' } }]) {
+      const response = await postRaw(t, { ...SUBMISSION, data })
+      expect(response.status, JSON.stringify(data)).toBe(400)
+      const body = (await response.json()) as { issues: { path: (string | number)[]; message: string }[] }
+      expect(body.issues[0]!.path[0]).toBe('data')
+      expect(body.issues[0]!.message).toMatch(/field name/i)
+    }
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
+
+  it('refuses data nested deeper than Convex arguments carry, with 400', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    let deep: Record<string, unknown> = { leaf: 1 }
+    for (let level = 0; level < 80; level++) deep = { n: deep }
+    expect((await postRaw(t, { ...SUBMISSION, data: deep })).status).toBe(400)
+  })
+
+  it('control: printable-ASCII keys (spaces, dashes, dots included) reach the handler', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await postRaw(t, { ...SUBMISSION, data: { 'first name': 'Ada', 'e-mail': 'a@b.c', 'a.b': 1, honeypot$: '' } })
+    expect(response.status).toBe(200)
+  })
+})
+
+describe('the ingest receiver — dispatch (EC-617)', () => {
+  it('a submission reaches the project’s handler, which writes a record; its refusal is relayed', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const accepted = await signedPost(t, SUBMISSION)
+    expect(accepted.status).toBe(200)
+    expect(await accepted.json()).toEqual({ ok: true, id: 'sub_1' })
+    const stored = await t.run(async (ctx) => (await ctx.db.query('records').collect()).filter((r) => r.kind === 'testSubmission'))
+    expect(stored.map((row) => [row.recordId, row.key1, row.data])).toEqual([
+      ['sub_1', 'contact', { form: 'contact', values: { email: 'ada@example.test' } }],
+    ])
+    const refused = await signedPost(t, { ...SUBMISSION, target: 'closed' })
+    expect(refused.status).toBe(404)
+    expect(await refused.json()).toEqual({ error: 'No form “closed”.' })
+  })
+
+  it('an upload the handler accepts gets ONE storage URL and an upload id; one it refuses gets none', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const upload = { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 500 } as const
+    const issued = await signedPost(t, upload)
+    expect(issued.status).toBe(200)
+    const body = (await issued.json()) as { uploadId: string; uploadUrl: string; expiresInSeconds: number }
+    expect(body.uploadId).toMatch(/^upload_/)
+    expect(typeof body.uploadUrl).toBe('string')
+    expect(body.expiresInSeconds).toBe(3600)
+    expect((await signedPost(t, { ...upload, size: 5000 })).status).toBe(413) // the handler's policy
+    expect((await signedPost(t, { ...upload, contentType: 'application/x-msdownload' })).status).toBe(415)
+  })
+
+  it('a submission claims its upload: the stored file must match the declaration; a mismatch is deleted', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const declare = async (contentType: string, size: number) =>
+      ((await (await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType, size })).json()) as {
+        uploadId: string
+      }).uploadId
+    const good = await declare('image/png', 500)
+    const goodFile = await storeFile(t, 400, 'image/png')
+    const ok = await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: good, storageId: goodFile }] })
+    expect(ok.status).toBe(200)
+    // A second claim of the same upload is a conflict.
+    expect((await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: good, storageId: goodFile }] })).status).toBe(409)
+
+    const liar = await declare('image/png', 500)
+    const wrongType = await storeFile(t, 10, 'text/html')
+    expect((await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: liar, storageId: wrongType }] })).status).toBe(415)
+    expect(await t.run((ctx) => ctx.storage.get(wrongType))).toBeNull() // deleted, never kept
+  })
+
+  it('an upload no submission claims is listed once its life is over (the visible orphan finding)', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 10 })
+    const later = (offsetMs: number) => new Date(Date.parse('2026-10-26T12:00:00.000Z') + offsetMs).toISOString()
+    expect(await t.run((ctx) => unclaimedIngestUploads(ctx, 'contact', later(30 * 60 * 1000)))).toEqual([])
+    const orphans = await t.run((ctx) => unclaimedIngestUploads(ctx, 'contact', later(2 * 60 * 60 * 1000)))
+    expect(orphans.map((orphan) => orphan.field)).toEqual(['cv'])
+  })
+})
+
+describe('the site’s route → the receiver, end to end (EC-617)', () => {
+  it('a visitor’s submission through createIngestRoute lands a record; a mismatched site secret is a 502', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const viaReceiver = (async (url: string, init: RequestInit) =>
+      t.fetch(new URL(url).pathname, init as RequestInit)) as unknown as typeof fetch
+    const site = createIngestRoute({ secret: SECRET, siteUrl: 'https://happy-otter-123.convex.site', fetchImpl: viaReceiver })
+    const visitor = new Request('https://example.test/api/ingest', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', origin: 'https://example.test' },
+      body: JSON.stringify(SUBMISSION),
+    })
+    const answer = await site.POST(visitor)
+    expect(answer.status).toBe(200)
+    expect(await answer.json()).toEqual({ ok: true, id: 'sub_1' })
+
+    const misconfigured = createIngestRoute({ secret: 'not-the-same', siteUrl: 'https://happy-otter-123.convex.site', fetchImpl: viaReceiver })
+    const rejected = await misconfigured.POST(
+      new Request('https://example.test/api/ingest', { method: 'POST', body: JSON.stringify(SUBMISSION) }),
+    )
+    expect(rejected.status).toBe(502)
+  })
+})
+
+describe('draftSnapshot’s token check is the timing-safe helper (EC-617)', () => {
+  const draftSnapshot = makeFunctionReference<'query'>('delivery:draftSnapshot')
+
+  it('the right token reads; a wrong, a prefix or an empty token is unauthorized; unset closes it', async () => {
+    const t = backend()
+    await expect(t.query(draftSnapshot, { projectId: 'demo', token: 'x' })).rejects.toThrow(/not configured/)
+    env()['DRAFT_PREVIEW_TOKEN'] = 'preview-token-123'
+    await expect(t.query(draftSnapshot, { projectId: 'demo', token: 'preview-token-123' })).resolves.toMatchObject({
+      perspective: { variant: 'draft' },
+    })
+    for (const token of ['preview-token-124', 'preview-token-12', '', 'preview-token-1234']) {
+      await expect(t.query(draftSnapshot, { projectId: 'demo', token })).rejects.toThrow(/invalid draft preview token/)
+    }
+  })
+})

package/convex/ingest.ts

@@ -0,0 +1,281 @@
+import { httpActionGeneric, makeFunctionReference } from 'convex/server'
+import type { FunctionReference, PublicHttpAction } from 'convex/server'
+import { v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import { z } from 'zod'
+import {
+  INGEST_MAX_BODY_BYTES,
+  INGEST_MAX_UPLOAD_BYTES,
+  INGEST_SIGNATURE_HEADER,
+  INGEST_UPLOAD_TTL_MS,
+  ingestPayloadSchema,
+  readIngestReceiverBody,
+  verifyIngestSignature,
+} from '@elytracms/core/ingest'
+import type { IngestHandlerResult, IngestPayload, IngestUploadClaim } from '@elytracms/core/ingest'
+import { defineRecordKind, resolveRecordQuery } from '@elytracms/core/persistence'
+import { createUuidIdFactory } from '@elytracms/core/determinism'
+import type { MutationCtx, QueryCtx } from './functions'
+import { findRecordDoc, listRecordWire, saveRecord } from './record-functions'
+
+/**
+ * EC-617 — the ONE inbound receiver of the public ingest seam (ruling EC-565 § 6c), and the
+ * helpers an addon's ingest handler is written with. A factory module: it registers no
+ * function itself — `defineStudioHttp({ auth, ingest })` (`http.ts`) mounts
+ * {@link ingestReceiver} at `INGEST_RECEIVER_PATH` (`POST /elytra/ingest`, an exact path).
+ *
+ * The receiver, per request:
+ *
+ * 1. `ELYTRA_INGEST_SECRET` unset → 401 `{ configured: false }` — closed until configured;
+ * 2. body over `INGEST_MAX_BODY_BYTES` → 413;
+ * 3. the HMAC (`x-elytra-signature: sha256=…`) verified in constant time with the
+ *    deployment's secret → 401 on anything else (the site's route signs with the same
+ *    value, `INGEST_SECRET`);
+ * 4. the envelope (`@elytracms/core/ingest`) → 400 with its issues;
+ * 5. the doctor's `probe` → 200 `{ ok: true, probe: true }`, nothing dispatched;
+ * 6. dispatch by kind to the handler the PROJECT registered — `event` / `submission`, and
+ *    `upload` to the submission handler (uploads are submission-scoped). A kind with no
+ *    handler is REFUSED (422, naming the kind) — never dropped: an `event` with no
+ *    analytics addon must fail visibly (EC-618's counsel gate relies on it);
+ * 7. an accepted `upload` gets ONE short-lived storage URL (`ctx.storage.generateUploadUrl`)
+ *    — the bytes go browser → storage, cross-origin by design; the submission that follows
+ *    claims the stored file with {@link claimIngestUpload}, which checks it against what the
+ *    upload request declared.
+ *
+ * The engine never imports an addon: the handler is an internal-mutation REFERENCE the
+ * consumer passes in its one `http.ts` line (`defineStudioHttp({ auth, ingest: {
+ * submission: formsIngest } })`), exported by the addon's `./convex` entry.
+ */
+
+/** What an ingest handler receives: the verified, parsed payload and the receipt time. */
+export const ingestHandlerArgs = { payload: v.any(), receivedAt: v.string() }
+
+/** An addon's ingest handler: an INTERNAL mutation (never client-callable). */
+export type IngestHandlerRef = FunctionReference<
+  'mutation',
+  'internal',
+  { payload: IngestPayload; receivedAt: string },
+  IngestHandlerResult
+>
+
+/**
+ * Name an addon's ingest handler for `defineStudioHttp({ ingest })` — its internal mutation by
+ * its module path (`ingestHandler('forms:ingest')`), the way every engine function is
+ * addressed (a string ref resolved against the consumer's deployment, EC-223). An addon
+ * exports the result from its `./convex` entry so the consumer writes no string.
+ */
+export function ingestHandler(name: `${string}:${string}`): IngestHandlerRef {
+  return makeFunctionReference<'mutation'>(name) as unknown as IngestHandlerRef
+}
+
+/** The handlers a project registers, by payload kind (`upload` goes to `submission`). */
+export interface IngestHandlers {
+  event?: IngestHandlerRef
+  submission?: IngestHandlerRef
+}
+
+/** Re-validate a handler's `payload` argument (it crossed a function boundary as `v.any()`). */
+export function parseIngestPayload(payload: unknown): IngestPayload {
+  return ingestPayloadSchema.parse(payload)
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+  })
+}
+
+function ingestSecret(): string | undefined {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const value = env['ELYTRA_INGEST_SECRET']?.trim()
+  return value ? value : undefined
+}
+
+function utf8Length(text: string): number {
+  return new TextEncoder().encode(text).byteLength
+}
+
+/** The receiver `httpAction` (see the module header). */
+export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction {
+  return httpActionGeneric(async (ctx, request) => {
+    const secret = ingestSecret()
+    if (!secret) return json(401, { error: 'Ingest is not configured on this deployment.', configured: false })
+
+    const declared = Number(request.headers.get('content-length'))
+    if (Number.isFinite(declared) && declared > INGEST_MAX_BODY_BYTES) {
+      return json(413, { error: 'The payload is too large.' })
+    }
+    const raw = await request.text()
+    if (utf8Length(raw) > INGEST_MAX_BODY_BYTES) return json(413, { error: 'The payload is too large.' })
+
+    if (!(await verifyIngestSignature(raw, request.headers.get(INGEST_SIGNATURE_HEADER), secret))) {
+      return json(401, { error: 'Invalid or missing ingest signature.', configured: true })
+    }
+    const read = readIngestReceiverBody(raw)
+    if (!read.ok) return json(400, { error: read.message, ...(read.issues ? { issues: read.issues } : {}) })
+    const body = read.value
+    if (body.kind === 'probe') return json(200, { ok: true, probe: true })
+
+    const handlerKind = body.kind === 'upload' ? 'submission' : body.kind
+    const handler = handlers[handlerKind]
+    if (!handler) {
+      return json(422, {
+        error: `No handler is registered for "${body.kind}" ingest payloads on this deployment — install the addon that handles them and pass its handler to defineStudioHttp({ ingest }).`,
+        kind: body.kind,
+        handled: false,
+      })
+    }
+    const result = await ctx.runMutation(handler, { payload: body, receivedAt: new Date().toISOString() })
+    if (!result.ok) {
+      return json(result.status, { error: result.message, ...(result.issues ? { issues: result.issues } : {}) })
+    }
+    if (body.kind === 'upload') {
+      if (!result.uploadId) {
+        return json(500, { error: 'The submission handler accepted the upload but recorded no upload intent (recordIngestUpload).' })
+      }
+      const uploadUrl = await ctx.storage.generateUploadUrl()
+      return json(200, { ok: true, uploadId: result.uploadId, uploadUrl, expiresInSeconds: INGEST_UPLOAD_TTL_MS / 1000 })
+    }
+    return json(200, { ok: true, ...(result.id ? { id: result.id } : {}) })
+  })
+}
+
+// --- Submission-scoped uploads -------------------------------------------------------------
+//
+// The receiver issues a storage URL only for an upload a handler ACCEPTED and RECORDED as an
+// intent (`recordIngestUpload`); a submission CLAIMS it (`claimIngestUpload`), which checks the
+// stored file against the intent. Abuse is bounded by: the route's limiter and bot gate on every
+// URL issued, `INGEST_MAX_UPLOAD_BYTES` per file, the URL's one-hour life, the post-upload check
+// (an over-size or mistyped file is deleted, never kept), and the unclaimed intents an addon can
+// list (`unclaimedIngestUploads`) and surface. Convex returns the storage id to the uploader
+// only, so the bytes of an upload no submission ever claims cannot be located by the engine —
+// that is the documented residue, bounded by the limits above.
+
+/** The upload intent — an engine-internal record kind (no public functions). */
+export const ingestUploadRecordKind = defineRecordKind({
+  kind: 'ingestUpload',
+  module: 'ingest',
+  keys: ['target', 'state'],
+  time: 'issuedAt',
+  fields: {
+    target: z.string().min(1),
+    field: z.string().min(1),
+    contentType: z.string().min(1),
+    size: z.number().int().positive(),
+    state: z.enum(['issued', 'claimed', 'rejected']),
+    issuedAt: z.string().min(1),
+    storageId: z.string().optional(),
+  },
+})
+
+let mintUploadUuid: (() => string) | undefined
+
+export interface IngestUploadPolicy {
+  /** Largest accepted file in bytes (≤ `INGEST_MAX_UPLOAD_BYTES`). */
+  maxBytes?: number
+  /** Accepted content types (exact, or `image/*`-style prefixes). Absent → any. */
+  contentTypes?: readonly string[]
+}
+
+function typeAllowed(contentType: string, allowed: readonly string[] | undefined): boolean {
+  if (!allowed) return true
+  return allowed.some((entry) => (entry.endsWith('/*') ? contentType.startsWith(entry.slice(0, -1)) : entry === contentType))
+}
+
+/**
+ * Accept an `upload` payload under the handler's policy and record its intent. Returns the
+ * handler result to hand back to the receiver (`{ ok: true, uploadId }`, or a 413/415
+ * refusal). Call it from the submission handler's `upload` branch.
+ */
+export async function recordIngestUpload(
+  ctx: MutationCtx,
+  payload: Extract<IngestPayload, { kind: 'upload' }>,
+  receivedAt: string,
+  policy: IngestUploadPolicy = {},
+): Promise<IngestHandlerResult> {
+  const maxBytes = Math.min(policy.maxBytes ?? INGEST_MAX_UPLOAD_BYTES, INGEST_MAX_UPLOAD_BYTES)
+  if (payload.size > maxBytes) return { ok: false, status: 413, message: `The file is larger than ${maxBytes} bytes.` }
+  if (!typeAllowed(payload.contentType, policy.contentTypes)) {
+    return { ok: false, status: 415, message: `Files of type “${payload.contentType}” are not accepted here.` }
+  }
+  // EC-578: the one id factory (UUID v4 from crypto.getRandomValues) — never a clock or a counter.
+  mintUploadUuid ??= createUuidIdFactory()
+  const uploadId = `upload_${mintUploadUuid()}`
+  await saveRecord(
+    ctx,
+    ingestUploadRecordKind,
+    uploadId,
+    { ...payloadColumns(payload), state: 'issued', issuedAt: receivedAt },
+    { createdAt: receivedAt, updatedAt: receivedAt },
+  )
+  return { ok: true, uploadId }
+}
+
+function payloadColumns(payload: Extract<IngestPayload, { kind: 'upload' }>) {
+  return { target: payload.target, field: payload.field, contentType: payload.contentType, size: payload.size }
+}
+
+/** What a claim yields: the stored file's facts, or a refusal for the handler to return. */
+export type IngestUploadClaimResult =
+  | { ok: true; storageId: string; field: string; contentType: string; size: number }
+  | { ok: false; status: 409 | 413 | 415 | 422; message: string }
+
+/**
+ * Claim one upload for a submission to `target`: the intent must exist, be unclaimed,
+ * belong to `target`, be younger than `INGEST_UPLOAD_TTL_MS`, and the STORED file must match
+ * it (size ≤ declared, same content type). A mismatched file is deleted and the intent
+ * marked `rejected` — never kept.
+ */
+export async function claimIngestUpload(
+  ctx: MutationCtx,
+  claim: IngestUploadClaim,
+  target: string,
+  receivedAt: string,
+): Promise<IngestUploadClaimResult> {
+  const intent = await findRecordDoc(ctx, ingestUploadRecordKind, claim.uploadId)
+  const columns = intent?.data as
+    | { target: string; field: string; contentType: string; size: number; state: string; issuedAt: string }
+    | undefined
+  if (!columns || columns.target !== target) return { ok: false, status: 422, message: `Unknown upload “${claim.uploadId}”.` }
+  if (columns.state !== 'issued') return { ok: false, status: 409, message: `Upload “${claim.uploadId}” was already claimed.` }
+  if (Date.parse(receivedAt) - Date.parse(columns.issuedAt) > INGEST_UPLOAD_TTL_MS) {
+    return { ok: false, status: 422, message: `Upload “${claim.uploadId}” expired.` }
+  }
+  const storageId = claim.storageId as GenericId<'_storage'>
+  const file = await ctx.db.system.get(storageId).catch(() => null)
+  const stamps = { createdAt: receivedAt, updatedAt: receivedAt }
+  if (!file) return { ok: false, status: 422, message: `No stored file “${claim.storageId}”.` }
+  const refused =
+    file.size > columns.size
+      ? ({ status: 413, message: 'The stored file is larger than the upload declared.' } as const)
+      : (file.contentType ?? '') !== columns.contentType
+        ? ({ status: 415, message: 'The stored file is not of the declared type.' } as const)
+        : undefined
+  if (refused) {
+    await ctx.storage.delete(storageId)
+    await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'rejected', storageId: claim.storageId }, stamps)
+    return { ok: false, ...refused }
+  }
+  await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'claimed', storageId: claim.storageId }, stamps)
+  return { ok: true, storageId: claim.storageId, field: columns.field, contentType: columns.contentType, size: file.size }
+}
+
+/** Upload intents of `target` still unclaimed past their life — the visible orphan finding. */
+export async function unclaimedIngestUploads(
+  ctx: QueryCtx | MutationCtx,
+  target: string,
+  now: string,
+): Promise<{ uploadId: string; field: string; issuedAt: string }[]> {
+  const before = new Date(Date.parse(now) - INGEST_UPLOAD_TTL_MS).toISOString()
+  const rows = await listRecordWire(
+    ctx,
+    ingestUploadRecordKind,
+    resolveRecordQuery(ingestUploadRecordKind, { where: { target, state: 'issued' }, before }),
+  )
+  return rows.map((row) => ({
+    uploadId: String(row[ingestUploadRecordKind.idKey]),
+    field: String(row['field']),
+    issuedAt: String(row['issuedAt']),
+  }))
+}

package/convex/invites.ts

@@ -3,6 +3,7 @@ import { selectOrphanCredentialPurges } from '@elytracms/core/persistence'
 import { mutation, query } from './functions'
 import type { MutationCtx } from './functions'
 import { requireCapability } from './guard'
+import { assertAuthorityFloor, assertDeclaredRole } from './authority'
 
 /**
  * Invite allowlist management (EC-324). An admin invites an email + role; the
@@ -11,10 +12,14 @@ import { requireCapability } from './guard'
  * `requireCapability('project.administer')`, the same trust boundary as
  * member/user management; UI gating alone is never trusted.
  *
- * The invited `role` is validated against the active policy at the operations
- * write boundary (`invites.create` input); this store keeps it a lenient string
- * (schema-as-lens, EC-277). Keyed by normalized (lowercased) email; `create`
- * upserts so re-inviting the same email replaces the pending role.
+ * The invited `role` is validated against the project's policy at the operations
+ * write boundary (`invites.create`) AND here, against the DEPLOYED policy (EC-605 —
+ * `assertDeclaredRole`): an invite grants its role on consumption, so a role nobody
+ * declared must never be stored. Granting it is authority, so the integrity floor's
+ * "assign only roles you hold" applies too (`assertAuthorityFloor`, no target yet).
+ * The table keeps the role a lenient string (schema-as-lens, EC-277). Keyed by
+ * normalized (lowercased) email; `create` upserts so re-inviting the same email
+ * replaces the pending role.
  */
 
 const normalizeEmail = (email: string): string => email.trim().toLowerCase()
@@ -109,7 +114,10 @@ export const create = mutation({
     updatedAt: v.string(),
   },
   handler: async (ctx, args) => {
-    await requireCapability(ctx, 'project.administer')
+    const callerId = await requireCapability(ctx, 'project.administer')
+    // EC-605: only a declared role, and only one the inviter could grant themselves.
+    assertDeclaredRole(args.role)
+    await assertAuthorityFloor(ctx, { callerId, rolesGranted: [args.role], removesMembership: false })
     const email = normalizeEmail(args.email)
     // EC-358: never adopt orphan credentials — purge member-less auth rows for
     // this email atomically with the invite, so the invitee sets their own password.