@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-permissions/SKILL.md

@@ -1,280 +1,126 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when adding authorization checks to Pikku functions — pikkuPermission, pikkuAuth, scopes and
-  defineScope, per-function permissions, global permissions, or understanding the scope/OR/AND
-  gating logic. TRIGGER when: user wants to restrict who can call a function, check resource
-  ownership, add role-based or scope-based access, declares or grants scopes, hits
-  MissingScopeError, or asks 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.
+  Use when deciding WHO may call a function — resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes, and where ownership belongs versus where it does not.
+  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, or about to write an `if` in a function body that decides whether the caller is allowed.
+  DO NOT TRIGGER when: the question is how to sign someone in or seed a persona (that is pikku-auth), or how to shape a paginated list (that is pikku-list-query).
 installGroups: [core]
 ---
 
 # Pikku Permissions
 
-## ⛔ FIRST: is the caller a machine with a token? ⛔
+## The rule
 
-**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 the machine-auth section of `pikku-middleware`. 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.
+**Authorization goes in the `permissions` field. Never in the `func` body.**
 
-## 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.
+`permissions` runs before `func`, and it is DECLARED — `pikku meta` and the auditor can
+see it. An `if` in the body is the same check, invisible: nothing can tell you which
+functions are gated or how, and the next person to add a caller gets no warning.
 
 ```typescript
-// CORRECT
+// RIGHT
 export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-  },
-  permissions: {
-    owner: isBookOwner, // ← authorization here
+  permissions: { owner: isBookOwner },
+  func: async ({ kysely }, { bookId }) => {
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
   },
 })
 
-// WRONG — permission check inside func body
+// WRONG — the gate is buried in the body
 export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }, { session }) => {
-    if (!session) throw new UnauthorizedError() // ← never do this
-    await db.deleteBook(bookId)
+  func: async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely.selectFrom('book')...executeTakeFirst()
+    if (book?.ownerId !== session.userId) throw new UnauthorizedError()
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
   },
 })
 ```
 
-## Agent Operating Procedure
+## `auth: true` IS NOT OWNERSHIP — this is the one people get wrong
 
-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. For an app-wide baseline that every function must additionally satisfy, use `addGlobalPermission`.
-4. Validate: run `pikku all --tsc` to confirm permission checker signatures are correct.
+`auth: true` means "somebody is signed in". It does NOT mean "this row is theirs". A CRUD
+function set to `auth: true` and nothing else lets ANY signed-in user delete ANY other
+user's row by passing its id. Every function that takes a row id needs BOTH: `auth: true`
+for the session, and a `permissions` entry for the ownership.
 
-## Permission Factories
+Equally: do NOT write an `isSignedIn` permission that returns `!!session`. That re-checks
+authentication, which `auth: true` already did. A permission answers *may this user do
+this* — role, ownership, tier — never *is there a session*.
 
-### `pikkuAuth(fn)` — Session-Only Checks
+## Single row vs list — where ownership actually goes
 
-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).
+This is the distinction to get right, and both halves are correct code:
 
-```typescript
-import { pikkuAuth } from '#pikku/auth'
+- **A function taking a row id** (`get`, `update`, `delete`) — ownership is a
+  PERMISSION. Load the row, compare the owner to the session. It is a yes/no question
+  about one row, which is exactly what a permission is.
+- **A function returning many rows** (`list`, `search`, any stats query) — ownership is
+  a `WHERE` clause in the query, because "only their rows" is a filter, not a yes/no.
+  There is no permission to write here; scoping the query IS the enforcement.
 
-// 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 }`.
+A list that fetches everything and then filters in JS is a bug, not a permission.
 
-```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 } /* ... */ })
+## Writing the checkers
 
-// 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).
+Put them in `src/permissions/`, one file per entity, and reuse one checker across every function on that
+entity rather than writing a near-copy per function.
 
 ```typescript
-import { pikkuPermission } from '#pikku/auth'
+// src/permissions/book.ts
+import { pikkuPermission, pikkuAuth } from '#pikku/auth'
 
+// Data-aware: gets the input, so it can load the row the caller named.
 export const isBookOwner = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    const book = await db.getBook(bookId)
-    return book?.authorId === session?.userId
-  }
+  async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely
+      .selectFrom('book')
+      .select('ownerId')
+      .where('bookId', '=', bookId)
+      .executeTakeFirst()
+    return book?.ownerId === session?.userId
+  },
 )
 
-export const hasBookAccess = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    return await db.hasAccess(session?.userId, bookId)
-  }
-)
+// Session-only: no input needed. Use for role and flag gates.
+export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
 ```
 
-## OR / AND Logic
+## OR and AND
 
 ```typescript
 permissions: {
-  verified: isVerified,                    // OR: verified users can access
-  owner: isBookOwner,                      // OR: owners can access
-  reviewer: [isVerified, hasBookAccess],   // AND: both must pass
+  owner: isBookOwner,            // OR — an owner may
+  admin: isAdmin,                // OR — an admin may
+  editor: [isAdmin, isBookOwner] // AND — both, inside one group
 }
-// 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.
+Groups are OR'd; entries inside a group array are AND'd.
 
-```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.
+## Roles
 
-## The Three Gates
+If the app has roles, the role lives on the session (see pikku-auth / `mapSession`) and
+every mutating or admin-only function names it in `permissions`. Gate the FUNCTION — hiding
+an admin button in the UI is UX, never enforcement, and a member who guesses the RPC name
+gets straight through if the function itself is open.
 
-Authorization is three independent gates, evaluated in this order, all of which must pass:
+## Scopes
 
-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.
+`scopes: ['admin:invoices:void']` is an AND gate checked BEFORE permissions and before
+input validation. Declare the tree once with `defineScope`; a function naming an
+undeclared scope fails codegen rather than gating on nothing. A grant satisfies a scope if
+it is that scope, an ancestor, or a wildcard — a session holding `admin` satisfies
+`admin:invoices:void`. Most apps need roles, not scopes; reach for these only when the
+plan asked for granular grants.
 
-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 one sanctioned exception
 
-## The Sanctioned Exception: `permissionsInBody`
+`permissionsInBody: true` — for a check that genuinely cannot be a permission because the
+identity arrives in the payload and there is no session: a webhook signature, a signed
+token, an invite code. It is purely declarative and enforces nothing; its job is to tell
+the auditor the openness is deliberate. Anything expressible as a permission must be one.
 
-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.
+## After changes
 
-```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)
-```
+`pikku all` — regenerates and typechecks the checkers. A permission whose signature is
+wrong fails here, not at runtime.