@pikku/skills 0.12.9 → 0.12.11

package/skills/pikku-better-auth/SKILL.md

@@ -5,7 +5,8 @@ description: >-
   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:
+  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).
@@ -146,6 +147,11 @@ strings):
 | delete a user and their data                                         | `admin:users:remove`     |
 | revoke a user's sessions                                             | `admin:users:sessions`   |
 | set a user's password                                                | `admin:users:password`   |
+| read credential values and who holds them                            | `admin:credentials:read` |
+| set and delete credentials                                           | `admin:credentials:manage` |
+| view declared scopes, roles, and who holds them                      | `admin:scopes:read`      |
+| create roles, change their scopes, grant them                        | `admin:scopes:manage`    |
+| read the audit trail                                                 | `admin:audit:read`       |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -166,6 +172,8 @@ defineScope({
         description: 'Application-wide credentials',
         scopes: {
           link: { description: 'Bind a shared credential for every user' },
+          read: { description: 'Read credential values and who holds them' },
+          manage: { description: 'Set and delete credentials' },
         },
       },
       users: {
@@ -179,6 +187,27 @@ defineScope({
           password: { description: "Set a user's password" },
         },
       },
+      scopes: {
+        description: 'Authorization management',
+        scopes: {
+          read: {
+            description: 'View declared scopes, roles, and who holds them',
+          },
+          manage: {
+            description:
+              'Create and delete roles, change their scopes, and grant roles to users',
+          },
+        },
+      },
+      audit: {
+        description: 'The audit trail',
+        scopes: {
+          read: {
+            description:
+              'Read the audit trail — every recorded action, and which user took it',
+          },
+        },
+      },
     },
   },
 })
@@ -191,22 +220,32 @@ a scope, so nothing is authorized, and the denial is logged at `warn` because
 that is a configuration bug rather than a permissions decision. Pass your own
 `canImpersonate` / `canLinkSingleton` to override the default entirely.
 
-### If you do wire better-auth's `admin()` plugin
+### Do not wire better-auth's `admin()` plugin
+
+Every capability in the table is pikku's own, gated by the scope next to it and
+implemented against better-auth's internal adapter — `createAuthUser`,
+`setAuthUserPassword`, `setAuthUserBanned`, `deleteAuthUser` and
+`revokeAuthUserSessions`, all exported from `@pikku/better-auth`.
 
-The last five capabilities in the table are implemented by better-auth's own
-`admin()` endpoints, which authorize against `user.role` — a column pikku
-otherwise ignores. Rather than making you maintain two grant systems,
-`syncProjectedAdminRole` keeps that column as a *projection* of the scope set:
-at the session boundary it writes `role = 'admin'` when the user holds any of
-`admin:users:{create,ban,remove,sessions,password}`, and the plugin's
-`defaultRole` otherwise. `projectedAdminRole(scopes, defaultRole)` computes the
-value if you need it yourself.
+`admin()` would add a second gate on a `user.role` column that pikku otherwise
+ignores, which means maintaining two grant systems that have to agree — and the
+column loses, since the scope store is what the rest of the framework reads.
+Pikku used to project scopes onto it for exactly that reason; dropping the
+plugin dropped the projection with it.
 
-The projection is deliberately not "any `admin:*` scope": `impersonate` and
-`users:list` are pikku's own gates, and rolling them in would hand ban and delete
-rights to someone granted only the ability to look. The plugin is auto-detected
-from the live instance, so an app without it never writes to a column that does
-not exist.
+Banning is the one capability with a schema requirement, and it has its own
+small plugin:
+
+```typescript
+import { ban } from '@pikku/better-auth'
+
+betterAuth({ plugins: [ban()] })
+```
+
+`ban()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
+create a session for a banned user, lapsing an expired ban as it goes. It makes
+no authorization decision — who may ban is decided by `admin:users:ban` — so it
+never needs to know about scopes or roles.
 
 ### 2. Production database adapter
 
@@ -273,7 +312,7 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables }) => {
 Functions that require a session use `pikkuFunc` — anonymous callers are rejected automatically. `betterAuthSession` has already bridged better-auth's session into `session`:
 
 ```typescript
-import { pikkuFunc } from '#pikku'
+import { pikkuFunc } from '#pikku/function'
 
 export const me = pikkuFunc({
   expose: true,
@@ -311,11 +350,52 @@ The session cookie is `better-auth.session_token` (dev) / `__Secure-better-auth.
 
 Set `PIKKU_DEV_QUICK_LOGIN=true` and `${basePath}/dev/quick-login` signs in a
 fixed dev admin (`admin@pikku.dev`), creating the user idempotently and granting
-it the bare `admin` scope. It is guarded twice — the env var *and* a localhost
+it the bare `admin` scope. It is guarded twice — the env var _and_ a localhost
 hostname check — because a one-request path to an admin session is exactly the
 thing that must not survive a deploy. An app that has not declared the `admin`
 scope still gets a session, with a warning, since a scopeless dev user is useful.
 
+### Actor sign-in (`actor` plugin)
+
+A different thing from dev quick login, and the one to reach for when "sign in as
+someone" means **a particular kind of user** rather than one fixed admin.
+Register it explicitly — it is not automatic:
+
+```typescript
+import { actor } from '@pikku/better-auth'
+
+plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
+```
+
+`POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
+session cookie. `secret` may also be a (possibly async) function, so it can come
+off the secrets service instead of a captured value.
+
+**`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
+persona.** `pikku persona sync` grants declared roles to actor accounts, so an
+`admin` persona is an actor holding real admin — anyone with the secret can take
+a session as one. Keep the endpoint **off outside development and sandbox
+deployments**: leave the secret unset on any stage that should not run scenarios,
+which is the supported switch (`Actor sign-in is not configured`), rather than
+conditionally registering the plugin. Do not treat "actors only" as a licence to
+enable it in production.
+
+Within that boundary, three properties bound the damage:
+
+- **It only ever signs in actors.** The plugin adds a `user.actor` boolean
+  column; an email matching a row without it is refused with `User is not an
+actor`. So the secret cannot take over a **real user's** account — the blast
+  radius is the actor accounts and whatever roles they were granted.
+- **Unknown emails are created**, flagged `actor: true`, so a scenario that
+  declares a new persona needs no seed step. Note the flip side: the secret
+  mints accounts, it does not merely use existing ones.
+- **The comparison is constant-time and length-hiding**, so a wrong secret leaks
+  neither the length nor a prefix of the right one.
+
+This is the endpoint `pikku scenario` signs its actors in through, and the one
+the frontend dev switcher posts to — see `pikku-scenario` for declaring the
+actors and `pikku-react` for `useDevActors()`.
+
 ---
 
 ## Secret Management