@owlmeans/auth-otp 0.1.18 → 0.1.19

package/README.md

@@ -11,7 +11,7 @@ stores, throttles and the auth plugin.
 ## Installation
 
 ```bash
-bun add @owlmeans/auth-otp@^0.1.18
+bun add @owlmeans/auth-otp@^0.1.19
 ```
 
 ## Concepts
@@ -23,6 +23,12 @@ bun add @owlmeans/auth-otp@^0.1.18
   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.
+- **Message** — `issueChallenge(email, { message })` mails an `OtpMessage` (`subject`, `text`,
+  `html` templates with `{{code}}` and `{{minutes}}` placeholders) instead of the default English
+  mail, e.g. a localized one; without it the default mail is sent unchanged.
+- **Rewrite seam** — the optional `rewriteChallenge(email, issuanceId, code)` replaces the code of a
+  pending issuance for developer tooling (lifetime kept, failed attempts reset); it answers `false`
+  for a gone issuance, another address or a code that is not `OTP_CODE_LENGTH` digits.
 - **Attempt limit** — a challenge is invalidated on its `OTP_MAX_FAILED_ATTEMPTS`-th (fifth) failed
   guess.
 
@@ -62,8 +68,11 @@ await otpService(ctx).verifyChallenge('user@example.com', issuanceId, '123456')
 | 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.issueChallenge(email, opts?)` | method | `→ Promise<string>` — generate, persist with TTL, email (`opts.message` overrides the mail); returns the opaque issuance id |
 | `OtpService.verifyChallenge(email, issuanceId, code)` | method | `→ Promise<void>` — verify and atomically consume one issuance |
+| `OtpService.rewriteChallenge?(email, issuanceId, code)` | optional method | `→ Promise<boolean>` — developer seam: replace a pending code, keep its TTL, reset attempts |
+| `OtpMessage` | interface | `{ subject, text, html }` templates; `{{code}}` and `{{minutes}}` are substituted |
+| `OtpIssueOptions` | interface | `{ message?: OtpMessage }` |
 
 ### Constants
 
@@ -76,7 +85,7 @@ await otpService(ctx).verifyChallenge('user@example.com', issuanceId, '123456')
 | `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
+The barrel exports only these string and number constants plus the types; the package tests pin every
 value, because changing one changes what server and clients agree on.
 
 ## Common pitfalls

package/build/types.d.ts

@@ -1,9 +1,28 @@
 import type { InitializedService } from '@owlmeans/context';
+/**
+ * The mail a login code travels in, as templates: every part may carry `{{code}}` (the code) and
+ * `{{minutes}}` (its lifetime in minutes), substituted at issuance.
+ */
+export interface OtpMessage {
+    subject: string;
+    text: string;
+    html: string;
+}
+export interface OtpIssueOptions {
+    /** Replaces the default English login-code mail; omitted keeps it. */
+    message?: OtpMessage;
+}
 /** 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, email it, and return its opaque issuance id. */
-    issueChallenge: (email: string) => Promise<string>;
+    issueChallenge: (email: string, opts?: OtpIssueOptions) => Promise<string>;
     /** Verify and atomically consume one issuance. */
     verifyChallenge: (email: string, issuanceId: string, code: string) => Promise<void>;
+    /**
+     * Developer seam: replace the code of a pending issuance, keeping its lifetime and resetting its
+     * failed attempts. `false` when the issuance is gone, names another address, the code is not
+     * `OTP_CODE_LENGTH` digits, or the store cannot rewrite. Never expose it to the public.
+     */
+    rewriteChallenge?: (email: string, issuanceId: string, code: string) => Promise<boolean>;
 }
 //# 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,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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,kGAAkG;AAClG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,yFAAyF;IACzF,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1E,kDAAkD;IAClD,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzF"}

package/package.json

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

package/src/types.ts

@@ -1,9 +1,30 @@
 import type { InitializedService } from '@owlmeans/context'
 
+/**
+ * The mail a login code travels in, as templates: every part may carry `{{code}}` (the code) and
+ * `{{minutes}}` (its lifetime in minutes), substituted at issuance.
+ */
+export interface OtpMessage {
+  subject: string
+  text: string
+  html: string
+}
+
+export interface OtpIssueOptions {
+  /** Replaces the default English login-code mail; omitted keeps it. */
+  message?: OtpMessage
+}
+
 /** 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, email it, and return its opaque issuance id. */
-  issueChallenge: (email: string) => Promise<string>
+  issueChallenge: (email: string, opts?: OtpIssueOptions) => Promise<string>
   /** Verify and atomically consume one issuance. */
   verifyChallenge: (email: string, issuanceId: string, code: string) => Promise<void>
+  /**
+   * Developer seam: replace the code of a pending issuance, keeping its lifetime and resetting its
+   * failed attempts. `false` when the issuance is gone, names another address, the code is not
+   * `OTP_CODE_LENGTH` digits, or the store cannot rewrite. Never expose it to the public.
+   */
+  rewriteChallenge?: (email: string, issuanceId: string, code: string) => Promise<boolean>
 }

package/tests/contract.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, expectTypeOf, test } from 'bun:test'
 import * as otp from '../src/index.js'
-import type { OtpService } from '../src/index.js'
+import type { OtpIssueOptions, OtpService } from '../src/index.js'
 
 /**
  * This package is the contract between the OTP server (`@owlmeans/server-auth-otp`) and the clients
@@ -27,9 +27,14 @@ describe('@owlmeans/auth-otp — the shared contract', () => {
   })
 
   test('the service issues an opaque id and verifies by email, id and code', () => {
-    expectTypeOf<OtpService['issueChallenge']>().parameters.toEqualTypeOf<[string]>()
+    expectTypeOf<OtpService['issueChallenge']>().parameters.toEqualTypeOf<[string, OtpIssueOptions?]>()
     expectTypeOf<OtpService['issueChallenge']>().returns.toEqualTypeOf<Promise<string>>()
     expectTypeOf<OtpService['verifyChallenge']>().parameters.toEqualTypeOf<[string, string, string]>()
     expectTypeOf<OtpService['verifyChallenge']>().returns.toEqualTypeOf<Promise<void>>()
   })
+
+  test('the optional developer seam rewrites a pending code by email, id and code', () => {
+    expectTypeOf<NonNullable<OtpService['rewriteChallenge']>>().parameters.toEqualTypeOf<[string, string, string]>()
+    expectTypeOf<NonNullable<OtpService['rewriteChallenge']>>().returns.toEqualTypeOf<Promise<boolean>>()
+  })
 })