@voltro/cli 0.1.0

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

@@ -0,0 +1,30 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@react-email/components": "^1.0.12",
+    "@react-email/render": "^1.4.0",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-mail": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

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

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

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

@@ -0,0 +1,20 @@
+// Streaming subscription: every change to `notes` for the caller's
+// tenant lands as a delta. The runtime AND-merges tenant scope into
+// the predicate via the `tenant()` mixin on the table — no manual
+// `eq('tenantId', ...)` needed in the handler.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-backend-mail",
+  "kind": "api",
+  "summary": "Voltro backend with transactional email wired: @voltro/plugin-mail + a React-Email welcome template you preview/send from the dashboard. Same minimal base as api-backend.",
+  "tags": ["api", "backend", "mail", "email", "starter"]
+}

package/templates/apps/api-backend-mail/tests/notes.create.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing` — no database, no running server. Importing
+// `../database/schema` registers the `notes` / `actors` / `tenants` tables
+// globally, so `makeTestContext` auto-wires them into the in-memory store.
+// `ctx.store` is the SAME mixin-wrapped store the handler gets in production,
+// so tenant auto-scoping + audit auto-fill behave exactly as at runtime.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema' // registers notes / actors / tenants
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ tenantId: 'acme', title: 'Hello', body: 'World' }, ctx)
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tenantId']).toBe('acme')  // assertOwnTenant let it through + stamped
+    expect(row['done']).toBe(false)
+    expect(String(row['id'])).toMatch(/^note_/) // TypeID auto-injected from id()
+  })
+
+  it('rejects a cross-tenant spoof — input.tenantId must match the subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    await expect(
+      createNote({ tenantId: 'other-tenant', title: 'spoof', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ notes: [] }),
+    })
+    await createNote({ tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // (eq tenantId) hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,35 @@
+# {{capProjectName}} — MariaDB backend env. Copy to `.env` and adjust.
+
+# ── Database (MariaDB + binlog CDC) ────────────────────────────────────
+DB_DIALECT=mariadb
+DB_URL=mysql://app:app@localhost:3307/{{projectNameSnake}}
+# Push-based real-time across replicas via the binlog reader. Requires the
+# DB to run with binlog_format=ROW + binlog_row_image=FULL (the compose
+# baseline sets these) and a user with REPLICATION SLAVE, REPLICATION
+# CLIENT. Set CDC=0 to fall back to single-process inline emit.
+CDC=1
+
+# ── File storage (A2) — MinIO locally, S3 in prod ──────────────────────
+STORAGE_PROVIDER=minio
+S3_ENDPOINT=http://localhost:9000
+S3_BUCKET={{projectNameSnake}}
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_FORCE_PATH_STYLE=1
+
+# ── AI runtime (A3) — set a real provider + key to enable agents ───────
+AI_PROVIDER=mock
+# AI_PROVIDER=anthropic
+# AI_MODEL=claude-opus-4-7
+# ANTHROPIC_API_KEY=
+
+# ── Auth ───────────────────────────────────────────────────────────────
+# HMAC key for signed sessions — REQUIRED in production (refuses to boot
+# without it). Generate: openssl rand -hex 32
+VOLTRO_SESSION_SECRET=dev-only-change-me
+
+# ── Cluster (K8s, >1 replica) ──────────────────────────────────────────
+# The workflow runner must advertise a routable host so a workflow can
+# resume on another pod. Inject POD_IP via the downward API in prod
+# (fieldRef: status.podIP); leave unset for single-node local dev.
+# VOLTRO_WORKFLOW_RUNNER_HOST=

package/templates/apps/api-backend-mariadb/README.md

@@ -0,0 +1,31 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-backend-mariadb**) — MariaDB-backed
+with binlog CDC real-time + file storage.
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+cp .env.example .env        # then adjust DB_URL / secrets
+# Start MariaDB (binlog ROW) + MinIO — see the compose baseline.
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+## What's in here
+
+| File | Role |
+|---|---|
+| `app.config.ts`            | `store: 'mariadb'` (binlog CDC) + the storage plugin. |
+| `.env.example`             | DB / storage / AI / auth / cluster env. |
+| `database/schema.ts`       | One example table (`notes`) with the `tenant()` mixin. |
+| `queries/notes.*`          | Streaming subscription example. |
+| `mutations/notes.create.*` | Tenant-guarded mutation example. |
+
+`store: 'mariadb'` fans subscriptions out across replicas via the binary
+log — the DB must run with `binlog_format=ROW` + `binlog_row_image=FULL`
+and a replication user (the compose baseline sets this up). Drop more
+`*.query.ts` + `*.query.server.ts`, `*.mutation.ts` + `*.mutation.server.ts`, `*.action.ts` + `*.action.server.ts`, or `*.stream.ts` + `*.stream.server.ts`, `*.workflow.tsx`, or `*.cron.tsx` files
+anywhere in this tree — discovery is by file convention.

package/templates/apps/api-backend-mariadb/app.config.ts

@@ -0,0 +1,68 @@
+// Backend app for the {{projectName}} project, backed by MariaDB. Read by
+// `voltro dev` (local) and `voltro serve` (production).
+//
+// `store: 'mariadb'` turns on the binlog CDC reader: real-time
+// subscriptions fan out across every replica via the database's binary
+// log (no Redis/NATS — the binlog IS the message bus). The DB must run
+// with `binlog_format=ROW` + `binlog_row_image=FULL` and a user holding
+// `REPLICATION SLAVE, REPLICATION CLIENT` — the compose baseline sets all
+// of this up; in prod the Helm baseline wires the per-pod `server_id`.
+//
+// `plugins` composes cross-cutting behaviour. File storage is on by
+// default (MinIO locally, S3 in prod).
+import { defineEnv, envVar } from '@voltro/env'
+import { storagePlugin } from '@voltro/plugin-storage'
+// Auth strategies (uncomment + configure to enable — see `auth` below):
+// import { jwtBearerStrategy } from '@voltro/protocol'
+// import { apiKeyStrategy } from '@voltro/protocol/apikey'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // Add your own, e.g.:
+  //   STRIPE_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'mariadb' as const,
+  env,
+  plugins: [
+    // Blobs in object storage; metadata in `_voltro_storage_refs`.
+    // Provider resolved from `STORAGE_PROVIDER` (minio | s3 | filesystem).
+    storagePlugin(),
+  ],
+
+  // Auth: the built-in signed-cookie password strategy ALWAYS runs first;
+  // these run after it, in order, until one matches or rejects. The same
+  // chain serves dev and prod. Uncomment + configure for your IdP / keys.
+  //
+  // auth: {
+  //   strategies: [
+  //     // JWKS cookie sessions — verifies a JWT from your IdP against its
+  //     // JWKS endpoint and maps a claim to the active org (tenantId).
+  //     jwtBearerStrategy({
+  //       id: 'idp',
+  //       jwksUrl: process.env.JWKS_URL!,
+  //       issuer: process.env.JWT_ISSUER,
+  //       cookieName: '{{projectName}}-session',
+  //       claimsToTenantId: (claims) => (claims.org as string) ?? null,
+  //     }),
+  //     // `{{projectName}}_`-prefixed API keys: the strategy strips the
+  //     // prefix, sha256-hashes the token, and hands you the hash —
+  //     // look it up in your key table and return id/tenantId/scopes.
+  //     apiKeyStrategy({
+  //       prefix: '{{projectName}}_',
+  //       resolveKey: async (hash) => {
+  //         // const row = await lookupApiKeyByHash(hash)
+  //         // return row ? { id: row.id, tenantId: row.orgId, scopes: row.scopes } : null
+  //         return null
+  //       },
+  //     }),
+  //   ],
+  // },
+}

package/templates/apps/api-backend-mariadb/database/schema.ts

@@ -0,0 +1,57 @@
+// Schema for the {{projectName}} backend.
+//
+// Tables are auto-discovered: every exported `table(...)` in this file
+// (or any `*.entity.ts` / `*.schema.ts` file) is registered by
+// `voltro dev` — no manual barrel. `actors` + `tenants` are the
+// framework's core tables: the built-in `audit()` / `tenant()` /
+// `softDelete()` mixins reference them, so they must be declared (the
+// CLI wires them into the mixin registry once it finds them).
+//
+// Add the `tenant()` mixin to a table to make it tenant-scoped — the
+// runtime AND-merges `eq('tenantId', subject.tenantId)` into every
+// subscription predicate, so cross-tenant reads can't leak.
+
+import {
+  boolean,
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application tables — rename / replace with your own ----------
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+  done:  boolean().default(false),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+  // Opt into the matcher engine: subscriptions against `notes` get a
+  // fresh snapshot/delta whenever a mutation writes the table.
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

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

@@ -0,0 +1,19 @@
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; title: string; body: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // Framework auto-injects a `note_…` id from the table's id() decl.
+  return ctx.store.insert('notes', {
+    title: input.title,
+    body: input.body,
+    done: false,
+    tenantId: input.tenantId,
+    createdAt: new Date(),
+  })
+}
+
+export default execute

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

@@ -0,0 +1,37 @@
+// Creates a note. The handler's `assertOwnTenant` guard rejects
+// cross-tenant spoofing — input.tenantId MUST match the resolved
+// subject's tenantId, else the rpc layer surfaces a typed
+// `TenantMismatch` error.
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: {
+    table: 'notes',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title,
+      body: input.body,
+      done: false,
+      tenantId: input.tenantId,
+      createdAt: new Date(),
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+  error: TenantMismatch,
+})

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

@@ -0,0 +1,30 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-storage": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "@voltro/sql-mysql": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

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

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

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

@@ -0,0 +1,20 @@
+// Streaming subscription: every change to `notes` for the caller's
+// tenant lands as a delta. The runtime AND-merges tenant scope into
+// the predicate via the `tenant()` mixin on the table — no manual
+// `eq('tenantId', ...)` needed in the handler.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-backend-mariadb",
+  "kind": "api",
+  "summary": "MariaDB-backed Voltro backend: binlog CDC real-time, file storage (MinIO/S3), tenant-aware schema. The dogfooded shape for K8s multi-replica apps.",
+  "tags": ["api", "backend", "mariadb", "cdc", "storage", "k8s"]
+}

package/templates/apps/api-backend-mariadb/tests/notes.create.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing` — no database, no running server. The
+// MariaDB store dialect is IRRELEVANT here: `makeTestContext` runs the handler
+// against the in-memory harness, so tenant auto-scoping + audit auto-fill
+// behave exactly as at runtime regardless of the production store. Importing
+// `../database/schema` registers the `notes` / `actors` / `tenants` tables
+// globally. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema' // registers notes / actors / tenants
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ tenantId: 'acme', title: 'Hello', body: 'World' }, ctx)
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tenantId']).toBe('acme')  // assertOwnTenant let it through + stamped
+    expect(row['done']).toBe(false)
+    expect(String(row['id'])).toMatch(/^note_/) // TypeID auto-injected from id()
+  })
+
+  it('rejects a cross-tenant spoof — input.tenantId must match the subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    await expect(
+      createNote({ tenantId: 'other-tenant', title: 'spoof', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ notes: [] }),
+    })
+    await createNote({ tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // (eq tenantId) hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

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

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-backend-storage/README.md

@@ -0,0 +1,86 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-backend-storage**).
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+## What's in here
+
+| File | Role |
+|---|---|
+| `app.config.ts`                            | App declaration + `storagePlugin` wired (`memory` provider). |
+| `database/schema.ts`                       | One example table (`notes`) with the `tenant()` mixin. |
+| `queries/` + `mutations/`                  | Streaming subscription + tenant-guarded mutation examples. |
+| `actions/uploadAvatar.{rpc,handler}.ts`    | `storage.uploadAvatar` — stores a PUBLIC avatar, returns its URL. |
+| `actions/uploadDocument.{rpc,handler}.ts`  | `storage.uploadDocument` — stores a PRIVATE doc (owner + admin + tenant policy). |
+
+## Storage
+
+File storage is wired out of the box via `@voltro/plugin-storage`:
+
+- **Public objects** (`visibility: 'public'`) are served direct from the
+  bucket/CDN — set `cdnBaseUrl` on the plugin for production. The app's
+  `/_voltro/storage/:id` route is only a fallback for the `memory` /
+  `filesystem` providers in dev.
+- **Private objects** (default) are gated by an **access policy** — any-of
+  rules over `owner` / `roles` / `groups` / `scopes` / `tenant` / `apiKey`
+  / `password` / a custom `guard` — PLUS **per-object grants** (share a
+  file with a specific user / group / api-key, optionally expiring).
+- **Browse + share** stored objects from the dashboard's **Storage** tab
+  (`/_voltro/inspect/plugins/storage/*`).
+
+### Delivering a private file
+
+```ts
+// In an action/handler — access-checked, returns a presigned URL (s3) or
+// an app URL carrying a short-lived signed grant token (fs/memory):
+import { StorageService } from '@voltro/plugin-storage'
+const storage = yield* StorageService
+const url = yield* storage.mintUrl(fileId, ctx.request.subject)
+```
+
+Or use the plugin's built-in typed RPC routes from the client:
+`storage.upload`, `storage.mintUrl`, `storage.mintUploadUrl` (presigned
+PUT), `storage.share`, `storage.revoke`, `storage.listGrants`.
+
+### Switching providers
+
+```ts
+storagePlugin({ provider: 's3', bucket: 'my-bucket', region: 'us-east-1',
+                cdnBaseUrl: 'https://cdn.example.com' })   // + S3_* env
+storagePlugin({ provider: 'minio', bucket: 'my-bucket', endpoint: 'http://localhost:9000' })
+storagePlugin({ provider: 'azure', bucket: 'my-container', accountName: 'acct' }) // + AZURE_STORAGE_KEY
+storagePlugin({ provider: 'filesystem', root: '.voltro-storage' })
+storagePlugin({ provider: 'database' })   // bytes in your DB — zero extra infra
+```
+
+Any S3-compatible bucket works via `endpoint` (AWS, Cloudflare R2, GCS,
+Backblaze B2, MinIO, Wasabi). `azure` covers Azure Blob; `database` keeps
+small blobs in the app's DB. `_voltro_storage_refs` +
+`_voltro_storage_grants` (+ `_voltro_storage_blobs` for the `database`
+provider) are auto-migrated on `store: 'postgres'`.
+
+### Constraints, virus scanning & image transforms
+
+```ts
+import { storagePlugin, clamavScanner } from '@voltro/plugin-storage'
+
+storagePlugin({
+  provider: 'memory',
+  limits: { maxBytes: 10_000_000, allowedContentTypes: ['image/*', 'application/pdf'], sniff: true },
+  scan: clamavScanner({ host: '127.0.0.1', port: 3310 }),  // optional — needs a clamd
+})
+```
+
+- **Constraints** reject oversized / wrong-type uploads (`sniff` magic-byte-checks
+  the bytes) with a typed `StorageRejected`.
+- **Virus scan** runs on every `put`; a detection fails with `StorageScanRejected`.
+- **Image transforms** are on-the-fly via the serve URL — `?w=400&format=webp&q=80`
+  (needs the optional `sharp` dependency).

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

@@ -0,0 +1,21 @@
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { StorageService } from '@voltro/plugin-storage'
+
+const execute = (input: { bytesBase64: string; contentType: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const storage = yield* StorageService
+    const bytes = new Uint8Array(Buffer.from(input.bytesBase64, 'base64'))
+    const ref = yield* storage.put({
+      bytes,
+      contentType: input.contentType,
+      visibility: 'public',
+      ownerId: ctx.request.subject.id,
+      tenantId: ctx.request.subject.tenantId,
+      key: `avatars/${ctx.request.subject.id ?? 'anon'}/avatar`,
+    })
+    const url = yield* storage.getUrl(ref.id)
+    return { id: ref.id, url }
+  })
+
+export default execute

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

@@ -0,0 +1,21 @@
+// `storage.uploadAvatar` — stores a PUBLIC avatar. Public objects are
+// served direct from the bucket/CDN; the returned `url` is what you'd put
+// in an <img src>. File upload is external I/O → an action.
+//
+// For large files prefer a presigned direct-to-bucket upload via the
+// plugin's built-in `storage.mintUploadUrl` route.
+
+import { Schema } from 'effect'
+import { defineAction } from '@voltro/protocol'
+
+export const uploadAvatar = defineAction({
+  name: 'storage.uploadAvatar',
+  input: Schema.Struct({
+    bytesBase64: Schema.String,
+    contentType: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    url: Schema.String,
+  }),
+})