@owlmeans/server-auth-otp 0.1.18-rc.8 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +156 -24
  2. package/agent-meta/manifest.json +3 -3
  3. package/agent-meta/skills/server-auth-otp/SKILL.md +64 -30
  4. package/build/challenge.d.ts +7 -0
  5. package/build/challenge.d.ts.map +1 -0
  6. package/build/challenge.js +77 -0
  7. package/build/challenge.js.map +1 -0
  8. package/build/consts.d.ts +16 -1
  9. package/build/consts.d.ts.map +1 -1
  10. package/build/consts.js +14 -1
  11. package/build/consts.js.map +1 -1
  12. package/build/consts.local.d.ts +4 -0
  13. package/build/consts.local.d.ts.map +1 -0
  14. package/build/consts.local.js +50 -0
  15. package/build/consts.local.js.map +1 -0
  16. package/build/errors.d.ts +18 -0
  17. package/build/errors.d.ts.map +1 -0
  18. package/build/errors.js +32 -0
  19. package/build/errors.js.map +1 -0
  20. package/build/index.d.ts +8 -1
  21. package/build/index.d.ts.map +1 -1
  22. package/build/index.js +6 -0
  23. package/build/index.js.map +1 -1
  24. package/build/keys/types.d.ts +10 -0
  25. package/build/keys/types.d.ts.map +1 -0
  26. package/build/keys/types.js +2 -0
  27. package/build/keys/types.js.map +1 -0
  28. package/build/keys.d.ts +4 -0
  29. package/build/keys.d.ts.map +1 -0
  30. package/build/keys.js +10 -0
  31. package/build/keys.js.map +1 -0
  32. package/build/plugin.d.ts.map +1 -1
  33. package/build/plugin.js +18 -18
  34. package/build/plugin.js.map +1 -1
  35. package/build/service.d.ts +1 -1
  36. package/build/service.d.ts.map +1 -1
  37. package/build/service.js +56 -25
  38. package/build/service.js.map +1 -1
  39. package/build/throttle-keys/types.d.ts +8 -0
  40. package/build/throttle-keys/types.d.ts.map +1 -0
  41. package/build/throttle-keys/types.js +2 -0
  42. package/build/throttle-keys/types.js.map +1 -0
  43. package/build/throttle-keys.d.ts +4 -0
  44. package/build/throttle-keys.d.ts.map +1 -0
  45. package/build/throttle-keys.js +9 -0
  46. package/build/throttle-keys.js.map +1 -0
  47. package/build/throttle.d.ts +11 -0
  48. package/build/throttle.d.ts.map +1 -0
  49. package/build/throttle.js +67 -0
  50. package/build/throttle.js.map +1 -0
  51. package/build/types.d.ts +29 -0
  52. package/build/types.d.ts.map +1 -1
  53. package/build/types.local.d.ts +16 -0
  54. package/build/types.local.d.ts.map +1 -0
  55. package/build/types.local.js +2 -0
  56. package/build/types.local.js.map +1 -0
  57. package/package.json +15 -14
  58. package/src/challenge.ts +86 -0
  59. package/src/consts.local.ts +51 -0
  60. package/src/consts.ts +18 -1
  61. package/src/errors.ts +37 -0
  62. package/src/index.ts +8 -1
  63. package/src/keys/types.ts +9 -0
  64. package/src/keys.ts +16 -0
  65. package/src/plugin.ts +21 -25
  66. package/src/service.ts +68 -41
  67. package/src/throttle-keys/types.ts +7 -0
  68. package/src/throttle-keys.ts +17 -0
  69. package/src/throttle.ts +85 -0
  70. package/src/types.local.ts +10 -0
  71. package/src/types.ts +36 -0
  72. package/tests/context.ts +43 -0
  73. package/tests/keys.spec.ts +23 -0
  74. package/tests/service.spec.ts +88 -0
package/src/types.ts CHANGED
@@ -1,4 +1,34 @@
1
1
  import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
2
+ import type { InitializedService } from '@owlmeans/context'
3
+ import { OtpChallengeOutcome } from './consts.js'
4
+
5
+ export interface ThrottleRule {
6
+ limit: number
7
+ windowSeconds: number
8
+ }
9
+
10
+ export interface ThrottleDecision {
11
+ allowed: boolean
12
+ retryAfter: number
13
+ }
14
+
15
+ /** Generic fixed-subject, sliding-window throttle service for server auth plugins. */
16
+ export interface AuthThrottleService extends InitializedService {
17
+ consume: (key: string, rules: readonly ThrottleRule[], token?: string) => Promise<ThrottleDecision>
18
+ }
19
+
20
+ export interface OtpChallenge {
21
+ id: string
22
+ emailKey: string
23
+ codeHash: string
24
+ }
25
+
26
+ export interface OtpChallengeStore extends InitializedService {
27
+ issue: (challenge: OtpChallenge, ttlSeconds: number) => Promise<boolean>
28
+ verify: (
29
+ id: string, emailKey: string, codeHash: string, maxFailedAttempts: number
30
+ ) => Promise<OtpChallengeOutcome>
31
+ }
2
32
 
3
33
  export interface OtpConfig extends ServerConfig {
4
34
  otp?: {
@@ -6,6 +36,12 @@ export interface OtpConfig extends ServerConfig {
6
36
  mailerAlias?: string
7
37
  /** Alias of the Redis resource for code storage. Defaults to OTP_RESOURCE. */
8
38
  resourceAlias?: string
39
+ /** Alias of an OtpChallengeStore. Defaults to OTP_CHALLENGE_STORE. */
40
+ challengeStoreAlias?: string
41
+ /** Optional AuthThrottleService alias. Omitted means no issuance throttle. */
42
+ throttleAlias?: string
43
+ /** Sliding-window limits applied together by the throttle service. */
44
+ throttleRules?: readonly ThrottleRule[]
9
45
  /** Alias of the IdentityLinkingService. Defaults to AUTH_IDENTITY_LINKING. */
10
46
  identityAlias?: string
11
47
  }
@@ -0,0 +1,43 @@
1
+ import { AppType, makeBasicContext } from '@owlmeans/context'
2
+ import { MAILER_SERVICE, makeConsoleMailerService } from '@owlmeans/mailer'
3
+ import { makeMemoryOtpChallengeStore } from '../src/challenge.js'
4
+ import { makeMemoryThrottleService } from '../src/throttle.js'
5
+ import { makeOtpService } from '../src/service.js'
6
+ import {
7
+ OTP_CHALLENGE_STORE, OTP_EMAIL_THROTTLE_RULES, OTP_THROTTLE_SERVICE,
8
+ } from '../src/consts.js'
9
+ import type { OtpConfig } from '../src/types.js'
10
+
11
+ export const makeOtpTestContext = (opts: { throttle?: boolean, now?: () => number } = {}) => {
12
+ const cfg: OtpConfig = {
13
+ ready: false,
14
+ service: 'server-auth-otp-tests',
15
+ type: AppType.Backend,
16
+ services: {},
17
+ otp: {
18
+ mailerAlias: MAILER_SERVICE,
19
+ challengeStoreAlias: OTP_CHALLENGE_STORE,
20
+ ...(opts.throttle === true ? {
21
+ throttleAlias: OTP_THROTTLE_SERVICE,
22
+ throttleRules: OTP_EMAIL_THROTTLE_RULES,
23
+ } : {}),
24
+ },
25
+ }
26
+ const context = makeBasicContext(cfg)
27
+ const mailer = makeConsoleMailerService(MAILER_SERVICE)
28
+ context.registerService(mailer)
29
+ context.registerService(makeMemoryOtpChallengeStore(OTP_CHALLENGE_STORE, opts.now))
30
+ if (opts.throttle === true) {
31
+ context.registerService(makeMemoryThrottleService(OTP_THROTTLE_SERVICE, opts.now))
32
+ }
33
+ const otp = makeOtpService()
34
+ context.registerService(otp)
35
+
36
+ return { context, mailer, otp }
37
+ }
38
+
39
+ export const codeFrom = (text: string | undefined): string => {
40
+ const match = text?.match(/\b(\d{6})\b/)
41
+ if (match == null) throw new Error('OTP code missing from captured message')
42
+ return match[1]
43
+ }
@@ -0,0 +1,23 @@
1
+ import { describe, expect, test } from 'bun:test'
2
+ import { throttleKeyHelper } from '../src/throttle-keys.js'
3
+ import { otpKeyHelper } from '../src/keys.js'
4
+
5
+ describe('@owlmeans/server-auth-otp — privacy-preserving keys', () => {
6
+ test('normalizes email case without storing the raw address', () => {
7
+ const lower = throttleKeyHelper.emailThrottleKey('person@example.com')
8
+ expect(throttleKeyHelper.emailThrottleKey(' PERSON@EXAMPLE.COM ')).toBe(lower)
9
+ expect(lower).not.toContain('person')
10
+ expect(otpKeyHelper.otpEmailKey('person@example.com')).not.toContain('person')
11
+ })
12
+
13
+ test('does not collapse punctuation the old lossy key strategy discarded', () => {
14
+ expect(throttleKeyHelper.emailThrottleKey('a+b@example.com')).not.toBe(throttleKeyHelper.emailThrottleKey('a_b@example.com'))
15
+ })
16
+
17
+ test('namespaces IP and email digests independently and keeps the IP non-raw', () => {
18
+ const ip = throttleKeyHelper.ipThrottleKey('203.0.113.7')
19
+ expect(ip).toStartWith('ip:')
20
+ expect(ip).not.toContain('203.0.113.7')
21
+ expect(ip).not.toBe(throttleKeyHelper.emailThrottleKey('203.0.113.7'))
22
+ })
23
+ })
@@ -0,0 +1,88 @@
1
+ import { describe, expect, test } from 'bun:test'
2
+ import { AuthenFailed } from '@owlmeans/auth'
3
+ import { OtpThrottled } from '../src/errors.js'
4
+ import { codeFrom, makeOtpTestContext } from './context.js'
5
+
6
+ const wrongFor = (code: string): string => code === '000000' ? '999999' : '000000'
7
+
8
+ describe('@owlmeans/server-auth-otp — challenge lifecycle', () => {
9
+ test('issues cryptographic-looking codes under independent opaque issuance ids', async () => {
10
+ const { context, mailer, otp } = makeOtpTestContext()
11
+ await context.configure().init()
12
+
13
+ const first = await otp.issueChallenge('Alice+one@example.com')
14
+ const second = await otp.issueChallenge('alice+one@example.com')
15
+ const firstCode = codeFrom(mailer.captured[0].text)
16
+ const secondCode = codeFrom(mailer.captured[1].text)
17
+
18
+ expect(first).toMatch(/^[A-Za-z0-9_-]{24}$/)
19
+ expect(second).not.toBe(first)
20
+ expect(firstCode).toMatch(/^\d{6}$/)
21
+ expect(secondCode).toMatch(/^\d{6}$/)
22
+ await otp.verifyChallenge('alice+one@example.com', first, firstCode)
23
+ await otp.verifyChallenge('alice+one@example.com', second, secondCode)
24
+ })
25
+
26
+ test('allows four failed guesses and consumes the challenge on a correct fifth try', async () => {
27
+ const { context, mailer, otp } = makeOtpTestContext()
28
+ await context.configure().init()
29
+ const issuanceId = await otp.issueChallenge('four@example.com')
30
+ const code = codeFrom(mailer.captured[0].text)
31
+
32
+ for (let attempt = 0; attempt < 4; attempt += 1) {
33
+ await expect(otp.verifyChallenge('four@example.com', issuanceId, wrongFor(code)))
34
+ .rejects.toBeInstanceOf(AuthenFailed)
35
+ }
36
+ await expect(otp.verifyChallenge('four@example.com', issuanceId, code)).resolves.toBeUndefined()
37
+ })
38
+
39
+ test('invalidates the challenge on exactly the fifth failed guess', async () => {
40
+ const { context, mailer, otp } = makeOtpTestContext()
41
+ await context.configure().init()
42
+ const issuanceId = await otp.issueChallenge('five@example.com')
43
+ const code = codeFrom(mailer.captured[0].text)
44
+
45
+ for (let attempt = 0; attempt < 5; attempt += 1) {
46
+ await expect(otp.verifyChallenge('five@example.com', issuanceId, wrongFor(code)))
47
+ .rejects.toBeInstanceOf(AuthenFailed)
48
+ }
49
+ await expect(otp.verifyChallenge('five@example.com', issuanceId, code))
50
+ .rejects.toBeInstanceOf(AuthenFailed)
51
+ })
52
+
53
+ test('only one concurrent correct verification consumes an issuance', async () => {
54
+ const { context, mailer, otp } = makeOtpTestContext()
55
+ await context.configure().init()
56
+ const issuanceId = await otp.issueChallenge('replay@example.com')
57
+ const code = codeFrom(mailer.captured[0].text)
58
+
59
+ const results = await Promise.allSettled([
60
+ otp.verifyChallenge('replay@example.com', issuanceId, code),
61
+ otp.verifyChallenge('replay@example.com', issuanceId, code),
62
+ ])
63
+ expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1)
64
+ expect(results.filter(result => result.status === 'rejected')).toHaveLength(1)
65
+ })
66
+ })
67
+
68
+ describe('@owlmeans/server-auth-otp — issuance throttle', () => {
69
+ test('enforces one per minute and ten per hour with retry metadata', async () => {
70
+ let now = 0
71
+ const fixture = makeOtpTestContext({ throttle: true, now: () => now })
72
+ await fixture.context.configure().init()
73
+
74
+ await fixture.otp.issueChallenge('rate@example.com')
75
+ const minute = await fixture.otp.issueChallenge('RATE@example.com').catch(error => error)
76
+ expect(minute).toBeInstanceOf(OtpThrottled)
77
+ expect((minute as OtpThrottled).retryAfter).toBe(60)
78
+
79
+ for (let issued = 1; issued < 10; issued += 1) {
80
+ now += 61_000
81
+ await fixture.otp.issueChallenge('rate@example.com')
82
+ }
83
+ now += 61_000
84
+ const hour = await fixture.otp.issueChallenge('rate@example.com').catch(error => error)
85
+ expect(hour).toBeInstanceOf(OtpThrottled)
86
+ expect((hour as OtpThrottled).retryAfter).toBeGreaterThan(0)
87
+ })
88
+ })