@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/audit.md

@@ -0,0 +1,324 @@
+# Audit
+
+> Mutation audit log — sinks (console/memory/custom), include/exclude filters, the audit() mixin, testing with the memory buffer.
+
+
+
+---
+
+<!-- source: en/plugins/audit.md -->
+## Audit
+
+_Mutation audit log — sinks (console/memory/custom), include/exclude filters, the audit() mixin, testing with the memory buffer._
+
+`@voltro/plugin-audit` has two independent surfaces, picked à la carte:
+
+1. **The `auditPlugin({ sink })` mutation interceptor** — records every mutation invocation (tag, subject, input, outcome, duration) to a configurable sink.
+2. **The `audit()` schema mixin** — adds `createdAt`/`updatedAt`/`createdBy`/`updatedBy` columns, auto-stamped by the runtime from the request subject.
+
+**Status:** ✓ shipped.
+
+## Installing
+
+```ts
+// app.config.ts
+import { auditPlugin } from '@voltro/plugin-audit'
+
+export default {
+  type: 'api' as const,
+  plugins: [
+    auditPlugin({ sink: 'console' }),
+  ],
+}
+```
+
+## What's recorded
+
+The interceptor records **mutation invocations only** — not queries, not actions, not AI/agent calls. (For AI token counts and cost, read the `usage` returned on every `@voltro/ai` call — see [Cost tracking](/docs/ai/cost-tracking).) One `AuditEvent` per outcome:
+
+```ts
+interface AuditEvent {
+  readonly ts: number           // start time (epoch ms)
+  readonly tag: string          // rpc tag, e.g. 'orders.create'
+  readonly subject: Subject     // resolved caller (carries tenantId)
+  readonly traceId: string
+  readonly input: unknown       // the mutation's validated input
+  readonly outcome:
+    | { readonly kind: 'ok';    readonly value: unknown; readonly durationMs: number }
+    | { readonly kind: 'error'; readonly error: unknown; readonly durationMs: number }
+}
+```
+
+A failure records the underlying `Effect.fail` value / thrown error (not the whole `Cause` tree); the original mutation outcome always flows through untouched.
+
+## Sinks
+
+`sink` is one of these shapes:
+
+```ts
+auditPlugin({ sink: 'console' })
+// default — one structured line per mutation via @voltro/logger
+// (log.info on success, log.warn on error)
+
+auditPlugin({ sink: 'memory' })
+// last 1000 events in an in-process ring buffer — for tests
+
+auditPlugin({ sink: 'datastore' })
+// DURABLE + queryable — contributes the _voltro_audit_log table
+// (extendSchema, under store:write) and appends one row per mutation
+
+auditPlugin({
+  sink: async (event) => { /* ship to wherever */ },
+})
+// custom function: (event: AuditEvent) => void | Promise<void> | Effect.Effect<void>
+```
+
+`'datastore'` is the production sink: it survives restarts, is shared across replicas, and is queryable via `ctx.store.select('_voltro_audit_log')`. Each row carries the flattened `tag` / `at` / `subjectId` / `tenantId` / `traceId` / `status` / `durationMs` (indexed by `tag` + `traceId`) plus the full `subject` / `input` / `outcome` as portable `json()` columns.
+
+The custom function is the escape hatch for persisting events anywhere the built-in table's schema doesn't fit — e.g. an `Effect.Effect<void>` sink that writes rows into your own audit table on top of `@effect/sql`. All return shapes are normalised by the interceptor. A sink that throws / rejects / dies is caught and swallowed, so a broken sink can never mask the mutation's real outcome.
+
+### `record` — which outcomes reach the sink
+
+`include` / `exclude` filter by TAG, before the call runs. `record` filters by what happened, after:
+
+```ts
+auditPlugin({ sink: 'datastore', record: 'errors' })
+```
+
+- `'all'` (default) — every invocation.
+- `'errors'` — refusals only: a denied guard, a revoked key, a rejected validation. This is the forensic core, and it pairs with [`@voltro/plugin-versioning`](/docs/plugins/versioning), which records the successful *writes* — so the two together still cover everything while this table stays small enough that retention is a footnote.
+- a predicate — `(event) => boolean`, for anything else.
+
+`'all'` is the default even though `'errors'` is often the right choice, because defaulting to errors would silently stop recording successes for every app that upgrades — and "what did this compromised account touch" is answered by successes. Shrinking the trail is a decision you make with your eyes open.
+
+### `redactInput` — what of the payload is kept
+
+**The default is `'all'`: the payload is replaced by `{ __redacted: 'all' }`.** The row still proves a payload existed; it just does not carry it.
+
+```ts
+auditPlugin({ sink: 'datastore', redactInput: 'none' })          // the raw input, verbatim
+auditPlugin({ sink: 'datastore', redactInput: (e) => pick(e) })  // field-level control
+```
+
+`input` is the raw mutation input, so an unredacted audit table is where a password change, an API key at issuance and a PAT land — the one place nobody thinks to look for a credential. Losing payload detail is visible the first time you read a row; leaking a credential is not visible at all.
+
+**Why it is not driven by `.serverOnly()` / `.sensitive()`,** which is the obvious design: those markers live on TABLE COLUMNS, and this is a mutation's INPUT. A `changePassword({ oldPassword, newPassword })` has no column to consult, so a marker-driven default would cover exactly 0% of the case it exists for — while reading, to whoever configured it, like protection. (`.sensitive()` is also the [export axis](/docs/database/sensitivity), not "unsafe to log"; treating one as the other is the category error that page warns about.) Pass a function once you know your own inputs.
+
+### `redactSubject` — what of the CALLER is kept
+
+**The default is `'metadata'`: `subject.metadata` is replaced by `{ __redacted: 'all' }`.** `type`, `id`, `tenantId` and `scopes` survive, which is everything the trail is actually read for.
+
+```ts
+auditPlugin({ sink: 'datastore', redactSubject: 'none' })              // the subject verbatim
+auditPlugin({ sink: 'datastore', redactSubject: (s) => pickSafe(s) })  // field-level control
+```
+
+**This exists because the durable sink wrote a live credential.** A reporter found a working Jira Personal Access Token in plaintext in 12 of 23 rows of their `_voltro_audit_log`, and neither plugin involved was wrong on its own:
+
+- [`plugin-atlassian`](/docs/plugins/atlassian)'s `credentialsResolver` took a `Subject` and nothing else, so an app doing per-user Atlassian auth had nowhere to put the caller's PAT except `subject.metadata`;
+- this plugin serialised the Subject verbatim into a json column.
+
+Two correct contracts disagreeing about what a Subject *is* — an identity, or a credential envelope — with nothing reconciling them.
+
+The reasoning is `redactInput`'s, word for word, applied to the field it did not cover: `metadata` is not a table column either, so no schema marker protects it; it is app-controlled, so its contents cannot be reasoned about here; and the framework's own per-user-credential mechanism puts a credential in it.
+
+`resolveScope` still sees the **live** subject, so a scope derived from `metadata` keeps working — redaction applies to what is stored, not to what the plugin can compute.
+
+> **If you are upgrading, check the rows you already have.** A safer default does not un-leak a past row.
+>
+> ```sql
+> SELECT count(*) FROM _voltro_audit_log WHERE subject::text ILIKE '%token%';
+> ```
+>
+> Purge what you find and rotate the credentials — assume anything written to a log table has been read.
+
+### Reading it back — the correlation join
+
+The trail is only useful if you can enter it by the questions an incident asks. Two entry points, matching the two indices:
+
+```ts
+import { auditByTrace, auditBySubject } from '@voltro/plugin-audit'
+import { historyByTrace } from '@voltro/plugin-versioning'
+
+// What happened during ONE call — and what it changed.
+const calls   = await auditByTrace(ctx.store, traceId)
+const changed = await historyByTrace(ctx.store, traceId, ctx.request.subject.tenantId)
+
+// Every refusal by one actor, newest first.
+const denied = await auditBySubject(ctx.store, actorId, { status: 'error', limit: 50 })
+```
+
+`traceId` is the join key. [`plugin-versioning`](/docs/plugins/versioning) records *what changed*; this records *who called and whether they were refused*. Neither is complete alone, and before the join key existed they could not be read together at all.
+
+`auditBySubject` takes `status` as a real argument rather than leaving you to filter in JS: the index is `(subjectId, status, at)`, so a filter applied after fetching would not use it.
+
+### Retention, and the GDPR interaction
+
+`sink: 'datastore'` registers its own retention: **365 days by default**, tunable with `VOLTRO_AUDIT_LOG_TTL_HOURS`, drained by the boot sweep. An append-only trail with no ceiling is the one that eventually takes the database down.
+
+**Erasure is deliberately NOT registered for you.** Erasing a subject must not delete the record that they were refused four hundred times — that record *is* the evidence. The defensible treatment is to anonymise rather than delete, and it is a compliance decision your app makes explicitly:
+
+```ts
+governancePlugin({
+  subjectScopes: [{ table: '_voltro_audit_log', subjectField: 'subjectId' }],
+  erasure: { mode: 'anonymize', anonymizeFields: ['subjectId', 'subject', 'input'] },
+})
+```
+
+**Not included (yet):** no built-in OpenTelemetry sink and no truncation options.
+
+## Scoping which mutations are recorded
+
+`include` / `exclude` are `RegExp`s tested against the rpc tag:
+
+```ts
+auditPlugin({
+  sink:    'console',
+  include: /^orders\./,      // record ONLY these tags (default: all)
+  exclude: /^orders\.debug/, // skip these — overrides `include`
+})
+```
+
+Useful for keeping high-frequency mutations (presence pings, analytics events) out of the log.
+
+## The `audit()` schema mixin
+
+Import from the browser-safe `/mixin` subpath in a `*.entity.ts` file and chain it with `.with(...)`:
+
+```ts
+// database/notes.entity.ts
+import { table, id, text } from '@voltro/database'
+import { audit } from '@voltro/plugin-audit/mixin'
+
+export const notes = table('notes', {
+  id:    id(),
+  title: text(),
+  body:  text(),
+})
+  .with(audit())   // + createdAt / updatedAt / createdBy / updatedBy
+```
+
+Mixin adds:
+
+| Column      | Type             | Filled on                    |
+| ----------- | ---------------- | ---------------------------- |
+| `createdAt` | `Date`           | insert                       |
+| `updatedAt` | `Date`           | insert + update              |
+| `createdBy` | `string \| null` | insert (→ `actors`)          |
+| `updatedBy` | `string \| null` | insert + update (→ `actors`) |
+
+The `*By` columns are `reference`s to the app's `actors` table and are **nullable** — a system-seeded or pre-auth write (e.g. signup) leaves them unset. The runtime fills all four from the request subject automatically; an explicit value the caller passes is respected, not overwritten. `softDelete()`, `tenant()`, and `deactivation()` all transitively require `audit()`.
+
+## Asserting on emitted events in a test
+
+```ts
+import { auditPlugin, readAuditBuffer, clearAuditBuffer } from '@voltro/plugin-audit'
+
+beforeEach(() => clearAuditBuffer())
+
+const plugin = auditPlugin({ sink: 'memory' })
+// … drive a mutation through the plugin …
+const events = readAuditBuffer()   // ReadonlyArray<AuditEvent>, oldest → newest
+```
+
+`readAuditBuffer()` returns a detached snapshot copy; the buffer caps at 1000 events (oldest evicted first).
+
+## Who acted — a snapshot, not a reference
+
+Both `_voltro_audit_log` and `_voltro_row_history` carry
+`actor json { id, type, displayName, email }`, resolved from the `actors` row at
+WRITE time.
+
+The reason is visible inside a single row: `data` on a history row is a full-row
+snapshot — deliberately, so it survives what happens to its source — while
+`changedBy` beside it is a foreign key that does not. One record, two
+philosophies.
+
+That matters because the right to be forgotten is one this framework grants:
+`@voltro/plugin-governance`'s `governance.erase` (`delete | anonymize`) exists
+for it. Without a snapshot, installing audit + versioning + governance together
+makes the first two unreadable for exactly the subjects an investigation is
+about. **Anonymisation is the worse half**: the join succeeds and returns
+"Anonymised" for every entry that actor ever produced, retroactively rewriting
+history that was correct when it was written.
+
+`email` is read opportunistically — the framework's own `actors` carries
+`id` / `kind` / `displayName`, and apps commonly extend it. Resolution is
+best-effort and never fails the mutation it records, and absent stays absent: a
+fabricated name is what this column exists to prevent.
+
+`_voltro_audit_log.metadata` is yours to write — the noun a diff cannot contain.
+"Anna removed Bernd from the Frontend sub-team" is one row-delete plus a
+membership row, and no column-level detail reconstructs the sentence.
+
+## What is recorded
+
+```ts
+auditPlugin({
+  // Actions record by default. Queries are opt-in — a read-heavy app would
+  // write one row per read and drown the trail it needs searchable.
+  recordQueries: true,
+  include: /^export\./,
+})
+```
+
+Mutations and actions record by default; both write. Queries are opt-in, for the
+surfaces where the READ is the sensitive act — a GDPR export, a salary view —
+usually together with `include` so it stays targeted.
+
+
+## Scoping the trail — `scope`
+
+```ts
+auditPlugin({
+  // The app's own dimension — the framework does not know what a team is.
+  // From the subject when your session is team-shaped …
+  resolveScope: (ctx) => ({ teamId: ctx.subject.metadata?.teamId }),
+})
+
+auditPlugin({
+  // … or from the call's INPUT, which is where it usually lives.
+  resolveScope: (ctx) =>
+    typeof ctx.input?.teamId === 'string' ? { teamId: ctx.input.teamId } : undefined,
+})
+
+versioningPlugin({
+  // From the ROW here — that is what this plugin has.
+  resolveScope: (row) => ({ teamId: row.teamId }),
+})
+```
+
+**`input` is there because the subject-only version covered the wrong half.** A
+reporter's users belong to MANY teams, so their session carries no "current
+team" and cannot without inventing a concept their product does not have — a
+mutation's team comes from its input or from the row it loads. Their API-key
+subjects *do* carry a `teamId`, which made subject-only worse than nothing for
+them: it would have populated for key-authenticated calls and been null for every
+human one, so a filtered view would have looked like it worked.
+
+The input here is **raw** — not what [`redactInput`](#redactinput--what-of-the-payload-is-kept)
+will store. That is required (a scope derived from a redacted payload is not
+derivable at all) and it is a hazard worth naming: whatever you return lands in
+`scope`, which is *not* redacted. Return the dimension, never the payload.
+
+`scope` is opaque json on both `_voltro_audit_log` and `_voltro_row_history`,
+stored and returned verbatim and filtered on equality — the same column
+`_voltro_webhook_targets` carries, for the same reason: `.with(tenant())` is one
+level too coarse when a trail is per-team and a tenant has many teams.
+
+**It is not `metadata`, and the distinction is load-bearing.** `metadata` is
+documented as the app's free-form note — the noun a diff cannot contain. Filtering
+on it means building a read path against a column whose contract says it is not
+one. Two columns, two jobs.
+
+Configure it on **both** plugins or half of every view is unfiltered. Neither
+resolver can fail your write: an underivable scope is `null`, the same answer as
+not configuring one.
+
+
+## Anti-patterns
+
+- **Relying on the `'memory'` sink in production.** It is a per-process test buffer capped at 1000 events — not a durable store. Use `sink: 'datastore'` (or a custom function sink) instead.
+- **A throwing sink as a validation gate.** Sink failures are deliberately swallowed; the sink can never veto or alter the mutation.
+- **PII in mutation inputs.** The interceptor records the validated input verbatim — there is no built-in redactor. Keep secrets out of mutation inputs, or redact inside your custom sink before persisting.
+- **Audit log as a queryable view of business state.** It's a write log. The actual current state lives in your normal tables.

package/templates/agent-docs/plugins/auth-auth0.md

@@ -0,0 +1,92 @@
+# Auth0
+
+> Auth0 AuthStrategy — verifies Auth0-issued JWTs via the tenant's JWKS (no client secret) and maps a namespaced custom claim → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-auth0.md -->
+## Auth0
+
+_Auth0 AuthStrategy — verifies Auth0-issued JWTs via the tenant's JWKS (no client secret) and maps a namespaced custom claim → tenantId._
+
+`@voltro/plugin-auth-auth0` integrates [Auth0](https://auth0.com): an `AuthStrategy` (conforming to `@voltro/protocol`) that verifies Auth0-issued JWTs against the tenant's **JWKS endpoint** (public-key verify — no client secret), maps a namespaced custom claim to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It's a thin specialization of the shared `jwtBearerStrategy` — it adds Auth0's defaults and performs no verification of its own. Verified claims arrive on the Subject as `metadata.provider === 'auth0'` + `metadata.claims`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-auth0
+```
+
+## Wiring
+
+Add `auth0Strategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { auth0Strategy } from '@voltro/plugin-auth-auth0'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      auth0Strategy({
+        domain:   'acme.us.auth0.com',                 // required — builds JWKS URL + issuer
+        audience: 'https://api.acme.com',              // your API identifier
+        // tenantClaim: 'https://voltro.dev/tenant',    // default namespaced URN
+        // defaultTenantId: 'public',                   // fallback for single-tenant setups
+        // scopesFromClaims: (c) => c.permissions ?? [], // Auth0 RBAC permissions → scopes
+      }),
+    ],
+  },
+}
+```
+
+`domain` is the only required option (protocol + trailing slash are stripped). From it: JWKS URL defaults to `https://<domain>/.well-known/jwks.json` and issuer to `https://<domain>/` — **the trailing slash matters for Auth0** (override `issuer` for a custom domain).
+
+Tenant resolution maps from `tenantClaim` (default the namespaced URN `https://voltro.dev/tenant` — Auth0's rules require non-standard claims to live under a URN). Use a custom Auth0 Action to copy your app metadata into the namespaced claim, or point `tenantClaim` at an unnamespaced field that already exists in your token. Supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict). `scopesFromClaims` maps verified claims (the `permissions` array with RBAC enabled, or the space-delimited `scope` claim) onto `Subject.scopes`.
+
+To accept your own password sessions AND Auth0 during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { auth0Strategy } from '@voltro/plugin-auth-auth0'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  auth0Strategy({ domain: process.env.AUTH0_DOMAIN!, audience: process.env.AUTH0_AUDIENCE! }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `domain` | — (**required**) | e.g. `acme.us.auth0.com`. Builds JWKS URL + issuer. |
+| `audience` | (off) | Your API identifier. String or array. |
+| `jwksUrl` | `https://<domain>/.well-known/jwks.json` | Override. |
+| `issuer` | `https://<domain>/` | Trailing slash matters; override for custom domains. |
+| `cookieName` | `null` (header-only) | Auth0's hosted flow uses Bearer tokens. |
+| `tenantClaim` | `'https://voltro.dev/tenant'` | Namespaced URN. |
+| `tenantIdFromClaims` | (uses `tenantClaim`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback for single-tenant setups. |
+| `scopesFromClaims` | (none) | Map claims → `Subject.scopes`. |
+
+Algorithms are pinned to `['RS256']` (no alg-confusion).
+
+## Environment variables
+
+None read directly — pass `domain` / `audience` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token, or one with no resolvable tenant, yields `failed`, never `matched`. JWKS public-key verify only; no Auth0 client secret is ever handled.
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)

package/templates/agent-docs/plugins/auth-clerk.md

@@ -0,0 +1,90 @@
+# Clerk
+
+> Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-clerk.md -->
+## Clerk
+
+_Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId._
+
+`@voltro/plugin-auth-clerk` integrates [Clerk](https://clerk.com): an `AuthStrategy` (conforming to `@voltro/protocol`) that verifies Clerk-issued `__session` JWTs against the **Frontend API JWKS** (public-key verify — no secret key), maps Clerk's Organizations `org_id` to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It's a thin specialization of the shared `jwtBearerStrategy` — it adds Clerk's defaults and performs no verification of its own. Verified claims arrive on the Subject as `metadata.provider === 'clerk'` + `metadata.claims`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-clerk
+```
+
+## Wiring
+
+Add `clerkStrategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { clerkStrategy } from '@voltro/plugin-auth-clerk'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      clerkStrategy({
+        frontendApi: 'https://clerk.yourapp.com',   // required — Clerk Frontend API host
+        // audience: '…',                            // ONLY with a Clerk JWT Template
+        // defaultTenantId: 'public',                // fallback when no org_id claim
+      }),
+    ],
+  },
+}
+```
+
+`frontendApi` is the only required option (trailing slash is normalised). From it: JWKS URL defaults to `<frontendApi>/.well-known/jwks.json` and issuer to `<frontendApi>` (Clerk mirrors the host into the `iss` claim). The cookie defaults to `__session` (Clerk's hardcoded session cookie name; pass `null` for header-only).
+
+Tenant resolution maps from `claims.org_id` (Clerk's "Organizations" feature), then `defaultTenantId`. Supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict). Clerk's default `__session` tokens carry no `aud` claim, so the audience check is off — only set `audience` when you've configured a Clerk **JWT Template** with one.
+
+To accept your own password sessions AND Clerk during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { clerkStrategy } from '@voltro/plugin-auth-clerk'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  clerkStrategy({ frontendApi: process.env.CLERK_FRONTEND_API! }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `frontendApi` | — (**required**) | Clerk Frontend API host. Builds JWKS URL + issuer. |
+| `jwksUrl` | `<frontendApi>/.well-known/jwks.json` | Override. |
+| `issuer` | `<frontendApi>` | Override. |
+| `audience` | (off) | Only with a Clerk JWT Template that sets one. |
+| `algorithms` | `['RS256', 'ES256']` | JWT signing-algorithm allowlist; override for a non-default Clerk config. |
+| `cookieName` | `'__session'` | Clerk's hardcoded cookie; `null` for header-only. |
+| `tenantIdFromClaims` | (uses `org_id`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback when no `org_id` claim. |
+| `scopesFromClaims` | (none) | Map claims (`org_permissions`, or a JWT-Template `permissions`) → `Subject.scopes`. |
+
+Algorithms default to `['RS256', 'ES256']` — pinned (not trusting the token's declared `alg`) to close alg-confusion; override via `algorithms`.
+
+## Environment variables
+
+None read directly — pass `frontendApi` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token, or one with no resolvable tenant, yields `failed`, never `matched`. JWKS public-key verify only; no Clerk secret key is ever handled.
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)

package/templates/agent-docs/plugins/auth-kinde.md

@@ -0,0 +1,88 @@
+# Kinde
+
+> Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-kinde.md -->
+## Kinde
+
+_Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId._
+
+`@voltro/plugin-auth-kinde` integrates [Kinde](https://kinde.com): an `AuthStrategy` (conforming to `@voltro/protocol`) that verifies Kinde-issued JWTs against the issuer's **JWKS endpoint** (public-key verify — no client secret), maps Kinde's `org_code` to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It's a thin specialization of the shared `jwtBearerStrategy` — it adds Kinde's defaults and performs no verification of its own. Verified claims arrive on the Subject as `metadata.provider === 'kinde'` + `metadata.claims`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-kinde
+```
+
+## Wiring
+
+Add `kindeStrategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { kindeStrategy } from '@voltro/plugin-auth-kinde'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      kindeStrategy({
+        issuer:   'https://yourcompany.kinde.com',   // required
+        // audience: '…',                             // your Kinde API audience
+        // defaultTenantId: 'public',                 // fallback for single-tenant setups
+        // scopesFromClaims: (c) => c.permissions ?? [],  // Kinde permissions → scopes
+      }),
+    ],
+  },
+}
+```
+
+`issuer` is the only required option (trailing slash is normalised). From it the JWKS URL defaults to `<issuer>/.well-known/jwks`. The cookie defaults to `kinde_access_token` (for apps that mirror the SDK's token into a cookie for SSR; pass `null` for header-only).
+
+Tenant resolution maps from `claims.org_code`, falling back to `claims.org_codes[0]`, then `defaultTenantId`. Supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict). `scopesFromClaims` maps verified claims onto `Subject.scopes` — Kinde emits a `permissions` array and a `roles` list (e.g. `roles.map((r) => r.key)`).
+
+To accept your own password sessions AND Kinde during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { kindeStrategy } from '@voltro/plugin-auth-kinde'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  kindeStrategy({ issuer: process.env.KINDE_ISSUER! }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `issuer` | — (**required**) | e.g. `https://acme.kinde.com`. Builds JWKS URL. |
+| `audience` | (off) | Your Kinde API audience. |
+| `jwksUrl` | `<issuer>/.well-known/jwks` | Override. |
+| `algorithms` | `['RS256']` | Allowlist; override for a non-default Kinde signing alg. |
+| `cookieName` | `'kinde_access_token'` | `null` for header-only. |
+| `tenantIdFromClaims` | (uses `org_code` → `org_codes[0]`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback for single-tenant setups. |
+| `scopesFromClaims` | (none) | Map claims → `Subject.scopes`. |
+
+## Environment variables
+
+None read directly — pass `issuer` / `audience` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token, or one with no resolvable tenant, yields `failed`, never `matched`. JWKS public-key verify only; no Kinde client secret is ever handled.
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)