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.
- package/dist/.build-ok +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +5 -5
- package/dist/server.js +5 -5
- package/dist/src/Client/ApiCaller/types.d.ts +4 -2
- package/dist/src/Nucleus/runtime.d.ts +10 -0
- package/dist/src/Services/Captcha/index.d.ts +2 -2
- package/dist/src/Services/Captcha/runtimeCaptcha.d.ts +14 -0
- package/dist/src/Services/Captcha/runtimeCaptchaTypes.d.ts +34 -0
- package/dist/src/Services/Captcha/types.d.ts +10 -0
- package/package.json +1 -1
|
@@ -425,11 +425,13 @@ export type CaptchaValidatePayload = {
|
|
|
425
425
|
challengeId: string;
|
|
426
426
|
answer: string;
|
|
427
427
|
};
|
|
428
|
-
|
|
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.
|
|
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",
|