@owlmeans/server-auth 0.1.18-rc.1 → 0.1.18-rc.11

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.11",
+  "generatedAt": "2026-08-24T21:14:00.116Z",
   "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

@@ -8,7 +8,7 @@ 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.11"` in `dependencies`
 
 ## Key Exports
 

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

@@ -0,0 +1,100 @@
+---
+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 credential back to `makeAuthModel` (which signs the
+credential envelope) and 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?, entityId?, 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. Wire to `@owlmeans/server-auth-identity`'s `IdentityLinkingService`
+  (`getLinkedProfile` / `linkProfile`) to find-or-create a real profile + entity.
+- `enabled` — force on/off. Default is development only. **Never enable in real production.**
+- `acceptInternalTokens` (requirement: understand internal tokens even when OIDC is the primary
+  guard) — when `true`, ensures the internal `Ed25519BasicToken` guard (`DEFAULT_GUARD`) is accepted
+  as a coguard on already-guarded modules. Also exposed standalone as
+  `setupInternalTokenCoguard(modules, guard?)`. Set `false` when modules already use `DEFAULT_GUARD`
+  as the primary guard (internal tokens already work).
+
+## 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`) 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.)
+
+## 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, ... })` — offline mint via `@owlmeans/test-auth`'s `makeBearer`
+  using the project's **own** trusted signing key (lowest-level primitive).
+
+## 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`), `@owlmeans/basic-keys` (sign/verify),
+  `@owlmeans/auth-common` (`DEFAULT_GUARD`, `TrustedRecord`), `@owlmeans/config` (`TRUSTED`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth",
-  "version": "0.1.18-rc.1",
+  "version": "0.1.18-rc.11",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,29 +37,29 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/api": "^0.1.18-rc.1",
-    "@owlmeans/api-config-server": "^0.1.18-rc.1",
-    "@owlmeans/auth": "^0.1.18-rc.1",
-    "@owlmeans/auth-common": "^0.1.18-rc.1",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.1",
-    "@owlmeans/basic-ids": "^0.1.18-rc.1",
-    "@owlmeans/basic-keys": "^0.1.18-rc.1",
-    "@owlmeans/client-config": "^0.1.18-rc.1",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.1",
-    "@owlmeans/config": "^0.1.18-rc.1",
-    "@owlmeans/context": "^0.1.18-rc.1",
-    "@owlmeans/kluster": "^0.1.18-rc.1",
-    "@owlmeans/entrypoint": "^0.1.18-rc.1",
-    "@owlmeans/redis-resource": "^0.1.18-rc.1",
-    "@owlmeans/resource": "^0.1.18-rc.1",
-    "@owlmeans/route": "^0.1.18-rc.1",
-    "@owlmeans/server-api": "^0.1.18-rc.1",
-    "@owlmeans/server-context": "^0.1.18-rc.1",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.1",
-    "@owlmeans/server-route": "^0.1.18-rc.1",
-    "@owlmeans/server-socket": "^0.1.18-rc.1",
-    "@owlmeans/socket": "^0.1.18-rc.1",
-    "@owlmeans/static-resource": "^0.1.18-rc.1",
+    "@owlmeans/api": "^0.1.18-rc.7",
+    "@owlmeans/api-config-server": "^0.1.18-rc.11",
+    "@owlmeans/auth": "^0.1.18-rc.6",
+    "@owlmeans/auth-common": "^0.1.18-rc.7",
+    "@owlmeans/basic-envelope": "^0.1.18-rc.7",
+    "@owlmeans/basic-ids": "^0.1.18-rc.6",
+    "@owlmeans/basic-keys": "^0.1.18-rc.7",
+    "@owlmeans/client-config": "^0.1.18-rc.7",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/config": "^0.1.18-rc.7",
+    "@owlmeans/context": "^0.1.18-rc.6",
+    "@owlmeans/kluster": "^0.1.18-rc.7",
+    "@owlmeans/entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/redis-resource": "^0.1.18-rc.7",
+    "@owlmeans/resource": "^0.1.18-rc.7",
+    "@owlmeans/route": "^0.1.18-rc.6",
+    "@owlmeans/server-api": "^0.1.18-rc.11",
+    "@owlmeans/server-context": "^0.1.18-rc.7",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/server-route": "^0.1.18-rc.6",
+    "@owlmeans/server-socket": "^0.1.18-rc.11",
+    "@owlmeans/socket": "^0.1.18-rc.6",
+    "@owlmeans/static-resource": "^0.1.18-rc.7",
     "@scure/base": "^2.3.0"
   },
   "peerDependencies": {
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-auth": "^0.1.18-rc.1",
+    "@owlmeans/test-auth": "^0.1.18-rc.7",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",