@pikku/cli 0.12.26 → 0.12.27

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-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