@voltro/cli 0.33.0 → 0.34.0

package/templates/apps/api-governance/mutations/profiles.create.mutation.ts

@@ -8,6 +8,18 @@ import { Schema } from 'effect'
 export const createProfile = defineMutation({
   name: 'profiles.create',
   target: { table: 'profiles', op: 'insert' },
+  // Open: writes exactly the three fields the caller passed and echoes back
+  // only `{ id, name, email }` — `ssn` is `.serverOnly()` and is deliberately
+  // absent from the output, so what the caller sent in never comes back out.
+  // It reads nothing and cannot reach an existing row.
+  //
+  // No auth strategy and no rbac ship in this template, so every caller is an
+  // anonymous Subject holding no scopes; a `guards: [{ scope }]` would deny all
+  // of them rather than the wrong ones. Add an identity, then the guard.
+  openAccess:
+    'inserts only the fields the caller supplied and echoes back `{ id, name, email }` — the '
+    + '`ssn` it takes is `.serverOnly()` and never appears in a response. Reads nothing, '
+    + 'modifies no existing row.',
   input: Schema.Struct({
     name: Schema.NonEmptyString,
     email: Schema.String,

package/templates/apps/api-governance/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-audit": "0.33.0",
-    "@voltro/plugin-governance": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-audit": "0.34.0",
+    "@voltro/plugin-governance": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-kv/actions/sync.pull.action.ts

@@ -13,6 +13,21 @@ import { Schema } from 'effect'
 
 export const syncPull = defineAction({
   name: 'sync.pull',
+  // Open: every KV key this touches is namespaced with the request's tenant
+  // (`sync:<tenantId>:cursor` / `:seen:*` in the executor) and the rows it
+  // writes go into a `tenant()` table, so one caller's sync state is not
+  // reachable from another's. The "upstream" is a pure local generator — there
+  // is no network call and no credential.
+  //
+  // No auth strategy and no rbac ship in this template, so a
+  // `guards: [{ scope: 'sync:run' }]` would be unsatisfiable: every caller is
+  // an anonymous Subject holding no scopes, and the guard would deny all of
+  // them. Growing a role map here purely to look guarded would teach a pattern
+  // this template is not about.
+  openAccess:
+    'advances the request tenant\'s own sync watermark; every KV key is namespaced by that '
+    + 'tenant and the rows land in a `tenant()` table. The upstream is a local pure generator '
+    + '— no network call, no credential.',
   input: Schema.Struct({
     // How many upstream events to pull this call (default 5, capped in the executor).
     limit: Schema.optional(Schema.Int.pipe(Schema.greaterThan(0))),

package/templates/apps/api-kv/actions/sync.reset.action.ts

@@ -11,6 +11,19 @@ import { Schema } from 'effect'
 
 export const syncReset = defineAction({
   name: 'sync.reset',
+  // Open — but note what bounds the blast radius, because it is a deliberate
+  // choice in the executor and not a property of "reset": it deletes only keys
+  // under `sync:<request tenantId>:`, never `ctx.kv.clear()`, which would drop
+  // the app's ENTIRE KV namespace across every tenant in one call. It destroys
+  // no rows; a following `sync.pull` rebuilds the watermark.
+  //
+  // No auth strategy and no rbac ship here, so a scope guard would deny every
+  // caller rather than the wrong ones. An operational reset is a good candidate
+  // for a `guards: [{ scope: 'sync:admin' }]` the moment you have an identity.
+  openAccess:
+    'deletes only the request tenant\'s own `sync:<tenant>:` keys — never `ctx.kv.clear()`, '
+    + 'which would wipe every tenant\'s namespace — and destroys no rows; the next `sync.pull` '
+    + 'rebuilds the watermark. An operational reset: guard it once an identity exists.',
   input: Schema.Struct({
     // Also delete the idempotency markers (default: keep them).
     markers: Schema.optional(Schema.Boolean),

package/templates/apps/api-kv/actions/sync.status.action.ts

@@ -9,6 +9,13 @@ import { Schema } from 'effect'
 
 export const syncStatus = defineAction({
   name: 'sync.status',
+  // Open: returns two integers about the request tenant's OWN sync state — a
+  // watermark and a marker count read from `sync:<tenantId>:` keys. No row
+  // contents, no other tenant's keys, no writes. No auth strategy or rbac ships
+  // in this template, so a scope guard would deny every caller.
+  openAccess:
+    'returns two integers describing the request tenant\'s own sync state (watermark + live '
+    + 'marker count) from its own KV namespace; no row contents, no writes.',
   input: Schema.Struct({}),
   output: Schema.Struct({
     cursor:        Schema.Int, // the durable watermark

package/templates/apps/api-kv/package.json

@@ -12,18 +12,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/kv": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/kv": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-kv/queries/events.list.query.ts

@@ -11,13 +11,24 @@ import { Schema } from 'effect'
 
 export const listEvents = defineQuery({
   name: 'events.list',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one caller's synced rows never reach another's subscription. With no auth
+  // strategy configured that tenantId is the caller's own `x-tenant` header —
+  // it shapes the feed, it does not authorize the caller — and a
+  // `guards: [{ scope }]` would be unsatisfiable, denying 100% of traffic.
+  openAccess:
+    'streams the synced event rows of the request\'s tenant (`tenant()` scopes every '
+    + 'delivery); the rows are this demo\'s own generated events. No auth strategy ships here, '
+    + 'so the tenant comes from the caller\'s `x-tenant` header — add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:         Schema.String,
-    externalId: Schema.String,
-    kind:       Schema.String,
-    sequence:   Schema.Number,
-    tenantId:   Schema.String,
-    createdAt:  Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:         Schema.String,
+      externalId: Schema.String,
+      kind:       Schema.String,
+      sequence:   Schema.Number,
+      tenantId:   Schema.String,
+      createdAt:  Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-moderation/mutations/comments.create.mutation.ts

@@ -9,6 +9,17 @@ import { Schema } from 'effect'
 export const createComment = defineMutation({
   name: 'comments.create',
   target: { table: 'comments', op: 'insert' },
+  // Open, same reasoning as `posts.create` — and here the `flag` action makes
+  // the distinction sharper still: it does not reject anything, it writes the
+  // row and queues it for review. A rule that never refuses is plainly not an
+  // access control, so the access decision has to be its own line.
+  //
+  // No auth strategy and no rbac ship here, so a `guards: [{ scope }]` would
+  // deny every caller instead of the wrong ones.
+  openAccess:
+    'inserts caller-supplied text into the request\'s tenant; the `flag` moderation rule '
+    + 'queues it for review and rejects nothing, so it is a review workflow rather than an '
+    + 'access control.',
   input: Schema.Struct({
     body: Schema.String,
   }),

package/templates/apps/api-moderation/mutations/posts.create.mutation.ts

@@ -11,6 +11,19 @@ import { Schema } from 'effect'
 export const createPost = defineMutation({
   name: 'posts.create',
   target: { table: 'posts', op: 'insert' },
+  // Content moderation is not access control, and this template is the place
+  // to be exact about that: the `block` rule inspects WHAT is being written and
+  // can reject it; `guards:` / `openAccess:` decide WHO may write at all. The
+  // moderation interceptor lets an authorized troll through and stops an
+  // unauthorized poet — neither substitutes for the other.
+  //
+  // Open because no auth strategy and no rbac ship here: every caller is an
+  // anonymous Subject with no scopes, so a scope guard would deny all of them.
+  // The write carries only caller-supplied text into the request's tenant.
+  openAccess:
+    'inserts caller-supplied text into the request\'s tenant, after the `block` moderation '
+    + 'rule has vetted it. Moderation judges the CONTENT, not the caller — it is not an '
+    + 'access decision, which is why this line exists beside it.',
   input: Schema.Struct({
     title: Schema.NonEmptyString,
     body: Schema.String,

package/templates/apps/api-moderation/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-moderation": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-moderation": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

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

@@ -4,6 +4,14 @@ import { Schema } from 'effect'
 export const createNote = defineMutation({
   name:   'notes.create',
   target: { table: 'notes', op: 'insert' },
+  // Open: writes only the title + body the caller sent, into the request's
+  // tenant (`tenant()` auto-stamps `tenantId`), and touches no existing row.
+  // No auth strategy and no rbac ship here, so every caller is an anonymous
+  // Subject holding no scopes and a scope guard would deny all of them.
+  openAccess:
+    'inserts a note built only from caller-supplied fields into the request\'s tenant; reads '
+    + 'nothing and modifies no existing row. No auth strategy ships here, so there is no '
+    + 'identity a scope guard could name.',
   input:  Schema.Struct({ title: Schema.NonEmptyString, body: Schema.String }),
   output: Schema.Struct({
     id:       Schema.String,

package/templates/apps/api-observability/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/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-prometheus": "0.33.0",
-    "@voltro/plugin-sentry": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-prometheus": "0.34.0",
+    "@voltro/plugin-sentry": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-observability/queries/notes.list.query.ts

@@ -4,6 +4,19 @@ import { Schema } from 'effect'
 export const listNotes = defineQuery({
   name:   'notes.list',
   source: 'notes',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one tenant's notes never reach another's subscription. With no auth
+  // strategy configured that tenantId comes from the caller's own `x-tenant`
+  // header — result shaping, not access control — and a `guards: [{ scope }]`
+  // would be unsatisfiable, denying 100% of traffic rather than some of it.
+  //
+  // Worth stating in the OBSERVABILITY template specifically: a denied call is
+  // still a span and still a metric. Traces show you what happened, not who was
+  // allowed to make it happen.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships here, so the tenant comes from the caller\'s `x-tenant` header — add a '
+    + 'strategy, then a `guards:`. Tracing records calls; it does not authorize them.',
   input:  Schema.Struct({}),
   output: Schema.Array(Schema.Struct({
     id:    Schema.String,

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

@@ -10,6 +10,20 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // A rate limit is not an access decision, and this template is where that is
+  // easiest to get wrong. The interceptor answers HOW OFTEN a caller may do
+  // this; `guards:` / `openAccess:` answer WHETHER THEY MAY AT ALL. A limit
+  // slows an attacker down and lets them through 99 times an hour, so it can
+  // never stand in for the second answer — the two live side by side.
+  //
+  // Open here because no auth strategy and no rbac ship in this template: every
+  // caller resolves to an anonymous Subject holding no scopes, so a
+  // `guards: [{ scope }]` would deny all of them. `assertOwnTenant` still
+  // rejects a `tenantId` that does not match the resolved subject.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). The rate limit bounds HOW OFTEN, never WHETHER '
+    + '— it is not an access decision, which is why this line exists beside it.',
   target: {
     table: 'notes',
     op: 'insert',

package/templates/apps/api-ratelimit/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/plugin-ratelimit": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-ratelimit": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-rbac/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/plugin-rbac": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-rbac": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-rest/package.json

@@ -13,17 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/plugin-openapi": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/plugin-openapi": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-saas/mutations/projects.create.mutation.ts

@@ -9,6 +9,19 @@ import { Schema } from 'effect'
 export const createProject = defineMutation({
   name:   'projects.create',
   target: { table: 'projects', op: 'insert' },
+  // An entitlement check is not an access decision. `requireEntitlement`
+  // answers HOW MANY the tenant has paid for; `guards:` / `openAccess:` answer
+  // WHO MAY CALL IT. A quota gate refuses the fourth project and cheerfully
+  // allows the first three — from anyone.
+  //
+  // Open because this template ships no auth strategy and no rbac (it is the
+  // billing bundle; `api-saas-starter` is the same domain WITH auth, and it
+  // guards these procedures). With no identity, every caller is an anonymous
+  // Subject holding no scopes and a `guards: [{ scope }]` would deny all of them.
+  openAccess:
+    'inserts a project named by the caller into the request\'s tenant, after the billing '
+    + 'entitlement gate. A quota bounds HOW MANY, never WHO — see `api-saas-starter` for the '
+    + 'same procedure with an auth strategy and a `projects:write` guard.',
   input:  Schema.Struct({ name: Schema.NonEmptyString }),
   output: Schema.Struct({
     id:       Schema.String,

package/templates/apps/api-saas/package.json

@@ -13,21 +13,22 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/plugin-analytics-postgres": "0.33.0",
-    "@voltro/plugin-billing": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-notifications": "0.33.0",
-    "@voltro/plugin-presence": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/plugin-analytics-postgres": "0.34.0",
+    "@voltro/plugin-billing": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-notifications": "0.34.0",
+    "@voltro/plugin-presence": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-saas/queries/projects.list.query.ts

@@ -8,6 +8,17 @@ import { Schema } from 'effect'
 export const listProjects = defineQuery({
   name:   'projects.list',
   source: 'projects',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one tenant's projects never reach another's subscription. This template
+  // bundles billing + notifications + presence and deliberately ships NO auth
+  // strategy — pair it with `api-auth` / `api-saas-starter` for the identity
+  // half. Until then the tenantId is the caller's own `x-tenant` header, and a
+  // `guards: [{ scope }]` would be unsatisfiable: an anonymous Subject holds no
+  // scopes, so the guard would deny 100% of traffic.
+  openAccess:
+    'lists the request tenant\'s own projects (`tenant()` scopes every delivery). This '
+    + 'template ships no auth strategy — see `api-saas-starter`, which does and guards these '
+    + 'same procedures — so the tenant comes from the caller\'s `x-tenant` header.',
   input:  Schema.Struct({}),
   output: Schema.Array(Schema.Struct({
     id:        Schema.String,

package/templates/apps/api-saas-starter/actions/me.action.ts

@@ -9,6 +9,19 @@ import { Schema } from 'effect'
 
 export const me = defineAction({
   name:  'session.me',
+  // The ONE open procedure in this app, and it has to be. The four domain
+  // procedures beside it carry guards an anonymous caller cannot satisfy —
+  // which is correct — but the dashboard's SSR 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({
     // 'anonymous' | 'user' | 'apiKey' | 'serviceAccount'

package/templates/apps/api-saas-starter/app.config.ts

@@ -22,6 +22,7 @@
 import { defineEnv, envVar } from '@voltro/env'
 import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
 import { billingPlugin } from '@voltro/plugin-billing'
+import { resolveScopes } from './authz'
 
 export const env = defineEnv({
   LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
@@ -83,5 +84,23 @@ export default {
     // Subject. Reads the SAME VOLTRO_SESSION_SECRET the routes sign with, so
     // the signing and verifying sides cannot drift.
     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 guards on the four domain procedures
+    // would be unsatisfiable — the dashboard would boot and answer `ScopeError`
+    // to every caller, which is an outage, not security.
+    //
+    // It runs ONLY on a subject a strategy matched, never for anonymous. That
+    // asymmetry IS what the guards enforce: signed in → member scopes; signed
+    // out → nothing. See `authz.ts` for the vocabulary, and for why a quota and
+    // a tenant filter are not substitutes for it.
+    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#MEMBER_SCOPES' },
 }

package/templates/apps/api-saas-starter/authz.ts

@@ -0,0 +1,75 @@
+// 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.
+//
+// ── Three gates, three different questions ─────────────────────────────────
+//
+// This template stacks all three, and conflating any two of them is the
+// classic SaaS authorization bug:
+//
+//   tenant()              WHICH ROWS — the runtime AND-merges
+//                         `tenantId = subject.tenantId` into every read.
+//   requireEntitlement()  HOW MANY — the plan's metered quota. It refuses the
+//                         fourth project and allows the first three, to anyone.
+//   guards: [{ scope }]   WHO MAY CALL IT AT ALL — this file.
+//
+// A quota is not an access control and neither is a tenant filter. The gate
+// that answers "may this caller do this" is the third one, and every
+// wire-exposed procedure here declares it (or an `openAccess:` reason — there
+// is exactly one, `session.me`).
+
+import type { Subject } from '@voltro/protocol'
+
+/**
+ * What a signed-in member of a tenant may do.
+ *
+ * **One role, on purpose.** This template has exactly one kind of account: a
+ * member of the tenant they signed up into. Inventing `owner` / `billing-admin`
+ * / `viewer` 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: **signed in or not.** With no cookie a
+ * caller cannot list a tenant's projects, cannot read the invite roster (which
+ * carries teammates' email addresses), and cannot spend a seat.
+ *
+ * Split it by BLAST RADIUS the day your product has two kinds of account.
+ * `team:invite` is already separate from `projects:write` for that reason:
+ * inviting a person costs a seat and puts an outsider inside the tenant, which
+ * is a bigger blast than creating a project.
+ */
+export const MEMBER_SCOPES = [
+  'projects:read',
+  'projects:write',
+  'team:read',
+  'team:invite',
+] 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
+ * exactly what makes these guards satisfiable AND meaningful:
+ *
+ *   • no session cookie  → `voltroPasswordStrategy` skips → anonymous Subject,
+ *     no scopes, every guard denies.
+ *   • valid cookie       → matched `user` Subject → this runs → member 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 a member's access
+ * takes effect on their EXISTING session rather than when the cookie expires.
+ *
+ * PRODUCTION replaces the body with a lookup: `subject.metadata.roles` (set by
+ * your strategy) or a read against your own tables through 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 though it were a policy decision.
+ */
+export const resolveScopes = (_subject: Subject): ReadonlyArray<string> => [...MEMBER_SCOPES]

package/templates/apps/api-saas-starter/mutations/invites.create.mutation.ts

@@ -8,6 +8,16 @@ import { Schema } from 'effect'
 export const createInvite = defineMutation({
   name:   'invites.create',
   target: { table: 'invites', op: 'insert' },
+  // Members only, and on its OWN scope rather than `projects:write` — the
+  // vocabulary is split by blast radius, not by convenience. Inviting a person
+  // spends a seat (real money) and puts an outsider inside the tenant; creating
+  // a project does neither. When this app grows an `owner` role, `team:invite`
+  // is the scope that moves to it and `projects:write` is the one that stays.
+  //
+  // The guard runs before `requireEntitlement`, so an anonymous call cannot
+  // spend the tenant's seat quota. Satisfiable as shipped: a matched session
+  // gets `team:invite` from `auth.resolveScopes` (authz.ts).
+  guards: [{ scope: 'team:invite' }],
   input:  Schema.Struct({ email: Schema.NonEmptyString }),
   output: Schema.Struct({
     id:       Schema.String,