@elytracms/studio 0.0.93 → 0.0.94

package/convex/auth.ts

@@ -4,8 +4,9 @@ import { actionGeneric } from 'convex/server'
 import type { AnyDataModel, GenericMutationCtx } from 'convex/server'
 import { ConvexError, v } from 'convex/values'
 import type { GenericId } from 'convex/values'
-import { classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
+import { bootstrapRole, classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
 import type { InviteSignupDecision } from '@elytracms/core/persistence'
+import { deployedRolePolicy } from './roles'
 
 /** The provider list `convexAuth` accepts, derived from its own signature. */
 type ConvexAuthProviders = Parameters<typeof convexAuth>[0]['providers']
@@ -210,7 +211,9 @@ export async function gateSessionCreation(
     case 'bootstrap-admin':
       await ctx.db.insert('members', {
         userId: args.userId,
-        role: 'admin',
+        // EC-605: the deployed policy's strongest role (which the policy rules require
+        // to grant `project.administer`) — `admin` under the default policy.
+        role: bootstrapRole(deployedRolePolicy()),
         createdAt: now,
         updatedAt: now,
       })

package/convex/authority.ts

@@ -1,12 +1,14 @@
 import { checkAuthorityFloor } from '@elytracms/core/operations'
 import {
   buildAuthorityAuditEntry,
-  defaultRolePolicy,
+  isKnownRole,
+  policyRoleIds,
   roleGrantsCapability,
 } from '@elytracms/core/persistence'
 import type { AuthorityAuditOutcome, ProjectRole } from '@elytracms/core/persistence'
 import type { MutationCtx } from './functions'
 import { memberRole, type GuardCtx } from './guard'
+import { deployedRolePolicy } from './roles'
 
 /**
  * The engine integrity FLOOR at the Convex trust boundary (EC-240 / AD-18 tenet
@@ -16,9 +18,10 @@ import { memberRole, type GuardCtx } from './guard'
  * invariants on authority-mutating handlers (`members:set`, `members:remove` —
  * and therefore `users.save`/`users.remove`, which delegate to them):
  *
- * - **(a) assign only roles you hold** — future-proofs the boundary for when
- *   policy opens member-management to non-admins; today an administrator can
- *   grant any role, so this never fires under the default policy.
+ * - **(a) assign only roles you hold** — never fires under the default policy (the
+ *   only administrator, `admin`, is the strongest role); under a declared policy
+ *   with an administering role below the strongest (EC-605) it is what stops that
+ *   role granting — or inviting someone into (`invites:create`) — a rank above its own.
  * - **(b) the last admin can't be removed or demoted** — the hole this closes:
  *   before EC-240 the handlers did a blind upsert/delete, so an admin could
  *   remove the sole admin and lock everyone out (the empty-table bootstrap in
@@ -27,28 +30,32 @@ import { memberRole, type GuardCtx } from './guard'
  * The decision logic is the ONE shared `checkAuthorityFloor` primitive that the
  * engine resolver also calls — this file only supplies the primitives it reads
  * from `ctx.db`, so client and server can never drift. Denials throw
- * `unauthorized: …`, matching the guard convention.
+ * `unauthorized: …`, matching the guard convention. The policy is the deployment's
+ * (EC-605, `deployedRolePolicy`) — the one `requireCapability` granted by.
  */
 export async function assertAuthorityFloor(
   ctx: GuardCtx,
   params: {
     /** The caller (already `requireCapability('project.administer')`-checked). */
     readonly callerId: string
-    /** The member whose role/membership this op changes. */
-    readonly targetUserId: string
+    /**
+     * The member whose role/membership this op changes; absent for an invite (EC-605 —
+     * it grants a role to someone who is not a member yet, so only (a) can apply).
+     */
+    readonly targetUserId?: string
     /** Roles this op grants the target (empty for a pure removal). */
     readonly rolesGranted: readonly ProjectRole[]
     /** True when the op removes the membership entirely. */
     readonly removesMembership: boolean
   },
 ): Promise<void> {
+  const policy = deployedRolePolicy()
   const callerRole = await memberRole(ctx, params.callerId)
-  const targetRole = await memberRole(ctx, params.targetUserId)
+  const targetRole = params.targetUserId !== undefined ? await memberRole(ctx, params.targetUserId) : null
   const members = await ctx.db.query('members').collect()
   // "admin" generalizes to "grants project.administer" (EC-240c) — the same
   // policy the engine resolver uses, so client and server can never drift.
-  const isAdministrator = (role: string) =>
-    roleGrantsCapability(role, 'project.administer', defaultRolePolicy)
+  const isAdministrator = (role: string) => roleGrantsCapability(role, 'project.administer', policy)
   const adminCount = members.filter((m) => isAdministrator(m.role)).length
 
   const decision = checkAuthorityFloor(
@@ -59,11 +66,28 @@ export async function assertAuthorityFloor(
       removesMembership: params.removesMembership,
       adminCount,
     },
-    defaultRolePolicy,
+    policy,
   )
   if (!decision.allow) throw new Error(`unauthorized: ${decision.reason}`)
 }
 
+/**
+ * EC-605 — refuse a role the deployed policy does not declare, at the WRITE (a member's
+ * role, an invite's role), visibly: `invalid-role: …` naming the declared set. The
+ * studio validates against the project's config first; this is the trust boundary's own
+ * check, so a hand-crafted client or a drifted deployment can never store a role nobody
+ * can enforce (an unknown role grants nothing — it would fail closed on every read,
+ * silently).
+ */
+export function assertDeclaredRole(role: string): void {
+  const policy = deployedRolePolicy()
+  if (!isKnownRole(role, policy)) {
+    throw new Error(
+      `invalid-role: role "${role}" is not declared in this deployment's role policy (declared: ${policyRoleIds(policy).join(', ')}). Declare it in elytra.config.ts \`roles\` and re-provision (\`elytra init\`), or pick a declared role.`,
+    )
+  }
+}
+
 /**
  * Append one {@link buildAuthorityAuditEntry} row to the `authorityAudit` table
  * (EC-240 H-tail item 6). Called at the floor chokepoint (`members:set` /

package/convex/contract-parity.test.ts

@@ -4,6 +4,7 @@ import type { ConvexHttpClient } from 'convex/browser'
 import type { FunctionReference } from 'convex/server'
 import { fieldPath, measureMaxDepth, nodePropPath } from '@elytracms/core/cms-core'
 import {
+  CONTRACT_RECORD_KINDS,
   PERSISTENCE_CONTRACT_SCENARIOS,
   publishCurrentDraft,
   replaceAtCurrentRevision,
@@ -12,6 +13,7 @@ import type { ContractContext } from '@elytracms/core/persistence'
 import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
 import type { ReactiveDocumentClient } from '../src/lib/persistence/convex-client'
 import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
 
 /**
  * EC-454 — Convex-side contract parity, restored.
@@ -40,6 +42,11 @@ import schema from './schema'
 const modules = {
   ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
   './_generated/api.ts': async () => ({}),
+  // EC-616: the contract's FIXTURE record kinds, registered as test-only modules exactly as
+  // an addon's convex module registers its kind (one module per kind, named by the kind).
+  ...Object.fromEntries(
+    CONTRACT_RECORD_KINDS.map((kind) => [`./${kind.module}.ts`, async () => defineRecordFunctions(kind)]),
+  ),
 }
 
 /** The config-owned slug this deployment's records are stamped with (EC-179). */

package/convex/delivery.ts

@@ -1,12 +1,14 @@
 import { v } from 'convex/values'
-import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, unfoldValue, variantOf } from '@elytracms/core/cms-core'
+import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, liveRedirectRecords, unfoldValue, variantOf } from '@elytracms/core/cms-core'
 import type { Perspective } from '@elytracms/core/cms-core'
 import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
+import { constantTimeEquals } from '@elytracms/core/revalidation'
 import type { AssetRecord } from '@elytracms/core/persistence'
 import studioPackage from '../package.json'
 import { query } from './functions'
 import type { QueryCtx } from './functions'
 import { requireCapability } from './guard'
+import { loadRedirectEntries } from './redirects'
 
 // EC-207: routes/redirects are config-sourced (authored in elytra.config.ts and
 // resolved by studio-core), NOT backend data. The delivery snapshot no longer
@@ -156,13 +158,12 @@ export async function loadSnapshot(
 
   const assets = await loadDeliveryAssets(ctx, projectId)
 
-  // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect
-  // is stored but never live, in either perspective. Projected to the routing
-  // `RedirectRecord` shape the router/`resolvePage` consume.
-  const redirectRows = await ctx.db.query('redirects').withIndex('by_redirect').collect()
-  const redirects = redirectRows
-    .filter((row) => row.enabled)
-    .map((row) => ({ id: row.redirectId, from: row.from, to: row.to, permanent: row.permanent }))
+  // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect is
+  // stored but never live, in either perspective. EC-616: read through the redirect
+  // kind's one server-side reader (records + the marked legacy tolerant read) and
+  // projected by the ONE enabled-redirect reader, `liveRedirectRecords` (EC-590 / EC-627 —
+  // this was the last hand-built copy on Convex).
+  const redirects = liveRedirectRecords(await loadRedirectEntries(ctx, projectId))
 
   return {
     projectId,
@@ -214,7 +215,9 @@ export const draftSnapshot = query({
     if (expected === undefined || expected.length === 0) {
       throw new Error('unauthorized: draft preview is not configured on this deployment')
     }
-    if (args.token !== expected) {
+    // EC-617: the one timing-safe comparison (`constantTimeEquals`, the MAC-compare the
+    // revalidation and ingest verifiers rest on) — never a string `!==`.
+    if (!(await constantTimeEquals(args.token, expected))) {
       throw new Error('unauthorized: invalid draft preview token')
     }
     return loadSnapshot(ctx, { projectId: args.projectId }, DRAFT_PERSPECTIVE)

package/convex/guard.ts

@@ -1,7 +1,8 @@
 import { getAuthUserId } from '@convex-dev/auth/server'
-import { defaultRolePolicy, roleGrantsCapability } from '@elytracms/core/persistence'
+import { roleGrantsCapability } from '@elytracms/core/persistence'
 import type { OperationCapabilityId, ProjectRole, RolePolicy } from '@elytracms/core/persistence'
 import type { QueryCtx } from './functions'
+import { deployedRolePolicy } from './roles'
 
 /**
  * Server-side authorization guards (EC-150). The operations chokepoint in the
@@ -18,9 +19,10 @@ import type { QueryCtx } from './functions'
  * imported here rather than re-declared. Handlers gate on CAPABILITIES
  * (`content.read` / `content.write` / `project.administer`), not literal roles
  * (EC-240c), so a project's custom role set enforces server-side by the same
- * policy the operations layer uses. The Convex trust boundary reads the shipped
- * {@link defaultRolePolicy}; a project overriding roles injects its policy (the
- * documented follow-up seam).
+ * policy the operations layer uses. EC-605: the policy is the project's `roles`
+ * declaration as DEPLOYED — the copy the `elytra` CLI provisions into
+ * `ELYTRA_ROLE_POLICY` (`./roles` `deployedRolePolicy`: the default when unset, a
+ * thrown, located error when malformed — never a silent default).
  *
  * Failures throw plain `Error('unauthorized: …')` — Convex transports the
  * message; the app's adapters normalize thrown backend errors onto the
@@ -78,13 +80,13 @@ export async function memberRole(ctx: GuardCtx, userId: string): Promise<Project
  * This is the ONE role-enforcement primitive at the trust boundary — every
  * handler gates on a capability rather than a literal role, so a project's
  * custom role set is honoured by the shared policy. `policy` defaults to the
- * shipped {@link defaultRolePolicy}; the override seam (a project injecting its
- * own policy) is the documented follow-up.
+ * deployment's policy (EC-605, {@link deployedRolePolicy}); the parameter stays for a
+ * caller that must judge against another (tests).
  */
 export async function requireCapability(
   ctx: GuardCtx,
   capability: OperationCapabilityId,
-  policy: RolePolicy = defaultRolePolicy,
+  policy: RolePolicy = deployedRolePolicy(),
 ): Promise<string> {
   const userId = await requireUserId(ctx)
   const actual = await memberRole(ctx, userId)

package/convex/http-routes.test.ts

@@ -33,9 +33,20 @@ function routeTable(http: HttpRouter): string[] {
     .sort()
 }
 
-describe('defineStudioHttp — the engine registers no HTTP routes of its own (EC-481)', () => {
-  it('contributes an EMPTY route table beyond what the injected auth registers', () => {
-    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual([])
+/** EC-617: the engine's ONE route — the public-ingest receiver, an exact path (the EC-481 bar: a real client, a narrow prefix). */
+const ENGINE_ROUTES = ['POST /elytra/ingest']
+
+describe('defineStudioHttp — the engine registers exactly one HTTP route of its own (EC-481 → EC-617)', () => {
+  it('contributes ONLY the ingest receiver beyond what the injected auth registers', () => {
+    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual(ENGINE_ROUTES)
+  })
+
+  it('the receiver is an EXACT path, POST only — it claims no prefix', () => {
+    const http = defineStudioHttp({ auth: silentAuth })
+    expect(http.lookup('/elytra/ingest', 'POST')).not.toBeNull()
+    expect(http.lookup('/elytra/ingest/anything', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/ingest', 'GET')).toBeNull()
   })
 
   it('control: the recorder DOES see routes, so the empty result above is real', () => {
@@ -45,10 +56,9 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         http.route({ pathPrefix: '/api/auth/callback/', method: 'POST', handler })
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([
-      'GET /.well-known/jwks.json',
-      'POST /api/auth/callback/*',
-    ])
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual(
+      ['GET /.well-known/jwks.json', 'POST /api/auth/callback/*', ...ENGINE_ROUTES].sort(),
+    )
   })
 
   it('passes the auth routes through untouched — nothing is added, dropped, or reordered', () => {
@@ -61,7 +71,7 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         }
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered].sort())
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered, ...ENGINE_ROUTES].sort())
   })
 })
 

package/convex/http.ts

@@ -1,5 +1,8 @@
 import { httpRouter } from 'convex/server'
 import type { HttpRouter } from 'convex/server'
+import { INGEST_RECEIVER_PATH } from '@elytracms/core/ingest'
+import { ingestReceiver } from './ingest'
+import type { IngestHandlers } from './ingest'
 
 /** The slice of the Convex Auth object the studio's HTTP routes need. */
 interface AuthHttpRoutes {
@@ -8,33 +11,36 @@ interface AuthHttpRoutes {
 
 /**
  * EC-252 — the studio's HTTP routes as a factory. Pure engine infra ships in the
- * package; only the consumer's `auth` (provider choice) is injected. The consumer's
- * `convex/http.ts` is a two-liner:
+ * package; only the consumer's `auth` (provider choice) and — since EC-617 — its ingest
+ * handlers are injected. The consumer's `convex/http.ts`:
  *
  * ```ts
  * import { auth } from './auth'
  * export default defineStudioHttp({ auth })
+ * // with an addon that handles ingest payloads (one import, one entry):
+ * // import { formsIngest } from '@elytracms/forms/convex'
+ * // export default defineStudioHttp({ auth, ingest: { submission: formsIngest } })
  * ```
  *
- * ## The engine registers NO HTTP routes of its own (EC-481)
+ * ## The engine registers exactly ONE route of its own (EC-481 → EC-617)
  *
- * Everything on this router comes from Convex Auth's `addHttpRoutes` — the JWT
- * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies
- * an OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
+ * Everything else on this router comes from Convex Auth's `addHttpRoutes` — the JWT
+ * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies an
+ * OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
  *
- * The engine used to add one more: `GET /api/projects/*`, the EC-157 Bearer-token
- * registry-sync endpoint backing `builder typegen`/`builder check`. EC-470 deleted
- * that CLI and with it the endpoint's only client; the handler had in any case
- * answered with config-owned placeholders since EC-287 retired the project graph
- * (`project: null`, `collections: []`). EC-481 removed the route and its handler
- * together rather than leave a Bearer-authenticated surface serving stub data on
- * every deployment. `http-routes.test.ts` pins that shut.
- *
- * A future engine-owned HTTP surface is fine — but it needs a real client and a
- * narrower prefix than `/api/projects/`.
+ * EC-481 removed the engine's former `GET /api/projects/*` (a Bearer-authenticated
+ * registry-sync endpoint with no client left) and set the bar for any future one: "a
+ * real client and a narrower prefix". EC-617's public-ingest RECEIVER is that route:
+ * `POST /elytra/ingest` — an EXACT path, not a prefix; its client is the site's
+ * `createIngestRoute` (`@elytracms/next`), which signs every payload with the
+ * server-held secret, and `elytra doctor`'s probe. It is mounted on every deployment,
+ * with or without handlers: closed (401) until `ELYTRA_INGEST_SECRET` is set, and a
+ * payload kind with no registered handler is refused visibly (422), never dropped.
+ * `http-routes.test.ts` pins the table.
  */
-export function defineStudioHttp({ auth }: { auth: AuthHttpRoutes }): HttpRouter {
+export function defineStudioHttp({ auth, ingest }: { auth: AuthHttpRoutes; ingest?: IngestHandlers }): HttpRouter {
   const http = httpRouter()
   auth.addHttpRoutes(http)
+  http.route({ path: INGEST_RECEIVER_PATH, method: 'POST', handler: ingestReceiver(ingest) })
   return http
 }