@owlmeans/server-auth-otp 0.1.17 → 0.1.18-rc.1

package/README.md

@@ -4,9 +4,9 @@ Email OTP `AuthPlugin` for OwlMeans servers — passwordless login via time-limi
 
 ## Overview
 
-- `makeOtpPlugin(context)` — factory for the `AuthPlugin` that handles `OTP_AUTH_TYPE` authentication requests
-- `OtpService` — issues email challenges and verifies submitted codes; backed by `@owlmeans/auth-otp`
-- Integrates with `@owlmeans/server-auth` plugin registry — plugs in alongside other auth strategies
+- `appendOtpPlugin(context)` — registers the `AuthPlugin` that handles `OTP_AUTH_TYPE` (`'email-otp'`) authentication requests
+- `makeOtpService(alias?)` — issues email challenges and verifies submitted codes; backed by `@owlmeans/auth-otp`
+- Integrates with the `@owlmeans/server-auth` plugin registry — plugs in alongside other auth strategies
 - Resolves identities through `@owlmeans/server-auth-identity` after OTP verification
 
 ## Installation
@@ -18,14 +18,26 @@ bun add @owlmeans/server-auth-otp
 ## Usage
 
 ```typescript
-import { makeOtpPlugin, OTP_SERVICE } from '@owlmeans/server-auth-otp'
-import { registerPlugin } from '@owlmeans/server-auth/manager/plugins'
+import { makeRedisResource } from '@owlmeans/redis-resource'
+import { OTP_RESOURCE, OTP_SERVICE } from '@owlmeans/auth-otp'
+import { appendOtpPlugin, makeOtpService } from '@owlmeans/server-auth-otp'
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeSmtpMailerService } from '@owlmeans/mailer-smtp'
 
-// Register in a server context that already has an OtpService wired
-registerPlugin(context, makeOtpPlugin(context))
+context.registerResource(makeRedisResource(OTP_RESOURCE))   // challenge store
+context.registerService(makeSmtpMailerService(MAILER_SERVICE))
+context.registerService(makeOtpService(OTP_SERVICE))
+
+appendOtpPlugin(context)   // registers the plugin factory under 'email-otp'
 ```
 
-The OTP service must be backed by a transport (e.g. `@owlmeans/mailer` → `@owlmeans/server-mailer-mailgun`) that can deliver the one-time code.
+`appendOtpPlugin` writes into a module-level registry, so it is a global side effect: the
+`context` it takes is only returned for chaining, and the plugin factory receives the live
+context per request.
+
+The OTP service must be backed by a transport that can deliver the one-time code —
+`@owlmeans/mailer-smtp` (SMTP) or `@owlmeans/server-mailer-mailgun` (Mailgun HTTP API),
+registered under `MAILER_SERVICE`. Override the alias with `cfg.otp.mailerAlias`.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-auth-otp",
-  "version": "0.1.17",
-  "generatedAt": "2026-08-15T13:01:19.932Z",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-08-16T22:20:50.506Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/build/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AA6DvD,sGAAsG;AACtG,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,KAAG,CAG1F,CAAA"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAmEvD,sGAAsG;AACtG,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,KAAG,CAG1F,CAAA"}

package/build/plugin.js

@@ -2,6 +2,9 @@ import { ALL_SCOPES, AuthenFailed, AuthRole, AuthenticationType } from '@owlmean
 import { registerPlugin } from '@owlmeans/server-auth/manager/plugins';
 import { OTP_AUTH_TYPE, OTP_SERVICE } from '@owlmeans/auth-otp';
 import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity';
+import { createIdOfLength, IdStyle } from '@owlmeans/basic-ids';
+// Separates the email from the per-request nonce inside the challenge (see init() below).
+const CHALLENGE_DELIMITER = '::';
 /** Factory that creates the email-OTP AuthPlugin bound to the given context. */
 const otpPlugin = (context) => ({
     type: OTP_AUTH_TYPE,
@@ -12,12 +15,15 @@ const otpPlugin = (context) => ({
         const email = request.userId.trim().toLowerCase();
         const otp = context.service(OTP_SERVICE);
         await otp.issueChallenge(email);
-        // Store the email in the challenge so the envelope preserves it for authenticate.
-        return { challenge: email };
+        // The auth manager's anti-replay cache (AUTH_CACHE) keys on this decoded challenge, so it
+        // must be unique per request — the plaintext email alone would be identical across every
+        // independent login attempt for that address and collide with a still-cached prior one.
+        const nonce = createIdOfLength(16, IdStyle.Base58);
+        return { challenge: `${email}${CHALLENGE_DELIMITER}${nonce}` };
     },
     authenticate: async (credential) => {
-        // credential.challenge is the email (opened from the signed envelope in makeAuthModel).
-        const email = credential.challenge;
+        // credential.challenge is "email::nonce" (opened from the signed envelope in makeAuthModel).
+        const email = credential.challenge?.split(CHALLENGE_DELIMITER)[0];
         const code = credential.credential;
         if (!email || !email.includes('@')) {
             throw new AuthenFailed('otp:email');

package/build/plugin.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-auth-otp",
-  "version": "0.1.17",
+  "version": "0.1.18-rc.1",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,17 +22,17 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.17",
-    "@owlmeans/auth-otp": "^0.1.17",
-    "@owlmeans/basic-ids": "^0.1.17",
-    "@owlmeans/context": "^0.1.17",
-    "@owlmeans/mailer": "^0.1.17",
-    "@owlmeans/oidc": "^0.1.17",
-    "@owlmeans/redis-resource": "^0.1.17",
-    "@owlmeans/resource": "^0.1.17",
-    "@owlmeans/server-auth": "^0.1.17",
-    "@owlmeans/server-auth-identity": "^0.1.17",
-    "@owlmeans/server-context": "^0.1.17"
+    "@owlmeans/auth": "^0.1.18-rc.1",
+    "@owlmeans/auth-otp": "^0.1.18-rc.1",
+    "@owlmeans/basic-ids": "^0.1.18-rc.1",
+    "@owlmeans/context": "^0.1.18-rc.1",
+    "@owlmeans/mailer": "^0.1.18-rc.1",
+    "@owlmeans/oidc": "^0.1.18-rc.1",
+    "@owlmeans/redis-resource": "^0.1.18-rc.1",
+    "@owlmeans/resource": "^0.1.18-rc.1",
+    "@owlmeans/server-auth": "^0.1.18-rc.1",
+    "@owlmeans/server-auth-identity": "^0.1.18-rc.1",
+    "@owlmeans/server-context": "^0.1.18-rc.1"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/plugin.ts

@@ -5,8 +5,12 @@ import type { OtpService } from '@owlmeans/auth-otp'
 import { OTP_AUTH_TYPE, OTP_SERVICE } from '@owlmeans/auth-otp'
 import type { IdentityLinkingService } from '@owlmeans/server-auth-identity'
 import { AUTH_IDENTITY_LINKING } from '@owlmeans/server-auth-identity'
+import { createIdOfLength, IdStyle } from '@owlmeans/basic-ids'
 import type { OtpConfig, OtpContext } from './types.js'
 
+// Separates the email from the per-request nonce inside the challenge (see init() below).
+const CHALLENGE_DELIMITER = '::'
+
 /** Factory that creates the email-OTP AuthPlugin bound to the given context. */
 const otpPlugin = <C extends OtpConfig, T extends OtpContext<C>>(context: T): AuthPlugin => ({
   type: OTP_AUTH_TYPE,
@@ -18,13 +22,16 @@ const otpPlugin = <C extends OtpConfig, T extends OtpContext<C>>(context: T): Au
     const email = request.userId.trim().toLowerCase()
     const otp = context.service<OtpService>(OTP_SERVICE)
     await otp.issueChallenge(email)
-    // Store the email in the challenge so the envelope preserves it for authenticate.
-    return { challenge: email }
+    // The auth manager's anti-replay cache (AUTH_CACHE) keys on this decoded challenge, so it
+    // must be unique per request — the plaintext email alone would be identical across every
+    // independent login attempt for that address and collide with a still-cached prior one.
+    const nonce = createIdOfLength(16, IdStyle.Base58)
+    return { challenge: `${email}${CHALLENGE_DELIMITER}${nonce}` }
   },
 
   authenticate: async credential => {
-    // credential.challenge is the email (opened from the signed envelope in makeAuthModel).
-    const email = credential.challenge
+    // credential.challenge is "email::nonce" (opened from the signed envelope in makeAuthModel).
+    const email = credential.challenge?.split(CHALLENGE_DELIMITER)[0]
     const code = credential.credential
 
     if (!email || !email.includes('@')) {