@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-auth/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: pikku-auth
+description: >-
+  Use for anything about identity in a Pikku app — authenticating a caller (login, logout,
+  sessions, cookies, bearer tokens, API keys, JWT, OAuth/social providers, MFA, Better Auth) and
+  authorizing one (pikkuPermission, pikkuAuth, scopes, defineScope, global permissions). Covers
+  which of the two a problem actually is, the built-in auth strategies, machine-to-machine auth
+  and `pikku login`, and the JWT service. TRIGGER when: user asks about login, logout, session,
+  cookie auth, bearer tokens, API keys, JWT, Better Auth, social providers, restricting who may
+  call a function, resource ownership, roles, scopes, or hits MissingScopeError or
+  InvalidSessionError. DO NOT TRIGGER when: user asks about middleware mechanics with no identity
+  involved (use pikku-middleware) or about secrets and env vars (use pikku-services).
+installGroups: [core]
+---
+
+# Pikku Auth
+
+Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the
+installed surface. This skill is the part the compiler cannot tell you: which of
+the two problems you actually have, and what goes wrong in each.
+
+## First: authentication or authorization?
+
+They are separate gates, and confusing them is the most common mistake in a
+Pikku app.
+
+**Authentication** answers _who is calling_. It happens in middleware, before the
+function runs, and ends in a call to `setSession`.
+
+**Authorization** answers _may this caller do this_. It is declared on the
+function — `scopes` and `permissions` — never checked inside its body.
+
+A `permissions` entry that verifies a bearer token and returns `true` is
+authentication wearing an authorization hat: it leaves the function sessionless,
+so every body still has to work out who called it. Resolve the credential in
+middleware instead.
+
+## Pick the reference
+
+| You are… | Read |
+| --- | --- |
+| Restricting who may call a function — ownership, roles, scopes | `references/permissions.md` |
+| Reading or setting the session, or wiring `authBearer`/`authCookie`/`authAPIKey` | `references/sessions.md` |
+| Standing up user sign-in — OAuth, email+password, MFA, organizations | `references/better-auth.md` |
+| Authenticating a CLI, agent, sandbox or worker — API keys, `pikku login` | `references/machine-auth.md` |
+| Configuring the JWT service, or rotating a signing secret | `references/jose.md` |
+
+## All authentication goes through `@pikku/better-auth`
+
+There is no second auth story. A hand-rolled user table, a bespoke password
+hash, a custom OAuth dance — all of them are the wrong answer, and the console
+will not work against them. `references/better-auth.md` has the setup; the
+built-in strategies in `references/sessions.md` are how a resolved credential
+becomes a Pikku session, not a replacement for it.
+
+## The three gates
+
+Authorization is three independent gates, all of which must pass, in this order:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation, fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd, an app-wide baseline.
+3. **The function's own `permissions`** — OR'd groups of AND'd entries.
+
+They are independent: a broad global gate can never satisfy a function's own
+requirement, and a scope can only ever narrow access, never grant it.
+
+## What NOT to do
+
+- **Do not check authorization inside `func`.** The `permissions` field is
+  visible to the inspector; a check in the body is invisible to `pikku info
+  permissions` and to an audit. The one sanctioned exception is
+  `permissionsInBody`, which is purely declarative — see
+  `references/permissions.md`.
+- **Do not write an "is signed in" permission.** `auth: true` (the default on
+  `pikkuFunc`) already requires the session. A checker returning `!!session`
+  gates nothing.
+- **Do not put `scopes` on a `pikkuSessionlessFunc`.** Scopes fail closed and an
+  anonymous caller holds none, so it would reject every caller it exists to
+  serve. Gate those with `permissions`, which receive an optional session.
+- **Do not expect the built-in strategies to authenticate a non-HTTP caller.**
+  `authBearer`, `authCookie` and `authAPIKey` all step aside when there is no
+  HTTP request — a queue job, a scheduled task or a channel message needs its
+  session set another way.
+- **Do not share one header between the human and machine paths.**
+  `Authorization: Bearer` is the human session; `x-api-key` is the machine key.
+  Merging them reintroduces the ambiguity the split exists to remove.
+- **Do not reach for wire-, tag- or route-level permissions.** They were removed
+  in #972. Permissions live on the function, plus the optional global gate; tags
+  are organizational only.

package/skills/{pikku-better-auth/SKILL.md → pikku-auth/references/better-auth.md}

@@ -1,18 +1,3 @@
----
-name: pikku-better-auth
-description: >-
-  Use when integrating Better Auth with a Pikku app. Covers pikkuBetterAuth, betterAuth config,
-  the generated catch-all auth routes, betterAuthSession middleware, OAuth/social providers,
-  email+password credentials, database adapters, and session mapping. TRIGGER when: code uses
-  pikkuBetterAuth, betterAuth, betterAuthSession, createAuthHandler, user asks about Better Auth,
-  OAuth/social providers, MFA, organizations, login/logout, or @pikku/better-auth. TRIGGER when: user asks
-  about the actor plugin, /sign-in/actor, signing in as a scenario persona, or SCENARIO_ACTOR_SECRET. TRIGGER when:
-  user asks about ANY form of authentication, login, logout, sessions, or user identity — always
-  answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
-  or custom session services (use pikku-services).
-installGroups: [fabric]
----
-
 # Pikku Better Auth Integration
 
 ## ⚠️ MANDATORY RULE — READ FIRST
@@ -30,18 +15,6 @@ The only acceptable auth implementation in a Pikku app is the one described in t
 
 ---
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, or build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated.
-4. Validate with the narrowest relevant command first, then run `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun. Do not edit generated files.
-
-`@pikku/better-auth` provides [Better Auth](https://better-auth.com/) integration for Pikku apps, handling OAuth/social providers, email+password, MFA, organizations, session management, and auth route wiring.
-
 ## Installation
 
 ```bash
@@ -61,7 +34,7 @@ You do NOT hand-write routes, the session middleware, or the secret wiring — `
 
 ### The console requires Better Auth
 
-The Pikku console (`@pikku/addon-console`, enabled via `scaffold.console` in `pikku.config.json`) is an admin surface: **every console RPC now requires an authenticated session** (the functions are `pikkuFunc`; unauthenticated calls return `403`). So `scaffold.console` alone is **no longer the minimum** — you also need an auth strategy, and Better Auth is the supported one. `pikku all` **throws** if `scaffold.console` is set but no `pikkuBetterAuth(...)` is found in the project. Baseline is "must be logged in"; finer policy (admin-only, org scoping) is layered host-side via tag/HTTP middleware. See `pikku-deps` for the console's Security screen.
+The Pikku console (`@pikku/addon-console`, enabled via `scaffold.console` in `pikku.config.json`) is an admin surface: **every console RPC now requires an authenticated session** (the functions are `pikkuFunc`; unauthenticated calls return `403`). So `scaffold.console` alone is **no longer the minimum** — you also need an auth strategy, and Better Auth is the supported one. `pikku all` **throws** if `scaffold.console` is set but no `pikkuBetterAuth(...)` is found in the project. Baseline is "must be logged in"; finer policy (admin-only, org scoping) is layered host-side via tag/HTTP middleware. See `pikku-meta` for the console's Security screen.
 
 ---
 
@@ -474,9 +447,14 @@ someone" means **a particular kind of user** rather than one fixed admin.
 Register it explicitly — it is not automatic:
 
 ```typescript
-import { pikkuActor } from '@pikku/better-auth'
-
-plugins: [pikkuActor({ secret: SCENARIO_ACTOR_SECRET })]
+import { ACTOR_SIGN_IN_OPT_IN_ENV, pikkuActor } from '@pikku/better-auth'
+
+plugins: [
+  pikkuActor({
+    secret: SCENARIO_ACTOR_SECRET,
+    allowSignIn: await variables.get(ACTOR_SIGN_IN_OPT_IN_ENV),
+  }),
+]
 ```
 
 `POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
@@ -507,9 +485,19 @@ itself instead.
 A stage that genuinely must run scenarios opts in on purpose, with
 `PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in`. Any other value is
 ignored and warned about, so the hatch cannot be opened by copying a `true` from
-the line above, and it is the only hatch — there is no build-time option, because
-an option compiled into the bundle cannot be audited from the environment it
-runs in.
+the line above.
+
+**Pass it in on any runtime without a populated `process.env`.** The gate reads
+the environment by default, which is enough for Node but not for a Worker: there
+the opt-in arrives as a binding and reaches user code through the variables
+service, so a gate left to `process.env` stays shut on exactly the stages a
+deployment targets. `allowSignIn` takes the value the caller already read —
+`await variables.get(ACTOR_SIGN_IN_OPT_IN_ENV)` — and is checked against the same
+literal, near-miss warning included. It is deliberately a value and not a flag:
+what opens the gate is still something the deployment set and an operator can
+read back out of it, never something compiled into the bundle. A value passed
+here is the one consulted, so the environment cannot quietly override what the
+stage was configured with.
 
 **Signing in and provisioning are separate powers.** An unknown address becomes
 an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
@@ -650,3 +638,107 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables, kysely }) => be
 - Export exactly ONE `pikkuBetterAuth` per project; the CLI generates a single catch-all worker for all auth routes.
 - `betterAuthSession({ auth })` (generated) bridges the better-auth session into the Pikku session on every request — you never add it by hand.
 - MFA, organizations, passkeys, etc. are better-auth plugins: add them to `betterAuth({ plugins: [...] })`. The catch-all route already forwards their endpoints.
+
+---
+
+## Post-signup side effects
+
+Anything that must happen after a user signs up — a welcome email, seeding a first
+row, creating a personal organization — goes in `databaseHooks.user.create.after`
+inside the `betterAuth({...})` config. Never a custom signup RPC that writes the
+user itself: better-auth owns the `user` table, and a second write path desyncs it
+from the session bridge.
+
+## Two-factor (2FA / MFA)
+
+TOTP authenticator apps, email/SMS OTP, backup codes and trusted devices are all
+better-auth's `twoFactor()` plugin. Never hand-roll TOTP or OTP.
+
+1. **Enable + migrate** — add `twoFactor({ issuer: '<AppName>' })` to the `plugins`
+   array in the `pikkuBetterAuth` factory, then generate its schema and apply it as a
+   migration like any other table change. Run the CLI at the version of better-auth the
+   project actually has installed (`npx @better-auth/cli@<that version> generate`) — a
+   bare `npx @better-auth/cli` resolves the latest release, which can emit a schema for
+   a library you are not running. `twoFactorSecret` lands on `user`.
+2. **Client** — add `twoFactorClient({ onTwoFactorRedirect() { /* go to /2fa */ } })`
+   to `createAuthClient({ plugins: [...] })`, and expose thin wrappers
+   (`enable2FA`, `verifyTotp`, `disable2FA`, …) rather than leaking the raw
+   `authClient`, same as every other auth call.
+3. **OTP delivery** — `otpOptions.sendOTP` goes through the injected email service
+   and a rendered template, not a raw `sendEmail`. Set `storeOTP: 'encrypted'`.
+4. **Sign-in flow** — the challenge is raised on the three CREDENTIAL endpoints:
+   `signIn.email`, `signIn.username` and `signIn.phoneNumber`. Check
+   `context.data.twoFactorRedirect` in `onSuccess`; if true, route to a `/2fa` page
+   and verify via `verifyTotp`/`verifyOtp`/`verifyBackupCode` (`trustDevice: true`
+   for a 30-day trusted device). The response also carries `twoFactorMethods`
+   (`'totp'` only once that user has a verified secret, `'otp'` whenever
+   `otpOptions.sendOTP` is configured) — render the choice from it rather than
+   assuming TOTP. The session cookie is only created after verification: the
+   credential handler's session is deleted while the challenge is in flight, so a
+   hook reading `ctx.context.newSession` after sign-in must null-check it.
+5. **UI** — a QR rendered from `data.totpURI` plus the `data.backupCodes` list.
+   Enabling, disabling and regenerating backup codes all require the user's
+   password.
+
+TOTP secrets and backup codes are encrypted at rest with the auth secret, and
+`/two-factor/*` is rate-limited (3/10s) out of the box.
+
+**2FA gates credential sign-in only.** Magic link, email OTP and OAuth are not
+matched by the plugin's hook, so a user with 2FA enabled who signs in through one
+of them is NOT challenged. If every route into the app must be gated, either do not
+offer the passwordless ones to 2FA users or add your own check — enabling the
+plugin does not do it.
+
+## Security hardening
+
+The `pikkuBetterAuth` factory — where `betterAuth({...})` is built — is the one
+place to harden. Everything below is a `betterAuth` option, not a pikku one.
+
+- **Secret** — `BETTER_AUTH_SECRET` comes from the injected secrets service
+  (`await secrets.getSecret('BETTER_AUTH_SECRET')`), never `process.env`, a
+  literal, or a fallback default. 32+ chars, high entropy
+  (`openssl rand -base64 32`). Better Auth rejects placeholder secrets in
+  production.
+- **Trusted origins** — the `baseURL` origin is auto-trusted, so a single-domain
+  app serving its API same-origin needs nothing. Add `trustedOrigins` (or a
+  comma-separated `BETTER_AUTH_TRUSTED_ORIGINS` variable; wildcards like
+  `*.example.com` allowed) ONLY when the browser origin differs from the API
+  origin — embedded, preview, or custom-domain deployments. An untrusted
+  `callbackURL`/`redirectTo`/`origin` is a 403.
+- **CSRF** — keep it on (`advanced.disableCSRFCheck: false`, the default). A
+  proxy in front of the app must preserve the `/api/auth/*` prefix so origin
+  checks still work; do not disable the check to "fix" a redirect.
+- **Rate limiting** — on by default in production (100/10s global, 3/10s on
+  sign-in/up/change-password). `storage: 'memory'` resets on restart, so a
+  deployed app wants `storage: 'database'`. Tighten sensitive routes with
+  `customRules`, e.g. `'/sign-in/email': { window: 60, max: 5 }` — the key is matched
+  against the path with the base path ALREADY STRIPPED, so a rule written as
+  `'/api/auth/sign-in/email'` matches nothing and silently leaves the route on the
+  default.
+- **Cookies & sessions** — `httpOnly`, `sameSite: 'lax'` and `path: '/'` are
+  unconditional, but `secure` and the `__Secure-` name prefix are NOT: they follow a
+  `baseURL` on `https://` (or production, or an explicit
+  `advanced.useSecureCookies: true`). A deployment whose TLS terminates at a proxy
+  and passes an `http://` baseURL through therefore ships session cookies with no
+  `secure` flag — set `useSecureCookies` there rather than assuming. Defaults are
+  `session.expiresIn` 7d and
+  `updateAge` 1d. Add `freshAge` for sensitive actions, and
+  `cookieCache: { strategy: 'jwe' }` if the session carries sensitive data — see
+  the cookieCache section above, which you want enabled regardless. Only enable
+  `crossSubDomainCookies` if auth is genuinely shared across subdomains.
+- **OAuth tokens** — set `account.encryptOAuthTokens: true` (AES-256-GCM) if you
+  store provider tokens to call their APIs later.
+- **Audit** — drive auth events from `databaseHooks` (`session.create.after`,
+  `user.update.after` for email changes, `account.create.after` for links) into
+  whatever audit service the app injects, never a bespoke audit table wired into
+  a function body. Returning `false` from a `before` hook blocks the operation.
+- **Background tasks** — on a serverless target, hand genuinely disposable work
+  (analytics, logging) to `advanced.backgroundTasks.handler` → `ctx.waitUntil(promise)`
+  so it does not delay the response. Not mail: the default handler is
+  `p.catch(() => {})`, so anything that must actually arrive — an invitation, a
+  password reset — is lost without a trace if the platform reaps the request first.
+  Better Auth sends its own through `runInBackgroundOrAwait`, which awaits when no
+  handler is configured; do the same for yours.
+- **Enumeration** — handled already (generic "Invalid credentials", dummy work on
+  unknown users). Keep your own error copy generic too; never leak "user not
+  found".

package/skills/{pikku-jose/SKILL.md → pikku-auth/references/jose.md}

@@ -1,27 +1,5 @@
----
-name: pikku-jose
-description: >-
-  Use when setting up JWT authentication with the jose library in a Pikku app. Covers
-  JoseJWTService constructor, secret rotation, token encoding/decoding/verification. TRIGGER when:
-  code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or
-  @pikku/jose. DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or
-  general service setup (use pikku-services).
-installGroups: [fabric]
----
-
 # Pikku Jose (JWT Service)
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-`@pikku/jose` provides JWT signing, verification, and decoding using the [jose](https://github.com/panva/jose) library. Implements the `JWTService` interface from `@pikku/core`.
 
 ## Installation
 
@@ -86,7 +64,7 @@ await jwt.init()
 A signing key is a secret, so it comes from the secrets service rather than
 `process.env` — and because `getSecrets` is a function called on demand, reading
 it there (not once at construction) is what makes the re-init-on-unknown-kid path
-above actually see a rotated key. See `pikku-config`.
+above actually see a rotated key. See `pikku-services`.
 
 ### Secret Rotation
 

package/skills/{pikku-machine-auth/SKILL.md → pikku-auth/references/machine-auth.md}

@@ -1,17 +1,3 @@
----
-name: pikku-machine-auth
-description: >-
-  Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine
-  (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions
-  into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key
-  plugin, machine identities, and `betterAuthSession` with the api-key branch. TRIGGER when: user
-  asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client
-  credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
-  NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
-  app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
-installGroups: [fabric]
----
-
 # Pikku Machine Auth
 
 Unified authentication for humans **and** machines against a Pikku + better-auth
@@ -29,15 +15,6 @@ Both resolve to a Pikku `UserSession` through one middleware:
 > better-auth's oidc-provider. The API Key plugin gives the same capability (a
 > baked secret a service presents for scoped access), not the wire protocol.
 
-## Agent Operating Procedure
-
-1. Discover before editing — inspect the app's `betterAuth({ plugins: [...] })`
-   config and existing middleware wiring before adding anything.
-2. Server changes go in the auth factory + a middleware wiring file; never put
-   auth checks in a function body (use `permissions`).
-3. The API Key plugin contributes an `apikey` table — add the matching SQL
-   migration and regenerate DB types before relying on it.
-4. Validate with the narrowest command, then `pikku all`.
 
 ## Human path — `pikku login`
 

package/skills/pikku-auth/references/permissions.md

@@ -0,0 +1,261 @@
+# Pikku Permissions
+
+## ⛔ FIRST: is the caller a machine with a token? ⛔
+
+**Then this is NOT a permissions problem.** Resolve the token in `addHTTPMiddleware('*')` middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with `scopes`. A `permissions` check that verifies a bearer token and returns `true` is authentication wearing an authorization hat — and it leaves the function sessionless, so every body still has to work out who called it. See `references/machine-auth.md`. The only exception is a bootstrap endpoint whose caller has no identity yet (a shared-secret registration, a login): that one is sessionless and declares its gate here.
+
+## The Rule
+
+**ALWAYS put authorization checks in the `permissions` field of `pikkuFunc` or `pikkuSessionlessFunc` — NEVER inside the `func` body.**
+
+This includes: org access checks, repo access checks, role checks, resource ownership, and any other authorization logic. The `permissions` field runs before `func` and is visible to the inspector, so the gate is declared rather than buried — which is what lets `pikku info permissions` and an audit see it at all. Alongside it sits `scopes` (see below) for grant-based gating; between them they are where Pikku enforces authorization. The one sanctioned exception is `permissionsInBody`, covered at the end.
+
+```typescript
+// CORRECT
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+  },
+  permissions: {
+    owner: isBookOwner, // ← authorization here
+  },
+})
+
+// WRONG — permission check inside func body
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }, { session }) => {
+    if (!session) throw new UnauthorizedError() // ← never do this
+    await db.deleteBook(bookId)
+  },
+})
+```
+
+
+## Permission Factories
+
+### `pikkuAuth(fn)` — Session-Only Checks
+
+Use for checks that read the session but need no request data — and that assert
+something **beyond** merely having a session (a flag, a tier, a claim).
+
+```typescript
+import { pikkuAuth } from '#pikku/auth'
+
+// Good: a real gate on the session's contents, not just its existence.
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
+)
+```
+
+**Do NOT write an "is signed in" permission.** A checker that just returns
+`!!session` is not authorization — it re-checks authentication, which the
+function already enforces. A function that needs a signed-in user sets
+`auth: true` (the default for `pikkuFunc`); it does not also carry a
+`permissions: { signedIn }`.
+
+```typescript
+// WRONG — redundant with auth: true; adds a permission that gates nothing.
+export const isSignedIn = pikkuAuth(async (_s, session) => !!session)
+pikkuFunc({ auth: true, permissions: { signedIn: isSignedIn } /* ... */ })
+
+// RIGHT — auth: true already requires the session; permissions are for capability.
+pikkuFunc({ auth: true /* ... */ })
+```
+
+A permission answers "_may this user do this?_" (role, ownership, tier) — never
+"_is there a session?_".
+
+### `pikkuPermission(fn)` — Data-Aware Checks
+
+Use when authorization depends on the actual request data (e.g., resource ownership).
+
+```typescript
+import { pikkuPermission } from '#pikku/auth'
+
+export const isBookOwner = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    const book = await db.getBook(bookId)
+    return book?.authorId === session?.userId
+  }
+)
+
+export const hasBookAccess = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    return await db.hasAccess(session?.userId, bookId)
+  }
+)
+```
+
+## OR / AND Logic
+
+```typescript
+permissions: {
+  verified: isVerified,                    // OR: verified users can access
+  owner: isBookOwner,                      // OR: owners can access
+  reviewer: [isVerified, hasBookAccess],   // AND: both must pass
+}
+// Logic: verified OR owner OR (isVerified AND hasBookAccess)
+```
+
+Groups are OR'd. Entries within a group array are AND'd.
+
+## Where to Apply Permissions
+
+### Per-Function (preferred)
+
+```typescript
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+  },
+  permissions: {
+    verified: isVerified,
+    owner: isBookOwner,
+  },
+})
+```
+
+### Global (`addGlobalPermission`) — App-Wide AND Gate
+
+A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
+
+```typescript
+import { addGlobalPermission } from '#pikku/auth'
+
+addGlobalPermission([isEmployee]) // every function now also requires an employee session
+```
+
+Multiple `addGlobalPermission` calls accumulate and are AND'd together.
+
+> Wire-, tag-, and HTTP-route-level permissions (`addHTTPPermission`, `addTagPermission`, and a `permissions` field on HTTP/channel/MCP wirings) were **removed in #972**. Permissions now live only on the function definition, plus the optional global gate. Tags are organizational only — use tag/HTTP _middleware_ (`addTagMiddleware`, `addHTTPMiddleware`) for cross-cutting request handling, not authorization.
+
+## Scopes — the AND Gate Above Permissions
+
+Scopes answer "what was this session granted?" before permissions ask "may this
+user do this to this resource?". They are AND-ed: every scope listed must be
+held. Because they are checked first and fail closed, a scope can only ever
+_narrow_ access — it never grants what `permissions` would deny.
+
+Declare the scope tree once with `defineScope`. The body is a no-op that
+tree-shakes away; the CLI reads the call by AST and generates a `ScopeId` union,
+so a function naming an undeclared scope fails the build rather than silently
+gating on nothing.
+
+```typescript
+// src/scopes.ts
+import { defineScope } from '#pikku/scopes'
+
+defineScope({
+  admin: {
+    displayName: 'Administration',
+    description: 'Administrative access',
+    scopes: {
+      invoices: {
+        description: 'Invoice management',
+        scopes: {
+          create: { description: 'Create invoices' },
+          void: { description: 'Void invoices' },
+        },
+      },
+    },
+  },
+  billing: {},
+})
+```
+
+Every node is grantable, keyed by segment: the above yields `admin`,
+`admin:invoices`, `admin:invoices:create`, `admin:invoices:void` and `billing`.
+Scopes may be declared across more than one file — the declarations merge.
+
+```typescript
+export const voidInvoice = pikkuFunc({
+  scopes: ['admin:invoices:void'],
+  permissions: { owner: isInvoiceOwner },
+  func: async ({ db }, { invoiceId }) => { ... },
+})
+```
+
+A grant satisfies a required scope if it is the scope itself, an ancestor of it,
+or a wildcard at any level — so a session holding `admin` satisfies
+`admin:invoices:void`, and `admin:*` does too. A missing scope throws
+`MissingScopeError` naming the first one that failed.
+
+`scopes` requires a session and so is unavailable on `pikkuSessionlessFunc`:
+scopes fail closed, an anonymous caller holds none, and a sessionless function
+with scopes would reject every caller it exists to serve. Gate those with
+`permissions`, which receive the optional session and may pass anonymous.
+
+## The Three Gates
+
+Authorization is three independent gates, evaluated in this order, all of which must pass:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation. Fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd together. A broad baseline that can only narrow access.
+3. **The function's own `permissions`** — OR'd groups (OR-of-ANDs), as above.
+
+The gates are independent: a broad global (e.g. `isEmployee`) can **never** satisfy an admin-only function's own requirement. Each function still enforces its own `scopes` and `permissions` in full.
+
+## The Sanctioned Exception: `permissionsInBody`
+
+A few checks genuinely cannot be expressed as a permission — verifying a webhook
+signature, a signed token, or an invite code, where the "identity" arrives in the
+payload and there is no session to check. For those, declare
+`permissionsInBody: true` on the function and keep the check in the body.
+
+```typescript
+export const handleStripeWebhook = pikkuSessionlessFunc({
+  permissionsInBody: true,
+  auth: false,
+  func: async ({ stripe }, data, { http }) => {
+    stripe.webhooks.constructEvent(
+      data.raw,
+      http.request.header('stripe-signature'),
+      secret
+    )
+    // ...
+  },
+})
+```
+
+This is a last resort, and it is purely declarative — it grants nothing and
+enforces nothing. Its only job is to tell the auditor that this function's
+apparent openness is deliberate, so asserting it falsely disables the very check
+that would have caught the mistake. It requires `"allow": { "permissionsInBody": true }`
+in `pikku.config.json`, which keeps the decision visible at the project level.
+Prefer `permissions` whenever the check can be expressed as one — they are
+declared, inspectable, and reusable.
+
+## Complete Example
+
+```typescript
+// src/permissions.ts
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
+
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
+)
+
+export const isOrgMember = pikkuPermission(
+  async ({ db }, { orgId }, { session }) => {
+    return await db.isMember(session?.userId, orgId)
+  }
+)
+
+// src/functions/org.function.ts
+export const deleteOrg = pikkuFunc({
+  func: async ({ db }, { orgId }) => {
+    await db.deleteOrg(orgId)
+  },
+  permissions: {
+    verified: isVerified,
+    owner: [isVerified, isOrgMember],
+  },
+})
+```
+
+## After Changes
+
+```bash
+pikku all              # regenerate if wirings changed
+pikku all --tsc        # regenerate, then verify permission checker types (fails on type errors)
+```

package/skills/{pikku-security/SKILL.md → pikku-auth/references/sessions.md}

@@ -1,25 +1,5 @@
----
-name: pikku-security
-description: >-
-  Use when adding authentication or session management to a Pikku app — pikkuAuth, session
-  lifecycle (setSession/clearSession), built-in auth strategies (authBearer, authCookie,
-  authAPIKey), or JWT setup. TRIGGER when: user asks about login, logout, session, bearer tokens,
-  cookie auth, API keys, or JWT. DO NOT TRIGGER when: user asks about middleware (use
-  pikku-middleware), permissions/authorization checks (use pikku-permissions), or secrets/env vars
-  (use pikku-config).
-installGroups: [core]
----
-
 # Pikku Security (Authentication & Sessions)
 
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info functions --verbose` to understand existing auth setup.
-2. Auth strategies live in wirings files — do not put `addHTTPMiddleware` calls inside function bodies.
-3. Validate with `pikku all --tsc` after changes — it regenerates and then type-checks in one pass, and fails on type errors. Use `--tsc-summary` for a compact one-line-per-error report.
-
-For **middleware** (including tag middleware and service-to-service bearer auth) see `pikku-middleware`.
-For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see `pikku-permissions`.
 
 ## Session Management