@aooth/auth-moost 0.2.5 → 0.2.7
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/atscript/index.d.mts +17 -18
- package/dist/atscript/index.mjs +1 -1
- package/dist/{forms-D-MZTAyd.mjs → forms-BUF9oMsE.mjs} +6 -6
- package/dist/index.d.mts +582 -131
- package/dist/index.mjs +1580 -438
- package/package.json +29 -24
- package/src/atscript/models/forms.as +23 -36
- package/src/atscript/models/forms.as.d.ts +17 -18
package/dist/index.d.mts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { Mate, TConsoleBase, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
|
|
2
|
-
import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, CredentialMetadata, EmailSender, EmailSender as EmailSender$1, EnrichedSession, EnrichedSession as EnrichedSession$1, IssueResult, IssueResult as IssueResult$1, RateLimitDecision, RateLimitDecision as RateLimitDecision$1, RateLimitRule, RateLimitRule as RateLimitRule$1, RateLimitRuleInput, RateLimitRuleInput as RateLimitRuleInput$1, RateLimitStore, RateLimitStore as RateLimitStore$1, RateLimitStoreMemory, RateLimiter, RateLimiter as RateLimiter$1, RateLimiterOptions, SessionEnricher, SessionEnricher as SessionEnricher$1, SessionInfo, SessionInfo as SessionInfo$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
|
|
2
|
+
import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, CredentialMetadata, EmailSender, EmailSender as EmailSender$1, EnrichedSession, EnrichedSession as EnrichedSession$1, IssueResult, IssueResult as IssueResult$1, RateLimitDecision, RateLimitDecision as RateLimitDecision$1, RateLimitRule, RateLimitRule as RateLimitRule$1, RateLimitRuleInput, RateLimitRuleInput as RateLimitRuleInput$1, RateLimitStore, RateLimitStore as RateLimitStore$1, RateLimitStoreMemory, RateLimitStoreMemory as RateLimitStoreMemory$1, RateLimiter, RateLimiter as RateLimiter$1, RateLimiterOptions, SessionEnricher, SessionEnricher as SessionEnricher$1, SessionInfo, SessionInfo as SessionInfo$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
|
|
3
3
|
import { EventContext } from "@wooksjs/event-core";
|
|
4
4
|
import { HttpError, TCookieAttributesInput } from "@wooksjs/event-http";
|
|
5
|
-
import { FederatedIdentityStore, FederatedProfileSnapshot, MfaMethod, TransferablePolicy, TrustedDeviceRecord, UserAuthError,
|
|
5
|
+
import { FederatedIdentityStore, FederatedProfileSnapshot, MfaMethod, TransferablePolicy, TrustedDeviceRecord, UserAuthError, UserAuthErrorCode, UserCredentials, UserService } from "@aooth/user";
|
|
6
6
|
import { HttpError as HttpError$1 } from "@moostjs/event-http";
|
|
7
7
|
import { FinishWfOpts, WfFinished, useAtscriptWf } from "@atscript/moost-wf";
|
|
8
|
-
import { MoostWf, WfOutlet, WfOutletTokenConfig, WfOutletTriggerConfig, WfStateStrategy } from "@moostjs/event-wf";
|
|
8
|
+
import { MoostWf, WfOutlet, WfOutletTokenConfig, WfOutletTriggerConfig, WfState, WfStateStore, WfStateStoreMemory, WfStateStrategy } from "@moostjs/event-wf";
|
|
9
9
|
import { FederatedLoginService, NormalizedProfile, OAuthProviderRegistry } from "@aooth/idp";
|
|
10
10
|
import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
|
|
11
11
|
import { AuthCodeStore, AuthorizationServerMetadata, AuthorizationServerMetadata as AuthorizationServerMetadata$1, BuildAuthorizationServerMetadataOptions, BuildProtectedResourceMetadataOptions, ClientRedirectPolicy, DynamicClientRegistration, DynamicClientRegistration as DynamicClientRegistration$1, DynamicClientRegistrationOptions, IdTokenSigner, OidcClaimsResolver, PendingAuthorizationStore, ProtectedResourceMetadata, WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer } from "@aooth/auth/authz";
|
|
@@ -347,34 +347,34 @@ export declare function getAuthMate(): AuthMate;
|
|
|
347
347
|
*/
|
|
348
348
|
export declare const AOOTH_MESSAGES: {
|
|
349
349
|
readonly INVALID_CREDENTIALS: "Invalid credentials";
|
|
350
|
-
readonly
|
|
350
|
+
readonly AOOTH_ACCOUNT_LOCKED: "Account locked, please try again later";
|
|
351
351
|
readonly INVALID_PASSWORD: "Invalid password";
|
|
352
352
|
readonly INCORRECT_PASSWORD: "Incorrect password";
|
|
353
353
|
readonly SESSION_LIMIT_REACHED: "Session limit reached";
|
|
354
354
|
readonly PASSWORD_CHANGED_SIGN_IN_AGAIN: "Your password was changed. Please sign in again.";
|
|
355
|
-
readonly
|
|
356
|
-
readonly
|
|
357
|
-
readonly
|
|
355
|
+
readonly AOOTH_INVALID_CODE: "Invalid code";
|
|
356
|
+
readonly AOOTH_CODE_EXPIRED: "Code expired";
|
|
357
|
+
readonly AOOTH_TOO_MANY_CODE_ATTEMPTS: "Too many invalid attempts. Please request a new code.";
|
|
358
358
|
/** Params: `seconds`. */
|
|
359
|
-
readonly
|
|
359
|
+
readonly AOOTH_RESEND_WAIT: "Please wait {seconds}s before requesting a new code.";
|
|
360
360
|
/** Params: `seconds`. */
|
|
361
|
-
readonly
|
|
361
|
+
readonly AOOTH_RESEND_WAIT_ANOTHER: "Please wait {seconds}s before requesting another code";
|
|
362
362
|
/** Params: `seconds`, `channel` (`SMS` / `email`). */
|
|
363
|
-
readonly
|
|
363
|
+
readonly AOOTH_RESEND_WAIT_CHANNEL: "Please wait {seconds}s before requesting another {channel} code";
|
|
364
364
|
readonly TOTP_RESEND_NOT_APPLICABLE: "Resend is not applicable for TOTP";
|
|
365
365
|
/** HTTP 400 — a TOTP code submitted for an account without TOTP. */
|
|
366
366
|
readonly TOTP_NOT_CONFIGURED: "No TOTP MFA configured";
|
|
367
|
-
readonly
|
|
368
|
-
readonly
|
|
369
|
-
readonly
|
|
367
|
+
readonly AOOTH_ADDRESS_REQUIRED: "This field is required";
|
|
368
|
+
readonly AOOTH_INVALID_EMAIL_ADDRESS: "Enter a valid email address";
|
|
369
|
+
readonly AOOTH_INVALID_PHONE_NUMBER: "Enter a valid phone number";
|
|
370
370
|
readonly OTP_DISCLOSURE_EMAIL: "By providing your email address, you consent to receive one-time security codes from us via email. Standard email delivery may apply.";
|
|
371
371
|
readonly OTP_DISCLOSURE_PHONE: "By providing your phone number, you consent to receive one-time security codes from us via SMS. Message and data rates may apply.";
|
|
372
372
|
readonly UNKNOWN_MFA_METHOD: "Unknown MFA method";
|
|
373
|
-
readonly
|
|
374
|
-
readonly
|
|
375
|
-
readonly
|
|
373
|
+
readonly AOOTH_UNKNOWN_METHOD: "Unknown method";
|
|
374
|
+
readonly AOOTH_METHOD_UNAVAILABLE: "That method isn't available";
|
|
375
|
+
readonly AOOTH_METHOD_NOT_CHANGEABLE: "That method can't be changed here.";
|
|
376
376
|
readonly KEEP_ONE_MFA_METHOD: "You must keep at least one two-factor method.";
|
|
377
|
-
readonly
|
|
377
|
+
readonly AOOTH_CHOOSE_OPTION: "Choose an option";
|
|
378
378
|
readonly ALL_MFA_METHODS_SET_UP: "You've already set up every available authentication method.";
|
|
379
379
|
readonly NO_MFA_CHANGES: "No changes were made to your two-factor methods.";
|
|
380
380
|
readonly LAST_MFA_METHOD_NOT_REMOVABLE: "You must keep at least one two-factor method, so this one can't be removed.";
|
|
@@ -402,16 +402,17 @@ export declare const AOOTH_MESSAGES: {
|
|
|
402
402
|
readonly SET_PASSWORD_INVITE_INTRO: "Choose a password to activate your account.";
|
|
403
403
|
readonly SET_PASSWORD_INITIAL_HEADING: "Set your initial password";
|
|
404
404
|
readonly SET_PASSWORD_INITIAL_INTRO: "Your account was created without a password. Choose one to continue.";
|
|
405
|
-
|
|
405
|
+
/** A magic link that cannot be used: expired, of another purpose, or already used up. */
|
|
406
|
+
readonly AOOTH_MAGIC_LINK_INVALID: "This link is invalid or has expired. Please request a new one.";
|
|
406
407
|
readonly SIGNUP_DISABLED: "Self-signup is currently disabled.";
|
|
407
|
-
readonly
|
|
408
|
-
readonly
|
|
408
|
+
readonly AOOTH_ALREADY_HAVE_ACCOUNT: "You already have an account. Please sign in.";
|
|
409
|
+
readonly AOOTH_ACCOUNT_LINKED: "Account linked.";
|
|
409
410
|
/** HTTP 400 — the SSO alt action named a provider that is not offered. */
|
|
410
411
|
readonly UNKNOWN_SSO_PROVIDER: "Unknown SSO provider";
|
|
411
|
-
readonly
|
|
412
|
-
readonly
|
|
412
|
+
readonly AOOTH_ACCOUNT_CREATED: "Your account has been created.";
|
|
413
|
+
readonly AOOTH_INVALID_ROLE: "Invalid role";
|
|
413
414
|
readonly INVITE_ALREADY_PENDING: "Invite already pending";
|
|
414
|
-
readonly
|
|
415
|
+
readonly AOOTH_USER_ALREADY_EXISTS: "User already exists";
|
|
415
416
|
readonly DUPLICATE_INVITE_REJECTED: "Duplicate invite rejected";
|
|
416
417
|
readonly INVITE_CANCELLED: "This invite has been cancelled";
|
|
417
418
|
readonly INVITE_REPLACED: "This invite was replaced by a newer one";
|
|
@@ -424,8 +425,8 @@ export declare const AOOTH_MESSAGES: {
|
|
|
424
425
|
readonly GO_TO_SIGN_IN: "Go to sign-in";
|
|
425
426
|
readonly BACK_TO_SIGN_IN: "Back to sign-in";
|
|
426
427
|
readonly REQUEST_NEW_INVITE: "Request a new invite";
|
|
427
|
-
readonly
|
|
428
|
-
readonly
|
|
428
|
+
readonly AOOTH_BACK: "Back";
|
|
429
|
+
readonly AOOTH_GO_NOW: "Go now";
|
|
429
430
|
};
|
|
430
431
|
/** A message code of {@link AOOTH_MESSAGES}. */
|
|
431
432
|
type AoothMessageCode = keyof typeof AOOTH_MESSAGES;
|
|
@@ -493,6 +494,14 @@ export declare class AuthController {
|
|
|
493
494
|
*/
|
|
494
495
|
initRefreshCookiePath(paths: string[], logger: TConsoleBase): Promise<void>;
|
|
495
496
|
logout(body: AuthLogoutBody | undefined): Promise<AuthOkResponse>;
|
|
497
|
+
/**
|
|
498
|
+
* Rotate the access/refresh pair. Rate limited by two policies, enforced
|
|
499
|
+
* when `rateLimitInterceptors` are installed ({@link REFRESH_RATE_LIMITS}):
|
|
500
|
+
* `aooth.refresh` per client IP (checked before the auth guard, so a flood
|
|
501
|
+
* of junk tokens costs no lookups), and `aooth.refresh-token` per presented
|
|
502
|
+
* refresh token from any IP (a request without one skips it — the handler
|
|
503
|
+
* answers 401).
|
|
504
|
+
*/
|
|
496
505
|
refresh(body: AuthRefreshBody | undefined): Promise<AuthLoginResponse>;
|
|
497
506
|
status(): AuthContext$1;
|
|
498
507
|
triggerWf(): void;
|
|
@@ -599,8 +608,9 @@ export declare class SessionEnricherProvider {
|
|
|
599
608
|
* Each `SessionInfo` is mapped through the injectable {@link SessionEnricherProvider}
|
|
600
609
|
* before returning, and the caller's own session is flagged `current: true`.
|
|
601
610
|
* Both reads default to the browser-safe set (ordinary interactive sessions);
|
|
602
|
-
* `?kind=<kind>` segments a non-browser bucket (e.g. `?kind=cli-session`)
|
|
603
|
-
* `?kind=*` returns
|
|
611
|
+
* `?kind=<kind>` segments a non-browser bucket (e.g. `?kind=cli-session`), a
|
|
612
|
+
* comma list takes several (`?kind=session,cli-session`) and `?kind=*` returns
|
|
613
|
+
* every kind.
|
|
604
614
|
* NOT `@Public()` — the auth guard rejects unauthenticated callers with 401 and
|
|
605
615
|
* ARBAC gates each action; a customer enables it with `allow("auth.sessions", "*")`.
|
|
606
616
|
*/
|
|
@@ -631,8 +641,8 @@ export declare class SessionsController {
|
|
|
631
641
|
/** The body of an `HttpError` made by {@link userAuthErrorToHttp}. */
|
|
632
642
|
interface UserAuthErrorBody {
|
|
633
643
|
message: string;
|
|
634
|
-
/** The `UserAuthError`
|
|
635
|
-
code:
|
|
644
|
+
/** The `UserAuthError`'s message code (`"PASSWORD_IN_HISTORY"`, `"AOOTH_USER_LOCKED"`, …) — see `USER_AUTH_ERROR_CODES`. */
|
|
645
|
+
code: UserAuthErrorCode;
|
|
636
646
|
/**
|
|
637
647
|
* `POLICY_VIOLATION`: `{ policies: [{ description, passed, errorMessage, code?, params? }] }`
|
|
638
648
|
* — every policy and its result (`code` / `params`: the built-in policies' `PP_*` codes).
|
|
@@ -643,19 +653,20 @@ interface UserAuthErrorBody {
|
|
|
643
653
|
}
|
|
644
654
|
/**
|
|
645
655
|
* Map a `UserAuthError` (thrown by `UserService`) to an `HttpError` whose body
|
|
646
|
-
* carries `code` (the error
|
|
647
|
-
* the form `field` it belongs to (named as in the bundled
|
|
656
|
+
* carries `code` (the error's message code, `err.code`), the message and — for
|
|
657
|
+
* password errors — the form `field` it belongs to (named as in the bundled
|
|
658
|
+
* password forms):
|
|
648
659
|
*
|
|
649
|
-
* | type | status | field |
|
|
650
|
-
*
|
|
651
|
-
* | `NOT_FOUND` | 404 | |
|
|
652
|
-
* | `ALREADY_EXISTS`, `CAS_EXHAUSTED` | 409 | |
|
|
653
|
-
* | `INVALID_CREDENTIALS` | 400 | `currentPassword` |
|
|
654
|
-
* | `PASSWORD_IN_HISTORY` | 400 | `newPassword` |
|
|
655
|
-
* | `POLICY_VIOLATION` (+ `params.policies`) | 422 | `newPassword` |
|
|
656
|
-
* | `PASSWORDS_MISMATCH` | 400 | `confirmPassword` |
|
|
657
|
-
* | `MFA_INVALID`, `MFA_NOT_CONFIGURED` | 400 | |
|
|
658
|
-
* | `INACTIVE`, `LOCKED`, `MFA_REQUIRED` | 403 | |
|
|
660
|
+
* | type | code | status | field |
|
|
661
|
+
* |---|---|---|---|
|
|
662
|
+
* | `NOT_FOUND` | `NOT_FOUND` | 404 | |
|
|
663
|
+
* | `ALREADY_EXISTS`, `CAS_EXHAUSTED` | `AOOTH_USER_ALREADY_EXISTS`, `AOOTH_USER_CAS_EXHAUSTED` | 409 | |
|
|
664
|
+
* | `INVALID_CREDENTIALS` | `INVALID_CREDENTIALS` | 400 | `currentPassword` |
|
|
665
|
+
* | `PASSWORD_IN_HISTORY` | `PASSWORD_IN_HISTORY` | 400 | `newPassword` |
|
|
666
|
+
* | `POLICY_VIOLATION` (+ `params.policies`) | `AOOTH_USER_POLICY_VIOLATION` | 422 | `newPassword` |
|
|
667
|
+
* | `PASSWORDS_MISMATCH` | `PASSWORDS_MISMATCH` | 400 | `confirmPassword` |
|
|
668
|
+
* | `MFA_INVALID`, `MFA_NOT_CONFIGURED` | same as type | 400 | |
|
|
669
|
+
* | `INACTIVE`, `LOCKED`, `MFA_REQUIRED` | `AOOTH_USER_INACTIVE`, `AOOTH_USER_LOCKED`, `MFA_REQUIRED` | 403 | |
|
|
659
670
|
*
|
|
660
671
|
* For routes such as an admin "set password" endpoint. Do not use it on a
|
|
661
672
|
* sign-in endpoint: distinct answers for unknown, inactive and locked accounts
|
|
@@ -689,7 +700,7 @@ declare const HOOK_NAMES: readonly ["around", "beforePersist", "renderEnvelope",
|
|
|
689
700
|
* (a route's hook replaces the provider's hook of the same name).
|
|
690
701
|
*
|
|
691
702
|
* - `around(run)` — wraps everything the request does to workflow state and
|
|
692
|
-
* the outside world (
|
|
703
|
+
* the outside world (access checks, consume/start/resume, `beforePersist`,
|
|
693
704
|
* persist, outlet delivery), e.g. `(run) => db.transaction(run)`. It may
|
|
694
705
|
* call `run()` again after a failure; each run starts over from the request.
|
|
695
706
|
* - `beforePersist(state, pause)` — runs right before a paused state is
|
|
@@ -714,10 +725,30 @@ type WfTriggerHooks = Pick<WfOutletTriggerConfig, (typeof HOOK_NAMES)[number]>;
|
|
|
714
725
|
interface WfTriggerOpts extends WfTriggerHooks {
|
|
715
726
|
/**
|
|
716
727
|
* Workflow ids this trigger may START and RESUME (a leading `/` is ignored).
|
|
717
|
-
* Omitted = unrestricted; `[]` = deny every workflow. A
|
|
718
|
-
*
|
|
728
|
+
* Omitted = unrestricted; `[]` = deny every workflow. A flow is judged by
|
|
729
|
+
* the registered flow a request resolves to (an `onNotFound` flow or a
|
|
730
|
+
* parametric route that catches the id counts as that flow), and an entry
|
|
731
|
+
* admits only a flow registered under exactly that id. A refused start
|
|
732
|
+
* answers 403 `AOOTH_WORKFLOW_NOT_ALLOWED`, a refused resume 403
|
|
733
|
+
* `AOOTH_WORKFLOW_RESUME_NOT_ALLOWED`; a state token minted for a workflow
|
|
734
|
+
* outside the list is not consumed.
|
|
719
735
|
*/
|
|
720
736
|
allow?: string[];
|
|
737
|
+
/**
|
|
738
|
+
* Workflow ids this trigger may RESUME but never START — e.g. a public
|
|
739
|
+
* trigger that continues an invite flow only an admin can issue. Additive to
|
|
740
|
+
* `allow` (a resume needs no `allow` entry); a start is refused (403
|
|
741
|
+
* `AOOTH_WORKFLOW_NOT_ALLOWED`) even when `allow` lists the flow. `block`
|
|
742
|
+
* still wins.
|
|
743
|
+
*/
|
|
744
|
+
resumeOnly?: string[];
|
|
745
|
+
/**
|
|
746
|
+
* Workflow ids this trigger refuses on start AND resume (403
|
|
747
|
+
* `AOOTH_WORKFLOW_NOT_ALLOWED` on a start, `AOOTH_WORKFLOW_RESUME_NOT_ALLOWED`
|
|
748
|
+
* on a resume), whatever `allow` / `resumeOnly` say. An entry also blocks the
|
|
749
|
+
* flow it resolves to (`'user/42'` blocks `'user/:id'`).
|
|
750
|
+
*/
|
|
751
|
+
block?: string[];
|
|
721
752
|
/** Per-endpoint token wire override. Defaults to the provider's wire (`{read:['body','query','cookie'], write:'body', name:'wfs'}`). */
|
|
722
753
|
token?: WfOutletTokenConfig;
|
|
723
754
|
}
|
|
@@ -785,9 +816,11 @@ export declare class WfTriggerProvider {
|
|
|
785
816
|
protected readonly wf: MoostWf;
|
|
786
817
|
protected readonly auth: AuthCredential;
|
|
787
818
|
/**
|
|
788
|
-
* Outlets the trigger can pause on: HTTP (forms)
|
|
789
|
-
* `AuthWorkflowOpts.inviteDelivery: 'deliver' | 'return-link'`)
|
|
790
|
-
* `
|
|
819
|
+
* Outlets the trigger can pause on: HTTP (forms), `invite` (the link of
|
|
820
|
+
* `AuthWorkflowOpts.inviteDelivery: 'deliver' | 'return-link'`) and
|
|
821
|
+
* `magic-link` (recovery and sign-in links — it sends through the `email`
|
|
822
|
+
* outlet). Append an `email` outlet (`createAuthEmailOutlet`) for the default
|
|
823
|
+
* invite delivery and for magic links.
|
|
791
824
|
*/
|
|
792
825
|
protected outlets: WfOutlet[];
|
|
793
826
|
protected token: WfOutletTokenConfig;
|
|
@@ -802,10 +835,36 @@ export declare class WfTriggerProvider {
|
|
|
802
835
|
* `return deriveWfStateSecret(env.MY_SECRET)`.
|
|
803
836
|
*/
|
|
804
837
|
protected wfStateSecret(): string | Buffer;
|
|
838
|
+
/**
|
|
839
|
+
* Secret that keys the digests of one-time codes (recovery, sign-in, signup
|
|
840
|
+
* and enrolment codes) held in workflow state — the state keeps a keyed
|
|
841
|
+
* digest of each code, never the code. Default: the wf-state secret, so a
|
|
842
|
+
* store-backed setup that overrides `wfStateSecret()` needs nothing more.
|
|
843
|
+
* All instances must agree on it.
|
|
844
|
+
*/
|
|
845
|
+
protected pincodeSecret(): string | Buffer;
|
|
846
|
+
private cachedPincodeKey?;
|
|
847
|
+
/**
|
|
848
|
+
* The key of the one-time-code digests this provider publishes on every
|
|
849
|
+
* request: {@link derivePincodeKey} of {@link pincodeSecret}. With the
|
|
850
|
+
* default secrets it equals what `AuthWorkflow.pincodeKey()` derives outside
|
|
851
|
+
* a provider (`defaultPincodeKey`).
|
|
852
|
+
*/
|
|
853
|
+
protected pincodeKey(): Buffer;
|
|
805
854
|
/** TTL (ms) for encapsulated pre-validation tokens. Default: undefined = no TTL (token valid until used), so an idle login form never expires server-side. */
|
|
806
855
|
protected wfStateEncapsulatedTtlMs(): number | undefined;
|
|
807
856
|
/** Durable strategy a workflow swaps to after the first validated input. Default = encapsulated (no real store); customers override to return e.g. new HandleStateStrategy({ store: <redis/db> }). */
|
|
808
857
|
protected storeStrategy(): WfStateStrategy;
|
|
858
|
+
/**
|
|
859
|
+
* Store of the magic-link pauses (recovery and sign-in links). Default: one
|
|
860
|
+
* in-memory store per provider — single process only. With several
|
|
861
|
+
* instances, return a shared `WfStateStore` (e.g. the `AsWfStore` of your
|
|
862
|
+
* wf-state table). The strategy around it is fixed: handles are stored
|
|
863
|
+
* hashed (a read of the store yields no usable link), each link is consumed
|
|
864
|
+
* by its first use, and it expires with the link (`magicLinkTtlMs`).
|
|
865
|
+
*/
|
|
866
|
+
protected magicLinkStore(): WfStateStore;
|
|
867
|
+
private defaultMagicLinkStore?;
|
|
809
868
|
private makeEncapsulated;
|
|
810
869
|
/**
|
|
811
870
|
* App-wide workflow-trigger hooks ({@link WfTriggerHooks}): `around`,
|
|
@@ -821,14 +880,22 @@ export declare class WfTriggerProvider {
|
|
|
821
880
|
*/
|
|
822
881
|
protected triggerHooks(): WfTriggerHooks;
|
|
823
882
|
private cachedState?;
|
|
824
|
-
/** Named strategy registry: every wf starts on `encapsulated` (default); a step calls swapStrategy('store') to move durable
|
|
883
|
+
/** Named strategy registry: every wf starts on `encapsulated` (default); a step calls swapStrategy('store') to move durable, and a magic-link pause swaps to `magic-link`. Built lazily so subclass overrides (storeStrategy/wfStateSecret/magicLinkStore) are in effect. */
|
|
825
884
|
protected stateRegistry(): StateRegistry;
|
|
826
885
|
/**
|
|
827
|
-
*
|
|
828
|
-
*
|
|
829
|
-
*
|
|
830
|
-
*
|
|
831
|
-
*
|
|
886
|
+
* Read the paused workflow state a resume token (`wfs`) points at, WITHOUT
|
|
887
|
+
* consuming it — e.g. to show what a link is for before its holder acts.
|
|
888
|
+
* The token is resolved exactly as a resume resolves it (its strategy
|
|
889
|
+
* prefix, the strategy's handle hashing and legacy-key rules, the strategy
|
|
890
|
+
* tag), so a peek finds what a resume would. An unknown, expired, malformed
|
|
891
|
+
* or foreign token is `null` — one answer for all. The state carries
|
|
892
|
+
* server-only context: project what you need, never send it as-is.
|
|
893
|
+
*/
|
|
894
|
+
peek(token: string): Promise<WfState | null>;
|
|
895
|
+
/**
|
|
896
|
+
* Handle one trigger request. `opts` is {@link WfTriggerOpts}: the access
|
|
897
|
+
* lists are judged by the wooks trigger before a state token is consumed, and
|
|
898
|
+
* hooks set in `opts` replace the {@link triggerHooks} of the same name.
|
|
832
899
|
*/
|
|
833
900
|
handle(opts?: WfTriggerOpts): Promise<unknown>;
|
|
834
901
|
}
|
|
@@ -840,16 +907,22 @@ export declare class WfTriggerProvider {
|
|
|
840
907
|
* that need to short-circuit (e.g. emit a custom error response) just return a
|
|
841
908
|
* non-undefined value from the overridden handler and the trigger is skipped.
|
|
842
909
|
*
|
|
843
|
-
* `opts`
|
|
910
|
+
* `opts` is `WfTriggerOpts`: the access lists `allow` / `resumeOnly` /
|
|
911
|
+
* `block` and the workflow-trigger hooks (`around`, `beforePersist`,
|
|
844
912
|
* `renderEnvelope`, `restoreOnError`, `maxRestores` — see `WfTriggerHooks`);
|
|
845
|
-
* each
|
|
913
|
+
* each hook set here replaces the provider's `triggerHooks()` hook of the
|
|
846
914
|
* same name for this route.
|
|
847
915
|
*
|
|
916
|
+
* Under `@Inherit()`, re-decorating an overridden handler REPLACES the base
|
|
917
|
+
* route's options as a whole (e.g. a narrower `allow` is the only list
|
|
918
|
+
* checked) — the trigger still runs once per request. An override without
|
|
919
|
+
* its own `@WfTrigger` keeps the base options.
|
|
920
|
+
*
|
|
848
921
|
* The single `useControllerContext().instantiate(...)` call is the one
|
|
849
922
|
* documented escape hatch: interceptors are functions, not classes, so there's
|
|
850
923
|
* no ctor to inject into. Every class still uses constructor injection.
|
|
851
924
|
*/
|
|
852
|
-
export declare const WfTrigger: (opts?: WfTriggerOpts) =>
|
|
925
|
+
export declare const WfTrigger: (opts?: WfTriggerOpts) => MethodDecorator;
|
|
853
926
|
/** Name of the outlet `AuthWorkflow` pauses on for `inviteDelivery: 'deliver' | 'return-link'`. */
|
|
854
927
|
export declare const INVITE_OUTLET = "invite";
|
|
855
928
|
/**
|
|
@@ -859,9 +932,36 @@ export declare const INVITE_OUTLET = "invite";
|
|
|
859
932
|
* (`'return-link'`). The token never rides the response on its own.
|
|
860
933
|
*/
|
|
861
934
|
export declare function createInviteOutlet(): WfOutlet;
|
|
935
|
+
/** What {@link peekInvite} tells about a pending invite — safe to show its holder. */
|
|
936
|
+
interface InvitePeek {
|
|
937
|
+
/** The invited address. */
|
|
938
|
+
email: string;
|
|
939
|
+
/** User id of the issuer — set when the invite was issued from a signed-in session. */
|
|
940
|
+
invitedBy?: string;
|
|
941
|
+
/** Roles the invite grants, when it grants any. */
|
|
942
|
+
roles?: string[];
|
|
943
|
+
/** When the link stops working (ms since epoch), when known. */
|
|
944
|
+
expiresAt?: number;
|
|
945
|
+
}
|
|
946
|
+
/**
|
|
947
|
+
* Read what an invite link (its `wfs` token) is for — the invited address,
|
|
948
|
+
* the issuer, the roles and the link's expiry — WITHOUT consuming it, e.g. to
|
|
949
|
+
* show "Ann invited you as an editor" on the invite page before the invitee
|
|
950
|
+
* acts. Resolves the token through {@link WfTriggerProvider.peek}, then checks
|
|
951
|
+
* it against the account: an invite that was replaced by a re-invite, accepted,
|
|
952
|
+
* cancelled or that is not an invite link reads as `null`, the same as an
|
|
953
|
+
* unknown or expired token.
|
|
954
|
+
*
|
|
955
|
+
* Mount it on your own route and rate-limit that route like invite
|
|
956
|
+
* redemption — e.g. `@RateLimit("30/5m", { id: "app.invite-info" })`.
|
|
957
|
+
*/
|
|
958
|
+
export declare function peekInvite(token: string, deps: {
|
|
959
|
+
trigger: WfTriggerProvider;
|
|
960
|
+
users: UserService;
|
|
961
|
+
}): Promise<InvitePeek | null>;
|
|
862
962
|
/**
|
|
863
963
|
* Caller-identity strategy for a rate-limited route (RL.spec.md §5.3):
|
|
864
|
-
* - `'ip'` — client IP (the public-endpoint mode;
|
|
964
|
+
* - `'ip'` — client IP (the public-endpoint mode; see `requestClientIp`).
|
|
865
965
|
* Evaluated PRE-guard — floods rejected before credential work.
|
|
866
966
|
* - any other string — a NAMED SUBJECT, looked up in the per-event
|
|
867
967
|
* subjects slot (see `setRateLimitSubject`) and evaluated POST-guard so
|
|
@@ -869,14 +969,16 @@ export declare function createInviteOutlet(): WfOutlet;
|
|
|
869
969
|
* `'session'` (per login/device) derive from the auth context; anything
|
|
870
970
|
* unresolved falls back to the IP budget. `'auto'` is an alias of
|
|
871
971
|
* `'user'`. Apps supply their own kinds (`'tenant'`, `'apiKey'`, …) via
|
|
872
|
-
* `setRateLimitSubject`.
|
|
972
|
+
* `setRateLimitSubject`. `'refresh-token'` keys on the refresh token the
|
|
973
|
+
* request presents (body `refreshToken`, else the refresh cookie), hashed;
|
|
974
|
+
* a request without one skips the policy.
|
|
873
975
|
* - custom function — runs inside the event context PRE-guard; must be
|
|
874
976
|
* self-sufficient (it cannot read what GUARD-priority code sets). Return
|
|
875
977
|
* a composite subject (e.g. client IP + submitted username) to key on
|
|
876
978
|
* several things at once, or `null` / `undefined` to SKIP the policy for
|
|
877
979
|
* this request (nothing is counted).
|
|
878
980
|
*/
|
|
879
|
-
type RateLimitKeyStrategy = "ip" | "user" | "auto" | "session" | (string & {}) | (() => string | null | undefined | Promise<string | null | undefined>);
|
|
981
|
+
type RateLimitKeyStrategy = "ip" | "user" | "auto" | "session" | "refresh-token" | (string & {}) | (() => string | null | undefined | Promise<string | null | undefined>);
|
|
880
982
|
/** Trailing options object accepted by `@RateLimit(...rules, opts)`. */
|
|
881
983
|
interface RateLimitDecoratorOptions {
|
|
882
984
|
/** Overrides the interceptor-level default key strategy for this route. */
|
|
@@ -935,14 +1037,24 @@ interface RateLimitInterceptorOptions {
|
|
|
935
1037
|
/** Default key strategy for routes whose `@RateLimit` doesn't set one. Default: `'ip'`. */
|
|
936
1038
|
key?: RateLimitKeyStrategy;
|
|
937
1039
|
/**
|
|
938
|
-
*
|
|
939
|
-
*
|
|
940
|
-
*
|
|
941
|
-
*
|
|
1040
|
+
* @deprecated Set `trustProxy` (and `proxyHeaders`) on the HTTP app instead;
|
|
1041
|
+
* removed in 0.3. Still honoured, with a one-time warning: `true` trusts
|
|
1042
|
+
* exactly one proxy hop, read from the header family the app's
|
|
1043
|
+
* `proxyHeaders` names. Without it, the client IP is the one the HTTP app
|
|
1044
|
+
* resolves (`useRequest().getIp()`).
|
|
942
1045
|
*/
|
|
943
1046
|
trustProxy?: boolean;
|
|
944
1047
|
/** Emit draft `RateLimit-*` headers on every response of a limited route. Default: `true`. */
|
|
945
1048
|
headers?: boolean;
|
|
1049
|
+
/**
|
|
1050
|
+
* Re-tune declared policies without redeclaring their routes, by policy id
|
|
1051
|
+
* (the `id` a `@RateLimit` names, or a bundled id such as `aooth.refresh` /
|
|
1052
|
+
* `aooth.send`): new rules replace the declared ones — the key strategy, id
|
|
1053
|
+
* and message stay — and `false` switches the policy off. E.g.
|
|
1054
|
+
* `{ "aooth.refresh": "300/5m", "aooth.refresh-token": false }`. Parsed at
|
|
1055
|
+
* registration, like `rules`; an id no policy declared throws.
|
|
1056
|
+
*/
|
|
1057
|
+
policies?: Record<string, RateLimitRuleInput$1 | RateLimitRuleInput$1[] | false>;
|
|
946
1058
|
/**
|
|
947
1059
|
* App-wide default 429 message template (placeholders `{{limit}}`,
|
|
948
1060
|
* `{{window}}`, `{{delta}}` humanized; `{limit}`, `{window}`, `{retryAfter}`
|
|
@@ -958,7 +1070,7 @@ interface RateLimitInterceptorOptions {
|
|
|
958
1070
|
* ```ts
|
|
959
1071
|
* app.applyGlobalInterceptors(
|
|
960
1072
|
* authGuardInterceptor({ ... }),
|
|
961
|
-
* ...rateLimitInterceptors({ limiter
|
|
1073
|
+
* ...rateLimitInterceptors({ limiter }),
|
|
962
1074
|
* )
|
|
963
1075
|
* ```
|
|
964
1076
|
*
|
|
@@ -976,8 +1088,12 @@ interface RateLimitInterceptorOptions {
|
|
|
976
1088
|
*
|
|
977
1089
|
* Ownership is static per policy (from metadata/options): a route whose
|
|
978
1090
|
* stacked policies mix both kinds is evaluated by both phases, each checking
|
|
979
|
-
* its own policies.
|
|
980
|
-
*
|
|
1091
|
+
* its own policies. Each policy is checked once per event: a per-event record
|
|
1092
|
+
* of the checked policies guards against double counting when the pair is also
|
|
1093
|
+
* attached per-controller (see {@link RateLimited}), and when a request runs
|
|
1094
|
+
* the handler chains of two apps sharing one router (wooks moves on to the next
|
|
1095
|
+
* chain when a handler throws) — the second chain re-answers a policy's
|
|
1096
|
+
* rejection without counting it again and checks only the policies it adds.
|
|
981
1097
|
*
|
|
982
1098
|
* On rejection: draft `RateLimit-*` headers + `Retry-After` are written to
|
|
983
1099
|
* the accumulated response (they survive the throw — wooks renders the error
|
|
@@ -1378,6 +1494,13 @@ export declare class AuthorizeController {
|
|
|
1378
1494
|
*/
|
|
1379
1495
|
protected scopesSupported(): string[] | undefined;
|
|
1380
1496
|
authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined, nonce: string | undefined, resource: string | undefined): Promise<string>;
|
|
1497
|
+
/**
|
|
1498
|
+
* Rate limited when `rateLimitInterceptors` are installed
|
|
1499
|
+
* ({@link AUTHZ_RATE_LIMITS}): `aooth.token` per client IP, and
|
|
1500
|
+
* `aooth.token-refresh` per presented `refresh_token` of a refresh grant.
|
|
1501
|
+
* Both are checked before the auth guard; over the limit the endpoint
|
|
1502
|
+
* answers the coded `429` (`RATE_LIMITED`, `Retry-After`).
|
|
1503
|
+
*/
|
|
1381
1504
|
token(body: TokenRequestBody | undefined): Promise<TokenSuccess | TokenError>;
|
|
1382
1505
|
/**
|
|
1383
1506
|
* `grant_type=refresh_token` (OAuth 2.1 §4.3): rotate the presented refresh
|
|
@@ -1728,12 +1851,32 @@ interface AuthWfSessionState {
|
|
|
1728
1851
|
activeSessions?: number;
|
|
1729
1852
|
riskStepUpEvaluated?: boolean;
|
|
1730
1853
|
}
|
|
1854
|
+
/** How recovery delivers its proof of inbox: a one-time code, a magic link, or the user's pick. */
|
|
1855
|
+
type AuthWfRecoveryDeliveryMode = "otp" | "magicLink" | "choice";
|
|
1856
|
+
/** Server-only state of a magic link (recovery or sign-in). */
|
|
1857
|
+
interface AuthWfMagicLinkState {
|
|
1858
|
+
/** What the link may do: reset the password, or sign in (first factor only). */
|
|
1859
|
+
purpose: "recovery" | "login";
|
|
1860
|
+
/** The account the identifier resolved to — unset for an unknown identifier. */
|
|
1861
|
+
subject?: string;
|
|
1862
|
+
/** The typed identifier, normalised — kept only until the send (the cooldown key of an unknown one). */
|
|
1863
|
+
identifier?: string;
|
|
1864
|
+
/** Where the link went (an inbox the account proved) — unset when nothing was sent. */
|
|
1865
|
+
address?: string;
|
|
1866
|
+
/** Set when the link pause was persisted; the resume (the click) skips the send. */
|
|
1867
|
+
sentAt?: number;
|
|
1868
|
+
/** When the link stops working. */
|
|
1869
|
+
expiresAt?: number;
|
|
1870
|
+
/** Set once the landing step ("Continue as …") was submitted — the link is then used up. */
|
|
1871
|
+
confirmed?: boolean;
|
|
1872
|
+
/** Sign-in links bound to the requesting browser: a hash of the binding cookie's nonce. */
|
|
1873
|
+
browser?: string;
|
|
1874
|
+
}
|
|
1731
1875
|
/** Alt-credential mirror flags (login). */
|
|
1732
1876
|
interface AuthWfAltActionsState {
|
|
1733
1877
|
forgotPassword?: boolean;
|
|
1734
1878
|
signup?: boolean;
|
|
1735
1879
|
magicLink?: boolean;
|
|
1736
|
-
usedMagicLink?: boolean;
|
|
1737
1880
|
/** SSO providers offered on the login form — each renders a `sso-<id>` button. */
|
|
1738
1881
|
ssoProviders?: SsoProvider[];
|
|
1739
1882
|
}
|
|
@@ -1742,11 +1885,15 @@ interface AuthWfAltCredsPolicy {
|
|
|
1742
1885
|
forgotPassword: boolean;
|
|
1743
1886
|
signup: boolean;
|
|
1744
1887
|
magicLink: boolean;
|
|
1745
|
-
|
|
1888
|
+
/**
|
|
1889
|
+
* Bind sign-in links to the browser that asked for them (a cookie nonce):
|
|
1890
|
+
* the link then works only there. Default `false` — opening the email on
|
|
1891
|
+
* another device is legitimate.
|
|
1892
|
+
*/
|
|
1893
|
+
magicLinkSameBrowser?: boolean;
|
|
1746
1894
|
ssoProviders: SsoProvider[];
|
|
1747
1895
|
recoveryUrl: string;
|
|
1748
1896
|
signupUrl: string;
|
|
1749
|
-
embedRecovery: boolean;
|
|
1750
1897
|
}
|
|
1751
1898
|
/** Device-trust policy (login). */
|
|
1752
1899
|
interface AuthWfDeviceTrustPolicy {
|
|
@@ -1870,7 +2017,7 @@ interface AuthWfAcceptState {
|
|
|
1870
2017
|
alreadyAcceptedRedirectUrl?: string;
|
|
1871
2018
|
loginUrl?: string;
|
|
1872
2019
|
showConfirmation?: boolean;
|
|
1873
|
-
/** The app's own confirmation text, shown as is; default: `
|
|
2020
|
+
/** The app's own confirmation text, shown as is; default: `AOOTH_ACCOUNT_CREATED`, rendered per request. */
|
|
1874
2021
|
confirmationMessage?: string;
|
|
1875
2022
|
alreadyAccepted?: boolean;
|
|
1876
2023
|
/** `inviteUsername: 'choose'` — the invitee picks their username at accept. */
|
|
@@ -2003,7 +2150,7 @@ interface AuthWfOAuthState {
|
|
|
2003
2150
|
* (the schema gate right after `sso-callback`) is what keeps an unproven user
|
|
2004
2151
|
* out of the token-issuing tail. The `snapshot` has `profile.raw` stripped (raw
|
|
2005
2152
|
* claims are never persisted — RFC §7). The OTP-proof code lives HERE, not on the
|
|
2006
|
-
* shared top-level `ctx.
|
|
2153
|
+
* shared top-level code fields (`ctx.pinNonce` …), so it cannot collide with the post-link MFA loop's
|
|
2007
2154
|
* own pincode in the same run.
|
|
2008
2155
|
*/
|
|
2009
2156
|
interface AuthWfPendingLinkState {
|
|
@@ -2029,9 +2176,9 @@ interface AuthWfPendingLinkState {
|
|
|
2029
2176
|
hint?: string;
|
|
2030
2177
|
/** OTP mode only — masked delivery target for the "code sent to …" copy. Safe to expose. */
|
|
2031
2178
|
sentTo?: string;
|
|
2032
|
-
|
|
2179
|
+
pinNonce?: string;
|
|
2180
|
+
pinDigest?: string;
|
|
2033
2181
|
pinExpire?: number;
|
|
2034
|
-
pinAttempts?: number;
|
|
2035
2182
|
}
|
|
2036
2183
|
/**
|
|
2037
2184
|
* Standalone add-MFA flow state (`auth/add-mfa/flow`). Populated by
|
|
@@ -2160,6 +2307,10 @@ interface AuthWfPublicState {
|
|
|
2160
2307
|
pending?: ConsentDescriptorLike[];
|
|
2161
2308
|
decidedAt?: number;
|
|
2162
2309
|
};
|
|
2310
|
+
/** The account a clicked magic link signs into / resets, masked (`MagicLinkConfirmForm`). */
|
|
2311
|
+
magicLink?: {
|
|
2312
|
+
account?: string;
|
|
2313
|
+
};
|
|
2163
2314
|
/** Mirrors `ctx.altActions` — which alt-action buttons render on login (incl. SSO providers). */
|
|
2164
2315
|
altActions?: {
|
|
2165
2316
|
forgotPassword?: boolean;
|
|
@@ -2282,10 +2433,11 @@ interface AuthWfCtx {
|
|
|
2282
2433
|
*/
|
|
2283
2434
|
email?: string;
|
|
2284
2435
|
defaults?: AuthWfDefaults;
|
|
2285
|
-
|
|
2436
|
+
/** Random id of the code currently in flight — keys its server-side attempt counter and single-use marker. Set by `mintPin`. */
|
|
2437
|
+
pinNonce?: string;
|
|
2438
|
+
/** Keyed digest of the code in flight, bound to who it was sent for — never the code itself. */
|
|
2439
|
+
pinDigest?: string;
|
|
2286
2440
|
pinExpire?: number;
|
|
2287
|
-
/** Wrong-code attempt counter for the currently minted pincode. Reset by `mintPin`; incremented by `verifyPin`; cleared when the cap is hit (which also clears `pin`/`pinExpire` so the user must request a fresh code). */
|
|
2288
|
-
pinAttempts?: number;
|
|
2289
2441
|
aborted?: boolean;
|
|
2290
2442
|
isFirstLogin?: boolean;
|
|
2291
2443
|
newPasswordRequired?: boolean;
|
|
@@ -2347,6 +2499,10 @@ interface AuthWfCtx {
|
|
|
2347
2499
|
accept?: AuthWfAcceptState;
|
|
2348
2500
|
postReset?: AuthWfPostResetState;
|
|
2349
2501
|
recoveryAltActions?: AuthWfRecoveryAltActions;
|
|
2502
|
+
/** How the recovery code goes out: `'choice'` until the user picks on `RecoveryModeSelectForm`. [recovery] */
|
|
2503
|
+
recoveryDelivery?: AuthWfRecoveryDeliveryMode;
|
|
2504
|
+
/** Server-only state of a recovery or sign-in magic link — never projected to the wire. [recovery, login] */
|
|
2505
|
+
magicLink?: AuthWfMagicLinkState;
|
|
2350
2506
|
mfa?: AuthWfMfaState;
|
|
2351
2507
|
channel?: AuthWfChannelState;
|
|
2352
2508
|
notice?: AuthWfNoticeState;
|
|
@@ -2489,9 +2645,11 @@ interface AuthWorkflowOpts {
|
|
|
2489
2645
|
*/
|
|
2490
2646
|
lockoutDisclosure?: "uniform" | "generic" | "reveal";
|
|
2491
2647
|
/**
|
|
2492
|
-
* Counter store for the `'uniform'` shadow lockout of unknown handles
|
|
2493
|
-
*
|
|
2494
|
-
* `
|
|
2648
|
+
* Counter store for the `'uniform'` shadow lockout of unknown handles and
|
|
2649
|
+
* for the magic-link send cooldown (one link per account and purpose per
|
|
2650
|
+
* `mfa.pincodeResendTimeoutMs`). Default: one process-wide in-memory store —
|
|
2651
|
+
* pass a shared store (e.g. `RateLimitStoreRedis`) when several instances
|
|
2652
|
+
* serve sign-ins.
|
|
2495
2653
|
*/
|
|
2496
2654
|
lockoutShadowStore?: RateLimitStore$1;
|
|
2497
2655
|
/** Pincode infrastructure shared by login MFA, invite MFA, and recovery OTP. */
|
|
@@ -2501,9 +2659,37 @@ interface AuthWorkflowOpts {
|
|
|
2501
2659
|
pincodeResendTimeoutMs?: number;
|
|
2502
2660
|
/** Max wrong-code submissions per minted pincode before the code is invalidated and the user must request a fresh one. Defaults to 5. */
|
|
2503
2661
|
pincodeMaxAttempts?: number;
|
|
2662
|
+
/**
|
|
2663
|
+
* Wrong codes allowed per destination (an account's address, or a typed
|
|
2664
|
+
* recovery / signup identifier) and client IP, across all its codes within
|
|
2665
|
+
* `pincodeFailureWindowMs`; past it every send and check for that
|
|
2666
|
+
* destination from that IP answers `429 AOOTH_CODE_LIMIT_REACHED`.
|
|
2667
|
+
* Defaults to 10.
|
|
2668
|
+
*/
|
|
2669
|
+
pincodeMaxFailures?: number;
|
|
2670
|
+
/** Window of `pincodeMaxFailures`, from the first wrong code. Defaults to 1 hour. */
|
|
2671
|
+
pincodeFailureWindowMs?: number;
|
|
2672
|
+
/**
|
|
2673
|
+
* Backstop over `pincodeMaxFailures`: wrong codes per destination from all
|
|
2674
|
+
* client IPs together within `pincodeFailureWindowMs`. Defaults to 100.
|
|
2675
|
+
*/
|
|
2676
|
+
pincodeMaxFailuresGlobal?: number;
|
|
2677
|
+
/**
|
|
2678
|
+
* Codes sent per destination from all client IPs together within
|
|
2679
|
+
* `pincodeFailureWindowMs`; past it a request mints a code and sends
|
|
2680
|
+
* nothing (the resend wait itself is per client IP). Defaults to 10 — a
|
|
2681
|
+
* person needs a few codes an hour; this caps mail-bombing and SMS
|
|
2682
|
+
* pumping spread over many IPs at 10 messages per destination per hour.
|
|
2683
|
+
*/
|
|
2684
|
+
pincodeMaxSendsGlobal?: number;
|
|
2504
2685
|
};
|
|
2505
2686
|
/** Persisted-state TTL for the recovery flow — caps the window between OTP request and password reset. Applied at every recovery-side `requireInput` pause via the wf engine's `output.expires`. */
|
|
2506
2687
|
recoveryStateTtlMs?: number;
|
|
2688
|
+
/**
|
|
2689
|
+
* Lifetime of a magic link (recovery and sign-in links), from the moment it
|
|
2690
|
+
* is sent. Default 15 minutes. The link is single-use either way.
|
|
2691
|
+
*/
|
|
2692
|
+
magicLinkTtlMs?: number;
|
|
2507
2693
|
/** Canonical login URL — used by invite (post-accept redirect) and recovery (abort-to-login + post-reset redirect) as the resolver-default loginUrl. */
|
|
2508
2694
|
loginUrl?: string;
|
|
2509
2695
|
/** TOTP provisioning issuer — used by login MFA and invite MFA enrollment. */
|
|
@@ -2566,6 +2752,12 @@ interface AuthWorkflowOpts {
|
|
|
2566
2752
|
termsBump?: TAtscriptAnnotatedType;
|
|
2567
2753
|
concurrencyLimit?: TAtscriptAnnotatedType;
|
|
2568
2754
|
recoveryPincode?: TAtscriptAnnotatedType;
|
|
2755
|
+
/** Recovery delivery picker (magic link vs one-time code) — `resolveRecoveryDeliveryMode` → `'choice'`. */
|
|
2756
|
+
recoveryModeSelect?: TAtscriptAnnotatedType;
|
|
2757
|
+
/** Identifier form of the login flow's `magicLink` alt-action. */
|
|
2758
|
+
magicLinkRequest?: TAtscriptAnnotatedType;
|
|
2759
|
+
/** Landing step of a clicked magic link ("Continue as …") — the link is used up on submit. */
|
|
2760
|
+
magicLinkConfirm?: TAtscriptAnnotatedType;
|
|
2569
2761
|
/** Self-signup identifier form (`auth/signup/flow` entry pause). */
|
|
2570
2762
|
signup?: TAtscriptAnnotatedType;
|
|
2571
2763
|
/** Consent prompt shown before `mint-authz-code` mints an auth code (AUTH-SERVER.md §6). */
|
|
@@ -2596,8 +2788,13 @@ interface ResolvedAuthWorkflowOpts {
|
|
|
2596
2788
|
pincodeTtlMs: number;
|
|
2597
2789
|
pincodeResendTimeoutMs: number;
|
|
2598
2790
|
pincodeMaxAttempts: number;
|
|
2791
|
+
pincodeMaxFailures: number;
|
|
2792
|
+
pincodeFailureWindowMs: number;
|
|
2793
|
+
pincodeMaxFailuresGlobal: number;
|
|
2794
|
+
pincodeMaxSendsGlobal: number;
|
|
2599
2795
|
};
|
|
2600
2796
|
recoveryStateTtlMs: number;
|
|
2797
|
+
magicLinkTtlMs: number;
|
|
2601
2798
|
loginUrl: string;
|
|
2602
2799
|
totpIssuer: string;
|
|
2603
2800
|
deviceTrust: {
|
|
@@ -2635,6 +2832,9 @@ interface ResolvedAuthWorkflowOpts {
|
|
|
2635
2832
|
termsBump: TAtscriptAnnotatedType;
|
|
2636
2833
|
concurrencyLimit: TAtscriptAnnotatedType;
|
|
2637
2834
|
recoveryPincode: TAtscriptAnnotatedType;
|
|
2835
|
+
recoveryModeSelect: TAtscriptAnnotatedType;
|
|
2836
|
+
magicLinkRequest: TAtscriptAnnotatedType;
|
|
2837
|
+
magicLinkConfirm: TAtscriptAnnotatedType;
|
|
2638
2838
|
signup: TAtscriptAnnotatedType;
|
|
2639
2839
|
authzConsent: TAtscriptAnnotatedType;
|
|
2640
2840
|
};
|
|
@@ -2713,6 +2913,12 @@ type AuthDeliveryPayloadOf = {
|
|
|
2713
2913
|
loginAt: number;
|
|
2714
2914
|
context?: Record<string, unknown>;
|
|
2715
2915
|
};
|
|
2916
|
+
/** Where a one-time code in flight lives (top-level ctx, or a pending federated link). */
|
|
2917
|
+
type PinState = {
|
|
2918
|
+
pinNonce?: string;
|
|
2919
|
+
pinDigest?: string;
|
|
2920
|
+
pinExpire?: number;
|
|
2921
|
+
};
|
|
2716
2922
|
/**
|
|
2717
2923
|
* Top-level `UserCredentials` keys that workflow-collected profile payloads
|
|
2718
2924
|
* MUST NEVER carry through to persistence. The server sets these out-of-band
|
|
@@ -3009,6 +3215,13 @@ export declare class AuthWorkflow {
|
|
|
3009
3215
|
* `Set-Cookie` is stored before `AsWfForm` follows the redirect.
|
|
3010
3216
|
*/
|
|
3011
3217
|
protected beginSso(providerId: string, authzHandle?: string): Promise<void>;
|
|
3218
|
+
/**
|
|
3219
|
+
* How recovery proves the inbox: `'otp'` (default — a one-time code),
|
|
3220
|
+
* `'magicLink'` (a single-use link, sent through the email outlet as
|
|
3221
|
+
* `recovery.magicLink`) or `'choice'` (the user picks on
|
|
3222
|
+
* `RecoveryModeSelectForm` after the identifier). Reached from recovery.flow.
|
|
3223
|
+
*/
|
|
3224
|
+
protected resolveRecoveryDeliveryMode(_ctx: AuthWfCtx): AuthWfRecoveryDeliveryMode | Promise<AuthWfRecoveryDeliveryMode>;
|
|
3012
3225
|
/**
|
|
3013
3226
|
* Resolve the alternate-credentials policy (forgot-password / signup /
|
|
3014
3227
|
* magic-link / SSO providers). Reached from login.flow.
|
|
@@ -3240,7 +3453,7 @@ export declare class AuthWorkflow {
|
|
|
3240
3453
|
* `freshLoginRequired` field is GONE — the auto-login choice is the static
|
|
3241
3454
|
* `AuthWorkflowOpts.autoLoginOnInvite` boolean (per §2 decision). Return
|
|
3242
3455
|
* `confirmationMessage` to replace the default confirmation text
|
|
3243
|
-
* (`
|
|
3456
|
+
* (`AOOTH_ACCOUNT_CREATED`, rendered in the finishing request's language) with your
|
|
3244
3457
|
* own, shown as is.
|
|
3245
3458
|
*/
|
|
3246
3459
|
protected resolveAccept(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["accept"]> | Promise<NonNullable<AuthWfCtx["accept"]>>;
|
|
@@ -3284,6 +3497,11 @@ export declare class AuthWorkflow {
|
|
|
3284
3497
|
* set) or from `ctx.email` (recovery path). Loads the user to read the raw
|
|
3285
3498
|
* method `value` — the `ctx.mfa.enrolledMethods` summary carries only the
|
|
3286
3499
|
* MASKED form, which is for display, never for delivery.
|
|
3500
|
+
*
|
|
3501
|
+
* In recovery it also runs for an identifier with no account a code can go
|
|
3502
|
+
* to (unknown, inactive), on a copy of `ctx` whose `subject` is the
|
|
3503
|
+
* placeholder `00000000-0000-4000-8000-000000000000` — so every identifier
|
|
3504
|
+
* makes the same calls. Its result (or any error) is discarded there.
|
|
3287
3505
|
*/
|
|
3288
3506
|
protected resolvePincodeTarget(ctx: AuthWfCtx): {
|
|
3289
3507
|
address: string;
|
|
@@ -3303,13 +3521,13 @@ export declare class AuthWorkflow {
|
|
|
3303
3521
|
* row (`selectRecoveryRegisteredMethod`) and the channel is that method's own
|
|
3304
3522
|
* kind. The user only typed an account identifier; the destination is a
|
|
3305
3523
|
* pre-verified channel they already control, so this also can't redirect
|
|
3306
|
-
* cross-account.
|
|
3307
|
-
*
|
|
3308
|
-
*
|
|
3309
|
-
* `RecoveryMethodUnavailableError`, which `pincode-send` degrades to the
|
|
3310
|
-
* same generic finish — never a distinguishable 500.
|
|
3524
|
+
* cross-account. With no deliverable method this throws
|
|
3525
|
+
* `RecoveryMethodUnavailableError`, which recovery treats as "no account"
|
|
3526
|
+
* (nothing sent, every code refused) — never a distinguishable 500.
|
|
3311
3527
|
*/
|
|
3312
3528
|
private recoveryPincodeTarget;
|
|
3529
|
+
/** `resolveRecoveryDeliverySource`, awaited. */
|
|
3530
|
+
private recoveryDeliverySource;
|
|
3313
3531
|
/**
|
|
3314
3532
|
* Recovery OTP delivery channel. The address is ALWAYS the typed recovery
|
|
3315
3533
|
* identifier (`ctx.email`) — symmetric with how email recovery already works:
|
|
@@ -3332,7 +3550,7 @@ export declare class AuthWorkflow {
|
|
|
3332
3550
|
* row** — `selectRecoveryRegisteredMethod` picks the confirmed MFA method;
|
|
3333
3551
|
* the destination is never taken from user input, so it cannot be redirected
|
|
3334
3552
|
* to an attacker-controlled address. A row with no deliverable confirmed
|
|
3335
|
-
* method
|
|
3553
|
+
* method runs the ghost OTP pause, like an unknown identifier (see `request`).
|
|
3336
3554
|
*
|
|
3337
3555
|
* Consulted inline by `request` (no-method guard) and `recoveryPincodeTarget`
|
|
3338
3556
|
* — no `prepare-*` step, mirroring `resolveRecoveryChannel`. Override to arm
|
|
@@ -3344,7 +3562,7 @@ export declare class AuthWorkflow {
|
|
|
3344
3562
|
* its OTP to. Prefers a confirmed SMS method, then a confirmed email method —
|
|
3345
3563
|
* phone-recovery-first. TOTP carries no deliverable address and is skipped.
|
|
3346
3564
|
* Returns `null` when the row has no deliverable confirmed method; the caller
|
|
3347
|
-
* turns that into the anti-enumeration
|
|
3565
|
+
* turns that into the ghost OTP run (anti-enumeration). Stays sync (operates on
|
|
3348
3566
|
* an already-loaded row); override to change the selection policy (e.g. honour
|
|
3349
3567
|
* the user's `mfa.defaultMethod`).
|
|
3350
3568
|
*/
|
|
@@ -3427,29 +3645,100 @@ export declare class AuthWorkflow {
|
|
|
3427
3645
|
protected useAtscriptWfPublic(ctx: AuthWfCtx, type: Parameters<typeof useAtscriptWf>[0]): ReturnType<typeof useAtscriptWf>;
|
|
3428
3646
|
/** Translate `CAS_EXHAUSTED` UserAuthError to 409 Conflict (OCC contract). */
|
|
3429
3647
|
protected withStoreErrorTranslation<T>(op: () => Promise<T>): Promise<T>;
|
|
3430
|
-
/**
|
|
3431
|
-
|
|
3432
|
-
|
|
3433
|
-
|
|
3434
|
-
|
|
3435
|
-
|
|
3436
|
-
|
|
3437
|
-
|
|
3438
|
-
|
|
3439
|
-
|
|
3440
|
-
|
|
3441
|
-
|
|
3442
|
-
|
|
3443
|
-
|
|
3444
|
-
*
|
|
3445
|
-
|
|
3446
|
-
|
|
3447
|
-
|
|
3448
|
-
|
|
3449
|
-
|
|
3450
|
-
|
|
3648
|
+
/**
|
|
3649
|
+
* Mint a numeric one-time code for `binding` (who it is sent for) and return
|
|
3650
|
+
* the plain code for delivery. The state keeps only a random nonce and a
|
|
3651
|
+
* keyed digest of `nonce|binding|code` — fixed lengths, never the code — so
|
|
3652
|
+
* a read of the state does not reveal it, and {@link verifyPin} accepts it
|
|
3653
|
+
* only for the same binding. `length` and `ttlMs` default to
|
|
3654
|
+
* `mfa.pincodeLength` / `mfa.pincodeTtlMs`.
|
|
3655
|
+
*/
|
|
3656
|
+
protected mintPin(ctx: PinState, binding: string, length?: number, ttlMs?: number): string;
|
|
3657
|
+
/** Drop the code in flight (its nonce stays spent or counted server-side). */
|
|
3658
|
+
protected clearPin(ctx: PinState): void;
|
|
3659
|
+
/** Binding of a code sent to `address` in this run (and for its subject, once known). */
|
|
3660
|
+
private pinFor;
|
|
3661
|
+
/**
|
|
3662
|
+
* Binding of a recovery code: the account and the address it went to (a
|
|
3663
|
+
* changed registered channel refuses the old channel's code). Without an
|
|
3664
|
+
* account, the placeholder — the digest has the same length either way.
|
|
3665
|
+
*/
|
|
3666
|
+
private recoveryBinding;
|
|
3667
|
+
/**
|
|
3668
|
+
* Server-side key of where a code goes — its resend cooldown and failed-code
|
|
3669
|
+
* budget. Never an account id the caller could not know: recovery and signup
|
|
3670
|
+
* key on the typed identifier, so known and unknown ones behave alike.
|
|
3671
|
+
*/
|
|
3672
|
+
private codeTarget;
|
|
3673
|
+
/** {@link codeTarget} of a code sent to `address` to enrol or verify a channel. */
|
|
3674
|
+
private enrollTarget;
|
|
3675
|
+
/** {@link codeTarget} of a federated link's proof-of-control code. */
|
|
3676
|
+
private linkTarget;
|
|
3677
|
+
/** {@link codeTarget} of the `pincode-send` / `pincode-check` pair. */
|
|
3678
|
+
private pincodeTarget;
|
|
3679
|
+
/**
|
|
3680
|
+
* Server-side gate of a code send to `target`, before minting: answers
|
|
3681
|
+
* `429 AOOTH_CODE_LIMIT_REACHED` once the target's failed-code budget is
|
|
3682
|
+
* spent (this client IP's, or all IPs' together), applies the per-account
|
|
3683
|
+
* `aooth.send-user` limit when `account` is given (sends after a first
|
|
3684
|
+
* factor), and claims this client IP's resend wait for the target
|
|
3685
|
+
* (`mfa.pincodeResendTimeoutMs`) and a slot of the target's send cap from
|
|
3686
|
+
* all IPs (`mfa.pincodeMaxSendsGlobal` per `pincodeFailureWindowMs`).
|
|
3687
|
+
* Returns whether the code may go out: `false` inside the wait or past the
|
|
3688
|
+
* cap — the caller mints a code all the same and sends nothing, for known
|
|
3689
|
+
* and unknown destinations alike.
|
|
3690
|
+
*/
|
|
3691
|
+
protected claimCodeSend(target: string, account?: string): Promise<boolean>;
|
|
3692
|
+
/** Whether a send to `target` is cooling down (`false` when the store cannot peek). */
|
|
3693
|
+
private codeSendCoolingDown;
|
|
3694
|
+
/**
|
|
3695
|
+
* Counters of a destination, per client IP and across all IPs:
|
|
3696
|
+
* - sends (`CODE_SEND_PREFIX`): this client's resend wait, and the sends
|
|
3697
|
+
* from all IPs together in the window (the cap on mail-bombing and SMS
|
|
3698
|
+
* pumping spread over many IPs);
|
|
3699
|
+
* - failed codes (`CODE_FAIL_PREFIX`): the budget one caller can spend (so
|
|
3700
|
+
* an attacker cannot lock the owner out from elsewhere), and the backstop
|
|
3701
|
+
* against distributed guessing.
|
|
3702
|
+
*
|
|
3703
|
+
* The client IP is hashed: fixed-size keys, no raw IPs in the store.
|
|
3704
|
+
*/
|
|
3705
|
+
private counterKeys;
|
|
3706
|
+
/** Answer `429 AOOTH_CODE_LIMIT_REACHED` once a destination's failed-code budget is spent. */
|
|
3707
|
+
private assertCodeBudget;
|
|
3708
|
+
/**
|
|
3709
|
+
* Verify a submitted code against the one minted for `binding`. Returns an
|
|
3710
|
+
* error map (keyed under `code` so it renders on the code input) or `null`
|
|
3711
|
+
* on success.
|
|
3712
|
+
*
|
|
3713
|
+
* Attempts are counted server-side in `lockoutShadowStore`, per minted code
|
|
3714
|
+
* (its nonce), before the comparison: a replayed older state token shares
|
|
3715
|
+
* the counter, so `pincodeMaxAttempts` holds across replays and parallel
|
|
3716
|
+
* submits. A code is single-use: once it verifies, its nonce is spent and
|
|
3717
|
+
* the same code through any copy of the state is refused. A binding that
|
|
3718
|
+
* differs from the one at mint (the account resolved differently since the
|
|
3719
|
+
* send) reads as a wrong code. Wrong codes also count against `target`'s
|
|
3720
|
+
* failed-code budgets across resends (`mfa.pincodeMaxFailures` per client
|
|
3721
|
+
* IP, `pincodeMaxFailuresGlobal` for all IPs, per
|
|
3722
|
+
* `pincodeFailureWindowMs`); once one is spent every check answers
|
|
3723
|
+
* `429 AOOTH_CODE_LIMIT_REACHED`.
|
|
3724
|
+
*/
|
|
3725
|
+
protected verifyPin(ctx: PinState, submitted: string | undefined, binding: string, target: string): Promise<{
|
|
3451
3726
|
code: string;
|
|
3452
|
-
} | null
|
|
3727
|
+
} | null>;
|
|
3728
|
+
/** Keyed digest of a code, bound to its nonce and to who it was sent for. */
|
|
3729
|
+
private pinDigest;
|
|
3730
|
+
/**
|
|
3731
|
+
* Key of the code digests: the one `WfTriggerProvider` publishes for the
|
|
3732
|
+
* request (derived from its `pincodeSecret()`), else the key a default
|
|
3733
|
+
* provider publishes (`defaultPincodeKey`: derived from the default wf-state
|
|
3734
|
+
* secret), so a code minted on one path verifies on the other. Throws
|
|
3735
|
+
* `INVALID_CONFIG` outside a provider when the credential store has no
|
|
3736
|
+
* derivable secret. Override when the workflow runs outside a
|
|
3737
|
+
* `WfTriggerProvider` whose `wfStateSecret()` / `pincodeSecret()` is
|
|
3738
|
+
* overridden — return that provider's key; every instance must agree.
|
|
3739
|
+
*/
|
|
3740
|
+
protected pincodeKey(): Buffer;
|
|
3741
|
+
private fallbackPincodeKey?;
|
|
3453
3742
|
/**
|
|
3454
3743
|
* Validate + stash inline-consent fields submitted on a carrier form.
|
|
3455
3744
|
* SECURITY: silently drops unknown ids (audit-grade defense — see base
|
|
@@ -3491,6 +3780,8 @@ export declare class AuthWorkflow {
|
|
|
3491
3780
|
* and resend.
|
|
3492
3781
|
*/
|
|
3493
3782
|
private mintAndSendEnrollPincode;
|
|
3783
|
+
/** Seconds a resend still has to wait — the state's hint, else a full cooldown. */
|
|
3784
|
+
private resendWaitSeconds;
|
|
3494
3785
|
/**
|
|
3495
3786
|
* Idempotent TOTP secret provisioning into wf-state ONLY (the QR renders
|
|
3496
3787
|
* from `public.mfaEnroll.secret/uri`; the user record is written on confirm
|
|
@@ -3646,6 +3937,17 @@ export declare class AuthWorkflow {
|
|
|
3646
3937
|
*/
|
|
3647
3938
|
initAddMfa(ctx: AuthWfCtx): Promise<undefined>;
|
|
3648
3939
|
credentials(ctx: AuthWfCtx): Promise<unknown>;
|
|
3940
|
+
/**
|
|
3941
|
+
* Bind the login run to the account that passed its first factor — shared
|
|
3942
|
+
* by the password and magic-link sign-ins, so both leave the run alike:
|
|
3943
|
+
* - `ctx.subject` and the password stamp;
|
|
3944
|
+
* - the inline password guards (`ctx.guards`): top-level
|
|
3945
|
+
* `isPasswordInitial` / `isPasswordExpired` (read by
|
|
3946
|
+
* `prepare-semantic-flags` later as a fallback) and the change reason;
|
|
3947
|
+
* - the account's confirmed channels, so `ensureEmail` / `ensurePhone` skip
|
|
3948
|
+
* what is already confirmed and security notices have a recipient.
|
|
3949
|
+
*/
|
|
3950
|
+
private bindSignedInUser;
|
|
3649
3951
|
/**
|
|
3650
3952
|
* Whether a failed password sign-in answers "Account locked" — see
|
|
3651
3953
|
* `AuthWorkflowOpts.lockoutDisclosure`. Under `'uniform'` an unknown or
|
|
@@ -3665,6 +3967,31 @@ export declare class AuthWorkflow {
|
|
|
3665
3967
|
*/
|
|
3666
3968
|
private handleCredentialsAlt;
|
|
3667
3969
|
request(ctx: AuthWfCtx): Promise<unknown>;
|
|
3970
|
+
/**
|
|
3971
|
+
* Start recovery's delivery `mode` — the same way for known and unknown
|
|
3972
|
+
* identifiers:
|
|
3973
|
+
* - `'magicLink'`: the link for the typed identifier, resolved now but held
|
|
3974
|
+
* only in the link's server-side pause (the requester never gets a token
|
|
3975
|
+
* for it, and an earlier picker's state holds nothing about the account);
|
|
3976
|
+
* - `'otp'`: the durable store strategy. Nothing about the account goes into
|
|
3977
|
+
* the state before the code is verified: `pincode-send` /
|
|
3978
|
+
* `pincode-check` resolve it from the typed identifier each time.
|
|
3979
|
+
*/
|
|
3980
|
+
private applyRecoveryMode;
|
|
3981
|
+
/** A recovery magic link for the typed identifier (`subject` unset when it matches no account). */
|
|
3982
|
+
private recoveryMagicLink;
|
|
3983
|
+
/** `emailToUserId`, with an unknown identifier as `undefined`. */
|
|
3984
|
+
private lookupRecoverySubject;
|
|
3985
|
+
/**
|
|
3986
|
+
* The account a recovery code for the typed identifier goes to, and where —
|
|
3987
|
+
* or `null` when no code can go anywhere: an unknown identifier, an inactive
|
|
3988
|
+
* (pending / deactivated) account, or under M2 an account without a
|
|
3989
|
+
* deliverable confirmed channel. A locked account may recover (self-service
|
|
3990
|
+
* unlock). Resolved from `ctx.email` on every send and at verification —
|
|
3991
|
+
* never kept in the state — and with the same reads for every identifier
|
|
3992
|
+
* (an unknown one reads a placeholder row).
|
|
3993
|
+
*/
|
|
3994
|
+
private recoveryAccount;
|
|
3668
3995
|
/**
|
|
3669
3996
|
* Resolves the recovery-step `email` input to the user's stable `id` (the
|
|
3670
3997
|
* token subject). Default: resolves via `findByHandle` (username exact, then
|
|
@@ -3672,8 +3999,6 @@ export declare class AuthWorkflow {
|
|
|
3672
3999
|
* user matches.
|
|
3673
4000
|
*/
|
|
3674
4001
|
protected emailToUserId(email: string): Promise<string | null>;
|
|
3675
|
-
/** Anti-enumeration generic finish envelope used when recovery's `request` step receives an unknown email. */
|
|
3676
|
-
private finishGenericRecovery;
|
|
3677
4002
|
/**
|
|
3678
4003
|
* Stamp `recoveryStateTtlMs` on a paused-state error so the wf engine's
|
|
3679
4004
|
* persisted-state strategy expires the state at that timestamp. Use at
|
|
@@ -4012,6 +4337,13 @@ export declare class AuthWorkflow {
|
|
|
4012
4337
|
*/
|
|
4013
4338
|
confirmRemoveMfa(ctx: AuthWfCtx): Promise<undefined>;
|
|
4014
4339
|
askChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
|
|
4340
|
+
/**
|
|
4341
|
+
* Mint the code proving a channel (`ask/*`, `verify/*`), deliver it when
|
|
4342
|
+
* `deliver`, and arm the PincodeForm: the resend wait `verifyChannel`
|
|
4343
|
+
* gates "Resend code" on (the same cooldown contract as `pincode-send`),
|
|
4344
|
+
* the masked `sentTo` its "Code sent to …" hint renders, and the code length.
|
|
4345
|
+
*/
|
|
4346
|
+
private sendChannelPincode;
|
|
4015
4347
|
verifyChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
|
|
4016
4348
|
/**
|
|
4017
4349
|
* Read the device-trust cookie; if it matches a valid record, set
|
|
@@ -4020,9 +4352,10 @@ export declare class AuthWorkflow {
|
|
|
4020
4352
|
*/
|
|
4021
4353
|
checkTrustedDevice(ctx: AuthWfCtx): Promise<undefined>;
|
|
4022
4354
|
/**
|
|
4023
|
-
* Resolve the client IP from the active HTTP request
|
|
4024
|
-
*
|
|
4025
|
-
*
|
|
4355
|
+
* Resolve the client IP from the active HTTP request — the IP the HTTP app
|
|
4356
|
+
* resolves (its `trustProxy` / `proxyHeaders`), the same one the rate
|
|
4357
|
+
* limiter keys on — swallowing the case where there is no HTTP context
|
|
4358
|
+
* (unit tests that hand-roll the wf runtime).
|
|
4026
4359
|
*/
|
|
4027
4360
|
protected resolveClientIp(): string | undefined;
|
|
4028
4361
|
/**
|
|
@@ -4301,6 +4634,19 @@ export declare class AuthWorkflow {
|
|
|
4301
4634
|
* authorization code. Skipped when this run changed the password itself.
|
|
4302
4635
|
*/
|
|
4303
4636
|
checkPasswordUnchanged(ctx: AuthWfCtx): Promise<undefined>;
|
|
4637
|
+
/**
|
|
4638
|
+
* Login-only guard before the `record-login` funnel: an account deactivated
|
|
4639
|
+
* or locked while the run was paused (MFA, enrolment, consents …) is not
|
|
4640
|
+
* stamped, announced or signed in — the run finishes with an error.
|
|
4641
|
+
*/
|
|
4642
|
+
checkCanSignIn(ctx: AuthWfCtx): Promise<undefined>;
|
|
4643
|
+
/**
|
|
4644
|
+
* Whether the run's account can no longer sign in (deactivated, locked or
|
|
4645
|
+
* deleted since it authenticated). If so the run is finished with an error
|
|
4646
|
+
* (`AOOTH_ACCOUNT_LOCKED` for a lock unless `lockoutDisclosure` is
|
|
4647
|
+
* `'generic'`, else `INVALID_CREDENTIALS`) and `ctx.aborted` is set.
|
|
4648
|
+
*/
|
|
4649
|
+
private loginAccountBlocked;
|
|
4304
4650
|
/**
|
|
4305
4651
|
* The SINGLE login-completion funnel. Every flow that establishes an
|
|
4306
4652
|
* authenticated session routes through here — placed in each login schema
|
|
@@ -4335,6 +4681,14 @@ export declare class AuthWorkflow {
|
|
|
4335
4681
|
* still locked: self-service ran `unlock-account`; temporary auto-expires).
|
|
4336
4682
|
*/
|
|
4337
4683
|
recoveryLockCheck(ctx: AuthWfCtx): Promise<undefined>;
|
|
4684
|
+
/**
|
|
4685
|
+
* Auto-login guard, ahead of `record-login` on every auto-login path (invite,
|
|
4686
|
+
* recovery, signup): never stamp a login, fire `afterLogin` or issue a
|
|
4687
|
+
* session for an account that is no longer active (deactivated meanwhile —
|
|
4688
|
+
* every flow reaching here activated or verified it first). Recovery and
|
|
4689
|
+
* invite fall back to the fresh-login finish (no session); signup fails.
|
|
4690
|
+
*/
|
|
4691
|
+
autoLoginCheck(ctx: AuthWfCtx): Promise<undefined>;
|
|
4338
4692
|
/**
|
|
4339
4693
|
* Thin dispatcher steps for the flow-specific lifecycle hooks. Each is its own
|
|
4340
4694
|
* schema step (rather than an in-terminal call) because its flow's finalize
|
|
@@ -4448,10 +4802,10 @@ export declare class AuthWorkflow {
|
|
|
4448
4802
|
* tokens (WF-INVITE-020).
|
|
4449
4803
|
*
|
|
4450
4804
|
* It records NOTHING and guards NOTHING: `account.lastLogin` + the
|
|
4451
|
-
* `afterLogin` hook are owned by the upstream `record-login` funnel step,
|
|
4452
|
-
* the
|
|
4453
|
-
*
|
|
4454
|
-
* still-frozen account never reaches here.
|
|
4805
|
+
* `afterLogin` hook are owned by the upstream `record-login` funnel step,
|
|
4806
|
+
* the inactive-account guard by `auto-login-check`, and the
|
|
4807
|
+
* admin-only-survived-lock guard by `recovery-lock-check` — all upstream, so
|
|
4808
|
+
* an inactive or still-frozen account never reaches here.
|
|
4455
4809
|
*/
|
|
4456
4810
|
finalizeAutoLogin(ctx: AuthWfCtx): Promise<undefined>;
|
|
4457
4811
|
/**
|
|
@@ -4495,9 +4849,80 @@ export declare class AuthWorkflow {
|
|
|
4495
4849
|
* the freshly-created `ctx.subject`. Mirrors login's `extra-step` seam.
|
|
4496
4850
|
*/
|
|
4497
4851
|
signupExtraStep(_ctx: AuthWfCtx): unknown | Promise<unknown>;
|
|
4498
|
-
|
|
4499
|
-
|
|
4500
|
-
|
|
4852
|
+
/**
|
|
4853
|
+
* Login's `magicLink` alt-action: the identifier form. Resolves the account
|
|
4854
|
+
* (unknown, inactive or locked identifiers resolve to none — the answer is
|
|
4855
|
+
* the same) and hands over to `magic-link-send`.
|
|
4856
|
+
*/
|
|
4857
|
+
magicLinkRequest(ctx: AuthWfCtx): Promise<unknown>;
|
|
4858
|
+
/**
|
|
4859
|
+
* Send a magic link (recovery or sign-in) and pause until it is used. The
|
|
4860
|
+
* pause is persisted under the `magic-link` strategy — a fresh, hashed,
|
|
4861
|
+
* single-use handle that expires with the link (`magicLinkTtlMs`) — and the
|
|
4862
|
+
* `magic-link` outlet hands the token to the email outlet only. Known and
|
|
4863
|
+
* unknown identifiers take the same path and get the same answer; nothing is
|
|
4864
|
+
* sent for an unknown identifier, an account without a proven inbox, a
|
|
4865
|
+
* sign-in the account may not start (inactive, locked), or a repeat within
|
|
4866
|
+
* `mfa.pincodeResendTimeoutMs`. The click resumes here and moves on to the
|
|
4867
|
+
* purpose's verify step.
|
|
4868
|
+
*/
|
|
4869
|
+
magicLinkSend(ctx: AuthWfCtx): Promise<unknown>;
|
|
4870
|
+
/**
|
|
4871
|
+
* Where a magic link may go — an inbox the account proved, or `undefined`
|
|
4872
|
+
* (nothing is sent). Recovery with the typed identifier as destination (M1,
|
|
4873
|
+
* email channel) sends to the typed address, like the recovery code; every
|
|
4874
|
+
* other case sends to the account's proven inbox: `account.verifiedEmail`,
|
|
4875
|
+
* else a confirmed email MFA method — never an unproven address. The account
|
|
4876
|
+
* must be active; a sign-in link also needs it unlocked (a recovery link may
|
|
4877
|
+
* go to a locked account — self-service unlock). Override to change the
|
|
4878
|
+
* destination.
|
|
4879
|
+
*/
|
|
4880
|
+
protected magicLinkAddress(ctx: AuthWfCtx, ml: NonNullable<AuthWfCtx["magicLink"]>): Promise<string | undefined>;
|
|
4881
|
+
/**
|
|
4882
|
+
* The landing step of a clicked link: "Continue as a•••@example.com". Opening
|
|
4883
|
+
* the link (or a mail scanner fetching it) only renders this step — the
|
|
4884
|
+
* pause stays on the link's own handle, so the link still works; it is used
|
|
4885
|
+
* up only when this form is submitted. The masked account lets the user see
|
|
4886
|
+
* which account the link signs into (a forwarded link would be someone
|
|
4887
|
+
* else's).
|
|
4888
|
+
*/
|
|
4889
|
+
magicLinkConfirm(ctx: AuthWfCtx): unknown;
|
|
4890
|
+
/** Name of the cookie binding a sign-in link to the browser that asked for it. */
|
|
4891
|
+
protected magicLinkBrowserCookie(): string;
|
|
4892
|
+
/** Set the browser-binding cookie; returns the hash the link keeps. */
|
|
4893
|
+
private bindMagicLinkBrowser;
|
|
4894
|
+
/** Whether this request carries the browser-binding cookie the link was sent with. */
|
|
4895
|
+
private sameMagicLinkBrowser;
|
|
4896
|
+
/**
|
|
4897
|
+
* A used sign-in link: the FIRST factor only. Re-checks the account
|
|
4898
|
+
* (active, not locked), binds `ctx.subject` and leaves the second factor to
|
|
4899
|
+
* the MFA loop, exactly as after a password. Refuses a link of another
|
|
4900
|
+
* purpose, an expired one, and one sent for no account.
|
|
4901
|
+
*/
|
|
4902
|
+
magicLinkVerified(ctx: AuthWfCtx): Promise<unknown>;
|
|
4903
|
+
/**
|
|
4904
|
+
* A used recovery link: proof of the inbox it went to, exactly like a
|
|
4905
|
+
* verified recovery code — `ctx.otp.verified` set, the inbox recorded as
|
|
4906
|
+
* the account's verified email, and the flow goes on to the new password.
|
|
4907
|
+
* Refuses a link of another purpose, an expired one, one sent for no
|
|
4908
|
+
* account, and one whose account is no longer active.
|
|
4909
|
+
*/
|
|
4910
|
+
recoveryLinkVerified(ctx: AuthWfCtx): Promise<unknown>;
|
|
4911
|
+
/**
|
|
4912
|
+
* The magic link this run was resumed through, checked for `purpose` and
|
|
4913
|
+
* expiry — or `undefined` after emitting the "invalid link" finish. Swaps
|
|
4914
|
+
* off the `magic-link` strategy first, so the link's token is never the
|
|
4915
|
+
* continuation (the next pause gets a fresh handle).
|
|
4916
|
+
*/
|
|
4917
|
+
private usedMagicLink;
|
|
4918
|
+
/** The finish of a link that cannot be used (wrong purpose, expired, no account). */
|
|
4919
|
+
private finishMagicLinkInvalid;
|
|
4920
|
+
/**
|
|
4921
|
+
* Recovery's `'choice'` delivery: the user picks a magic link or a one-time
|
|
4922
|
+
* code. Shown for known and unknown identifiers alike. A one-time code for
|
|
4923
|
+
* an unknown identifier runs the ghost OTP pause, like the default path.
|
|
4924
|
+
*/
|
|
4925
|
+
selectRecoveryMode(ctx: AuthWfCtx): Promise<unknown>;
|
|
4501
4926
|
passkey(_ctx: AuthWfCtx): unknown | Promise<unknown>;
|
|
4502
4927
|
/**
|
|
4503
4928
|
* Verify the OAuth callback and resolve a user. Reaches here (instead of
|
|
@@ -4615,8 +5040,9 @@ export declare class AuthWorkflow {
|
|
|
4615
5040
|
*/
|
|
4616
5041
|
inviteFlow(): void;
|
|
4617
5042
|
/**
|
|
4618
|
-
* recovery.flow —
|
|
4619
|
-
*
|
|
5043
|
+
* recovery.flow — reset by a one-time code or a magic link
|
|
5044
|
+
* (`resolveRecoveryDeliveryMode`). `@Public()` on the body because anonymous
|
|
5045
|
+
* users start recovery.
|
|
4620
5046
|
*/
|
|
4621
5047
|
recoveryFlow(): void;
|
|
4622
5048
|
/**
|
|
@@ -4702,11 +5128,11 @@ export declare class AuthWorkflow {
|
|
|
4702
5128
|
*/
|
|
4703
5129
|
export declare const AOOTH_HTTP_MESSAGES: {
|
|
4704
5130
|
/** 401 — the guard found no credential on a protected route. */
|
|
4705
|
-
readonly
|
|
5131
|
+
readonly AOOTH_AUTH_REQUIRED: "Unauthorized";
|
|
4706
5132
|
/** 401 — the guard's credential is invalid, expired or revoked. */
|
|
4707
|
-
readonly
|
|
5133
|
+
readonly AOOTH_CREDENTIAL_INVALID: "Invalid credential";
|
|
4708
5134
|
/** 401 — `useAuth().getUserId()` and `AuthController` routes without a signed-in user. */
|
|
4709
|
-
readonly
|
|
5135
|
+
readonly AOOTH_NOT_AUTHENTICATED: "Not authenticated";
|
|
4710
5136
|
/** 401 — "log out other sessions" without a current session. */
|
|
4711
5137
|
readonly NO_CURRENT_SESSION: "No current session to keep";
|
|
4712
5138
|
/** 401 — `POST /auth/refresh` without a refresh token. */
|
|
@@ -4718,15 +5144,19 @@ export declare const AOOTH_HTTP_MESSAGES: {
|
|
|
4718
5144
|
/** 404 — `GET /auth/invite/post-redemption` for an unknown or still pending invite. */
|
|
4719
5145
|
readonly INVITE_NOT_FOUND: "Invite not found";
|
|
4720
5146
|
/** 400 — `GET /auth/invite/post-redemption` without `uid`. */
|
|
4721
|
-
readonly
|
|
5147
|
+
readonly AOOTH_MISSING_UID: "Missing uid query parameter";
|
|
4722
5148
|
/** 404 — unlinking an identity the user does not have. */
|
|
4723
5149
|
readonly LINKED_IDENTITY_NOT_FOUND: "Linked identity not found";
|
|
4724
5150
|
/** 409 — unlinking the user's only sign-in method. */
|
|
4725
5151
|
readonly LAST_SIGN_IN_METHOD: "Cannot remove your only sign-in method. Set a password first, or link another provider.";
|
|
4726
5152
|
/** 404 — unlinking an identity of an unconfigured provider. Params: `provider`. */
|
|
4727
|
-
readonly
|
|
4728
|
-
/**
|
|
4729
|
-
readonly
|
|
5153
|
+
readonly AOOTH_UNKNOWN_PROVIDER: "Unknown provider '{provider}'";
|
|
5154
|
+
/** 429 — the one-time codes of this account or address failed too often; answered to every code send and check until the window passes. */
|
|
5155
|
+
readonly AOOTH_CODE_LIMIT_REACHED: "Too many code attempts. Try again later.";
|
|
5156
|
+
/** 403 — the workflow trigger refused a START (outside `allow`, in `resumeOnly`, or `block`ed, or an unregistered id under `allow`). Params: `workflow`. */
|
|
5157
|
+
readonly AOOTH_WORKFLOW_NOT_ALLOWED: "Workflow '{workflow}' is not allowed";
|
|
5158
|
+
/** 403 — a refused RESUME (not in the route's `allow` / `resumeOnly`, or `block`ed). No params: it never names the stored flow. */
|
|
5159
|
+
readonly AOOTH_WORKFLOW_RESUME_NOT_ALLOWED: "Workflow is not allowed";
|
|
4730
5160
|
};
|
|
4731
5161
|
/** A code of {@link AOOTH_HTTP_MESSAGES}. */
|
|
4732
5162
|
type AoothHttpMessageCode = keyof typeof AOOTH_HTTP_MESSAGES;
|
|
@@ -4742,6 +5172,27 @@ interface AuthEmailOutletDeps {
|
|
|
4742
5172
|
* `handleWfOutletRequest({ outlets })`.
|
|
4743
5173
|
*/
|
|
4744
5174
|
export declare function createAuthEmailOutlet(deps: AuthEmailOutletDeps): WfOutlet;
|
|
5175
|
+
/** Name of the outlet `AuthWorkflow` pauses on to send a recovery or sign-in magic link. */
|
|
5176
|
+
export declare const MAGIC_LINK_OUTLET = "magic-link";
|
|
5177
|
+
/**
|
|
5178
|
+
* Name of the state strategy a magic link's pause is persisted under
|
|
5179
|
+
* (registered by `WfTriggerProvider`). Its own keyspace makes the trigger mint
|
|
5180
|
+
* a fresh handle for the link, and the next pause swaps off it again — so the
|
|
5181
|
+
* emailed token is consumed by its first use and never becomes the
|
|
5182
|
+
* continuation of the flow.
|
|
5183
|
+
*/
|
|
5184
|
+
export declare const MAGIC_LINK_STRATEGY = "magic-link";
|
|
5185
|
+
/**
|
|
5186
|
+
* The `magic-link` outlet (registered by default on `WfTriggerProvider`). The
|
|
5187
|
+
* step decides whether a link goes out (`context.deliver`); when it does, the
|
|
5188
|
+
* link is handed to the app's `email` outlet (`createAuthEmailOutlet`) with
|
|
5189
|
+
* the step's template (`recovery.magicLink` / `login.magicLink`). Known and
|
|
5190
|
+
* unknown identifiers get the same answer, and a failed delivery is logged,
|
|
5191
|
+
* not reported — the response never says whether an account exists.
|
|
5192
|
+
*
|
|
5193
|
+
* @param emailOutlet - resolves the app's `email` outlet at delivery time.
|
|
5194
|
+
*/
|
|
5195
|
+
export declare function createMagicLinkOutlet(emailOutlet: () => WfOutlet | undefined): WfOutlet;
|
|
4745
5196
|
/**
|
|
4746
5197
|
* Audit event emitter — used by `AuthWorkflow`'s audit-login step (and
|
|
4747
5198
|
* future recovery / invite audit steps) to fan out login.success and similar
|
|
@@ -4767,4 +5218,4 @@ interface AuditEvent {
|
|
|
4767
5218
|
interface AuditEmitter {
|
|
4768
5219
|
emit(event: AuditEvent): Promise<void> | void;
|
|
4769
5220
|
}
|
|
4770
|
-
export { type AoothHttpMessageCode, type AoothMessageCode, type AoothMessageParams, type AoothMessages, type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, type AuthDeliveryPayload, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type AuthWfCompletionState, type AuthWfConsentsState, type AuthWfCtx, type AuthWfMfaEnrollState, type AuthWfOAuthState, type AuthWfPasswordUiState, type AuthWfPincodeUiState, type AuthWorkflowOpts, type AuthorizationServerMetadata, type AuthzReauthPolicy, type BuildAuthorizationServerMetadataOptions, type BuildMagicLinkUrl, type BuildProtectedResourceMetadataOptions, type ConcurrencyLimitOptions, type ConnectedAccount, type ConsentDescriptor, type ConsentDescriptorLike, type ConsentEvent, DynamicClientRegistration, type DynamicClientRegistrationOptions, type EmailSender, type EnrichedSession, type IssueResult, type LoginRedirect, type MfaSummary, type MfaTransport, type ProtectedResourceMetadata, type RateLimitBindings, type RateLimitDecision, type RateLimitDecoratorOptions, type RateLimitInterceptorOptions, type RateLimitKeyStrategy, type RateLimitRule, type RateLimitRuleInput, type RateLimitStore, RateLimitStoreMemory, RateLimiter, type RateLimiterOptions, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedAuthWorkflowOpts, type SessionEnricher, type SessionInfo, type SetPasswordCopy, type SmsSender, type SsoProvider, type TAuthMeta, type TRateLimitMeta, type UserAuthErrorBody, type WfTriggerHooks, type WfTriggerOpts, type WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, generateMagicLinkToken };
|
|
5221
|
+
export { type AoothHttpMessageCode, type AoothMessageCode, type AoothMessageParams, type AoothMessages, type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, type AuthDeliveryPayload, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type AuthWfCompletionState, type AuthWfConsentsState, type AuthWfCtx, type AuthWfMagicLinkState, type AuthWfMfaEnrollState, type AuthWfOAuthState, type AuthWfPasswordUiState, type AuthWfPincodeUiState, type AuthWfRecoveryDeliveryMode, type AuthWorkflowOpts, type AuthorizationServerMetadata, type AuthzReauthPolicy, type BuildAuthorizationServerMetadataOptions, type BuildMagicLinkUrl, type BuildProtectedResourceMetadataOptions, type ConcurrencyLimitOptions, type ConnectedAccount, type ConsentDescriptor, type ConsentDescriptorLike, type ConsentEvent, DynamicClientRegistration, type DynamicClientRegistrationOptions, type EmailSender, type EnrichedSession, type InvitePeek, type IssueResult, type LoginRedirect, type MfaSummary, type MfaTransport, type ProtectedResourceMetadata, type RateLimitBindings, type RateLimitDecision, type RateLimitDecoratorOptions, type RateLimitInterceptorOptions, type RateLimitKeyStrategy, type RateLimitRule, type RateLimitRuleInput, type RateLimitStore, RateLimitStoreMemory, RateLimiter, type RateLimiterOptions, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedAuthWorkflowOpts, type SessionEnricher, type SessionInfo, type SetPasswordCopy, type SmsSender, type SsoProvider, type TAuthMeta, type TRateLimitMeta, type UserAuthErrorBody, type WfTriggerHooks, type WfTriggerOpts, type WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, generateMagicLinkToken };
|