@voltro/cli 0.33.0 → 0.34.0

package/templates/apps/api-cms/tests/accessDecisions.test.ts

@@ -0,0 +1,121 @@
+// 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 the directory keeps passing while the editor
+// 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 to see.
+
+import { describe, it, expect } from 'vitest'
+import {
+  anonymousSubject,
+  applyScopeDecision,
+  checkGuards,
+  ScopeError,
+  type Subject,
+} from '@voltro/protocol'
+import { EDITOR_SCOPES, resolveScopes } from '../authz'
+
+import { listContent } from '../queries/content.list.query'
+import { getContent } from '../actions/content.get.action'
+import { contentTypes } from '../actions/content.types.action'
+import { me } from '../actions/me.action'
+import { saveDraft } from '../mutations/content.saveDraft.mutation'
+import { publishContent } from '../mutations/content.publish.mutation'
+import { unpublishContent } from '../mutations/content.unpublish.mutation'
+
+/** 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 editor gets. `voltroPasswordStrategy` matches the
+ *  cookie into a `user` Subject carrying NO scopes (a cookie never carries
+ *  authority), then the composer applies this app's own `resolveScopes` to it.
+ *  Built through the framework's `applyScopeDecision` so this file cannot
+ *  disagree with the runtime about how a grant lands on a subject. */
+const editor = (): Subject => {
+  const matched: Subject = { type: 'user', id: 'usr_editor', tenantId: 'acme', scopes: [] }
+  return applyScopeDecision(matched, { kind: 'grant', scopes: resolveScopes(matched) }).subject
+}
+
+/** Exactly what the dispatch spine asks before an executor runs. */
+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 = [listContent, getContent, contentTypes, saveDraft, publishContent, unpublishContent] as const
+
+describe('the caller this app actually has — a signed-in editor', () => {
+  // If any of these regress the editor 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, editor())).toBeNull()
+  })
+
+  it('is not just passing because the guards are empty', () => {
+    // The silent-zero shape: `checkGuards` with no guards would return null too.
+    // Assert the decisions are really there before trusting the line above.
+    for (const d of GUARDED) expect(d.guards?.length ?? 0).toBeGreaterThan(0)
+    expect(GUARDED).toHaveLength(6)
+  })
+})
+
+describe('the caller with no session — every content 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('…and that is structural, not a resolver quirk', () => {
+    // The reason an anonymous caller can never hold `content:write` in this app,
+    // 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 cookie is the
+    // only way into the granted set.
+    const granted = applyScopeDecision(visitor, { kind: 'grant', scopes: [...EDITOR_SCOPES] })
+    expect(granted.subject).toEqual(visitor)
+    expect(decide(saveDraft, 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 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(EDITOR_SCOPES).not.toContain('*')
+    expect(EDITOR_SCOPES).not.toContain('admin:full')
+  })
+
+  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(editor()))
+    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-cms/tests/content.descriptors.test.ts

@@ -30,11 +30,15 @@ describe('content.list descriptor', () => {
     expect(decodeIn({ type: 'blogPost', status: 'draft' })).toEqual({ type: 'blogPost', status: 'draft' })
     // The output carries only what a list view needs — id/status/title?/slug?/
     // updatedAt; the runtime drops a row's other columns against this shape.
+    // It is an ARRAY schema (a query delivers rows, not a row), so encode a
+    // list and read the first element — passing a bare object here typechecked
+    // as the array type and made `wire.id` a compile error that `voltro test`
+    // never sees, because it transpiles without type-checking.
     const encode = Schema.encodeUnknownSync(listContent.output)
-    const wire = encode({ id: 'p1', status: 'published', title: 'T', slug: 't', updatedAt: new Date(0) })
-    expect(wire.id).toBe('p1')
-    expect(wire.status).toBe('published')
-    expect(wire.title).toBe('T')
+    const [wire] = encode([{ id: 'p1', status: 'published', title: 'T', slug: 't', updatedAt: new Date(0) }])
+    expect(wire?.id).toBe('p1')
+    expect(wire?.status).toBe('published')
+    expect(wire?.title).toBe('T')
   })
 })
 

package/templates/apps/api-collab/mutations/documents.create.mutation.ts

@@ -9,6 +9,14 @@ import { Schema } from 'effect'
 
 export const createDocument = defineMutation({
   name: 'documents.create',
+  // Open: inserts a title the caller supplied into the caller's own tenant
+  // (`assertOwnTenant` rejects a mismatched `tenantId`) and touches no existing
+  // row. With no auth strategy configured every caller is an anonymous Subject
+  // holding no scopes, so a `guards: [{ scope }]` would deny all of them.
+  openAccess:
+    'inserts a new document (title only, empty CRDT body) into the caller\'s own tenant; '
+    + '`assertOwnTenant` rejects a mismatch and no existing row is touched. No auth strategy '
+    + 'ships here, so there is no identity a scope guard could name.',
   target: {
     table: 'documents',
     op: 'insert',

package/templates/apps/api-collab/mutations/documents.setBody.mutation.ts

@@ -16,6 +16,19 @@ import { Schema } from 'effect'
 export const setDocumentBody = defineMutation({
   name: 'documents.setBody',
   target: { table: 'documents', op: 'update' },
+  // Open, and note WHAT the CRDT changes about the risk: the server does not
+  // overwrite `body` with the caller's bytes, it MERGES them
+  // (`mergeCrdtStates`), so a concurrent editor's text is not destroyed by a
+  // conflicting write — the two converge. `tenant()` scopes the update, so an
+  // id from another tenant matches no row at all.
+  //
+  // What remains open is who may join an editing session, and that needs an
+  // identity this template does not ship: with no auth strategy every caller is
+  // an anonymous Subject holding no scopes, so a `guards:` would deny everyone.
+  openAccess:
+    'merges a caller-supplied CRDT update into a document of the request\'s tenant — a merge, '
+    + 'not an overwrite, so no concurrent editor\'s text is lost, and an id outside the tenant '
+    + 'matches no row. Guard who may edit once the app has an identity.',
   input: Schema.Struct({
     id: Schema.NonEmptyString,
     update: Schema.Uint8ArrayFromBase64,

package/templates/apps/api-collab/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/local-first": "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/local-first": "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-collab/queries/documents.query.ts

@@ -12,12 +12,24 @@ import { Schema } from 'effect'
 
 export const listDocuments = defineQuery({
   name: 'documents.list',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one tenant's CRDT state never reaches another's subscription — but this
+  // template configures no auth strategy, so that tenantId is the caller's own
+  // `x-tenant` header. It shapes the feed; it does not authorize the caller.
+  // A `guards: [{ scope }]` would be unsatisfiable here (an anonymous Subject
+  // holds no scopes) and would deny 100% of traffic instead of some of it.
+  openAccess:
+    'streams the documents of the request\'s tenant, CRDT body included (`tenant()` scopes '
+    + 'every delivery). No auth strategy ships here, so the tenant comes from the caller\'s own '
+    + '`x-tenant` header — add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.NullOr(Schema.Uint8ArrayFromBase64),
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.NullOr(Schema.Uint8ArrayFromBase64),
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-data-advanced/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/plugin-governance": "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-governance": "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-data-advanced/queries/authors.withBooks.query.ts

@@ -26,6 +26,18 @@ const Book = Schema.Struct({
 export const authorsWithBooks = defineQuery({
   name:   'authors.withBooks',
   source: ['authors', 'books'],
+  // Open: the rows are this template's own seeded catalogue
+  // (`seeds/catalog.seed.ts` — a public book list, no personal data), and
+  // `tenant()` on both tables scopes every delivery to the request's tenant.
+  //
+  // `bio` is the `.encrypted()` column and it IS in this output — deliberately,
+  // because the lesson is that `.encrypted()` is about bytes AT REST and says
+  // nothing about the wire. If a column must not leave the server, that is a
+  // different marker (`.serverOnly()`), not this one.
+  openAccess:
+    'streams the seeded demo catalogue (authors + their books) for the request\'s tenant; the '
+    + 'seed holds no personal data. `bio` is `.encrypted()` and still crosses the wire on '
+    + 'purpose — encryption at rest is not an exposure marker; `.serverOnly()` is.',
   input:  Schema.Struct({}),
   output: Schema.Struct({
     id:       Schema.String,

package/templates/apps/api-data-advanced/queries/books.search.query.ts

@@ -24,6 +24,15 @@ import { Schema } from 'effect'
 export const searchBooks = defineQuery({
   name:   'books.search',
   source: 'books',
+  // Open: full-text search over this template's own seeded book catalogue
+  // (`seeds/catalog.seed.ts`), scoped to the request's tenant by `tenant()`.
+  // Note that `cache.scope: 'subject'` below is a SEPARATE decision from this
+  // one and stays right either way — the snapshot key includes the subject, so
+  // an open procedure still cannot serve one caller's rows to another.
+  openAccess:
+    'full-text search over the seeded demo book catalogue, tenant-scoped; the seed holds no '
+    + 'personal data. The result cache is `scope: \'subject\'`, so an open read still cannot '
+    + 'serve one caller a snapshot built for another.',
   input:  Schema.Struct({ q: Schema.String }),
   output: Schema.Struct({
     id:       Schema.String,

package/templates/apps/api-durable/mutations/orders.approve.mutation.ts

@@ -11,6 +11,23 @@ import { Schema } from 'effect'
 
 export const approveOrder = defineMutation({
   name: 'orders.approve',
+  // This is the human-APPROVAL surface, so state plainly what "open" costs
+  // here rather than hiding it behind the word demo: whoever can call this
+  // decides whether an order ships. `assertOwnTenant` confines the signal to
+  // the caller's own tenant and the executionId is DERIVED from
+  // `{ orderId, tenantId }` (so no caller-supplied id can address another
+  // tenant's run), but nothing in this template distinguishes an approver from
+  // anyone else — it configures no auth strategy and no rbac, so an anonymous
+  // Subject with no scopes is the only caller that exists and a
+  // `guards: [{ scope: 'orders:approve' }]` would deny 100% of traffic.
+  //
+  // This is THE procedure in this template to guard first. Add an auth
+  // strategy (`api-auth`) or rbac (`api-rbac`), then that guard.
+  openAccess:
+    'injects the approval signal into the caller\'s own tenant\'s parked fulfilment run — the '
+    + 'executionId is derived from `{ orderId, tenantId }` and `assertOwnTenant` rejects a '
+    + 'mismatch, so no other tenant\'s run is addressable. It still decides whether an order '
+    + 'ships: the first procedure here to grow an `orders:approve` guard once an identity exists.',
   input: Schema.Struct({
     orderId:  Schema.String,
     tenantId: Schema.String,

package/templates/apps/api-durable/mutations/orders.place.mutation.ts

@@ -12,6 +12,15 @@ import { Schema } from 'effect'
 
 export const placeOrder = defineMutation({
   name: 'orders.place',
+  // Open: writes an order carrying only what the caller sent, into the caller's
+  // own tenant (`assertOwnTenant` rejects a mismatched `tenantId`), and touches
+  // no existing row. No auth strategy and no rbac ship in this template, so
+  // every caller resolves to an anonymous Subject with no scopes and a
+  // `guards: [{ scope }]` would deny all of them.
+  openAccess:
+    'inserts an order built only from caller-supplied fields into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch); reads nothing and modifies no existing row. '
+    + 'No auth strategy ships here, so there is no identity a scope guard could name.',
   // Auto-optimistic: every query whose `source: 'orders'` matches gets a
   // placeholder row prepended; the server delta replaces it on commit.
   target: {

package/templates/apps/api-durable/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/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/workflow": "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/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/workflow": "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-feature-flags/actions/notes.export.action.ts

@@ -12,6 +12,22 @@ import { Schema } from 'effect'
 
 export const exportNotes = defineAction({
   name: 'notes.export',
+  // A flag gate is NOT an access decision, and this pair is the clearest place
+  // in the templates to see why. `gatedBy` decides WHETHER THE FEATURE IS ON —
+  // it is a release control, flipped for everyone at once (or by rollout
+  // bucket), and `betaExport: false` in app.config.ts happens to close this
+  // door today. `guards:` / `openAccess:` decide WHO MAY CALL IT. Turning the
+  // flag on must not silently also decide the second question, so the
+  // procedure declares both.
+  //
+  // Open because no auth strategy and no rbac ship here: every caller resolves
+  // to an anonymous Subject with no scopes, so a scope guard would deny all of
+  // them. What the handler returns is a COUNT of the request tenant's own notes
+  // — no bodies, no other tenant's rows (`tenant()` scopes the read).
+  openAccess:
+    'returns a COUNT of the request tenant\'s own notes — no row contents leave. The '
+    + '`betaExport` flag gates whether the feature runs at all; that is a release control, not '
+    + 'an access decision, which is why this line exists alongside it.',
   input: Schema.Struct({}),
   output: Schema.Struct({ exported: Schema.Number }),
   error: FlagDisabled,

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

@@ -13,6 +13,18 @@ import { Schema } from 'effect'
 export const createNote = defineMutation({
   name: 'notes.create',
   target: { table: 'notes', op: 'insert' },
+  // `requireFlag(ctx, 'newEditor')` in the executor answers "is this feature
+  // switched on"; this line answers "who may call it". Two different questions
+  // — a flag flipped on for everyone would otherwise silently answer both.
+  //
+  // Open because no auth strategy and no rbac ship here, so every caller is an
+  // anonymous Subject holding no scopes and a `guards: [{ scope }]` would deny
+  // all of them. The write carries only what the caller sent, into the tenant
+  // on the request.
+  openAccess:
+    'inserts a note built only from caller-supplied fields into the request\'s tenant. The '
+    + '`newEditor` flag decides whether the feature runs; this decides who may call it — a '
+    + 'release control is not an access decision.',
   input: Schema.Struct({
     tenantId: Schema.String,
     title: Schema.NonEmptyString,

package/templates/apps/api-feature-flags/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-flags": "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.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-flags": "0.34.0",
+    "@voltro/plugin-multitenancy": "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-governance/README.md

@@ -11,17 +11,32 @@ pnpm --filter @{{projectName}}/{{appName}} dev
 # → http://localhost:4000  (store: memory — zero infra)
 ```
 
-The `.env` ships a DEV encryption key. Generate your own with
-`openssl rand -hex 32` and keep it in a secret store for production.
+**No encryption key ships with this template** — a key committed to a template
+is a key published to everyone who downloads it. `VOLTRO_FIELD_ENCRYPTION_KEY`
+is declared with `generate: 'hex'`, so `voltro dev` mints a unique one into a
+gitignored `.env.local` on first boot. Your deployment mints its own:
+`voltro secret generate field-encryption`.
 
 ## What this shows
 
-- **Field encryption** — `profiles.ssn` is `text().encrypted()`. You pass
-  plaintext; the store middleware encrypts it (AES-256-GCM) on write and
-  decrypts on read, so handlers always see plaintext while the column holds an
-  opaque `enc:v1:…` string at rest. `governancePlugin({ fieldEncryption: true })`
+- **Field encryption** — `profiles.ssn` is `text().encrypted().serverOnly()`.
+  You pass plaintext; the store middleware encrypts it (AES-256-GCM) on write
+  and decrypts on read, so handlers always see plaintext while the column holds
+  an opaque `enc:v1:…` string at rest. `governancePlugin({ fieldEncryption: true })`
   registers the cipher from `VOLTRO_FIELD_ENCRYPTION_KEY`. Boot fails loud if an
   `.encrypted()` column exists but no cipher is registered.
+- **…and why the second marker is there.** `.encrypted()` is about bytes AT
+  REST; it says nothing about the wire, and the runtime decrypts for the
+  handler — so an encrypted column reaches a client exactly like any other
+  unless it is also `.serverOnly()`. `profiles.get` therefore returns the last
+  four digits it derived server-side, which proves the cipher ran without
+  publishing the value.
+- **Every procedure declares an access decision.** `guards: [{ scope }]` or
+  `openAccess: '<why>'`, or the app refuses to boot (`security.defaultDeny`).
+  Both procedures here are `openAccess` with the reason in the file — this
+  template configures no auth strategy and no rbac, so every caller resolves to
+  an anonymous Subject holding no scopes and a scope guard would deny 100% of
+  traffic. Add an identity (see `api-auth` / `api-rbac`), then the guard.
 - **GDPR** — admin-gated `governance.export` / `governance.erase` walk the
   declared `subjectScopes` (`[{ table: 'profiles', subjectField: 'id' }]`) to
   bundle or erase everything belonging to a subject.
@@ -33,12 +48,14 @@ The `.env` ships a DEV encryption key. Generate your own with
 ## Try it
 
 ```bash
-# create a profile, then read it back — ssn round-trips as plaintext:
+# create a profile, then read it back — the cipher round-trips, the value doesn't:
 ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
   -d '{"tag":"profiles.create","input":{"name":"Ada","email":"ada@acme.com","ssn":"123-45-6789"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
 curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
   -d "{\"tag\":\"profiles.get\",\"input\":{\"id\":\"$ID\"}}"
-# → { ok:true, result:{ …, ssn:"123-45-6789" } }   (plaintext — cipher decrypted it)
+# → { ok:true, result:{ …, ssnLast4:"6789" } }
+#   The handler read "123-45-6789" as plaintext (the cipher decrypted it) and
+#   published four digits, because the column is `.serverOnly()`.
 
 # record consent (a mutation):
 curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
@@ -59,3 +76,8 @@ subject with the `admin:full` scope (see [`api-rbac`](https://voltro.cloud/docs/
   whole (PII, tokens, notes).
 - **The key is everything.** GCM fails closed on a bad key — you get an error,
   never silent corruption. Back the key up; rotating it needs re-encrypting.
+- **`.encrypted()` is not `.serverOnly()`.** Three orthogonal markers, three
+  questions: `.encrypted()` = encrypted at rest, `.serverOnly()` = may it leave
+  the server at all, `.sensitive()`/`.safe()` = may it appear in a
+  `voltro data export`. Using one to answer another's question is the mistake —
+  say both when you mean both.

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