nucleus-core-ts 0.10.231 → 0.10.232

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.
@@ -425,11 +425,13 @@ export type CaptchaValidatePayload = {
425
425
  challengeId: string;
426
426
  answer: string;
427
427
  };
428
- export type CaptchaValidateResponse = StandardReturn<{
428
+ /** `POST /auth/captcha/validate` answers the service result as it is (HTTP 400 when not valid), not under `data`. */
429
+ export type CaptchaValidateResponse = {
430
+ success: boolean;
429
431
  valid: boolean;
430
432
  message?: string;
431
433
  attemptsRemaining?: number;
432
- }>;
434
+ };
433
435
  export type AuthFeatureConfig = {
434
436
  route?: string;
435
437
  isPublic?: boolean;
@@ -1,4 +1,6 @@
1
1
  import type { NucleusEmail } from 'src/Services/Email/directSendTypes';
2
+ import type { NucleusCaptcha } from 'src/Services/Captcha/runtimeCaptchaTypes';
3
+ import type { CaptchaService } from 'src/Services/Captcha';
2
4
  import type { EmailPayload, EmailSendResult, EmailService } from 'src/Services/Email/types';
3
5
  import { type Logger } from 'src/Services/Logger';
4
6
  import type { NotificationDeliveryReport, NotificationService, SendNotificationOptions, SendNotificationParams } from 'src/Services/Notification';
@@ -57,6 +59,12 @@ export type NucleusRuntime = {
57
59
  * only; the log carries the address redacted. See the nucleus-email skill.
58
60
  */
59
61
  email: NucleusEmail;
62
+ /**
63
+ * Validate a captcha answer in-process, from a route or from a job (`server.runtime.captcha`): single-use
64
+ * like `POST /auth/captcha/validate`, typed result `{ ok: true } | { ok: false, code }`. `enabled()` says
65
+ * whether a public form should ask for a challenge. See the nucleus-authentication skill.
66
+ */
67
+ captcha: NucleusCaptcha;
60
68
  /**
61
69
  * The server's own logger: the instance with the installation's transports,
62
70
  * redaction keys and audit rules. Pass it as `logger` to
@@ -116,6 +124,8 @@ export declare function createNucleusRuntime(deps: {
116
124
  activeEmailProvider: () => 'azure' | 'gmail' | 'smtp' | null;
117
125
  /** The server's logger; the module-level one when omitted. */
118
126
  logger?: Logger;
127
+ /** The captcha service once the auth routes have built it; null while it is off or not built yet. */
128
+ getCaptchaService?: () => CaptchaService | null;
119
129
  /** The live notification service, or null while the database is not up. */
120
130
  getNotificationService?: () => NotificationService | null;
121
131
  /** The data access of the install; without it `data` refuses every use (a runtime built outside nucleus). */
@@ -1,11 +1,11 @@
1
- import type { CaptchaDifficulty, CaptchaGenerateResult, CaptchaServiceDeps, CaptchaType, CaptchaValidateResult } from './types';
1
+ import type { CaptchaDifficulty, CaptchaGenerateResult, CaptchaServiceDeps, CaptchaType, CaptchaValidateOptions, CaptchaValidateResult } from './types';
2
2
  export declare class CaptchaService {
3
3
  private redis;
4
4
  private logger;
5
5
  private config;
6
6
  constructor(deps: CaptchaServiceDeps);
7
7
  generate(type?: CaptchaType, difficulty?: CaptchaDifficulty, ipAddress?: string): Promise<CaptchaGenerateResult>;
8
- validate(challengeId: string, userAnswer: string): Promise<CaptchaValidateResult>;
8
+ validate(challengeId: string, userAnswer: string, options?: CaptchaValidateOptions): Promise<CaptchaValidateResult>;
9
9
  invalidate(challengeId: string): Promise<void>;
10
10
  isEnabled(): boolean;
11
11
  private checkRateLimit;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * `nucleus.captcha`: the captcha service lent to host code.
3
+ *
4
+ * Same service, same single-use rule as the HTTP route: a host no longer posts to its own
5
+ * `/auth/captcha/validate` over loopback. The service is reached through an accessor because it is
6
+ * built when the auth routes are mounted, after the runtime exists.
7
+ */
8
+ import type { Logger } from '../Logger';
9
+ import type { CaptchaService } from './index';
10
+ import type { NucleusCaptcha } from './runtimeCaptchaTypes';
11
+ export declare function createCaptchaRuntime(deps: {
12
+ getService: () => CaptchaService | null;
13
+ logger: Logger;
14
+ }): NucleusCaptcha;
@@ -0,0 +1,34 @@
1
+ /** The public shape of `nucleus.captcha`: validate a captcha answer in-process, from a route or a job. */
2
+ export type CaptchaCheckInput = {
3
+ challengeId: string;
4
+ answer: string;
5
+ /**
6
+ * Default true: a correct answer spends the challenge, exactly like `POST /auth/captcha/validate`.
7
+ * False only checks it and leaves it usable (a multi-step form that re-checks before the final submit).
8
+ */
9
+ consume?: boolean;
10
+ };
11
+ /** Why a check failed. `captcha_disabled` is a deployment state: the install runs without a captcha. */
12
+ export type CaptchaCheckFailure =
13
+ /** No challenge id or no answer was given. */
14
+ 'captcha_required'
15
+ /** Wrong answer, or the challenge's attempts are used up. */
16
+ | 'captcha_invalid'
17
+ /** The challenge aged out or never existed. */
18
+ | 'captcha_expired'
19
+ /** The challenge was already spent by an earlier correct answer. */
20
+ | 'captcha_used'
21
+ /** `authentication.captcha` is off or has no Redis to keep challenges in. */
22
+ | 'captcha_disabled';
23
+ export type CaptchaCheckResult = {
24
+ ok: true;
25
+ } | {
26
+ ok: false;
27
+ code: CaptchaCheckFailure;
28
+ };
29
+ export type NucleusCaptcha = {
30
+ /** Never throws: a store failure answers `captcha_invalid` (fail closed) and is logged. */
31
+ validate(input: CaptchaCheckInput): Promise<CaptchaCheckResult>;
32
+ /** True when the captcha service is running, i.e. a public form should ask for a challenge. */
33
+ enabled(): boolean;
34
+ };
@@ -47,11 +47,21 @@ export interface CaptchaGenerateResult {
47
47
  rateLimited?: boolean;
48
48
  message?: string;
49
49
  }
50
+ /**
51
+ * Why a validation failed, for in-process callers (`nucleus.captcha.validate`). The HTTP route strips it:
52
+ * its answer keeps the three fields below.
53
+ */
54
+ export type CaptchaFailureReason = 'not_found' | 'used' | 'expired' | 'attempts_exceeded' | 'incorrect';
50
55
  export interface CaptchaValidateResult {
51
56
  success: boolean;
52
57
  valid: boolean;
53
58
  message?: string;
54
59
  attemptsRemaining?: number;
60
+ reason?: CaptchaFailureReason;
61
+ }
62
+ export interface CaptchaValidateOptions {
63
+ /** Default true: a correct answer spends the challenge. False checks the answer and leaves it usable. */
64
+ consume?: boolean;
55
65
  }
56
66
  export interface CaptchaServiceDeps {
57
67
  redis: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nucleus-core-ts",
3
- "version": "0.10.231",
3
+ "version": "0.10.232",
4
4
  "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
5
5
  "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
6
6
  "license": "SEE LICENSE IN LICENSE",