@owlmeans/server-auth-otp 0.1.7 → 0.1.8

package/README.md

@@ -0,0 +1,45 @@
+# @owlmeans/server-auth-otp
+
+Email OTP `AuthPlugin` for OwlMeans servers — passwordless login via time-limited one-time codes.
+
+## 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
+- Resolves identities through `@owlmeans/server-auth-identity` after OTP verification
+
+## Installation
+
+```bash
+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'
+
+// Register in a server context that already has an OtpService wired
+registerPlugin(context, makeOtpPlugin(context))
+```
+
+The OTP service must be backed by a transport (e.g. `@owlmeans/mailer` → `@owlmeans/server-mailer-mailgun`) that can deliver the one-time code.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

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

@@ -0,0 +1,83 @@
+---
+description: "How to use @owlmeans/server-auth-otp — email OTP AuthPlugin and OtpService. Use when wiring passwordless email login in an OwlMeans server context."
+applyTo: "**/context.ts, **/app/auth/*, **/services/otp*"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Using `@owlmeans/server-auth-otp`
+
+Email OTP authentication plugin for the OwlMeans auth-manager plugin system. Relies on `@owlmeans/auth-otp` for the OTP service interface, a Redis resource for code storage, and a `MailerService` to send codes.
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `makeOtpService(alias?)` | fn | Service factory — stores/verifies OTP codes |
+| `appendOtpPlugin(context)` | fn | Registers the OTP `AuthPlugin` into the server-auth plugin registry |
+| `OTP_AUTH_TYPE` | const | `'email-otp'` — the auth type string to pass in `init` requests |
+| `OTP_RESOURCE` | const | Redis resource alias for code storage |
+| `OTP_TTL_SECONDS` | const | Code TTL (600 s = 10 min) |
+| `OTP_CODE_LENGTH` | const | 6 |
+
+## Registration requirements
+
+```ts
+import { makeOtpService, appendOtpPlugin, OTP_RESOURCE } from '@owlmeans/server-auth-otp'
+import { makeRedisResource } from '@owlmeans/redis-resource'
+import { makeConsoleMailerService, CONSOLE_MAILER, MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeMailgunMailerService } from '@owlmeans/server-mailer-mailgun'
+
+// 1. Register the Redis code-cache resource.
+context.registerResource(makeRedisResource(OTP_RESOURCE))
+
+// 2. Register a MailerService (console for dev/tests, Mailgun for prod).
+context.registerService(makeConsoleMailerService(MAILER_SERVICE))
+// or:
+context.registerService(makeMailgunMailerService(MAILER_SERVICE))
+
+// 3. Register the OTP service (reads from Redis + Mailer).
+context.registerService(makeOtpService())
+
+// 4. Register the OTP AuthPlugin into the auth-manager plugin registry.
+appendOtpPlugin(context)
+```
+
+## Auth flow
+
+**Init** — client sends `{ type: 'email-otp', userId: 'user@email.com' }`:
+- OTP service generates a 6-digit code, stores it in Redis with 10 min TTL, emails it.
+- Returns `{ challenge: email }` in a signed envelope.
+
+**Authenticate** — client sends `{ challenge: <signed-envelope>, userId: email, credential: '123456', entityId: 'the-entity' }`:
+- Envelope is opened → email is extracted.
+- OTP service verifies the code (throws `AuthenFailed` if wrong or expired), then deletes it.
+- `IdentityLinkingService` finds or creates the user profile scoped to `entityId`.
+- Sets `credential.type = AuthenticationType.OneTimeToken` and returns the signed auth token.
+
+## Config overrides (optional)
+
+Pass `ctx.cfg.otp` to override defaults:
+
+```ts
+cfg.otp = {
+  mailerAlias: 'my-mailer',       // default: MAILER_SERVICE ('mailer-service')
+  resourceAlias: 'my-otp-cache',  // default: OTP_RESOURCE  ('auth-otp-cache')
+  identityAlias: 'my-identity',   // default: AUTH_IDENTITY_LINKING
+}
+```
+
+## Rules
+
+- Always register the Redis resource AND the mailer service BEFORE the OTP service.
+- Call `appendOtpPlugin(context)` once per context — it adds to the shared plugin registry singleton.
+- The `credential.entityId` in the authenticate request determines which entity the resulting identity profile is scoped to. Pass it from the OIDC interaction.
+- Errors from this plugin are `AuthenFailed` (from `@owlmeans/auth`) — callers catch that, not raw `Error`.
+- For tests, use `makeConsoleMailerService()` and read `svc.captured[n].text` to extract the code.
+
+## Related instructions
+
+- `@owlmeans/auth-otp` (common) — `OtpService` interface and constants
+- `@owlmeans/mailer` (common) — `MailerService` interface, console transport
+- `@owlmeans/server-mailer-mailgun` (common) — production Mailgun transport
+- `@owlmeans/server-auth` (common) — auth-manager plugin system
+- `auth-protocol` instructions — error hierarchy, identity read rules

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/server-auth-otp",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.191Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "instruction",
+      "name": "server-auth-otp",
+      "category": "package-specific",
+      "file": "instructions/server-auth-otp.instructions.md",
+      "canonicalPath": ".github/instructions/server-auth-otp.instructions.md"
+    }
+  ]
+}

package/package.json

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