@voltro/cli 0.33.0 → 0.35.0

package/templates/apps/api-backend-mail/actions/sendWelcome.action.ts

@@ -10,6 +10,23 @@ import { defineAction } from '@voltro/protocol'
 
 export const sendWelcome = defineAction({
   name: 'mail.sendWelcome',
+  // Read this one carefully before copying it. Sending THIS APP'S branded mail
+  // to a caller-supplied address is one of the few things a tenant boundary
+  // does not bound — the recipient is an arbitrary third party, not a row.
+  //
+  // It is open here for exactly two reasons, both checkable in this repo:
+  // `provider: 'console'` in app.config.ts means nothing leaves the process
+  // (the send is logged and captured in the dev outbox), and no auth strategy
+  // ships in this template, so a `guards: [{ scope: 'mail:send' }]` would deny
+  // every caller rather than the wrong ones.
+  //
+  // The moment you swap in `resend` / `postmark` / `sendgrid` / `smtp`, this
+  // becomes an open relay for your own domain's reputation. Add an auth
+  // strategy and that `mail:send` guard in the SAME change.
+  openAccess:
+    'sends the `welcome` template to a caller-supplied address via the `console` provider — '
+    + 'nothing leaves the process, it is logged and captured in the dev outbox. Switching to a '
+    + 'real provider makes this an open relay: add an auth strategy and a `mail:send` guard first.',
   input: Schema.Struct({
     email: Schema.String,
     name: Schema.String,

package/templates/apps/api-backend-mail/mutations/notes.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // Open, deliberately — see `queries/notes.query.ts` for the long form. In
+  // short: `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, but with no auth strategy configured that subject is
+  // anonymous and holds no scopes, so any `guards: [{ scope }]` would deny
+  // every caller instead of some of them.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: {
     table: 'notes',
     op: 'insert',

package/templates/apps/api-backend-mail/package.json

@@ -13,19 +13,20 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-mail": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-mail": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend-mail/queries/notes.query.ts

@@ -8,13 +8,35 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  // Every wire-exposed procedure must declare an access decision — `guards:` or
+  // `openAccess:` — or the app refuses to boot (`security.defaultDeny`). This
+  // one is open, and the reason says what that buys and what it does not:
+  //
+  // `tenant()` confines the result to the tenantId on the request and re-checks
+  // it on every delivery, so one tenant's rows never reach another's
+  // subscription. But this template configures NO auth strategy, so that
+  // tenantId comes from the caller's own `x-tenant` header — it shapes the
+  // result, it does not authorize the caller. A `guards: [{ scope }]` here
+  // would be unsatisfiable: with no auth strategy and no rbac, every caller
+  // resolves to an anonymous Subject that holds no scopes, so the guard would
+  // deny 100% of traffic. That is not strict security, it is an outage.
+  //
+  // So: add an auth strategy (see the `api-auth` template) FIRST, then swap
+  // this line for a `guards:` in the same change — at that point `tenant()`
+  // becomes real isolation because the tenant comes from a verified session.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    done: Schema.Boolean,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      done: Schema.Boolean,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-backend-mariadb/.env.example

@@ -1,5 +1,19 @@
 # {{capProjectName}} — MariaDB backend env. Copy to `.env` and adjust.
 
+# ── Environment ────────────────────────────────────────────────────────
+#
+# DECLARE IT. Every `voltro db …` / `voltro migrate` invocation resolves an
+# UNSET `NODE_ENV` to `production` — the same way `voltro serve` and `voltro
+# start` do — so a bare `pnpm migrate` with no NODE_ENV refuses rather than
+# applying an un-reviewed diff to what might be a production database. It also
+# decides which `_voltro_*` bookkeeping tables the command declares, and a
+# migration command that resolves it differently from the serving process
+# declares a DIFFERENT schema.
+#
+# `voltro dev` declares `development` for itself and needs nothing from here;
+# this line is what makes the explicit schema commands work locally.
+NODE_ENV=development
+
 # ── Database (MariaDB + binlog CDC) ────────────────────────────────────
 DB_DIALECT=mariadb
 DB_URL=mysql://app:app@localhost:3307/{{projectNameSnake}}

package/templates/apps/api-backend-mariadb/mutations/notes.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // Open, deliberately — see `queries/notes.query.ts` for the long form. In
+  // short: `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, but with no auth strategy configured that subject is
+  // anonymous and holds no scopes, so any `guards: [{ scope }]` would deny
+  // every caller instead of some of them.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: {
     table: 'notes',
     op: 'insert',

package/templates/apps/api-backend-mariadb/package.json

@@ -13,19 +13,20 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-storage": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-mysql": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-storage": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-mysql": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend-mariadb/queries/notes.query.ts

@@ -8,13 +8,35 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  // Every wire-exposed procedure must declare an access decision — `guards:` or
+  // `openAccess:` — or the app refuses to boot (`security.defaultDeny`). This
+  // one is open, and the reason says what that buys and what it does not:
+  //
+  // `tenant()` confines the result to the tenantId on the request and re-checks
+  // it on every delivery, so one tenant's rows never reach another's
+  // subscription. But this template configures NO auth strategy, so that
+  // tenantId comes from the caller's own `x-tenant` header — it shapes the
+  // result, it does not authorize the caller. A `guards: [{ scope }]` here
+  // would be unsatisfiable: with no auth strategy and no rbac, every caller
+  // resolves to an anonymous Subject that holds no scopes, so the guard would
+  // deny 100% of traffic. That is not strict security, it is an outage.
+  //
+  // So: add an auth strategy (see the `api-auth` template) FIRST, then swap
+  // this line for a `guards:` in the same change — at that point `tenant()`
+  // becomes real isolation because the tenant comes from a verified session.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    done: Schema.Boolean,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      done: Schema.Boolean,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-backend-sqlite/.env.example

@@ -1,5 +1,19 @@
 # {{capProjectName}} — SQLite backend env. Copy to `.env` and adjust.
 
+# ── Environment ────────────────────────────────────────────────────────
+#
+# DECLARE IT. Every `voltro db …` / `voltro migrate` invocation resolves an
+# UNSET `NODE_ENV` to `production` — the same way `voltro serve` and `voltro
+# start` do — so a bare `pnpm migrate` with no NODE_ENV refuses rather than
+# applying an un-reviewed diff to what might be a production database. It also
+# decides which `_voltro_*` bookkeeping tables the command declares, and a
+# migration command that resolves it differently from the serving process
+# declares a DIFFERENT schema.
+#
+# `voltro dev` declares `development` for itself and needs nothing from here;
+# this line is what makes the explicit schema commands work locally.
+NODE_ENV=development
+
 # ── Database (embedded SQLite) ─────────────────────────────────────────
 DB_DIALECT=sqlite
 # A file path keeps data across restarts (the `.data/` dir is gitignored):

package/templates/apps/api-backend-sqlite/mutations/notes.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // Open, deliberately — see `queries/notes.query.ts` for the long form. In
+  // short: `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, but with no auth strategy configured that subject is
+  // anonymous and holds no scopes, so any `guards: [{ scope }]` would deny
+  // every caller instead of some of them.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: {
     table: 'notes',
     op: 'insert',

package/templates/apps/api-backend-sqlite/package.json

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-sqlite": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-sqlite": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend-sqlite/queries/notes.query.ts

@@ -8,13 +8,35 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  // Every wire-exposed procedure must declare an access decision — `guards:` or
+  // `openAccess:` — or the app refuses to boot (`security.defaultDeny`). This
+  // one is open, and the reason says what that buys and what it does not:
+  //
+  // `tenant()` confines the result to the tenantId on the request and re-checks
+  // it on every delivery, so one tenant's rows never reach another's
+  // subscription. But this template configures NO auth strategy, so that
+  // tenantId comes from the caller's own `x-tenant` header — it shapes the
+  // result, it does not authorize the caller. A `guards: [{ scope }]` here
+  // would be unsatisfiable: with no auth strategy and no rbac, every caller
+  // resolves to an anonymous Subject that holds no scopes, so the guard would
+  // deny 100% of traffic. That is not strict security, it is an outage.
+  //
+  // So: add an auth strategy (see the `api-auth` template) FIRST, then swap
+  // this line for a `guards:` in the same change — at that point `tenant()`
+  // becomes real isolation because the tenant comes from a verified session.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    done: Schema.Boolean,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      done: Schema.Boolean,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-backend-storage/actions/uploadAvatar.action.ts

@@ -10,6 +10,19 @@ import { defineAction } from '@voltro/protocol'
 
 export const uploadAvatar = defineAction({
   name: 'storage.uploadAvatar',
+  // Writes bytes the caller sent to a PUBLIC object and returns its URL. It
+  // reads nothing and can overwrite nothing — the key is minted server-side per
+  // upload — but an unguarded upload endpoint is free hosting for whatever the
+  // internet feels like storing. `provider: 'memory'` in app.config.ts keeps
+  // that inside this process; the plugin's `maxBytes` / content-type policy is
+  // what bounds it once you point at S3/R2.
+  //
+  // No auth strategy ships in this template, so a scope guard would deny every
+  // caller. Add one, then `guards: [{ scope: 'files:write' }]`.
+  openAccess:
+    'stores caller-supplied bytes as a new PUBLIC object and returns its URL — reads nothing, '
+    + 'overwrites nothing (the key is minted server-side). The `memory` provider keeps it '
+    + 'in-process; guard it before pointing at a real bucket.',
   input: Schema.Struct({
     bytesBase64: Schema.String,
     contentType: Schema.String,

package/templates/apps/api-backend-storage/actions/uploadDocument.action.ts

@@ -9,6 +9,18 @@ import { defineAction } from '@voltro/protocol'
 
 export const uploadDocument = defineAction({
   name: 'storage.uploadDocument',
+  // The WRITE is open; the READ is not, and the split is the point. This stores
+  // caller-supplied bytes as a PRIVATE object and returns only its id — the
+  // bytes come back exclusively through the plugin's access-checked
+  // `storage.mintUrl` route, which applies the object's policy (owner + tenant
+  // + granted roles) and is not this procedure's decision to make.
+  //
+  // No auth strategy ships in this template, so a `guards:` here would deny
+  // every caller. Add one, then `guards: [{ scope: 'files:write' }]`.
+  openAccess:
+    'stores caller-supplied bytes as a new PRIVATE object and returns only its id; reading it '
+    + 'back goes through the plugin\'s access-checked `storage.mintUrl`, which this does not '
+    + 'bypass. Guard the write too once the app has an identity.',
   input: Schema.Struct({
     bytesBase64: Schema.String,
     contentType: Schema.String,

package/templates/apps/api-backend-storage/mutations/notes.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // Open, deliberately — see `queries/notes.query.ts` for the long form. In
+  // short: `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, but with no auth strategy configured that subject is
+  // anonymous and holds no scopes, so any `guards: [{ scope }]` would deny
+  // every caller instead of some of them.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: {
     table: 'notes',
     op: 'insert',

package/templates/apps/api-backend-storage/package.json

@@ -11,18 +11,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-storage": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-storage": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend-storage/queries/notes.query.ts

@@ -8,13 +8,35 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  // Every wire-exposed procedure must declare an access decision — `guards:` or
+  // `openAccess:` — or the app refuses to boot (`security.defaultDeny`). This
+  // one is open, and the reason says what that buys and what it does not:
+  //
+  // `tenant()` confines the result to the tenantId on the request and re-checks
+  // it on every delivery, so one tenant's rows never reach another's
+  // subscription. But this template configures NO auth strategy, so that
+  // tenantId comes from the caller's own `x-tenant` header — it shapes the
+  // result, it does not authorize the caller. A `guards: [{ scope }]` here
+  // would be unsatisfiable: with no auth strategy and no rbac, every caller
+  // resolves to an anonymous Subject that holds no scopes, so the guard would
+  // deny 100% of traffic. That is not strict security, it is an outage.
+  //
+  // So: add an auth strategy (see the `api-auth` template) FIRST, then swap
+  // this line for a `guards:` in the same change — at that point `tenant()`
+  // becomes real isolation because the tenant comes from a verified session.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    done: Schema.Boolean,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      done: Schema.Boolean,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-cms/actions/content.get.action.ts

@@ -8,6 +8,13 @@ import { Schema } from 'effect'
 
 export const getContent = defineAction({
   name:  'content.get',
+  // Editors only — it returns the FULL row, every per-type field, for a
+  // caller-supplied id. Tenant scoping already makes another tenant's row read
+  // as absent; this decides whether an unauthenticated visitor may ask at all.
+  // Satisfied by a signed-in session (`auth.resolveScopes` in app.config.ts
+  // grants `content:read` to a matched subject); anonymous callers hold no
+  // scopes and are refused.
+  guards: [{ scope: 'content:read' }],
   input: Schema.Struct({
     type:   Schema.NonEmptyString,
     id:     Schema.NonEmptyString,

package/templates/apps/api-cms/actions/content.types.action.ts

@@ -23,6 +23,12 @@ const FieldWire = Schema.Struct({
 
 export const contentTypes = defineAction({
   name:  'content.types',
+  // Editors only. It carries no row data at all — but it IS a map of your
+  // content model (every type, every field, every constraint), which is
+  // reconnaissance you have no reason to hand an anonymous caller. Guarded with
+  // the same `content:read` the editor already needs, so this costs a signed-in
+  // editor nothing and tells a stranger nothing.
+  guards: [{ scope: 'content:read' }],
   input: Schema.Struct({}),
   output: Schema.Struct({
     types: Schema.Array(

package/templates/apps/api-cms/actions/me.action.ts

@@ -7,6 +7,19 @@ import { Schema } from 'effect'
 
 export const me = defineAction({
   name:  'session.me',
+  // The ONE open procedure in this app, and it has to be. Every `content.*`
+  // procedure beside it carries a `content:*` guard that an anonymous caller
+  // cannot satisfy — which is correct — but the SSR auth gate has to be able to
+  // ask "who am I" while it is still nobody, or it has nothing to branch on and
+  // the redirect to /login never happens.
+  //
+  // Safe because the answer is a projection of the caller's own request: the
+  // Subject `voltroPasswordStrategy` resolved from the cookie they sent. It
+  // reads no table and can say nothing about anybody else.
+  openAccess:
+    'echoes the caller\'s own resolved Subject (type/id/tenantId) — reads no table and reveals '
+    + 'nothing the caller did not present. Anonymous callers must reach it, or the SSR gate '
+    + 'cannot redirect them to sign in.',
   input: Schema.Struct({}),
   output: Schema.Struct({
     type:     Schema.String,

package/templates/apps/api-cms/app.config.ts

@@ -19,6 +19,7 @@
 // (`store: 'memory'`, in-process users); the README shows the production swaps.
 import { defineEnv, envVar } from '@voltro/env'
 import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { resolveScopes } from './authz'
 
 export const env = defineEnv({
   LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
@@ -57,5 +58,23 @@ export default {
     // Resolves the session cookie into the request Subject the handlers read
     // (`ctx.request.subject`) and the store spine scopes writes by.
     strategies: [voltroPasswordStrategy()],
+    // …and turns that identity into AUTHORITY. A session cookie carries no
+    // `scopes` by design (identity is settled at sign-in; authority is re-read
+    // per request), so without this the `content:*` guards on every procedure
+    // below would be unsatisfiable — the editor would boot and answer
+    // `ScopeError` to everyone, which is an outage, not security.
+    //
+    // It runs ONLY on a subject a strategy matched, never for anonymous. That
+    // asymmetry is what the guards actually enforce here: signed in → editor
+    // scopes; signed out → nothing. See `authz.ts` for the vocabulary and for
+    // what to replace this with when roles live in your own tables.
+    resolveScopes,
   },
+  // Point `voltro doctor` / `voltro check` at the scope vocabulary so the
+  // unknown-scope rule is LIVE here. This app does scope-based authorization
+  // without `@voltro/plugin-rbac`, and the plugin is what normally publishes
+  // that set — without this pointer the rule stays dormant and a guard naming a
+  // scope nothing grants (a typo, a rename) becomes a permanently uncallable
+  // procedure that nothing reports.
+  doctor: { scopeVocabulary: './authz.ts#EDITOR_SCOPES' },
 }

package/templates/apps/api-cms/authz.ts

@@ -0,0 +1,63 @@
+// The app's authorization vocabulary, in ONE place.
+//
+// Split out of `app.config.ts` for the same reason `api-rbac` splits its role
+// map: the tests can build the real resolver from the real scopes. A test that
+// redeclares the vocabulary it is testing proves only that its own copy is
+// self-consistent — the copy drifts, the test stays green, and the drift is
+// exactly the thing worth catching.
+//
+// ── Every procedure in this app declares an access decision ────────────────
+//
+// `guards: [{ scope }]` naming a scope from this file, or an `openAccess:`
+// reason. The framework refuses to boot on a procedure that declares neither
+// (`security.defaultDeny`, on by default). There is exactly one `openAccess`
+// here — `session.me`, which an anonymous browser MUST be able to call, or
+// nothing can tell it to sign in.
+
+import type { Subject } from '@voltro/protocol'
+
+/**
+ * What a signed-in editor may do.
+ *
+ * **One role, on purpose, and read the reason before you copy it.** This
+ * template has exactly one kind of account: an editor. Inventing `author` /
+ * `reviewer` / `publisher` here would be a role map written to look secure
+ * rather than to describe this app, and a scope every caller already holds is
+ * a guard that reads as protection and enforces nothing.
+ *
+ * The line these guards DO draw is real, and it is the line the template is
+ * about: **signed in or not.** `content.saveDraft` / `publish` / `unpublish`
+ * are refused to an anonymous caller, and the README's claim that only
+ * signed-in editors reach the write surface stops being a comment and becomes
+ * something the dispatch spine enforces before the executor runs.
+ *
+ * Split it the day your product has two kinds of account — by BLAST RADIUS,
+ * not by job title: publishing to the live site is a bigger blast than saving
+ * a draft, so `content:publish` is the natural second scope.
+ */
+export const EDITOR_SCOPES = ['content:read', 'content:write'] as const
+
+/**
+ * Where a caller's authority comes from.
+ *
+ * `auth.resolveScopes` runs ONLY on a subject a strategy MATCHED — never for
+ * anonymous, where there is no identity to look anything up for. That is
+ * precisely what makes these guards satisfiable AND meaningful here:
+ *
+ *   • no session cookie  → `voltroPasswordStrategy` skips → anonymous Subject,
+ *     no scopes, every `content:*` guard denies.
+ *   • valid cookie       → matched `user` Subject → this runs → editor scopes.
+ *
+ * A session cookie deliberately carries no `scopes` of its own (identity is
+ * settled at sign-in; authority is re-read per request), so this function is
+ * the only thing that can grant them — which is why removing an editor's
+ * access takes effect on their EXISTING session rather than when it expires.
+ *
+ * PRODUCTION replaces the body with a lookup: `subject.metadata.roles` (set by
+ * your strategy) or a read against your own tables via the `store` the
+ * framework hands the resolver. Failure posture: return
+ * `{ kind: 'unavailable', reason }` if the lookup itself fails — the request
+ * then fails CLOSED with a named reason instead of an empty array being
+ * applied as a policy decision.
+ */
+export const resolveScopes = (_subject: Subject): ReadonlyArray<string> => [...EDITOR_SCOPES]

package/templates/apps/api-cms/mutations/content.publish.mutation.ts

@@ -7,6 +7,16 @@ import { Schema } from 'effect'
 
 export const publishContent = defineMutation({
   name: 'content.publish',
+  // Editors only — this is the procedure that makes content LIVE, so it is the
+  // one whose guard matters most. Enforced before the executor and before the
+  // transaction opens; satisfied by a signed-in session (`auth.resolveScopes`
+  // grants `content:write`), refused to an anonymous caller.
+  //
+  // When your product grows a review step, this is where the vocabulary splits:
+  // give publishing its own `content:publish` scope in `authz.ts` and leave
+  // `content:write` on saveDraft. Split by BLAST RADIUS — going live is a
+  // bigger blast than saving a draft.
+  guards: [{ scope: 'content:write' }],
   input: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
   output: Schema.Union(
     Schema.Struct({ ok: Schema.Literal(true), id: Schema.String, status: Schema.String }),