@owlmeans/server-auth 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -1,72 +1,218 @@
 # @owlmeans/server-auth
 
-Server-side Ed25519 authentication service for OwlMeans backends.
-
-## Overview
-
-- Implements the `GuardService` interface for Ed25519-signed token verification
-- `appendAuthService()` registers the auth guard into a server context
-- `DEFAULT_ALIAS` (`'auth'`) is the service alias and re-exported as `DAUTH_GUARD` via `@owlmeans/server-app`
-- Handles token caching via a static resource identified by `AUTH_CACHE`
+The server side of OwlMeans authentication, in two halves. The root export is what every protected
+API service needs: the guard that verifies an Ed25519-signed bearer token and resolves
+`request.auth`, and the dispatcher bindings that exchange a credential issued by the auth manager
+for a bearer of this service. The `./manager` subpath is the auth manager application itself — the
+challenge endpoints, the authentication plugin registry, the signed credential envelope and the rely
+handshake. An ordinary service imports the root (usually implicitly, through
+`@owlmeans/server-app`'s `makeContext`); only the auth manager imports `./manager`. OIDC tokens are
+`@owlmeans/server-oidc-rp`, long-lived API keys `@owlmeans/server-auth-token`, local
+account/profile records `@owlmeans/server-auth-identity`, and the browser side `@owlmeans/client-auth`.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-auth
+bun add @owlmeans/server-auth@^0.1.18-rc.29
 ```
 
+## Concepts
+
+- **Guard** — the `AuthService` registered as `auth` (the value of `DEFAULT_GUARD`). `match` hits a
+  request carrying an `ed25519-basic-token`; `handle` verifies it against this service's own trusted
+  key (`cfg.alias ?? cfg.service`) and resolves the `Auth`. It authenticates only — authorization is
+  gates and handlers.
+- **Token exchange** — `authenticate(token)` verifies a credential envelope against the
+  `auth-service` trusted record (`AUTH_SRV_KEY`), burns its challenge into `AUTH_CACHE`, and returns
+  a bearer signed by this service.
+- **`AUTH_CACHE`** — the anti-replay store: each challenge is created once with an
+  `AUTHEN_TIMEFRAME` TTL. A static in-process resource by default.
+- **Auth manager** — the `./manager` application: `init(request)` returns a challenge,
+  `authenticate(credential)` returns a signed credential envelope, and the slug on the credential is
+  canonicalized through the entity resolver before signing.
+- **Authentication plugin** — `{ type, init, authenticate }` registered under an
+  `AuthenticationType`; the manager dispatches by the request's `type`.
+- **Rely** — the wallet handshake that lets one authenticated party vouch for another over a socket
+  (`DEFAULT_RELY` guard, `RELY_TUNNEL`).
+
 ## Usage
 
-Registered automatically by `makeContext()` from `@owlmeans/server-app`. To customize, pass `customize: true` and append manually:
+### Protect routes on an ordinary service
 
-```typescript
-import { makeContext } from '@owlmeans/server-app'
-import { appendAuthService, AUTH_CACHE } from '@owlmeans/server-auth'
+`@owlmeans/server-app`'s `makeContext(cfg)` registers the guard. A protocol opts in with `guards`,
+and everything declared under it inherits them.
 
-const context = makeContext(appConfig, true)  // skip default auth
+```ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { route, RouteMethod } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
 
-// Append auth with custom config
-appendAuthService(context)
+const invoiceBase = openProtocol(route('my-app:api:invoice', '/invoice'), { guards: DEFAULT_GUARD })
+
+export const invoiceProtocols = {
+  base: invoiceBase,
+  list: protocol(
+    route('my-app:api:invoice:list', '/', { parent: invoiceBase, method: RouteMethod.GET }),
+    contract(typed<Invoice[]>()),
+  ),
+}
 ```
 
-Reference the guard by alias when protecting routes:
+```ts
+import { handlers } from '@owlmeans/server-app'
+import { requireEntityKey } from '@owlmeans/auth-common'
 
-```typescript
-import { DAUTH_GUARD } from '@owlmeans/server-app'
-// same as DEFAULT_ALIAS from @owlmeans/server-auth
+const api = handlers<Context>()
 
-const adminModule = module(route('admin', '/admin'), guard(DAUTH_GUARD))
+export const list = api.request(invoiceProtocols.list, async (request, context) => {
+  // request.auth is the verified Auth: userId, profileId, role, scopes, entitySlug
+  const { items } = await context.invoice().list({ entityId: requireEntityKey(request) })
+  return items
+})
 ```
 
-## API
+### Scaled deployment
+
+Replace the in-process cache with a shared one before registering the guard, and declare the trusted
+keys the guard verifies against.
+
+```ts
+import { makeContext as makeAppContext } from '@owlmeans/server-app'
+import { appendRedis } from '@owlmeans/redis'
+import { makeRedisResource } from '@owlmeans/redis-resource'
+import { appendAuthService, AUTH_CACHE, AUTH_SRV_KEY } from '@owlmeans/server-auth'
+import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
+
+// config.ts — keys are loaded from the environment, never committed
+cfg.trusted.push({
+  id: process.env.AUTH_SERVICE_DID!, name: AUTH_SRV_KEY,
+  credential: process.env.AUTH_SERVICE_PUB!, scopes: ['*'],
+})
+cfg.trusted.push({
+  id: process.env.MY_APP_API_DID!, name: MY_APP_API,
+  credential: process.env.MY_APP_API_PUB!, secret: process.env.MY_APP_API_PK!, scopes: ['*'],
+})
+
+// context.ts
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeAppContext<C, T>(cfg, true)
+  appendRedis<C, T>(context)
+
+  context.registerResource(makeRedisResource(AUTH_CACHE))
+  appendAuthService<C, T>(context)
+  appendAuthIdentityResources(context)
+
+  return context
+}
+```
 
-### `appendAuthService<C, T>(context): void`
+### Verify a token outside the HTTP pipeline
 
-Registers the Ed25519 auth service and its nonce cache resource into the context.
+```ts
+import type { AuthServiceAppend } from '@owlmeans/server-auth'
 
-### `makeAuthService(alias?): AuthService`
+const readAuth = async (context: Context & AuthServiceAppend, authorization: string) =>
+  context.auth().unpack(authorization) // 'ED25519-BASIC-TOKEN <envelope>' -> Auth, or throws
+```
 
-Creates the auth service directly (used internally by `appendAuthService`).
+### Run the auth manager
 
-### `DEFAULT_ALIAS`
+```ts
+import { config, makeContext, main } from '@owlmeans/server-auth/manager'
+import type { AppConfig } from '@owlmeans/server-auth/manager'
+import '@owlmeans/server-oidc-rp/auth/plugins' // optional: OIDC and Google login plugins
 
-The auth service alias: `'auth'`. Re-exported as `DAUTH_GUARD` from `@owlmeans/server-app`.
+const cfg = config<AppConfig>(MY_APP_AUTH, commonConfig as AppConfig)
+const context = makeContext(cfg)
 
-### `AUTH_CACHE`
+await main(context)
+```
 
-Resource alias for the nonce replay-prevention cache.
+### Add an authentication method
 
-## Product-Viable Integration Notes
+```ts
+import { registerPlugin } from '@owlmeans/server-auth/manager/plugins'
+import type { AuthPlugin } from '@owlmeans/server-auth/manager/plugins'
 
-- Register `appendAuthService(context)` before `appendAuthIdentityResources(context)` and product-specific gate services.
-- Register `AUTH_CACHE` explicitly as a Redis resource when customizing the backend context.
-- This package verifies bearer tokens and populates `request.auth`; authorization remains the job of module gates and handler-level entity checks.
-- Pair it with `@owlmeans/server-auth-identity` when external provider login should produce durable local account/profile/credentials records.
+registerPlugin('my-method', context => ({
+  type: 'my-method',
+  init: async request => ({ challenge: /* unique per request */ '' }),
+  authenticate: async credential => {
+    // verify credential.credential, then set userId / profileId / entitySlug / role / scopes
+    return { token: '' } // '' keeps the manager's own challenge as the credential token
+  },
+}) as AuthPlugin)
+```
 
-## Related Packages
+## API
 
-- [`@owlmeans/auth-common`](../auth-common) — `GUARD_ED25519` constant and auth modules
+### Root export
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendAuthService(ctx, alias = DEFAULT_ALIAS)` | function | Register the guard as `context.auth()`; registers a static `AUTH_CACHE` when the context has none |
+| `makeAuthService(alias?)` | function | The guard: `match`, `handle`, `unpack(token)`, `authenticate(token)` |
+| `entrypoints` | const | Server bindings of `authProtocols.dispatcher` and `authProtocols.dispatcherAuthenticate` |
+| `DEFAULT_ALIAS` | const | `'auth'` — equals `DEFAULT_GUARD`; re-exported as `DAUTH_GUARD` by `@owlmeans/server-app` |
+| `AUTH_CACHE` | const | `'auth-cache'` — the single-use challenge store |
+| `AUTH_SRV_KEY` | const | `'auth-service'` — the trusted record whose key signs credential envelopes |
+| `AUTHEN_TIMEFRAME` | const | `15 * 60 * 1000` ms — challenge lifetime and anti-replay window |
+| `makeRelyModel`, `makeProviderRely`, `makeConsumerRely` | function | Rely envelope models |
+| `AuthService`, `AuthServiceAppend`, `AuthSpent`, `RelyOptions` | type | Guard service, context mixin, cache record, rely options |
+
+### `./manager`
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeContext(cfg, customize?)` | function | Server context with API server, API client, socket service, rely guard and static `AUTH_CACHE` |
+| `main(ctx)` | function | Register the manager entrypoints, init and listen |
+| `entrypoints` | const | Bindings for authen, init, authenticate, rely, api-config and reCAPTCHA siteverify |
+| `authenticationInit`, `authenticate`, `rely` | function | Implementations bound to the auth protocols |
+| `plugins`, `registerPlugin(type, factory)` | const / function | The plugin registry |
+| `appendSupervisorAuth(ctx, opts?)`, `setupInternalTokenCoguard(entrypoints, guard?)` | function | PK supervisor login (development only by default) |
+| `createRelyService(alias?)`, `createRelyFlow(context, conn, auth?)` | function | Rely guard service and socket authentication flow |
+| `DEFAULT_RELY`, `RELY_TUNNEL` | const | `'auth-rely'`, `'rely-tunnel'` |
+| `config`, `service`, `TRUSTED`, `addWebService`, `AppType`, `assertContext`, `klusterize`, `stab`, `backend`, `filterObject` | re-export | Config and context helpers for a manager app |
+| `handleIntermediate`, `handleBody`, `handleRequest`, `handleParams` | re-export | `@owlmeans/server-api` wrappers |
+| `AUTHEN`, `AUTHEN_AUTHEN`, `AUTHEN_INIT`, `GUARD_ED25519`, `BED255_CASHE_RESOURCE` | re-export | Auth aliases |
+| `AppConfig`, `AppContext`, `AuthModel`, `RelyService`, `RelyAllowanceRequest`, `RelyLinker`, `RelyCarrier` | type | Manager shapes |
+| `SupervisorAuthOptions`, `SupervisorUserResolver`, `SupervisorUserResolution`, `SupervisorPluginOptions` | type | Supervisor options |
+| `TrustedRecord`, `RefedEntrypointHandler`, `AbstractRequest`, `AbstractResponse` | type | Re-exported types |
+
+### `./manager/plugins`
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `registerPlugin(type, factory)`, `plugins` | function / const | The module-level registry |
+| `getPlugin(type, context)`, `assertType(type, plugin)` | function | Resolution; `getPlugin` throws `AuthUnknown(type)` for an unregistered type |
+| `basicEd25519`, `reCaptcha`, `basicRely` | function | Built-in plugins |
+| `makeSupervisorPlugin(context, opts)` | function | PK supervisor plugin factory |
+| `AuthPlugin`, `RecpatchaResponse`, `RecaptchaRequest`, `RelyRecord`, `AuthRedisResource` | type | Plugin shapes |
+
+## Common pitfalls
+
+- The guard verifies a bearer and sets `request.auth`; it decides nothing about ownership. Pair it
+  with gates and keep a handler-level organization check.
+- The default static `AUTH_CACHE` is correct for one replica only. Register a Redis resource under
+  the same alias before `appendAuthService` in any scaled deployment.
+- A plugin's `init` must return a challenge unique per request; a repeated challenge collides in
+  `AUTH_CACHE` and fails as `AuthenFailed('challenge')`.
+- The manager replaces whatever slug a plugin sets on `credential.entitySlug` with the current slug;
+  an unresolvable value fails as `AuthenFailed('entity')`. A token carries `entitySlug`, never an
+  entity id.
+- Register `appendAuthService` before `appendAuthIdentityResources` and product gate services.
+- Import `./manager` only in the auth manager process.
+
+## Related packages
+
+- [`@owlmeans/auth`](../auth) — `Auth`, `AuthCredentials`, error classes
+- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD`, `authProtocols`, `trust()`, entity helpers
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — local identity records and the entity resolver
+- [`@owlmeans/server-oidc-rp`](../server-oidc-rp) — OIDC login plugins and guard
+- [`@owlmeans/server-auth-otp`](../server-auth-otp) — email OTP plugin
+- [`@owlmeans/server-auth-token`](../server-auth-token) — long-lived access tokens
 - [`@owlmeans/server-app`](../server-app) — `makeContext` calls `appendAuthService` by default
+- [`@owlmeans/client-auth`](../client-auth) — the browser side
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -76,7 +222,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.23
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-auth",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.502Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-15T12:50:32.600Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -11,6 +11,13 @@
       "category": "package-specific",
       "file": "skills/server-auth/SKILL.md",
       "canonicalPath": ".agents/skills/server-auth/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "supervisor-auth",
+      "category": "multi-package",
+      "file": "skills/supervisor-auth/SKILL.md",
+      "canonicalPath": ".agents/skills/supervisor-auth/SKILL.md"
     }
   ]
 }

package/agent-meta/skills/server-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-auth
-description: How to use @owlmeans/server-auth — server-side authentication manager, AUTH_API alias, setupAuthServiceModules() to wire auth modules into your app. Auto-invoked when importing auth manager primitives.
+description: How to use @owlmeans/server-auth — the server side of OwlMeans authentication. Two halves in one package - appendAuthService/makeAuthService, which verify Ed25519 bearer tokens on an ordinary API server, and the ./manager subpath, which IS the auth manager service (challenge, plugin registry, credential envelope, rely). Auto-invoked when importing the server auth guard, registering an auth plugin, or building the auth manager.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,41 +8,112 @@ user-invocable: false
 # @owlmeans/server-auth
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/server-auth": "^0.1.18-rc.30"` in `dependencies`
 
-## Key Exports
+Two halves, deliberately split by subpath:
+
+- the **root** export is what every protected API server needs — the guard that verifies an
+  `Ed25519BasicToken` bearer and resolves an `Auth`;
+- **`./manager`** is the auth manager application itself — it serves `/authentication/init` and
+  `/authentication/authenticate`, owns the plugin registry, and signs the credential envelope.
+
+An ordinary service imports the root. Only the auth manager imports `./manager`.
+
+## Key Exports — root
+
+| Export | Description |
+|--------|-------------|
+| `appendAuthService(ctx, alias?)` | Register the guard on a server context and expose it as `context.auth()`. Registers a static `AUTH_CACHE` resource when the context has none |
+| `makeAuthService(alias?)` | The guard service itself: `match`, `handle`, `unpack(token)`, `authenticate(token)` |
+| `entrypoints` | `DISPATCHER` and `DISPATCHER_AUTHEN`, server-bound — spread these into a service that accepts a manager-issued credential and exchanges it for a bearer |
+| `DEFAULT_ALIAS` | `'auth'` — the guard's service alias, matching `DEFAULT_GUARD` |
+| `AUTH_CACHE` | `'auth-cache'` — the single-use challenge store |
+| `AUTH_SRV_KEY` | `'auth-service'` — the TRUSTED record whose key signs credential envelopes |
+| `AUTHEN_TIMEFRAME` | `15 * 60 * 1000` — challenge lifetime and anti-replay window, in ms |
+| `AuthService`, `AuthServiceAppend`, `AuthSpent` | Types |
+| `makeRelyModel`, `makeProviderRely`, `makeConsumerRely`, `RelyOptions` | The rely (wallet handshake) models |
+
+## Key Exports — `./manager`
 
 | Export | Description |
 |--------|-------------|
-| `setupAuthServiceModules(modules, alias)` | Wire auth modules into your app modules array |
-| `AUTH_API` (re-exported) | Auth service alias |
-| Auth service factory | Backend auth manager |
-| Plugin types | Pluggable auth verifiers |
+| `makeContext(cfg, customize?)` | A server context preconfigured with the API server, API client, socket service and static `AUTH_CACHE` |
+| `main(ctx)` | Register the manager entrypoints, configure, init and listen |
+| `entrypoints` | `AUTHEN`, `AUTHEN_INIT`, `AUTHEN_AUTHEN`, `AUTHEN_RELY`, the api-config entrypoints and the reCAPTCHA siteverify entrypoint |
+| `authenticationInit`, `authenticate`, `rely` | Implementations bound to auth protocols: `init(request)` → challenge, `authenticate(credential)` → signed credential envelope, and the rely socket |
+| `plugins`, `registerPlugin(type, factory)` | The plugin registry (also on `./manager/plugins`) |
+| `appendSupervisorAuth(ctx, opts?)`, `setupInternalTokenCoguard(entrypoints, guard?)` | PK supervisor login — see the `supervisor-auth` skill |
+| `createRelyService(alias?)`, `DEFAULT_RELY`, `RELY_TUNNEL` | The rely guard service |
+| `AppConfig`, `AppContext`, `AuthModel`, `RelyService`, `RelyAllowanceRequest`, `RelyLinker`, `RelyCarrier` | Types |
+
+`./manager` also re-exports the handful of symbols a manager application needs from elsewhere
+(`config`, `service`, `TRUSTED`, `bind`, `handlers`, `backend`,
+`GUARD_ED25519`, `AUTHEN*` aliases, `TrustedRecord`), so a manager app can be written against this
+one import.
 
-## Subpath Exports
+## Key Exports — `./manager/plugins`
 
-- `./manager` — auth manager service implementation
-- `./manager/plugins` — pluggable manager plugins
+| Export | Description |
+|--------|-------------|
+| `AuthPlugin` | `{ type, init(request), authenticate(credential) }` — `AuthModel` minus `rely` |
+| `registerPlugin(type, factory)` | Add a plugin under a type string. The registry is a module-level singleton |
+| `plugins` | The registry map |
+| `getPlugin(type, context)`, `assertType(type, plugin)` | Resolution; `getPlugin` throws `AuthUnknown(type)` for an unregistered type |
+| `basicEd25519`, `reCaptcha`, `basicRely` | The plugins registered out of the box, for `AuthenticationType.BasicEd25519`, `ReCaptcha` and `RelyHandshake` |
+| `makeSupervisorPlugin(context, opts)` | The PK supervisor plugin factory |
+| `RecpatchaResponse`, `RecaptchaRequest`, `RelyRecord`, `AuthRedisResource` | Types |
 
 ## Usage
 
+Protect an ordinary API server:
+
+```typescript
+import { appendAuthService } from '@owlmeans/server-auth'
+import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
+
+// in makeContext, after the db/cache services are appended:
+appendAuthService(context)
+appendAuthIdentityResources(context)
+```
+
+Add an authentication method to the manager:
+
 ```typescript
-import { setupAuthServiceModules } from '@owlmeans/server-auth'
-import { AUTH_API } from '@owlmeans/auth-common'
+import { registerPlugin } from '@owlmeans/server-auth/manager/plugins'
+import type { AuthPlugin } from '@owlmeans/server-auth/manager/plugins'
 
-setupAuthServiceModules(appModules, AUTH_API)
+registerPlugin('my-method', context => ({
+  type: 'my-method',
+  init: async request => ({ challenge: /* unique per request */ '' }),
+  authenticate: async credential => {
+    // verify credential.credential, then set userId / profileId / entitySlug / role / scopes
+    return { token: '' }   // '' keeps the manager's own challenge as the credential token
+  },
+}) as AuthPlugin)
 ```
 
-## Product-Viable Usage Notes
+## Rules
 
-- Backend context registers `appendAuthService(context)` before identity resources and product-specific gate services.
-- `AUTH_CACHE` must be registered as a Redis resource when the backend context does not rely on the default `server-app` setup.
-- `server-auth` verifies bearer tokens and populates `req.auth`; it does not decide product ownership or permissions by itself.
-- Pair this package with `@owlmeans/server-auth-identity` when an external provider such as Google should map into local account/profile/credentials records.
-- Pair it with `@owlmeans/entrypoint` gates for authorization, and keep handler-level `entityId` checks as a second line of defense.
+- The guard verifies a bearer token and populates `req.auth`. It decides nothing about ownership or
+  permissions — pair it with `@owlmeans/entrypoint` gates, and keep a handler-level organization
+  check as a second line of defence.
+- `AUTH_CACHE` is the anti-replay store: the manager burns each decoded challenge into it as a
+  create-once record with `AUTHEN_TIMEFRAME` TTL. `appendAuthService` registers a **static**
+  (in-process) resource when the context has none, which is correct for a single replica only —
+  register a Redis resource under the same alias before calling it in any scaled deployment.
+- A plugin's `init` must return a challenge that is unique per request. A challenge that repeats
+  across independent attempts collides in `AUTH_CACHE` and surfaces as `AuthenFailed('challenge')`.
+- The manager canonicalizes the organization entity: whatever slug (current, retired, or the frozen
+  key) a plugin leaves on `credential.entitySlug` is resolved through `ENTITY_RESOLVER` and replaced
+  with the current slug before the envelope is signed. An unresolvable value throws
+  `AuthenFailed('entity')`. Where no resolver is registered the value is passed through untouched.
+- Pair this package with `@owlmeans/server-auth-identity` when an external provider (Google, OIDC,
+  email OTP) must map onto local account/profile/credential records.
 
 ## Depends On
 
-- `@owlmeans/auth`, `@owlmeans/auth-common`
-- `@owlmeans/server-entrypoint`, `@owlmeans/server-context`
-- `@owlmeans/basic-keys` — Ed25519 verification
+- `@owlmeans/auth`, `@owlmeans/auth-common` — types, aliases, `trust()`, `extractAuthToken`
+- `@owlmeans/basic-envelope`, `@owlmeans/basic-keys` — envelope signing and Ed25519 verification
+- `@owlmeans/server-context`, `@owlmeans/server-entrypoint`, `@owlmeans/server-api`
+- `@owlmeans/config` — the `TRUSTED` config resource
+- `@owlmeans/static-resource` — the default `AUTH_CACHE` backing

package/agent-meta/skills/supervisor-auth/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: supervisor-auth
+description: PK-based supervisor authentication — a development-only login where a holder of one of the project's trusted private keys mints a token for any user id/email (registering them on first use), bypassing external IdPs. Primary use is end-to-end tests. Covers appendSupervisorAuth (server + web), the supervisor plugin, and the @owlmeans/test-ui helpers. Use when wiring or testing supervisor auth.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# PK-Based Supervisor Authentication
+
+**Layer:** Server (`@owlmeans/server-auth`) + Web (`@owlmeans/web-auth`) + Tests (`@owlmeans/test-ui`)
+
+A privileged, **development-only** auth path: a holder of one of the project's trusted private keys
+(the allowlisted "supervisors") signs a server challenge to mint a valid owlmeans token for an
+arbitrary user id / email — **without** Google/OIDC. Unknown users are **registered** on first use.
+The primary purpose is deterministic **end-to-end tests** that authenticate against real environments.
+
+It reuses the existing flow end-to-end: the plugin only **verifies the supervisor signature and
+resolves/registers the user**, then hands the mutated credential back to the auth manager's own
+model (which signs the credential envelope) and to the project's auth service (which exchanges it
+for the final `Ed25519BasicToken` bearer). No new token-minting code.
+
+## Type & payload
+
+- `AuthenticationType.Supervisor = 'pk-supervisor'` (in `@owlmeans/auth`).
+- Shared signed payload: `buildSupervisorPayload(challenge, userId, salt)` (in `@owlmeans/auth`) —
+  binds the signature to the **single-use server challenge** (replay protection), the target
+  `userId`, and a fresh client `salt`. The front-end packs `{ salt, signature }` (JSON) into
+  `AuthCredentials.credential`.
+
+## Server: `appendSupervisorAuth` (from `@owlmeans/server-auth/manager`)
+
+Call once on the **auth-manager** context (the one that serves `AUTHEN_INIT`/`AUTHEN_AUTHEN` and holds
+`AUTH_SRV_KEY`), beside other plugin appends (e.g. `appendOtpPlugin`).
+
+```ts
+import { appendSupervisorAuth } from '@owlmeans/server-auth/manager'
+
+appendSupervisorAuth(context, {
+  supervisors: ['master-key', 'super-user', 'shared-key'], // TRUSTED record `name`s allowed to sign
+  resolveUser: async (userId, ctx, { register }) => {        // find-or-create the target identity
+    // wire to your identity store; return { userId, profileId?, entitySlug?, role?, scopes? }
+  },
+  allowRegistration: true,        // default true
+  enabled: undefined,             // default: development only (cfg.debug.all || cfg.debug.supervisor)
+  acceptInternalTokens: true,     // default true — see below
+})
+```
+
+Options:
+- `supervisors` — TRUSTED-record `name`s authorized to sign. Default `['master','superuser']`. The
+  matching **public** key must be in the project's TRUSTED config; the **private** key is what the
+  front-end signs with. Pick aliases whose private keys you actually have (e.g. in `.env.dev.secrets`).
+- `resolveUser` — `(userId, context, { register }) => Promise<SupervisorUserResolution>`. Default:
+  trust the id as-is (`{ userId }`). Wire it to `@owlmeans/server-auth-identity`'s
+  `IdentityLinkingService` (`getLinkedProfile` / `linkProfile`) to find-or-create a real profile and
+  organization entity. `SupervisorUserResolution` is `{ userId }` plus optional `profileId`,
+  `entitySlug`, `role` and `scopes` — the organization value is a SLUG, the renameable public name
+  that a token carries, never the stable `entityId`. `profileId` defaults to `userId`, `scopes` to
+  the credential's own or `[ALL_SCOPES]`, and `role` to `AuthRole.User`.
+- `enabled` — force on/off. Default is development only. **Never enable in real production.**
+- `acceptInternalTokens` — when `true`, appends the internal `Ed25519BasicToken` guard
+  (`DEFAULT_GUARD`) as a coguard on every already-guarded backend entrypoint, so internal OwlMeans
+  tokens keep working where another guard (OIDC, say) is the primary one. The primary guard stays
+  first; the internal guard only matches an `Ed25519BasicToken` authorization header. Also exposed
+  standalone as `setupInternalTokenCoguard(entrypoints, guard?)`. Set `false` when the entrypoints
+  already use `DEFAULT_GUARD` as their primary guard.
+- `guard` — which guard alias `acceptInternalTokens` appends. Default `DEFAULT_GUARD` (`'auth'`).
+
+## Web: `appendSupervisorAuth` (from `@owlmeans/web-auth`)
+
+Call once on the web client context. Registers the self-contained login form plugin; the form renders
+at the standard typed route `SUPERVISOR_LOGIN_PATH` = `/authentication/login/pk-supervisor`.
+
+```ts
+import { appendSupervisorAuth } from '@owlmeans/web-auth'
+
+appendSupervisorAuth(context) // dev-only by default; or appendSupervisorAuth(context, { enabled })
+```
+
+The form (`data-testid="supervisor-auth-form"`, inputs `supervisor-user-id`, `supervisor-pk`, button
+`supervisor-submit`, error `supervisor-error`) fetches a challenge, signs it, exchanges it for a
+bearer, stores it, and redirects HOME — mirroring the Google plugin. (Alternatively, the side-effect
+import `@owlmeans/web-auth/auth/plugins` always-registers it.)
+
+The web append reads `cfg.debug.supervisor` alone; the server append accepts either
+`cfg.debug.all` or `cfg.debug.supervisor`. A deployment that wants the operator login therefore sets
+`debug.supervisor` — it is the flag both halves honour, and the only one that does not arrive by
+accident. The plugin is `restricted`, so `appendSupervisorAuth` also writes
+`cfg.security.auth.login.overrides` to make it offerable; `{ offer: false }` registers it without
+advertising it.
+
+## Tests: `@owlmeans/test-ui` helpers
+
+- `authenticateViaSupervisorApi({ apiBaseUrl, userId, pk })` — drives the live API
+  (`/authentication/init` → sign → `/authentication/authenticate` → `/authenticate`) and returns the
+  final bearer. **No browser**; registers the user on first use. The "set a token directly via API" path.
+- `loginViaSupervisorForm(page, { baseUrl, userId, pk })` — Playwright: drives the real login form
+  end-to-end (faithful path that exercises the plugin + registration).
+- `loginViaDispatcher(page, baseUrl, token)` — inject a pregenerated bearer via the standard
+  `/dispatcher?token=` route (apps that override DISPATCHER, e.g. for a forced IdP, can't use this —
+  use the form).
+- `pregenerateAuthToken({ userId, pk, scopes?, role?, profileId?, source?, ... })` — offline mint via
+  `@owlmeans/test-auth`'s `makeBearer`, using the project's **own** trusted signing key (lowest-level
+  primitive). No plugin, no registration.
+
+`loginViaSupervisorForm` answers a cookie-consent dialog by default (`consent: 'accept'`): an
+OwlMeans app refuses to start an authentication flow until consent is answered, and the modal
+intercepts every click at the form underneath. Both browser helpers navigate with
+`waitUntil: 'domcontentloaded'` rather than Playwright's `load`, because `load` waits for every
+subresource and a tag manager or analytics beacon that never settles holds it open until timeout.
+
+## Security
+
+- Development/stage only. Gate on `cfg.debug`; never ship enabled to real production.
+- Anyone with a supervisor **private** key can impersonate/register any user — treat those keys as
+  highly sensitive.
+
+## Depends On
+- `@owlmeans/auth` (type + `buildSupervisorPayload` + `SupervisorCredentialPayload`),
+  `@owlmeans/basic-keys` (sign/verify), `@owlmeans/basic-ids` (the salt),
+  `@owlmeans/auth-common` (`DEFAULT_GUARD`, `TrustedRecord`), `@owlmeans/config` (`TRUSTED`).
+- Tests: `@owlmeans/test-ui` (the helpers above) over `@owlmeans/test-auth` (`makeBearer`).
+
+## Related
+
+`server-auth` (the plugin registry and the manager) · `web-auth` (the form package) ·
+`server-auth-identity` (what `resolveUser` should be wired to) · `login-methods` (why a
+`restricted` method has to be named in the configuration)

package/build/actions/service.d.ts

@@ -1,4 +1,8 @@
-import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint';
+import type { EntrypointProtocol } from '@owlmeans/entrypoint';
 import type { AuthToken } from '@owlmeans/auth';
-export declare const authenticate: RefedEntrypointHandler<AuthToken>;
+export declare const authenticate: (protocol: EntrypointProtocol<{
+    body: AuthToken;
+}, AuthToken>) => import("@owlmeans/server-entrypoint").BoundEntrypointHandler<EntrypointProtocol<{
+    body: AuthToken;
+}, AuthToken>>;
 //# sourceMappingURL=service.d.ts.map

package/build/actions/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAS/C,eAAO,MAAM,YAAY,EAAE,sBAAsB,CAAC,SAAS,CAK1D,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAS/C,eAAO,MAAM,YAAY,aAAc,kBAAkB,CAAC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,EAAE,SAAS,CAAC;UAAvB,SAAS;cAKvE,CAAA"}

package/build/actions/service.js

@@ -1,7 +1,8 @@
-import { handleBody } from '@owlmeans/server-api';
+import { handlers } from '@owlmeans/server-api';
 import { assertContext } from '@owlmeans/context';
-export const authenticate = handleBody(async (payload, ctx) => {
-    const context = assertContext(ctx, 'authenticate');
-    return await context.auth().authenticate(payload);
+const api = handlers();
+export const authenticate = (protocol) => api.request(protocol, async (request, context) => {
+    const ctx = assertContext(context, 'authenticate');
+    return await ctx.auth().authenticate(request.body);
 });
 //# sourceMappingURL=service.js.map

package/build/actions/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAKjD,MAAM,CAAC,MAAM,YAAY,GAAsC,UAAU,CACvE,KAAK,EAAE,OAAkB,EAAE,GAAG,EAAE,EAAE;IAChC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,EAAE,cAAc,CAAY,CAAA;IAC7D,OAAO,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;AACnD,CAAC,CACF,CAAA"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/actions/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAK/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAIjD,MAAM,GAAG,GAAG,QAAQ,EAAW,CAAA;AAE/B,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAA4D,EAAE,EAAE,CAC3F,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;IAC/C,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,cAAc,CAAY,CAAA;IAE7D,OAAO,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AACpD,CAAC,CAAC,CAAA"}

package/build/entrypoints.d.ts

@@ -0,0 +1,5 @@
+import type { ServerProtocolEntrypoint } from '@owlmeans/server-entrypoint';
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint';
+/** Server entrypoints required by the generic authentication service. */
+export declare const entrypoints: ServerProtocolEntrypoint<EntrypointProtocolDeclaration>[];
+//# sourceMappingURL=entrypoints.d.ts.map

package/build/entrypoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAA;AAE3E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAA;AAGzE,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,wBAAwB,CAAC,6BAA6B,CAAC,EAGhF,CAAA"}

package/build/entrypoints.js

@@ -0,0 +1,9 @@
+import { bind } from '@owlmeans/server-entrypoint';
+import { authProtocols } from '@owlmeans/auth-common';
+import { authenticate } from './actions/service.js';
+/** Server entrypoints required by the generic authentication service. */
+export const entrypoints = [
+    bind(authProtocols.dispatcher),
+    bind(authProtocols.dispatcherAuthenticate, authenticate(authProtocols.dispatcherAuthenticate)),
+];
+//# sourceMappingURL=entrypoints.js.map

package/build/entrypoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.js","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAA;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAA8D;IACpF,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC;IAC9B,IAAI,CAAC,aAAa,CAAC,sBAAsB,EAAE,YAAY,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC/F,CAAA"}

package/build/index.d.ts

@@ -1,6 +1,6 @@
 export type * from './types.js';
 export * from './model/index.js';
 export * from './consts.js';
-export * from './modules.js';
+export * from './entrypoints.js';
 export * from './service.js';
 //# sourceMappingURL=index.d.ts.map