@voltro/cli 0.33.0 → 0.35.0

package/templates/apps/api-governance/actions/profiles.get.action.server.ts

@@ -1,7 +1,22 @@
+// Executor for `profiles.get`.
+//
+// `p['ssn']` is PLAINTEXT here — the store middleware decrypted the
+// `.encrypted()` column on the way out, and the handler never sees the
+// `enc:v1:…` ciphertext. That is the round-trip this template exists to show,
+// and the last-four projection below is what proves it happened.
+//
+// The projection is not decoration: the column is `.serverOnly()`, so the full
+// value must not reach a client. Deriving the suffix HERE — rather than sending
+// the whole string and trimming it in the browser — is the difference between a
+// value that never left the server and one that did.
 import type { AppContext } from '@voltro/runtime'
 import { eq } from '@voltro/database'
 import { database } from '../database/schema'
 
+/** Last four characters, or '' when there is nothing to show. Never throws on a
+ *  short or empty value — a masked field is not a place to fail a read. */
+const last4 = (value: string): string => (value.length >= 4 ? value.slice(-4) : '')
+
 const execute = async (input: { id: string }, ctx: AppContext) => {
   const rows = await ctx.store.query(database.profiles.where(eq('id', input.id)).descriptor)
   const p = rows[0]
@@ -10,7 +25,8 @@ const execute = async (input: { id: string }, ctx: AppContext) => {
     id: p['id'] as string,
     name: p['name'] as string,
     email: p['email'] as string,
-    ssn: p['ssn'] as string,        // decrypted by the store middleware
+    // Decrypted by the store middleware, then narrowed to what may leave.
+    ssnLast4: last4(p['ssn'] as string),
   }
 }
 

package/templates/apps/api-governance/actions/profiles.get.action.ts

@@ -1,17 +1,42 @@
-// Reads a profile back — `ssn` comes out as PLAINTEXT. The store middleware
-// decrypts the `.encrypted()` column on read; the handler never touches the
-// `enc:v1:…` ciphertext. (In a real app you'd gate this read behind auth.)
+// Reads a profile back. The store middleware DECRYPTS the `.encrypted()` column
+// on read, so the handler holds `ssn` as plaintext and never touches the
+// `enc:v1:…` ciphertext — that is the round-trip this template exists to show.
+//
+// What crosses the WIRE is a SEPARATE decision, and the schema makes it: `ssn`
+// is also `.serverOnly()`, so the full value may not leave the server. The
+// executor proves the decryption worked by returning the last four digits it
+// derived from the plaintext — which is what a support UI would actually
+// render. Encryption at rest is not an exposure marker; `.serverOnly()` is.
 
 import { defineAction } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const getProfile = defineAction({
   name: 'profiles.get',
+  // Open, and the reason is a claim you can check against the two files beside
+  // this one: the full `ssn` is `.serverOnly()` in `database/schema.ts` and is
+  // not named in the output below, so the sensitive value cannot cross the wire
+  // at all. What is left — name, email, four digits — is the row this demo's
+  // own `profiles.create` put there; the template ships no seed and no other
+  // writer.
+  //
+  // A `guards: [{ scope: 'profiles:read' }]` is what a real deployment wants
+  // here, and it is unsatisfiable in THIS app: no auth strategy and no rbac are
+  // configured, so every caller resolves to an anonymous Subject holding no
+  // scopes and the guard would deny 100% of traffic — an outage, not security.
+  // Add an identity (see `api-auth` / `api-rbac`), then the guard.
+  openAccess:
+    'returns name, email and the last four digits derived server-side from the decrypted '
+    + '`ssn`; the full value is `.serverOnly()` and is absent from this output, so it cannot '
+    + 'cross the wire. Rows come only from this demo\'s own `profiles.create` — no seed, no '
+    + 'other writer.',
   input: Schema.Struct({ id: Schema.String }),
   output: Schema.NullOr(Schema.Struct({
     id: Schema.String,
     name: Schema.String,
     email: Schema.String,
-    ssn: Schema.String,
+    // Proof the cipher decrypted the column, without publishing it. Empty when
+    // the stored value is shorter than four characters.
+    ssnLast4: Schema.String,
   })),
 })

package/templates/apps/api-governance/database/schema.ts

@@ -28,10 +28,22 @@ export const profiles = table('profiles', {
   id:    id({ prefix: 'prof' }),
   name:  text(),
   email: text(),
-  // .encrypted() → AES-256-GCM at rest. The handler always sees plaintext; the
-  // stored value is an opaque `enc:v1:…` string. Encrypt only what you read
-  // back WHOLE (you can't filter/sort on it in SQL — it's ciphertext on disk).
-  ssn:   text().encrypted(),
+  // TWO markers, because they answer two different questions — say both when
+  // you mean both:
+  //
+  //   .encrypted()  → AES-256-GCM AT REST. The handler always sees plaintext;
+  //                   the stored value is an opaque `enc:v1:…` string. Encrypt
+  //                   only what you read back WHOLE (you can't filter/sort on
+  //                   it in SQL — it's ciphertext on disk).
+  //   .serverOnly() → may this value leave the server AT ALL. It may not.
+  //
+  // Reading `.encrypted()` as "safe to expose" is a category error and a
+  // tempting one: the runtime DECRYPTS for the handler, so an encrypted column
+  // flows to a client exactly like any other unless it is also `.serverOnly()`.
+  // `crud.*` strips serverOnly columns for you; a hand-written procedure must
+  // simply not name it in its output — see `actions/profiles.get.action.ts`,
+  // which returns the last four digits it derived server-side instead.
+  ssn:   text().encrypted().serverOnly(),
 })
   .with(audit())     // createdAt drives the retention sweep
 

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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-audit": "0.35.0",
+    "@voltro/plugin-governance": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/kv": "0.35.0",
+    "@voltro/plugin-multitenancy": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-moderation": "0.35.0",
+    "@voltro/plugin-multitenancy": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-prometheus": "0.35.0",
+    "@voltro/plugin-sentry": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-ratelimit": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-rbac": "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-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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/plugin-openapi": "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/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.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/plugin-analytics-postgres": "0.35.0",
+    "@voltro/plugin-billing": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-notifications": "0.35.0",
+    "@voltro/plugin-presence": "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/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'