@owlmeans/auth-otp 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -0,0 +1,100 @@
+# @owlmeans/auth-otp
+
+The shared contract of OwlMeans passwordless email login: the `OtpService` interface and the
+constants both sides of an email-OTP flow agree on — the service alias, the auth type a client
+selects, the code-store alias, the code length, its lifetime and the failed-attempt limit. A shared
+(common) package depends on it when it must name the `'email-otp'` auth type or type the service. It
+contains no runtime code beyond those constants: it generates, stores and mails nothing. A server
+wires the actual flow with `@owlmeans/server-auth-otp`, which implements `OtpService`, the challenge
+stores, throttles and the auth plugin.
+
+## Installation
+
+```bash
+bun add @owlmeans/auth-otp@^0.1.18
+```
+
+## Concepts
+
+- **Contracts half** — this package is the producer/consumer contract; `@owlmeans/server-auth-otp`
+  is the implementation. A new constant or method signature is added here, never only in the
+  implementation.
+- **Challenge** — one issuance of a code. `issueChallenge(email)` generates a code, persists it with
+  a TTL, mails it and returns an **opaque issuance id** that contains neither the email nor the code.
+- **Verification** — `verifyChallenge(email, issuanceId, code)` checks and atomically consumes that
+  exact issuance; it resolves on success and throws otherwise.
+- **Attempt limit** — a challenge is invalidated on its `OTP_MAX_FAILED_ATTEMPTS`-th (fifth) failed
+  guess.
+
+## Usage
+
+### Select the email-OTP auth type on a client
+
+A client names the plugin by its auth type when it starts an authentication; the constant keeps the
+string identical on both sides.
+
+```typescript
+import { OTP_AUTH_TYPE, OTP_CODE_LENGTH } from '@owlmeans/auth-otp'
+
+const init = { type: OTP_AUTH_TYPE, userId: email }  // 'email-otp'
+
+const isComplete = (code: string) => code.length === OTP_CODE_LENGTH && /^\d+$/.test(code)
+```
+
+### Type the service in shared code
+
+```typescript
+import type { BasicContext, BasicConfig } from '@owlmeans/context'
+import { OTP_SERVICE } from '@owlmeans/auth-otp'
+import type { OtpService } from '@owlmeans/auth-otp'
+
+export const otpService = (ctx: BasicContext<BasicConfig>) => ctx.service<OtpService>(OTP_SERVICE)
+
+// server side, after @owlmeans/server-auth-otp registered the implementation
+const issuanceId = await otpService(ctx).issueChallenge('user@example.com')
+await otpService(ctx).verifyChallenge('user@example.com', issuanceId, '123456')
+```
+
+## API
+
+### Types
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `OtpService` | interface | extends `InitializedService` (`@owlmeans/context`) |
+| `OtpService.issueChallenge(email)` | method | `→ Promise<string>` — generate, persist with TTL, email; returns the opaque issuance id |
+| `OtpService.verifyChallenge(email, issuanceId, code)` | method | `→ Promise<void>` — verify and atomically consume one issuance |
+
+### Constants
+
+| Symbol | Value | Purpose |
+|---|---|---|
+| `OTP_SERVICE` | `'auth-otp-service'` | service alias the implementation registers under |
+| `OTP_AUTH_TYPE` | `'email-otp'` | auth plugin type string a client sends |
+| `OTP_RESOURCE` | `'auth-otp-cache'` | resource alias for pending codes |
+| `OTP_TTL_SECONDS` | `600` | code lifetime (10 minutes) |
+| `OTP_CODE_LENGTH` | `6` | numeric digits per code |
+| `OTP_MAX_FAILED_ATTEMPTS` | `5` | a challenge is invalidated on its fifth failed guess |
+
+The barrel exports only these string and number constants plus the type; the package tests pin every
+value, because changing one changes what server and clients agree on.
+
+## Common pitfalls
+
+- Do not import this package expecting an implementation — `makeOtpService`, `appendOtpPlugin` and
+  the stores live in `@owlmeans/server-auth-otp`.
+- Never encode the email or the code into the issuance id; it stays opaque and owned by the OTP
+  store, which counts attempts and consumes it.
+- Do not hard-code `'email-otp'` or `6` in clients — import `OTP_AUTH_TYPE` and `OTP_CODE_LENGTH`.
+- Depend on `@owlmeans/server-auth-otp` only where the server wires itself up; shared packages depend
+  on this one.
+
+The `server-auth-otp` skill covers this package together with its implementation: registration
+order, the auth flow, config overrides and throttling.
+
+## Related packages
+
+- [`@owlmeans/server-auth-otp`](../server-auth-otp) — the `OtpService` implementation, challenge stores, throttles and the `AuthPlugin`
+- [`@owlmeans/context`](../context) — `InitializedService`, the base of `OtpService`
+- [`@owlmeans/auth`](../auth) — the auth payload and credential types the OTP flow produces
+- [`@owlmeans/mailer`](../mailer) — the `MailerService` that delivers the codes

package/build/consts.d.ts

@@ -7,4 +7,6 @@ export declare const OTP_RESOURCE = "auth-otp-cache";
 export declare const OTP_TTL_SECONDS = 600;
 /** OTP code length (numeric digits) */
 export declare const OTP_CODE_LENGTH = 6;
+/** A challenge is invalidated on its fifth failed guess. */
+export declare const OTP_MAX_FAILED_ATTEMPTS = 5;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,qBAAqB,CAAA;AAE7C,yEAAyE;AACzE,eAAO,MAAM,aAAa,cAAc,CAAA;AAExC,yDAAyD;AACzD,eAAO,MAAM,YAAY,mBAAmB,CAAA;AAE5C,uCAAuC;AACvC,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,uCAAuC;AACvC,eAAO,MAAM,eAAe,IAAI,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,qBAAqB,CAAA;AAE7C,yEAAyE;AACzE,eAAO,MAAM,aAAa,cAAc,CAAA;AAExC,yDAAyD;AACzD,eAAO,MAAM,YAAY,mBAAmB,CAAA;AAE5C,uCAAuC;AACvC,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,uCAAuC;AACvC,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,IAAI,CAAA"}

package/build/consts.js

@@ -7,4 +7,6 @@ export const OTP_RESOURCE = 'auth-otp-cache';
 export const OTP_TTL_SECONDS = 600;
 /** OTP code length (numeric digits) */
 export const OTP_CODE_LENGTH = 6;
+/** A challenge is invalidated on its fifth failed guess. */
+export const OTP_MAX_FAILED_ATTEMPTS = 5;
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,kBAAkB,CAAA;AAE7C,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AAExC,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAA;AAE5C,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;AAElC,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,kBAAkB,CAAA;AAE7C,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AAExC,yDAAyD;AACzD,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAA;AAE5C,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;AAElC,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAA;AAEhC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA"}

package/build/types.d.ts

@@ -1,9 +1,9 @@
 import type { InitializedService } from '@owlmeans/context';
 /** Passwordless email OTP service — generates, stores, and verifies short-lived one-time codes */
 export interface OtpService extends InitializedService {
-    /** Generate a code, persist it with TTL, and email it to the user. */
-    issueChallenge: (email: string) => Promise<void>;
-    /** Verify and consume the code. Throws OtpInvalidError if the code is wrong or expired. */
-    verifyChallenge: (email: string, code: string) => Promise<void>;
+    /** Generate a code, persist it with TTL, email it, and return its opaque issuance id. */
+    issueChallenge: (email: string) => Promise<string>;
+    /** Verify and atomically consume one issuance. */
+    verifyChallenge: (email: string, issuanceId: string, code: string) => Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,kGAAkG;AAClG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,sEAAsE;IACtE,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,2FAA2F;IAC3F,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAChE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,kGAAkG;AAClG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,yFAAyF;IACzF,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClD,kDAAkD;IAClD,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/auth-otp",
-  "version": "0.1.18-rc.9",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,12 +22,12 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.9",
-    "@owlmeans/error": "^0.1.18-rc.9"
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/error": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/bun": "^1.4.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/bun": "^1.4.2",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.ts

@@ -11,3 +11,6 @@ export const OTP_TTL_SECONDS = 600
 
 /** OTP code length (numeric digits) */
 export const OTP_CODE_LENGTH = 6
+
+/** A challenge is invalidated on its fifth failed guess. */
+export const OTP_MAX_FAILED_ATTEMPTS = 5

package/src/types.ts

@@ -2,8 +2,8 @@ import type { InitializedService } from '@owlmeans/context'
 
 /** Passwordless email OTP service — generates, stores, and verifies short-lived one-time codes */
 export interface OtpService extends InitializedService {
-  /** Generate a code, persist it with TTL, and email it to the user. */
-  issueChallenge: (email: string) => Promise<void>
-  /** Verify and consume the code. Throws OtpInvalidError if the code is wrong or expired. */
-  verifyChallenge: (email: string, code: string) => Promise<void>
+  /** Generate a code, persist it with TTL, email it, and return its opaque issuance id. */
+  issueChallenge: (email: string) => Promise<string>
+  /** Verify and atomically consume one issuance. */
+  verifyChallenge: (email: string, issuanceId: string, code: string) => Promise<void>
 }

package/tests/contract.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, expectTypeOf, test } from 'bun:test'
+import * as otp from '../src/index.js'
+import type { OtpService } from '../src/index.js'
+
+/**
+ * This package is the contract between the OTP server (`@owlmeans/server-auth-otp`) and the clients
+ * that select it: a value changed here changes what both sides agree on, so each one is pinned.
+ */
+describe('@owlmeans/auth-otp — the shared contract', () => {
+  test('names the service, the auth type and the code store', () => {
+    expect(otp.OTP_SERVICE).toBe('auth-otp-service')
+    expect(otp.OTP_AUTH_TYPE).toBe('email-otp')
+    expect(otp.OTP_RESOURCE).toBe('auth-otp-cache')
+  })
+
+  test('a code is six digits, lives ten minutes and survives four wrong guesses', () => {
+    expect(otp.OTP_CODE_LENGTH).toBe(6)
+    expect(otp.OTP_TTL_SECONDS).toBe(600)
+    expect(otp.OTP_MAX_FAILED_ATTEMPTS).toBe(5)
+  })
+
+  test('the barrel exports constants only — no runtime code to drift', () => {
+    expect(Object.keys(otp).sort()).toEqual([
+      'OTP_AUTH_TYPE', 'OTP_CODE_LENGTH', 'OTP_MAX_FAILED_ATTEMPTS', 'OTP_RESOURCE', 'OTP_SERVICE', 'OTP_TTL_SECONDS',
+    ])
+    expect(Object.values(otp).every(value => typeof value === 'string' || typeof value === 'number')).toBe(true)
+  })
+
+  test('the service issues an opaque id and verifies by email, id and code', () => {
+    expectTypeOf<OtpService['issueChallenge']>().parameters.toEqualTypeOf<[string]>()
+    expectTypeOf<OtpService['issueChallenge']>().returns.toEqualTypeOf<Promise<string>>()
+    expectTypeOf<OtpService['verifyChallenge']>().parameters.toEqualTypeOf<[string, string, string]>()
+    expectTypeOf<OtpService['verifyChallenge']>().returns.toEqualTypeOf<Promise<void>>()
+  })
+})