@voltro/cli 0.33.0 → 0.35.0

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,

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

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 export const createProject = defineMutation({
   name:   'projects.create',
   target: { table: 'projects', op: 'insert' },
+  // Members only. Note the ORDER, because it is the whole reason this line
+  // exists next to `requireEntitlement`: the guard runs in the dispatch spine
+  // BEFORE the executor and before the transaction opens, so an anonymous call
+  // is refused without ever consuming a paying tenant's metered quota. A quota
+  // gate alone would let a stranger burn the free plan's three projects.
+  //
+  // Satisfiable as shipped: a matched session gets `projects:write` from
+  // `auth.resolveScopes` (authz.ts); anonymous callers hold no scopes.
+  guards: [{ scope: 'projects:write' }],
   input:  Schema.Struct({ name: Schema.NonEmptyString }),
   output: Schema.Struct({
     id:       Schema.String,

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

@@ -3,30 +3,34 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "exports": {
+    "./rpcGroup": "./rpcGroup.generated.ts"
+  },
   "scripts": {
     "dev": "voltro dev .",
     "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "voltro codegen . && tsc --noEmit"
   },
   "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-auth": "0.33.0",
-    "@voltro/plugin-billing": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-auth": "0.35.0",
+    "@voltro/plugin-billing": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-postgres": "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-saas-starter/queries/invites.list.query.ts

@@ -1,17 +1,28 @@
 // Streaming subscription of the tenant's teammate invites. Tenant-scoped like
 // projects.list — read live from the frontend's team page with
-// `useSubscription('app', 'invites.list')`.
+// `useSubscription('invites.list')`.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const listInvites = defineQuery({
   name: 'invites.list',
+  // Members only — and of the four domain procedures this is the one whose
+  // guard is load-bearing rather than tidy: the rows are teammates' EMAIL
+  // ADDRESSES. `tenant()` keeps them inside the tenant; this keeps them away
+  // from a caller who has not signed in to that tenant at all.
+  //
+  // Satisfiable as shipped: a matched session gets `team:read` from
+  // `auth.resolveScopes` (authz.ts). Anonymous callers hold no scopes and are
+  // refused with a typed `ScopeError`.
+  guards: [{ scope: 'team:read' }],
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:        Schema.String,
-    email:     Schema.String,
-    status:    Schema.String,
-    tenantId:  Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:        Schema.String,
+      email:     Schema.String,
+      status:    Schema.String,
+      tenantId:  Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

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

@@ -1,6 +1,6 @@
 // Streaming subscription of the tenant's projects. Every change to `projects`
 // for the caller's tenant lands as a delta — the frontend upgrades its first
-// paint to live with `useSubscription('app', 'projects.list')`. The runtime
+// paint to live with `useSubscription('projects.list')`. The runtime
 // AND-merges the tenant predicate (the table carries `tenant()`), so this never
 // leaks across tenants — no manual `eq('tenantId', ...)` needed.
 import { defineQuery } from '@voltro/protocol'
@@ -8,11 +8,22 @@ import { Schema } from 'effect'
 
 export const listProjects = defineQuery({
   name: 'projects.list',
+  // Members only. `tenant()` decides WHICH rows; this decides WHO may open the
+  // subscription at all — and the guard is re-checked on EVERY delivery, so a
+  // member whose access is revoked mid-session stops receiving rows instead of
+  // keeping a live feed open on a grant that has expired.
+  //
+  // Satisfiable by this app as shipped: sign in → `voltroPasswordStrategy`
+  // matches the cookie → `auth.resolveScopes` (authz.ts) grants
+  // `projects:read`. Anonymous → no scopes → refused.
+  guards: [{ scope: 'projects:read' }],
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:        Schema.String,
-    name:      Schema.String,
-    tenantId:  Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:        Schema.String,
+      name:      Schema.String,
+      tenantId:  Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-saas-starter/tests/accessDecisions.test.ts

@@ -0,0 +1,135 @@
+// The app's ACCESS POSTURE, asserted from BOTH sides against the real resolver.
+//
+// Why this file exists rather than one guard assertion per handler test: a
+// per-procedure test hands `invoke` a subject it constructed itself, so it
+// passes with a scope literal no real caller could ever obtain. The question it
+// structurally cannot ask is the one that matters —
+// **can the caller this app actually has satisfy these guards, and is there
+// anything that still cannot?** Both halves, or the suite stays green on an app
+// that is either wide open or completely dead.
+//
+// The second failure is the easy one to ship by accident. A guard nobody can
+// satisfy is not strict security; it is a 100% outage wearing security's
+// clothes, and every unit test in this directory keeps passing while the
+// dashboard answers `ScopeError` to its own sign-in flow. So the subjects below
+// are built the way the framework builds them (`applyScopeDecision` over this
+// app's real `resolveScopes`), never by writing the scopes the assertions want.
+
+import { describe, it, expect } from 'vitest'
+import {
+  anonymousSubject,
+  applyScopeDecision,
+  checkGuards,
+  ScopeError,
+  type Subject,
+} from '@voltro/protocol'
+import { MEMBER_SCOPES, resolveScopes } from '../authz'
+
+import { listProjects } from '../queries/projects.list.query'
+import { listInvites } from '../queries/invites.list.query'
+import { createProject } from '../mutations/projects.create.mutation'
+import { createInvite } from '../mutations/invites.create.mutation'
+import { me } from '../actions/me.action'
+
+/** The Subject a browser with no session cookie gets: `voltroPasswordStrategy`
+ *  finds nothing to match, so the composer falls back to anonymous. */
+const visitor = anonymousSubject('acme')
+
+/** The Subject a signed-in member gets. The cookie resolves to a `user` Subject
+ *  carrying NO scopes (a cookie never carries authority), then the composer
+ *  applies this app's own `resolveScopes`. Built through the framework's
+ *  `applyScopeDecision` so this file cannot disagree with the runtime about how
+ *  a grant lands on a subject. */
+const member = (): Subject => {
+  const matched: Subject = { type: 'user', id: 'user_1', tenantId: 'acme', scopes: [] }
+  return applyScopeDecision(matched, { kind: 'grant', scopes: resolveScopes(matched) }).subject
+}
+
+/** Exactly what the dispatch spine asks before an executor runs — and, for the
+ *  two creates, before `requireEntitlement` can spend the tenant's quota. */
+const decide = (
+  descriptor: { readonly name: string; readonly guards?: ReadonlyArray<unknown> | undefined },
+  subject: Subject,
+): ScopeError | null =>
+  checkGuards(
+    subject,
+    descriptor.guards as Parameters<typeof checkGuards>[1],
+    { defaultDeny: true, procedure: descriptor.name },
+  )
+
+const GUARDED = [listProjects, listInvites, createProject, createInvite] as const
+
+describe('the caller this app actually has — a signed-in member', () => {
+  // If any of these regress the dashboard boots and shows nothing but denials,
+  // which no other test in this directory can see.
+  it.each(GUARDED.map((d) => [d.name, d] as const))('%s is callable', (_name, descriptor) => {
+    expect(decide(descriptor, member())).toBeNull()
+  })
+
+  it('is not just passing because the guards are empty', () => {
+    // The silent-zero shape: `checkGuards` with no guards returns null too.
+    for (const d of GUARDED) expect(d.guards?.length ?? 0).toBeGreaterThan(0)
+    expect(GUARDED).toHaveLength(4)
+  })
+})
+
+describe('the caller with no session — every domain procedure is refused', () => {
+  it.each(GUARDED.map((d) => [d.name, d] as const))('%s denies an anonymous visitor', (_name, descriptor) => {
+    expect(decide(descriptor, visitor)).toBeInstanceOf(ScopeError)
+  })
+
+  it('so a stranger cannot read teammate emails or spend a seat', () => {
+    // The two that carry real cost. `invites.list` returns email addresses;
+    // `invites.create` consumes the tenant's metered `seats` entitlement, and
+    // the guard runs BEFORE that gate — a quota is not an access control.
+    expect(decide(listInvites, visitor)).toBeInstanceOf(ScopeError)
+    expect(decide(createInvite, visitor)).toBeInstanceOf(ScopeError)
+  })
+
+  it('…and that is structural, not a resolver quirk', () => {
+    // Pinned so a framework change would surface here: `applyScopeDecision`
+    // returns an anonymous Subject UNTOUCHED under both decision kinds (the
+    // schema has no `scopes` field to write). `auth.resolveScopes` also never
+    // runs for one — it fires only on a MATCHED subject — so a session cookie
+    // is the only way into the granted set.
+    const granted = applyScopeDecision(visitor, { kind: 'grant', scopes: [...MEMBER_SCOPES] })
+    expect(granted.subject).toEqual(visitor)
+    expect(decide(createProject, granted.subject)).toBeInstanceOf(ScopeError)
+  })
+})
+
+describe('session.me stays open, and that is the point', () => {
+  it('answers an anonymous caller instead of denying them', () => {
+    // A guard here would return `ScopeError` to the dashboard's SSR gate, which
+    // would then have nothing to branch on and would never redirect to /login.
+    expect(decide(me, visitor)).toBeNull()
+    expect(me.openAccess).toBeTruthy()
+  })
+})
+
+describe('the vocabulary is a boundary, not a rubber stamp', () => {
+  it('grants no wildcard and no admin bypass', () => {
+    expect(MEMBER_SCOPES).not.toContain('*')
+    expect(MEMBER_SCOPES).not.toContain('admin:full')
+  })
+
+  it('separates inviting a person from creating a project', () => {
+    // Split by blast radius: one spends a seat and lets an outsider into the
+    // tenant, the other does not. Collapsing them into one scope is what makes
+    // a later `owner` role impossible to express.
+    const scopeOf = (d: { readonly guards?: ReadonlyArray<unknown> | undefined }): string =>
+      ((d.guards ?? []) as ReadonlyArray<{ scope?: string }>)[0]?.scope ?? ''
+    expect(scopeOf(createInvite)).not.toBe(scopeOf(createProject))
+  })
+
+  it('every guard names a scope the resolver actually grants', () => {
+    // The other half of unsatisfiability: a typo'd scope makes a procedure
+    // permanently uncallable, and nothing else in this app would notice.
+    const granted = new Set(resolveScopes(member()))
+    for (const d of GUARDED) {
+      for (const g of (d.guards ?? []) as ReadonlyArray<{ scope?: string }>) {
+        expect(granted.has(g.scope ?? '')).toBe(true)
+      }
+    }
+  })
+})

package/templates/apps/api-search/mutations/articles.create.mutation.ts

@@ -8,6 +8,20 @@ import { Schema } from 'effect'
 
 export const createArticle = defineMutation({
   name: 'articles.create',
+  // Open — with one consequence worth naming because it reaches OUTSIDE the
+  // database: on commit the search plugin's ChangeEvent tap mirrors the row
+  // into the external index (Typesense / Meilisearch / Algolia). So an
+  // unguarded write here is an unguarded write there too, and the index is
+  // usually not tenant-partitioned by the same machinery your tables are.
+  //
+  // `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, and no auth strategy or rbac ships in this template, so a
+  // `guards: [{ scope: 'articles:write' }]` would deny every caller. Add an
+  // identity, then that guard — before you point `search` at a real cluster.
+  openAccess:
+    'inserts an article carrying only caller-supplied fields into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). On commit it also mirrors the row into the '
+    + 'external search index, so guard it before pointing the plugin at a real cluster.',
   target: {
     table: 'articles',
     op: 'insert',

package/templates/apps/api-search/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-search": "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-search": "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-search/queries/articles.list.query.ts

@@ -7,13 +7,26 @@ import { Schema } from 'effect'
 
 export const listArticles = defineQuery({
   name: 'articles.list',
+  // Open: the rows are this template's own seeded demo articles
+  // (`seeds/articles.seed.ts`), and `tenant()` confines every delivery to the
+  // tenantId on the request. No auth strategy and no rbac ship here, so a
+  // `guards: [{ scope }]` would be unsatisfiable and deny 100% of traffic.
+  //
+  // The plugin's own `search.query` procedure is a SEPARATE surface with its
+  // own decision, made by the plugin — this line covers only the list.
+  openAccess:
+    'lists the request tenant\'s seeded demo articles (`tenant()` scopes every delivery); the '
+    + 'seed holds no personal data. No auth strategy ships here, so the tenant comes from the '
+    + 'caller\'s `x-tenant` header.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    tag: Schema.String,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      tag: Schema.String,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-status/README.md

@@ -14,15 +14,22 @@ voltro dev
 
 A status page is read by everyone and written by a few — so:
 
-- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list`
-  carry **no guard**, so an anonymous browser can `useSubscription('app',
-  'incidents.live')` and the timeline updates live.
+- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list` each
+  declare `openAccess: '<why>'`, so an anonymous browser can
+  `useSubscription('app', 'incidents.live')` and the timeline updates live.
 - **Writes are OPERATOR-ONLY.** Every mutation declares
   `guards: [{ scope: 'status:write' }]`, enforced by `@voltro/plugin-rbac` in the
   dispatch spine before the executor. The demo resolver (`authz.ts`) grants the
   `operator` role to the `ops` tenant; everyone else — anonymous included — is
   denied.
 
+Note that **both** of those are DECISIONS, and the framework requires one or the
+other: under `security.defaultDeny` (on by default) a wire-exposed procedure
+that declares neither `guards:` nor `openAccess:` refuses to boot. `openAccess`
+is not the lax option — it is the honest spelling of an open endpoint, and the
+reason it carries is what a reviewer reads and what `voltro doctor` prints. This
+template is the clearest place in the library to see the two side by side.
+
 ## Surface
 
 | Tag | Kind | Guard |

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

@@ -2,10 +2,15 @@
 //
 // The shape of a status page is asymmetric, and this config encodes it:
 //   • READS are PUBLIC — `incidents.live` / `updates.list` / `components.list`
-//     carry NO guard, so an anonymous visitor's browser can subscribe and see
-//     the live timeline. (A status page that requires a login is useless during
-//     an outage.)
+//     each declare `openAccess: '<why>'`, so an anonymous visitor's browser can
+//     subscribe and see the live timeline. (A status page that requires a login
+//     is useless during an outage.)
 //   • WRITES are OPERATOR-ONLY — every mutation declares a `status:write` guard.
+//
+// Both halves are DECISIONS, and the framework insists on one or the other:
+// under `security.defaultDeny` a wire-exposed procedure declaring neither does
+// not boot. `openAccess` is not the lax option — it is the honest spelling of an
+// open endpoint, and it leaves the reason where a reviewer will read it.
 //     `rbacPlugin` resolves each caller's ROLES to SCOPES and the framework
 //     enforces the guard in the dispatch spine, before the executor. `voltro
 //     check` can see the guard statically.

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

@@ -3,9 +3,11 @@
 // test that redeclares the roles only proves its own copy is self-consistent).
 //
 // A status page has exactly two kinds of caller: the PUBLIC (anonymous
-// visitors, who only READ — the live queries carry no guard) and OPERATORS
-// (who post incidents). So there is one write scope, `status:write`, held by
-// the `operator` role; `admin` gets the wildcard bypass.
+// visitors, who only READ — the live queries declare `openAccess` with their
+// reason) and OPERATORS (who post incidents). So there is one write scope,
+// `status:write`, held by the `operator` role; `admin` gets the wildcard
+// bypass. Both kinds of caller are DECIDED about: `security.defaultDeny`
+// refuses to boot a procedure that declares neither form.
 //
 // This map is ALSO the app's declared scope vocabulary: `rbacPlugin` publishes
 // its union, and `voltro check` errors on any descriptor guard requiring a

package/templates/apps/api-status/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-rbac": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-rbac": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-postgres": "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-status/queries/components.list.query.ts

@@ -1,13 +1,21 @@
-// Live list of service components + their current status. Public (no guard).
+// Live list of service components + their current status — public by design.
+// `components.create` beside it is `status:write`-guarded: reads are for
+// visitors, writes are for operators.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const componentsList = defineQuery({
   name: 'components.list',
+  openAccess:
+    'the public component roster a status page exists to publish — this operator\'s own '
+    + 'service names and their current status, nothing caller-derived and no personal data. '
+    + 'Writing that roster is `status:write`-guarded.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:     Schema.String,
-    name:   Schema.String,
-    status: Schema.String,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:     Schema.String,
+      name:   Schema.String,
+      status: Schema.String,
+    }),
+  ),
 })