@pikku/cli 0.12.26 → 0.12.28

package/skills/pikku-permissions/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: pikku-permissions
+description: 'Use when adding authorization checks to Pikku functions or routes — pikkuPermission, pikkuAuth, per-function permissions, pattern-based permissions, or understanding OR/AND permission logic.
+TRIGGER when: user wants to restrict who can call a function, check resource ownership, add role-based access, or understand where permission checks belong.
+DO NOT TRIGGER when: user asks about middleware or request interception (use pikku-middleware), authentication strategies (use pikku-security), or session management.'
+installGroups: [core]
+---
+
+# Pikku Permissions
+
+## 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`, is visible to the inspector, and is the only place Pikku enforces authorization.
+
+```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)
+  },
+})
+```
+
+## Agent Operating Procedure
+
+1. Discover before editing. Run `pikku info permissions --verbose` and `pikku info functions --verbose` to understand what permissions are already defined and applied.
+2. Define permission checkers in a `src/permissions.ts` or domain-specific `src/lib/*-permissions.ts` file.
+3. Apply them via the `permissions` field on the function, or via `addHTTPPermission` / `addPermission` for pattern/tag-based application.
+4. Validate: run `pikku tsc` to confirm permission checker signatures are correct.
+
+## Permission Factories
+
+### `pikkuAuth(fn)` — Session-Only Checks
+
+Use for checks that only need the session — no request data required.
+
+```typescript
+import { pikkuAuth } from '#pikku'
+
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+```
+
+### `pikkuPermission(fn)` — Data-Aware Checks
+
+Use when authorization depends on the actual request data (e.g., resource ownership).
+
+```typescript
+import { pikkuPermission } from '#pikku'
+
+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: {
+  admin: isAdmin,                              // OR: admins can access
+  owner: isBookOwner,                          // OR: owners can access
+  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
+}
+// Logic: admin OR owner OR (isAuthenticated 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: {
+    admin: isAdmin,
+    owner: isBookOwner,
+  },
+})
+```
+
+### Pattern-Based (`addHTTPPermission`)
+
+```typescript
+import { addHTTPPermission } from '@pikku/core/http'
+
+addHTTPPermission('/admin/*', { admin: isAdmin })
+```
+
+### Tag-Based (`addPermission`)
+
+```typescript
+import { addPermission } from '.pikku/pikku-types.gen.js'
+
+addPermission('internal', { machine: isMachineAgent })
+```
+
+## Complete Example
+
+```typescript
+// src/permissions.ts
+import { pikkuAuth, pikkuPermission } from '#pikku'
+
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+
+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: {
+    admin: isAdmin,
+    owner: [isAuthenticated, isOrgMember],
+  },
+})
+```
+
+## After Changes
+
+```bash
+pikku tsc        # verify permission checker types are correct
+pikku all        # regenerate if wirings changed
+```

package/skills/pikku-security/SKILL.md

@@ -1,43 +1,26 @@
 ---
 name: pikku-security
-description: 'Use when adding authentication, authorization, permissions, middleware, or security to a Pikku app. Covers pikkuAuth, pikkuPermission, pikkuMiddleware, built-in auth strategies (bearer, cookie, API key), and permission scoping.
-TRIGGER when: code uses pikkuAuth/pikkuPermission/pikkuMiddleware, user asks about auth, login, session, permissions, RBAC, middleware, or API keys.
-DO NOT TRIGGER when: user asks about JWT service setup (use pikku-services) or secrets/env vars (use pikku-config).'
+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 (Auth, Permissions, Middleware)
+# Pikku Security (Authentication & Sessions)
 
 ## Agent Operating Procedure
 
-Use this skill as an execution checklist, not reference material.
+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 tsc` after changes; run `pikku all` if wirings changed.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
+For **middleware** (including tag middleware and service-to-service bearer auth) see `pikku-middleware`.
+For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see `pikku-permissions`.
 
-Pikku provides a layered security model: authentication middleware (who are you?), auth checks (are you logged in?), and permissions (can you do this?). All work across every transport (HTTP, WebSocket, CLI, queue, etc.).
-
-## Before You Start
-
-```bash
-pikku info middleware --verbose    # See existing middleware and where it's applied
-pikku info permissions --verbose   # See existing permissions
-pikku info functions --verbose     # See which functions have auth/permissions
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### Session Management
-
-Functions access session via the wire object:
+## Session Management
 
 ```typescript
-// In pikkuFunc (authenticated)
+// Read session in pikkuFunc (session guaranteed to exist)
 const getProfile = pikkuFunc({
   func: async ({ db }, _data, { session }) => {
     return await db.getUser(session.userId)
@@ -62,78 +45,19 @@ const logout = pikkuFunc({
 })
 ```
 
-### `pikkuAuth(fn)` — Session-Only Checks
-
-Use for authentication gates that only need the session (no request data).
-
-```typescript
-import { pikkuAuth } from '#pikku'
-
-// Receives (services, session)
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
-)
-
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
-)
-```
-
-### `pikkuPermission(fn)` — Data-Aware Checks
-
-Use when authorization depends on the actual request data.
-
-```typescript
-import { pikkuPermission } from '#pikku'
-
-// Receives (services, data, wire)
-export const isOwner = 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)
-  }
-)
-```
-
-### Permission Groups (OR/AND Logic)
+## Built-in Auth Strategies
 
-```typescript
-{
-  admin: isAdmin,                          // OR: admins can access
-  owner: isOwner,                          // OR: owners can access
-  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
-}
-// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
-```
-
-### `pikkuMiddleware(fn)` — Before/After Wrapping
-
-```typescript
-import { pikkuMiddleware } from '#pikku'
-
-const logRequest = pikkuMiddleware(async ({ logger }, wire, next) => {
-  logger.info('Before')
-  await next()
-  logger.info('After')
-})
-```
-
-### Built-in Auth Middleware
+Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
+import { addHTTPMiddleware } from '@pikku/core/http'
 
 // JWT bearer token — reads Authorization header
-addHTTPMiddleware([authBearer()])
+addHTTPMiddleware('*', [authBearer()])
 
 // Cookie-based sessions — auto-refreshes JWT
-addHTTPMiddleware([
+addHTTPMiddleware('*', [
   authCookie({
     name: 'session',
     expiresIn: { value: 30, unit: 'day' },
@@ -141,48 +65,8 @@ addHTTPMiddleware([
   }),
 ])
 
-// API key — from x-api-key header or ?apiKey= query
-addHTTPMiddleware([authAPIKey({ source: 'all' })])
-```
-
-### Scoping: Where to Apply
-
-Four levels of scoping, from broadest to narrowest:
-
-```typescript
-// 1. Global: all HTTP routes
-addHTTPMiddleware('*', [authBearer()])
-
-// 2. Prefix-based: URL pattern
-addHTTPMiddleware('/admin/*', [auditLog])
-addHTTPPermission('/admin/*', { admin: requireAdmin })
-
-// 3. Tag-based: any wiring with matching tag
-addMiddleware('api', [rateLimiter])
-addPermission('api', { auth: requireAuth })
-
-// 4. Inline: per-wiring
-wireHTTP({
-  route: '/books/:id',
-  func: getBook,
-  middleware: [cacheControl],
-  permissions: { owner: requireOwnership },
-})
-```
-
-### Per-Function Permissions
-
-```typescript
-export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-  },
-  permissions: {
-    admin: isAdmin,
-    owner: isOwner,
-    reviewer: [isAuthenticated, hasBookAccess],
-  },
-})
+// API key — from x-api-key header or ?apiKey= query param
+addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 ```
 
 ## Complete Example
@@ -191,53 +75,30 @@ export const deleteBook = pikkuFunc({
 // permissions.ts
 import { pikkuAuth, pikkuPermission } from '#pikku'
 
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
-)
-
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
-)
-
-export const isBookOwner = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    const book = await db.getBook(bookId)
-    return book?.authorId === session?.userId
-  }
-)
-
-// middleware.ts
-import { pikkuMiddleware } from '#pikku'
-
-export const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
-  const start = Date.now()
-  await next()
-  await db.createAuditLog({
-    duration: Date.now() - start,
-  })
-})
-
-// wirings/security.wiring.ts
-import { authBearer } from '@pikku/core/middleware'
-import { addHTTPMiddleware, addHTTPPermission } from '#pikku'
+export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
+export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
 
-// All routes require bearer auth
-addHTTPMiddleware('*', [authBearer()])
+// wirings/auth.wiring.ts
+import { authCookie } from '@pikku/core/middleware'
+import { addHTTPMiddleware } from '@pikku/core/http'
 
-// Admin routes need admin permission + audit logging
-addHTTPMiddleware('/admin/*', [auditLog])
-addHTTPPermission('/admin/*', { admin: isAdmin })
+addHTTPMiddleware('*', [
+  authCookie({ name: 'session', expiresIn: { value: 30, unit: 'day' } }),
+])
 
-// functions/books.functions.ts
-export const deleteBook = pikkuFunc({
-  title: 'Delete Book',
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-    return { deleted: true }
+// functions/auth.functions.ts
+export const login = pikkuFunc({
+  auth: false,
+  func: async ({ jwt, db }, { email, password }, { setSession }) => {
+    const user = await db.verifyCredentials(email, password)
+    setSession({ userId: user.id, role: user.role })
+    return { token: jwt.sign({ userId: user.id }) }
   },
-  permissions: {
-    admin: isAdmin,
-    owner: isBookOwner,
+})
+
+export const logout = pikkuFunc({
+  func: async ({}, _data, { clearSession }) => {
+    clearSession()
   },
 })
 ```

package/skills/pikku-services/SKILL.md

@@ -173,15 +173,52 @@ const createSingletonServices = pikkuServices(async (config) => {
 })
 ```
 
+### Audit Wire Service
+
+`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without Fabric), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
+
+Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit event.
+
+```typescript
+// services.ts
+import { createInvocationAudit } from '@pikku/core/services'
+import { createAuditedKysely } from '@pikku/kysely'
+
+export const createWireServices = pikkuWireServices(async (singletonServices, wire) => {
+  const audit = createInvocationAudit(singletonServices.audit, wire)
+  const kysely = singletonServices.kysely
+    ? createAuditedKysely(singletonServices.kysely, { audit })
+    : undefined
+  return { audit, ...(kysely ? { kysely } : {}) }
+})
+```
+
+The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions that emit custom events use it directly:
+
+```typescript
+const deleteUser = pikkuFunc({
+  func: async ({ audit }, { userId }) => {
+    await audit.audit({ type: 'user.deleted', actor_user_id: userId })
+    // ...
+  },
+})
+```
+
+`closeWireServices` (called automatically by the function-runner) invokes `audit.close()` → `singletonServices.audit.write(batch)` → platform-specific flush (e.g. CF Queue, libsql INSERT). No manual flushing needed.
+
+> **Fabric note:** Fabric provisions the audit queue and consumer worker automatically. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku fabric validate` to confirm the migration is in place.
+
 ### Built-in Services
 
-| Service                 | Package                | Purpose                     |
-| ----------------------- | ---------------------- | --------------------------- |
-| `ConsoleLogger`         | `@pikku/core/services` | Console-based logging       |
-| `JoseJWTService`        | `@pikku/jose`          | JWT sign/verify via jose    |
-| `LocalSecretService`    | `@pikku/core/services` | Local development secrets   |
-| `LocalVariablesService` | `@pikku/core/services` | Local environment variables |
-| `PinoLogger`            | `@pikku/pino`          | Structured logging via Pino |
+| Service                    | Package                | Purpose                          |
+| -------------------------- | ---------------------- | -------------------------------- |
+| `ConsoleLogger`            | `@pikku/core/services` | Console-based logging            |
+| `JoseJWTService`           | `@pikku/jose`          | JWT sign/verify via jose         |
+| `LocalSecretService`       | `@pikku/core/services` | Local development secrets        |
+| `LocalVariablesService`    | `@pikku/core/services` | Local environment variables      |
+| `PinoLogger`               | `@pikku/pino`          | Structured logging via Pino      |
+| `createInvocationAudit`    | `@pikku/core/services` | Per-request audit buffer         |
+| `createAuditedKysely`      | `@pikku/kysely`        | Auto-capture DB queries as audit events |
 
 ## Complete Example
 

package/skills/pikku-tag-middleware/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: pikku-tag-middleware
+description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.'
+---
+
+# Deprecated: use `pikku-middleware`
+
+Tag middleware is covered in the **`pikku-middleware`** skill, which also covers:
+- `addHTTPMiddleware` (global / prefix-based)
+- `addTagMiddleware` (tag-scoped)
+- Middleware execution order and priority
+- Service-to-service bearer auth pattern
+- Session-setting middleware pattern