@owlmeans/server-auth 0.1.10 → 0.1.14

package/agent-meta/instructions/server-auth.instructions.md

@@ -7,7 +7,7 @@ applyTo: "**/*.ts, **/*.tsx"
 # @owlmeans/server-auth
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-auth": "^0.1.10"` in `dependencies`
+**Install:** `"@owlmeans/server-auth": "^0.1.14"` in `dependencies`
 
 ## Key Exports
 

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/server-auth",
-  "version": "0.1.10",
-  "generatedAt": "2026-06-17T09:37:28.169Z",
+  "version": "0.1.14",
+  "generatedAt": "2026-08-05T16:56:53.374Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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.10"` in `dependencies`
+**Install:** `"@owlmeans/server-auth": "^0.1.14"` in `dependencies`
 
 ## Key Exports
 

package/build/manager/index.d.ts

@@ -8,4 +8,5 @@ export * from './consts.js';
 export * from './rely/index.js';
 export * from './actions/index.js';
 export * from './plugins/index.js';
+export * from './supervisor.js';
 //# sourceMappingURL=index.d.ts.map

package/build/manager/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manager/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manager/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA"}

package/build/manager/index.js

@@ -7,4 +7,5 @@ export * from './consts.js';
 export * from './rely/index.js';
 export * from './actions/index.js';
 export * from './plugins/index.js';
+export * from './supervisor.js';
 //# sourceMappingURL=index.js.map

package/build/manager/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/manager/index.ts"],"names":[],"mappings":"AAEA,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/manager/index.ts"],"names":[],"mappings":"AAEA,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA"}

package/build/manager/plugins/export.d.ts

@@ -2,6 +2,7 @@ export type * from './types.js';
 export * from './basic-ed25519.js';
 export * from './re-captcha.js';
 export * from './basic-rely.js';
+export * from './supervisor.js';
 export * from './utils.js';
 export { plugins, registerPlugin } from './index.js';
 //# sourceMappingURL=export.d.ts.map

package/build/manager/plugins/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/manager/plugins/export.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/manager/plugins/export.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/build/manager/plugins/export.js

@@ -1,6 +1,7 @@
 export * from './basic-ed25519.js';
 export * from './re-captcha.js';
 export * from './basic-rely.js';
+export * from './supervisor.js';
 export * from './utils.js';
 export { plugins, registerPlugin } from './index.js';
 //# sourceMappingURL=export.js.map

package/build/manager/plugins/export.js.map

@@ -1 +1 @@
-{"version":3,"file":"export.js","sourceRoot":"","sources":["../../../src/manager/plugins/export.ts"],"names":[],"mappings":"AAEA,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../../src/manager/plugins/export.ts"],"names":[],"mappings":"AAEA,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/build/manager/plugins/supervisor.d.ts

@@ -0,0 +1,18 @@
+import type { AuthPlugin } from './types.js';
+import type { AppConfig, AppContext } from '../types.js';
+import type { SupervisorPluginOptions } from '../supervisor.js';
+/**
+ * PK-based supervisor authentication plugin. A privileged operator (or an e2e
+ * test) holds one of the project's trusted private keys (the allowlisted
+ * `supervisors`) and signs `buildSupervisorPayload` to mint a token for an
+ * arbitrary user id / email - bypassing external IdPs. Development-only by
+ * design (see `appendSupervisorAuth`).
+ *
+ * The plugin issues NO token itself: it only verifies the supervisor signature
+ * and resolves/registers the target user, then hands the mutated credential back
+ * to the existing `makeAuthModel` flow which signs the credential envelope, and
+ * to the project's auth service which exchanges it for the final
+ * `Ed25519BasicToken` bearer.
+ */
+export declare const makeSupervisorPlugin: (context: AppContext<AppConfig>, opts: SupervisorPluginOptions) => AuthPlugin;
+//# sourceMappingURL=supervisor.d.ts.map

package/build/manager/plugins/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/manager/plugins/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAM5C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAS,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,uBAAuB,KAC5D,UA8DF,CAAA"}

package/build/manager/plugins/supervisor.js

@@ -0,0 +1,75 @@
+import { AuthenticationType, AuthenFailed, AuthRole, ALL_SCOPES, buildSupervisorPayload } from '@owlmeans/auth';
+import { base64 } from '@scure/base';
+import { randomBytes } from '@noble/hashes/utils';
+import { fromPubKey } from '@owlmeans/basic-keys';
+import { TRUSTED } from '@owlmeans/config';
+/**
+ * PK-based supervisor authentication plugin. A privileged operator (or an e2e
+ * test) holds one of the project's trusted private keys (the allowlisted
+ * `supervisors`) and signs `buildSupervisorPayload` to mint a token for an
+ * arbitrary user id / email - bypassing external IdPs. Development-only by
+ * design (see `appendSupervisorAuth`).
+ *
+ * The plugin issues NO token itself: it only verifies the supervisor signature
+ * and resolves/registers the target user, then hands the mutated credential back
+ * to the existing `makeAuthModel` flow which signs the credential envelope, and
+ * to the project's auth service which exchanges it for the final
+ * `Ed25519BasicToken` bearer.
+ */
+export const makeSupervisorPlugin = (context, opts) => {
+    const plugin = {
+        type: AuthenticationType.Supervisor,
+        init: async () => ({ challenge: base64.encode(randomBytes(32)) }),
+        authenticate: async (credential) => {
+            // `credential.challenge` has already been replaced by the model with the
+            // unwrapped, single-use server challenge (`msg`).
+            let parsed;
+            try {
+                parsed = JSON.parse(credential.credential);
+            }
+            catch {
+                throw new AuthenFailed('supervisor:credential');
+            }
+            if (parsed?.signature == null || parsed?.salt == null || credential.userId == null) {
+                throw new AuthenFailed('supervisor:payload');
+            }
+            const payload = buildSupervisorPayload(credential.challenge, credential.userId, parsed.salt);
+            let matched = null;
+            for (const alias of opts.supervisors) {
+                try {
+                    const record = await context.getConfigResource(TRUSTED)
+                        .load(alias, 'name');
+                    if (record?.credential == null) {
+                        continue;
+                    }
+                    if (await fromPubKey(record.credential).verify(payload, parsed.signature)) {
+                        matched = alias;
+                        break;
+                    }
+                }
+                catch {
+                    // unknown trusted alias or verification error - try the next supervisor
+                }
+            }
+            if (matched == null) {
+                throw new AuthenFailed('supervisor:signature');
+            }
+            const resolution = opts.resolveUser != null
+                ? await opts.resolveUser(credential.userId, context, { register: opts.allowRegistration })
+                : { userId: credential.userId };
+            credential.userId = resolution.userId;
+            credential.profileId = resolution.profileId ?? resolution.userId;
+            if (resolution.entityId != null) {
+                credential.entityId = resolution.entityId;
+            }
+            credential.scopes = resolution.scopes ?? credential.scopes ?? [ALL_SCOPES];
+            credential.role = resolution.role ?? AuthRole.User;
+            const token = base64.encode(randomBytes(32));
+            credential.challenge = token;
+            credential.type = AuthenticationType.OneTimeToken;
+            return { token };
+        }
+    };
+    return plugin;
+};
+//# sourceMappingURL=supervisor.js.map

package/build/manager/plugins/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/manager/plugins/supervisor.ts"],"names":[],"mappings":"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"}

package/build/manager/supervisor.d.ts

@@ -0,0 +1,63 @@
+import type { AuthPayload } from '@owlmeans/auth';
+import type { AppConfig, AppContext } from './types.js';
+/**
+ * What a `SupervisorUserResolver` returns: the identity the supervisor-minted
+ * token will represent. Only `userId` is required - the rest default sensibly.
+ */
+export interface SupervisorUserResolution extends Partial<Pick<AuthPayload, 'profileId' | 'entityId' | 'role' | 'scopes'>> {
+    userId: string;
+}
+/**
+ * Find-or-create the target identity for a supervisor login. `register` reflects
+ * `allowRegistration`; when false the resolver should only look existing users up.
+ * Wire this to the project's identity store (e.g. `@owlmeans/server-auth-identity`).
+ */
+export interface SupervisorUserResolver {
+    <C extends AppConfig, T extends AppContext<C>>(userId: string, context: T, opts: {
+        register: boolean;
+    }): Promise<SupervisorUserResolution>;
+}
+/** Resolved options handed to the plugin factory. */
+export interface SupervisorPluginOptions {
+    supervisors: string[];
+    allowRegistration: boolean;
+    resolveUser?: SupervisorUserResolver;
+}
+export interface SupervisorAuthOptions {
+    /** Trusted-record aliases authorized to act as supervisor. Default: master + superuser. */
+    supervisors?: string[];
+    /** Find-or-create the target user by id/email. Default: trust the id as-is. */
+    resolveUser?: SupervisorUserResolver;
+    /** Allow minting a token for an unknown user (registration). Default: true. */
+    allowRegistration?: boolean;
+    /** Force enable/disable. Default: development only (cfg.debug.all || cfg.debug.supervisor). */
+    enabled?: boolean;
+    /**
+     * Also accept internal owlmeans `Ed25519BasicToken`s even when another guard
+     * (e.g. OIDC) is the primary guard on protected modules. Default: true.
+     */
+    acceptInternalTokens?: boolean;
+    /** The internal-token guard to add as a coguard. Default: DEFAULT_GUARD ('auth'). */
+    guard?: string;
+}
+/**
+ * Ensure the internal `Ed25519BasicToken` guard is accepted as a coguard on every
+ * already-guarded backend module, so internal owlmeans tokens keep working even
+ * when another guard (e.g. OIDC) is the primary guard. The primary guard stays
+ * first; the internal guard is appended as a fallback (its `match` only fires for
+ * an `Ed25519BasicToken` authorization header).
+ */
+export declare const setupInternalTokenCoguard: (modules: Array<{
+    guards?: string[];
+}>, guard?: string) => void;
+/**
+ * Unified, explicit append for PK-based supervisor authentication. Call it once
+ * on the auth-manager server context. Development-only by default.
+ *
+ * It registers the supervisor auth plugin (verifies a front-end signature against
+ * the allowlisted trusted keys, then resolves/registers the target user) and -
+ * unless disabled - makes protected modules also accept internal owlmeans tokens
+ * (requirement: understand internal tokens even when OIDC is the primary guard).
+ */
+export declare const appendSupervisorAuth: <C extends AppConfig, T extends AppContext<C>>(context: T, opts?: SupervisorAuthOptions) => T;
+//# sourceMappingURL=supervisor.d.ts.map

package/build/manager/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/manager/supervisor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAIvD;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,OAAO,CAAC,IAAI,CAAC,WAAW,EACxE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAC3C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,GACtD,OAAO,CAAC,wBAAwB,CAAC,CAAA;CACrC;AAED,qDAAqD;AACrD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,WAAW,CAAC,EAAE,sBAAsB,CAAA;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,sBAAsB,CAAA;IACpC,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,+FAA+F;IAC/F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,KAAK,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EAAE,QAAO,MAAsB,KACnE,IAMF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAC/E,SAAS,CAAC,EAAE,OAAO,qBAAqB,KACvC,CAyBF,CAAA"}

package/build/manager/supervisor.js

@@ -0,0 +1,46 @@
+import { AuthenticationType } from '@owlmeans/auth';
+import { DEFAULT_GUARD } from '@owlmeans/auth-common';
+import { registerPlugin } from './plugins/index.js';
+import { makeSupervisorPlugin } from './plugins/supervisor.js';
+const DEFAULT_SUPERVISORS = ['master', 'superuser'];
+const isDevelopment = (context) => context.cfg.debug?.all === true || context.cfg.debug?.supervisor === true;
+/**
+ * Ensure the internal `Ed25519BasicToken` guard is accepted as a coguard on every
+ * already-guarded backend module, so internal owlmeans tokens keep working even
+ * when another guard (e.g. OIDC) is the primary guard. The primary guard stays
+ * first; the internal guard is appended as a fallback (its `match` only fires for
+ * an `Ed25519BasicToken` authorization header).
+ */
+export const setupInternalTokenCoguard = (modules, guard = DEFAULT_GUARD) => {
+    modules.forEach(module => {
+        if (module.guards != null && module.guards.length > 0 && !module.guards.includes(guard)) {
+            module.guards.push(guard);
+        }
+    });
+};
+/**
+ * Unified, explicit append for PK-based supervisor authentication. Call it once
+ * on the auth-manager server context. Development-only by default.
+ *
+ * It registers the supervisor auth plugin (verifies a front-end signature against
+ * the allowlisted trusted keys, then resolves/registers the target user) and -
+ * unless disabled - makes protected modules also accept internal owlmeans tokens
+ * (requirement: understand internal tokens even when OIDC is the primary guard).
+ */
+export const appendSupervisorAuth = (context, opts) => {
+    const enabled = opts?.enabled ?? isDevelopment(context);
+    if (!enabled) {
+        return context;
+    }
+    const resolved = {
+        supervisors: opts?.supervisors ?? DEFAULT_SUPERVISORS,
+        allowRegistration: opts?.allowRegistration ?? true,
+        resolveUser: opts?.resolveUser
+    };
+    registerPlugin(AuthenticationType.Supervisor, (ctx => makeSupervisorPlugin(ctx, resolved)));
+    if (opts?.acceptInternalTokens !== false) {
+        setupInternalTokenCoguard(context.entrypoints(), opts?.guard ?? DEFAULT_GUARD);
+    }
+    return context;
+};
+//# sourceMappingURL=supervisor.js.map

package/build/manager/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../src/manager/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AA+C9D,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;AAEnD,MAAM,aAAa,GAAG,CAAC,OAAqE,EAAW,EAAE,CACvG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;AAE3E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,OAAqC,EAAE,QAAgB,aAAa,EAC9D,EAAE;IACR,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACvB,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACxF,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,OAAU,EAAE,IAA4B,EACrC,EAAE;IACL,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,MAAM,QAAQ,GAA4B;QACxC,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,mBAAmB;QACrD,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,IAAI,IAAI;QAClD,WAAW,EAAE,IAAI,EAAE,WAAW;KAC/B,CAAA;IAED,cAAc,CACZ,kBAAkB,CAAC,UAAU,EAC7B,CAAC,GAAG,CAAC,EAAE,CAAC,oBAAoB,CAAC,GAAuC,EAAE,QAAQ,CAAC,CAAyC,CACzH,CAAA;IAED,IAAI,IAAI,EAAE,oBAAoB,KAAK,KAAK,EAAE,CAAC;QACzC,yBAAyB,CACvB,OAAO,CAAC,WAAW,EAA6C,EAChE,IAAI,EAAE,KAAK,IAAI,aAAa,CAC7B,CAAA;IACH,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth",
-  "version": "0.1.10",
+  "version": "0.1.14",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,29 +37,29 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/api": "^0.1.10",
-    "@owlmeans/api-config-server": "^0.1.10",
-    "@owlmeans/auth": "^0.1.10",
-    "@owlmeans/auth-common": "^0.1.10",
-    "@owlmeans/basic-envelope": "^0.1.10",
-    "@owlmeans/basic-ids": "^0.1.10",
-    "@owlmeans/basic-keys": "^0.1.10",
-    "@owlmeans/client-config": "^0.1.10",
-    "@owlmeans/client-entrypoint": "^0.1.10",
-    "@owlmeans/config": "^0.1.10",
-    "@owlmeans/context": "^0.1.10",
-    "@owlmeans/kluster": "^0.1.10",
-    "@owlmeans/entrypoint": "^0.1.10",
-    "@owlmeans/redis-resource": "^0.1.10",
-    "@owlmeans/resource": "^0.1.10",
-    "@owlmeans/route": "^0.1.10",
-    "@owlmeans/server-api": "^0.1.10",
-    "@owlmeans/server-context": "^0.1.10",
-    "@owlmeans/server-entrypoint": "^0.1.10",
-    "@owlmeans/server-route": "^0.1.10",
-    "@owlmeans/server-socket": "^0.1.10",
-    "@owlmeans/socket": "^0.1.10",
-    "@owlmeans/static-resource": "^0.1.10",
+    "@owlmeans/api": "^0.1.14",
+    "@owlmeans/api-config-server": "^0.1.14",
+    "@owlmeans/auth": "^0.1.14",
+    "@owlmeans/auth-common": "^0.1.14",
+    "@owlmeans/basic-envelope": "^0.1.14",
+    "@owlmeans/basic-ids": "^0.1.14",
+    "@owlmeans/basic-keys": "^0.1.14",
+    "@owlmeans/client-config": "^0.1.14",
+    "@owlmeans/client-entrypoint": "^0.1.14",
+    "@owlmeans/config": "^0.1.14",
+    "@owlmeans/context": "^0.1.14",
+    "@owlmeans/kluster": "^0.1.14",
+    "@owlmeans/entrypoint": "^0.1.14",
+    "@owlmeans/redis-resource": "^0.1.14",
+    "@owlmeans/resource": "^0.1.14",
+    "@owlmeans/route": "^0.1.14",
+    "@owlmeans/server-api": "^0.1.14",
+    "@owlmeans/server-context": "^0.1.14",
+    "@owlmeans/server-entrypoint": "^0.1.14",
+    "@owlmeans/server-route": "^0.1.14",
+    "@owlmeans/server-socket": "^0.1.14",
+    "@owlmeans/socket": "^0.1.14",
+    "@owlmeans/static-resource": "^0.1.14",
     "@scure/base": "^1.1.9"
   },
   "peerDependencies": {
@@ -67,12 +67,11 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-auth": "^0.1.10",
-    "@types/bun": "^1.3.0",
-    "@types/node": "^24.10.1",
-    "nodemon": "^3.1.11",
-    "npm-check": "^6.0.1",
-    "typescript": "^6.0.2"
+    "@owlmeans/test-auth": "^0.1.14",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public"

package/src/manager/index.ts

@@ -9,3 +9,4 @@ export * from './consts.js'
 export * from './rely/index.js'
 export * from './actions/index.js'
 export * from './plugins/index.js'
+export * from './supervisor.js'

package/src/manager/plugins/export.ts

@@ -3,5 +3,6 @@ export type * from './types.js'
 export * from './basic-ed25519.js'
 export * from './re-captcha.js'
 export * from './basic-rely.js'
+export * from './supervisor.js'
 export * from './utils.js'
 export { plugins, registerPlugin } from './index.js'

package/src/manager/plugins/supervisor.ts

@@ -0,0 +1,89 @@
+import { AuthenticationType, AuthenFailed, AuthRole, ALL_SCOPES, buildSupervisorPayload } from '@owlmeans/auth'
+import type { SupervisorCredentialPayload } from '@owlmeans/auth'
+import type { AuthPlugin } from './types.js'
+import { base64 } from '@scure/base'
+import { randomBytes } from '@noble/hashes/utils'
+import { fromPubKey } from '@owlmeans/basic-keys'
+import { TRUSTED } from '@owlmeans/config'
+import type { TrustedRecord } from '@owlmeans/auth-common'
+import type { AppConfig, AppContext } from '../types.js'
+import type { SupervisorPluginOptions } from '../supervisor.js'
+
+/**
+ * PK-based supervisor authentication plugin. A privileged operator (or an e2e
+ * test) holds one of the project's trusted private keys (the allowlisted
+ * `supervisors`) and signs `buildSupervisorPayload` to mint a token for an
+ * arbitrary user id / email - bypassing external IdPs. Development-only by
+ * design (see `appendSupervisorAuth`).
+ *
+ * The plugin issues NO token itself: it only verifies the supervisor signature
+ * and resolves/registers the target user, then hands the mutated credential back
+ * to the existing `makeAuthModel` flow which signs the credential envelope, and
+ * to the project's auth service which exchanges it for the final
+ * `Ed25519BasicToken` bearer.
+ */
+export const makeSupervisorPlugin = (
+  context: AppContext<AppConfig>, opts: SupervisorPluginOptions
+): AuthPlugin => {
+  const plugin: AuthPlugin = {
+    type: AuthenticationType.Supervisor,
+
+    init: async () => ({ challenge: base64.encode(randomBytes(32)) }),
+
+    authenticate: async credential => {
+      // `credential.challenge` has already been replaced by the model with the
+      // unwrapped, single-use server challenge (`msg`).
+      let parsed: SupervisorCredentialPayload
+      try {
+        parsed = JSON.parse(credential.credential) as SupervisorCredentialPayload
+      } catch {
+        throw new AuthenFailed('supervisor:credential')
+      }
+      if (parsed?.signature == null || parsed?.salt == null || credential.userId == null) {
+        throw new AuthenFailed('supervisor:payload')
+      }
+
+      const payload = buildSupervisorPayload(credential.challenge, credential.userId, parsed.salt)
+
+      let matched: string | null = null
+      for (const alias of opts.supervisors) {
+        try {
+          const record = await context.getConfigResource(TRUSTED)
+            .load<TrustedRecord>(alias, 'name')
+          if (record?.credential == null) {
+            continue
+          }
+          if (await fromPubKey(record.credential).verify(payload, parsed.signature)) {
+            matched = alias
+            break
+          }
+        } catch {
+          // unknown trusted alias or verification error - try the next supervisor
+        }
+      }
+      if (matched == null) {
+        throw new AuthenFailed('supervisor:signature')
+      }
+
+      const resolution = opts.resolveUser != null
+        ? await opts.resolveUser(credential.userId, context, { register: opts.allowRegistration })
+        : { userId: credential.userId }
+
+      credential.userId = resolution.userId
+      credential.profileId = resolution.profileId ?? resolution.userId
+      if (resolution.entityId != null) {
+        credential.entityId = resolution.entityId
+      }
+      credential.scopes = resolution.scopes ?? credential.scopes ?? [ALL_SCOPES]
+      credential.role = resolution.role ?? AuthRole.User
+
+      const token = base64.encode(randomBytes(32))
+      credential.challenge = token
+      credential.type = AuthenticationType.OneTimeToken
+
+      return { token }
+    }
+  }
+
+  return plugin
+}

package/src/manager/supervisor.ts

@@ -0,0 +1,111 @@
+import { AuthenticationType } from '@owlmeans/auth'
+import type { AuthPayload } from '@owlmeans/auth'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import type { AppConfig, AppContext } from './types.js'
+import { registerPlugin } from './plugins/index.js'
+import { makeSupervisorPlugin } from './plugins/supervisor.js'
+
+/**
+ * What a `SupervisorUserResolver` returns: the identity the supervisor-minted
+ * token will represent. Only `userId` is required - the rest default sensibly.
+ */
+export interface SupervisorUserResolution extends Partial<Pick<AuthPayload,
+  'profileId' | 'entityId' | 'role' | 'scopes'>> {
+  userId: string
+}
+
+/**
+ * Find-or-create the target identity for a supervisor login. `register` reflects
+ * `allowRegistration`; when false the resolver should only look existing users up.
+ * Wire this to the project's identity store (e.g. `@owlmeans/server-auth-identity`).
+ */
+export interface SupervisorUserResolver {
+  <C extends AppConfig, T extends AppContext<C>>(
+    userId: string, context: T, opts: { register: boolean }
+  ): Promise<SupervisorUserResolution>
+}
+
+/** Resolved options handed to the plugin factory. */
+export interface SupervisorPluginOptions {
+  supervisors: string[]
+  allowRegistration: boolean
+  resolveUser?: SupervisorUserResolver
+}
+
+export interface SupervisorAuthOptions {
+  /** Trusted-record aliases authorized to act as supervisor. Default: master + superuser. */
+  supervisors?: string[]
+  /** Find-or-create the target user by id/email. Default: trust the id as-is. */
+  resolveUser?: SupervisorUserResolver
+  /** Allow minting a token for an unknown user (registration). Default: true. */
+  allowRegistration?: boolean
+  /** Force enable/disable. Default: development only (cfg.debug.all || cfg.debug.supervisor). */
+  enabled?: boolean
+  /**
+   * Also accept internal owlmeans `Ed25519BasicToken`s even when another guard
+   * (e.g. OIDC) is the primary guard on protected modules. Default: true.
+   */
+  acceptInternalTokens?: boolean
+  /** The internal-token guard to add as a coguard. Default: DEFAULT_GUARD ('auth'). */
+  guard?: string
+}
+
+const DEFAULT_SUPERVISORS = ['master', 'superuser']
+
+const isDevelopment = (context: { cfg: { debug?: { all?: boolean, supervisor?: boolean } } }): boolean =>
+  context.cfg.debug?.all === true || context.cfg.debug?.supervisor === true
+
+/**
+ * Ensure the internal `Ed25519BasicToken` guard is accepted as a coguard on every
+ * already-guarded backend module, so internal owlmeans tokens keep working even
+ * when another guard (e.g. OIDC) is the primary guard. The primary guard stays
+ * first; the internal guard is appended as a fallback (its `match` only fires for
+ * an `Ed25519BasicToken` authorization header).
+ */
+export const setupInternalTokenCoguard = (
+  modules: Array<{ guards?: string[] }>, guard: string = DEFAULT_GUARD
+): void => {
+  modules.forEach(module => {
+    if (module.guards != null && module.guards.length > 0 && !module.guards.includes(guard)) {
+      module.guards.push(guard)
+    }
+  })
+}
+
+/**
+ * Unified, explicit append for PK-based supervisor authentication. Call it once
+ * on the auth-manager server context. Development-only by default.
+ *
+ * It registers the supervisor auth plugin (verifies a front-end signature against
+ * the allowlisted trusted keys, then resolves/registers the target user) and -
+ * unless disabled - makes protected modules also accept internal owlmeans tokens
+ * (requirement: understand internal tokens even when OIDC is the primary guard).
+ */
+export const appendSupervisorAuth = <C extends AppConfig, T extends AppContext<C>>(
+  context: T, opts?: SupervisorAuthOptions
+): T => {
+  const enabled = opts?.enabled ?? isDevelopment(context)
+  if (!enabled) {
+    return context
+  }
+
+  const resolved: SupervisorPluginOptions = {
+    supervisors: opts?.supervisors ?? DEFAULT_SUPERVISORS,
+    allowRegistration: opts?.allowRegistration ?? true,
+    resolveUser: opts?.resolveUser
+  }
+
+  registerPlugin(
+    AuthenticationType.Supervisor,
+    (ctx => makeSupervisorPlugin(ctx as unknown as AppContext<AppConfig>, resolved)) as Parameters<typeof registerPlugin>[1]
+  )
+
+  if (opts?.acceptInternalTokens !== false) {
+    setupInternalTokenCoguard(
+      context.entrypoints() as unknown as Array<{ guards?: string[] }>,
+      opts?.guard ?? DEFAULT_GUARD
+    )
+  }
+
+  return context
+}

package/tests/supervisor.spec.ts

@@ -0,0 +1,108 @@
+import { describe, test, expect } from 'bun:test'
+import { makeFixtureKeyPair } from '@owlmeans/test-auth'
+import { AuthenticationType, AuthRole, buildSupervisorPayload } from '@owlmeans/auth'
+import type { AuthCredentials } from '@owlmeans/auth'
+import type { TrustedRecord } from '@owlmeans/auth-common'
+import { makeSupervisorPlugin } from '../src/manager/plugins/supervisor.js'
+import type { AppConfig, AppContext } from '../src/manager/types.js'
+
+const SUPERVISOR = 'master'
+
+const makeStubContext = (records: TrustedRecord[]): AppContext<AppConfig> => ({
+  getConfigResource: () => ({
+    load: async (id: string, field?: string) =>
+      records.find(r => (field === 'name' ? r.name === id : r.id === id)) ?? null
+  })
+} as unknown as AppContext<AppConfig>)
+
+const signCredential = async (
+  kp: ReturnType<typeof makeFixtureKeyPair>, challenge: string, userId: string, salt: string
+): Promise<string> => {
+  const signature = await kp.sign(buildSupervisorPayload(challenge, userId, salt))
+  return JSON.stringify({ salt, signature })
+}
+
+const baseCredential = (challenge: string, userId: string, credential: string): AuthCredentials => ({
+  type: AuthenticationType.Supervisor,
+  challenge,
+  credential,
+  userId,
+  role: AuthRole.User,
+  scopes: ['*'],
+})
+
+describe('@owlmeans/server-auth — supervisor plugin', () => {
+  test('verifies an allowlisted supervisor signature and issues a one-time token', async () => {
+    const kp = makeFixtureKeyPair(SUPERVISOR)
+    const record: TrustedRecord = { id: kp.exportAddress(), name: SUPERVISOR, credential: kp.exportPublic(), scopes: ['*'] }
+    const context = makeStubContext([record])
+
+    const plugin = makeSupervisorPlugin(context, { supervisors: [SUPERVISOR], allowRegistration: true })
+
+    const challenge = 'challenge-' + Date.now()
+    const userId = 'newuser@example.com'
+    const credential = baseCredential(challenge, userId, await signCredential(kp, challenge, userId, 'salt-1'))
+
+    const result = await plugin.authenticate(credential)
+
+    expect(result.token).toBeString()
+    expect(result.token.length).toBeGreaterThan(0)
+    expect(credential.type).toBe(AuthenticationType.OneTimeToken)
+    expect(credential.challenge).toBe(result.token)
+    expect(credential.userId).toBe(userId)
+    expect(credential.role).toBe(AuthRole.User)
+  })
+
+  test('applies the resolveUser mapping (registration / impersonation)', async () => {
+    const kp = makeFixtureKeyPair(SUPERVISOR)
+    const record: TrustedRecord = { id: kp.exportAddress(), name: SUPERVISOR, credential: kp.exportPublic(), scopes: ['*'] }
+    const context = makeStubContext([record])
+
+    const plugin = makeSupervisorPlugin(context, {
+      supervisors: [SUPERVISOR],
+      allowRegistration: true,
+      resolveUser: async (userId) => ({ userId: 'internal-id', profileId: 'profile-1', entityId: 'entity-1', scopes: ['project'] })
+    })
+
+    const challenge = 'challenge-' + Date.now()
+    const userId = 'someone@example.com'
+    const credential = baseCredential(challenge, userId, await signCredential(kp, challenge, userId, 'salt-2'))
+
+    await plugin.authenticate(credential)
+
+    expect(credential.userId).toBe('internal-id')
+    expect(credential.profileId).toBe('profile-1')
+    expect(credential.entityId).toBe('entity-1')
+    expect(credential.scopes).toEqual(['project'])
+  })
+
+  test('rejects a signature from a non-allowlisted key', async () => {
+    const supervisorKp = makeFixtureKeyPair(SUPERVISOR)
+    const attackerKp = makeFixtureKeyPair('attacker')
+    const record: TrustedRecord = { id: supervisorKp.exportAddress(), name: SUPERVISOR, credential: supervisorKp.exportPublic(), scopes: ['*'] }
+    const context = makeStubContext([record])
+
+    const plugin = makeSupervisorPlugin(context, { supervisors: [SUPERVISOR], allowRegistration: true })
+
+    const challenge = 'challenge-' + Date.now()
+    const userId = 'victim@example.com'
+    const credential = baseCredential(challenge, userId, await signCredential(attackerKp, challenge, userId, 'salt-3'))
+
+    await expect(plugin.authenticate(credential)).rejects.toThrow()
+  })
+
+  test('rejects a signature bound to a different challenge (replay protection)', async () => {
+    const kp = makeFixtureKeyPair(SUPERVISOR)
+    const record: TrustedRecord = { id: kp.exportAddress(), name: SUPERVISOR, credential: kp.exportPublic(), scopes: ['*'] }
+    const context = makeStubContext([record])
+
+    const plugin = makeSupervisorPlugin(context, { supervisors: [SUPERVISOR], allowRegistration: true })
+
+    const userId = 'user@example.com'
+    // signature made for one challenge, presented with another
+    const credentialStr = await signCredential(kp, 'original-challenge', userId, 'salt-4')
+    const credential = baseCredential('different-challenge', userId, credentialStr)
+
+    await expect(plugin.authenticate(credential)).rejects.toThrow()
+  })
+})