@pattern-js/mod-identity 0.2.0

package/docs/index.md

@@ -0,0 +1,162 @@
+# Identity
+
+`@pattern-js/mod-identity` is the identity kernel: users, revocable cookie
+sessions, roles→scopes, a single-use token system, the login page, and the
+admin's Access screens (Users / Invite / Sessions). Login *methods* are
+separate mods that plug into it — `@pattern-js/mod-auth-magic-link` is the
+reference.
+
+```jsonc
+{ "mods": ["@pattern-js/mod-identity", "@pattern-js/mod-auth-magic-link"] }
+```
+
+## When to use it
+
+Install it the moment you want **users, sessions, or roles** — a login page,
+who-is-this-request, gated routes. It is opt-in: a project without it behaves
+exactly as before. But installing it alongside `@pattern-js/mod-admin` **flips the
+admin to secure-by-default** — `/admin` (API + SPA) starts requiring the
+`admin` scope, and a logged-out browser is 302'd to the login page. Pass
+`adminMod({ auth: false })` to keep the admin open anyway. If you only need a
+machine-to-machine API key, you don't need this mod; reach for it when a
+*human* has to prove who they are.
+
+## Roles → scopes
+
+Users carry **roles** (strings); the `roles` map compiles them into **scopes**
+on the principal at **resolve time** — so editing the map applies on the *next*
+request, and sessions store no scopes of their own. The default map is
+`{ admin: ["admin"] }`. Adding application scopes is *just this map*:
+
+```js
+// mods/identity.mjs — a local wrapper mod
+import { identityMod } from "@pattern-js/mod-identity";
+export default identityMod({
+  roles: { admin: ["admin"], editor: ["edit", "read"], viewer: ["read"] },
+});
+```
+
+Now a user with role `editor` resolves to scopes `["edit","read"]`; gate a
+route with `requireAuth: { scopes: ["edit"] }` and both `admin` (if you also
+grant it `edit`) and `editor` users get through, `viewer` does not. The same
+roles surface on the admin Users screen and are settable there
+(`identity.users.setRoles` — which **ends the user's sessions**, because a
+privilege change must re-login).
+
+## Bootstrap on first boot
+
+With an empty user store, the mod's `ready` hook mints a one-time **bootstrap
+token** (valid 24h) and prints a setup link to the **server console**:
+
+```
+[pattern] ◆ No users yet — create the first admin with this one-time link (valid 24h):
+[pattern]   http://localhost:3000/auth/bootstrap?t=…
+```
+
+Open it: `GET /auth/bootstrap?t=…` renders a form, the `POST` creates the first
+user (roles `["admin"]` by default — `bootstrapRoles`) and signs them in. It's
+the *same single-use-token primitive* as login and invites, so there's no
+special-case admin password anywhere.
+
+## Sessions
+
+Opaque 256-bit secrets in an `HttpOnly; SameSite=Lax` cookie (`pattern_session`
+by default); only the sha256 is stored. Sliding 30-day expiry with throttled
+touches. Sessions are **revocable** — individually (`identity.sessions.revoke`),
+per user (`identity.users.revokeSessions`), and automatically when a role
+changes or a user is disabled. Set `cookieSecure: true` behind TLS in
+production. CSRF protection lives *inside* the session provider: a cross-site
+state-changing request simply doesn't authenticate (so it 401s with no token
+machinery), while GETs always pass — the magic-link callback is a cross-site
+top-level GET by nature.
+
+## The `user` port
+
+Host-bound triggers (`boundary.http.request`, `boundary.ws.*`) expose a `user`
+output port — `{ id, provider, email?, name?, scopes, claims } | null` — so
+the caller's identity is an *edge you can see*, not ambient context. Wire it
+like any value:
+
+```jsonc
+{ "from": { "node": "in", "port": "user" }, "to": { "node": "listNotes", "port": "owner" } }
+```
+
+For an op deeper in the graph, `identity.whoami` and `ctx.principal` cover the
+same ground.
+
+## Gating a route with `requireAuth`
+
+Enforcement is the **trigger's** job, on its config — core is untouched. Stamp
+`requireAuth` on a `boundary.http.request` (or `boundary.ws.*`):
+
+```jsonc
+{ "op": "boundary.http.request",
+  "config": { "method": "POST", "path": "/api/publish",
+              "requireAuth": { "scopes": ["edit"] } } }
+```
+
+Forms: `true` (any signed-in user), `{ "scopes": [...] }` (needs all listed
+scopes), or the env-deferred `{ "env": "MY_SWITCH" }` (read per request, so you
+can flip a surface open/closed without redeploying). The admin's own Access
+routes stamp `{ scopes: ["admin"] }` on the boundary; the underlying
+`identity.*` ops stay pure and are tagged `sensitivity: "privileged"`, so the
+validator flags any route that exposes them without a gate.
+
+## WebSockets
+
+Auth happens **at upgrade** — the same cookie resolves the principal, the
+trigger's `requireAuth` is enforced before the socket is accepted, and the
+principal is fixed for the connection. Authenticated sockets auto-join two
+rooms:
+
+- `user:{id}` — broadcast to all of a user's devices,
+- `session:{sessionId}` — **revoking the session closes its sockets** (code 4001).
+
+## Tokens & delivery
+
+Magic links, invites, and the bootstrap link all print to the **server
+console** until you register a delivery workflow on the `identity.deliverToken`
+hook (`payload: { email, url, purpose, delivered }`) — send the link by
+email/SMS/chat and return `delivered: true`. No subscriber (or
+`delivered: false`) falls back to the console, which **is** the zero-config dev
+login. Tokens are single-use, short-TTL (15 min; invites 7 days), sha256 at
+rest, consumed via CAS so replays fail closed. Purposes: `login`, `invite`
+(carries roles), `bootstrap`. The `/auth/token` callback turns a consumed token
+into a user + session per the **signup policy** — `invite` (default; unknown
+emails refused) or `open` — a runtime setting toggled on the admin's Settings
+page (the mod option only seeds it).
+
+## Minimal config
+
+Defaults work from the bare `"@pattern-js/mod-identity"` config entry. To
+customize, export a local wrapper mod:
+
+```js
+// mods/identity.mjs
+import { identityMod } from "@pattern-js/mod-identity";
+export default identityMod({
+  signup: "open",                          // default "invite"
+  roles: { admin: ["admin"], editor: ["edit", "read"] },
+  cookieSecure: true,                      // REQUIRED behind TLS
+  storage: "./.pattern-data/identity.db",  // or "memory"
+});
+```
+
+`storage` is `node:sqlite` at `./.pattern-data/identity.db` by default —
+**gitignored**; never put identity data in `.pattern/`, which is committed
+workflow storage.
+
+## Routes
+
+| Route | What |
+| --- | --- |
+| `GET /auth/login` | Login page (a section per registered method) |
+| `GET /auth/token?t=…` | Token callback → session cookie → redirect `next` |
+| `POST /auth/logout` | Revoke the current session, clear the cookie |
+| `GET /auth/whoami` | The current principal (JSON) |
+| `GET /auth/welcome` | Post-login landing when no home is advertised |
+| `GET/POST /auth/bootstrap` | First-admin setup (the one-time link) |
+
+All public by design — the privileged surface is ops (`identity.users.*`,
+`identity.sessions.*`, `identity.settings.*`), reached through their own
+admin-scope-stamped routes under `/admin/api/identity/*`.

package/docs/ops/identity.bootstrap.page.md

@@ -0,0 +1,5 @@
+Render the first-admin setup form, reached via the one-time link printed to the
+console on first boot when the user store is empty. The GET half of a two-step
+flow (this renders, `identity.bootstrap.submit` creates) — deliberately not a
+one-click GET. An HTTP-shaped op backing `GET /auth/bootstrap`; a missing `t`
+redirects to login. You never trigger this manually — boot prints the link.

package/docs/ops/identity.bootstrap.submit.md

@@ -0,0 +1,5 @@
+Consume the bootstrap token, create the first user with the bootstrap roles
+(`["admin"]` by default), and sign them in. The POST half of the first-boot
+flow backing `POST /auth/bootstrap`; it accepts a `bootstrap`-purpose token
+only (never an upgraded login token), so it works exactly once on an empty
+store. Re-renders the form with an error on a bad email.

package/docs/ops/identity.login.page.md

@@ -0,0 +1,5 @@
+Render the login page, one section per login method registered by provider mods
+(e.g. magic-link) in their `ready` hook — so an identity install with no
+provider shows an empty page. An HTTP-shaped op: it emits `{ body, status }`,
+not JSON. Backs `GET /auth/login`; you rarely wire it by hand. The `sent` and
+`error` query params drive the post-submit and error states.

package/docs/ops/identity.logout.md

@@ -0,0 +1,4 @@
+Revoke the current session (from `ctx.principal`'s `sessionId`) and clear the
+cookie, then redirect to the login page. Backs `POST /auth/logout` — a POST, so
+the CSRF guard makes forged cross-site logouts inert. Anonymous callers just
+get the redirect (nothing to revoke).

package/docs/ops/identity.sessions.list.md

@@ -0,0 +1,5 @@
+List sessions newest-first with user email and a derived status
+(active/expired/revoked); pass `userId` to scope to one user, omit it for all.
+Backs the admin Sessions screen and a user's session sub-list. Privileged —
+gate the trigger with the `admin` scope; revoke a row with
+`identity.sessions.revoke`.

package/docs/ops/identity.sessions.revoke.md

@@ -0,0 +1,4 @@
+Revoke one session by id — it stops resolving on the next request and its live
+WS sockets close (code 4001). Use it to kill a single device; for all of a
+user's sessions use `identity.users.revokeSessions`. Privileged — gate the
+trigger with the `admin` scope.

package/docs/ops/identity.settings.get.md

@@ -0,0 +1,4 @@
+Read the effective signup policy (`"open"` or `"invite"`) — the runtime
+setting, not the construction-time mod option, so it reflects whatever was last
+toggled. Pairs with `identity.settings.set`; backs the admin Settings section.
+Privileged — gate the trigger with the `admin` scope.

package/docs/ops/identity.settings.set.md

@@ -0,0 +1,5 @@
+Switch the signup policy between `"open"` and `"invite"` — persisted, so it
+survives restarts and **overrides** the `signup` mod option (which only seeds
+the initial value). This is the live switch that governs whether unknown emails
+can self-register through `/auth/token` and `auth.magiclink.request`.
+Privileged — gate the trigger with the `admin` scope.

package/docs/ops/identity.token.callback.md

@@ -0,0 +1,7 @@
+The security heart of login: consume a single-use `login`/`invite` token,
+find-or-create the user per the **effective** signup policy, mint a session,
+and redirect to `next` with the cookie set. An HTTP-shaped op backing
+`GET /auth/token` — provider mods (magic-link, OIDC) issue tokens whose links
+land here; they never mint sessions themselves. Bootstrap tokens are refused
+here (they have their own flow), and a closed-signup unknown email redirects to
+the login page with an error rather than creating an account.

package/docs/ops/identity.users.get.md

@@ -0,0 +1,5 @@
+One user's profile shaped for the admin details page — email, name, roles, the
+**resolved scopes** (via the role→scopes map), disabled flag, created time, and
+active-session count. Use this for a single user; `identity.users.list` for the
+table. Privileged — gate the trigger with the `admin` scope; throws if the user
+isn't found.

package/docs/ops/identity.users.invite.md

@@ -0,0 +1,7 @@
+Invite a user by email: mints a 7-day `invite` token (carrying the given
+roles) and delivers it via the `identity.deliverToken` hook. Use this — not
+`auth.magiclink.request` — when signup is `invite` (the default) and you need
+to onboard someone who can't sign themselves up. When no delivery channel is
+wired the result carries the link as `copy` (a copyable field) for the admin to
+hand over manually; `roles` accepts an array or a comma string. Privileged —
+gate the trigger with the `admin` scope.

package/docs/ops/identity.users.list.md

@@ -0,0 +1,5 @@
+List every user with roles flattened to a comma string for table rendering —
+backs the admin Users screen. Privileged and pure: it never checks scopes
+itself, so a route or workflow wiring it MUST stamp `requireAuth: { scopes:
+["admin"] }` on the trigger (the validator flags it otherwise). For one user's
+detail use `identity.users.get`.

package/docs/ops/identity.users.loginLink.md

@@ -0,0 +1,5 @@
+Mint a single-use sign-in link for an existing user and return it as `copy`
+(a copyable field) — for handing over manually when no email/SMS delivery is
+wired. Use it to sign in an *existing* user; for someone new under invite-only
+signup use `identity.users.invite` instead. Throws if the user is disabled
+(re-enable first). Privileged — gate the trigger with the `admin` scope.

package/docs/ops/identity.users.revokeSessions.md

@@ -0,0 +1,5 @@
+Revoke every session of one user — logs them out on all devices and closes
+their live WS sockets (code 4001) — without disabling the account, so they can
+sign back in immediately. Use it for "sign out everywhere"; to also bar
+re-entry use `identity.users.toggleDisabled`. Privileged — gate the trigger
+with the `admin` scope.

package/docs/ops/identity.users.runStats.md

@@ -0,0 +1,7 @@
+Per-workflow run counts (runs, errors, avg ms, last run) for one user, read
+from the admin's trace sink. Feature-detected: it returns an empty list when
+`@pattern-js/mod-admin` isn't installed, and only covers the sink's **retained
+window** (a bounded ring buffer), not all-time history — so treat the numbers
+as recent-activity, not an audit log. Admin plumbing routes (`__`-prefixed,
+`*.route.admin.*`) are filtered out. Privileged — gate the trigger with the
+`admin` scope.

package/docs/ops/identity.users.setRoles.md

@@ -0,0 +1,5 @@
+Replace a user's roles, then **revoke all their sessions** — a privilege change
+forces a re-login, so don't reach for this on a hot path expecting the user to
+stay signed in. New scopes take effect from the role→scopes map on their next
+session. `roles` accepts an array or a comma string; privileged — gate the
+trigger with the `admin` scope.

package/docs/ops/identity.users.toggleDisabled.md

@@ -0,0 +1,5 @@
+Flip a user between disabled and enabled — disabling also revokes all their
+sessions and closes their sockets, so it's the lock-out switch. It reads the
+current state and inverts it (no explicit on/off arg), so two concurrent calls
+cancel out. Privileged — gate the trigger with the `admin` scope. A disabled
+user can't be issued a login link until re-enabled.

package/docs/ops/identity.welcome.page.md

@@ -0,0 +1,5 @@
+The post-login landing of last resort — shown only when no app advertised a
+home under core's `AUTH_HOME_URL` (the admin registers its mount there). Renders
+who-you-are plus a sign-out button; an HTTP-shaped op backing `GET
+/auth/welcome` that redirects anonymous callers to the login page. If you have
+an app, advertise its home and users never see this.

package/docs/ops/identity.whoami.md

@@ -0,0 +1,6 @@
+Report the calling principal — `{ kind: "anonymous" }` when unauthenticated,
+else `{ kind: "user", id, email, name, roles, scopes, sessionId }`. Pure and
+unprivileged (it only ever sees the caller's own principal), so wire it into
+any graph that needs to know who's running; for a host trigger prefer the
+`user` port, and reach for this when the answer is needed deeper in the
+workflow.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pattern-js/mod-identity",
+  "version": "0.2.0",
+  "description": "Users, sessions, roles and pluggable login methods for Pattern — the optional identity brick. Opaque revocable cookie sessions (CAS-backed, sqlite or in-memory), a single-use token kernel (login/invite/bootstrap), a login page, and admin screens.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@pattern-js/runtime-node": "0.2.0",
+    "@pattern-js/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "@pattern-js/runtime-node": "0.2.0"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makkr-studio/pattern.git",
+    "directory": "packages/mod-identity"
+  },
+  "homepage": "https://github.com/makkr-studio/pattern#readme",
+  "bugs": "https://github.com/makkr-studio/pattern/issues",
+  "author": "Makkr Studio (https://github.com/makkr-studio)",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}