โ๏ธ Authentication handlers
Authentication handlers are route-pipeline functions, not Express middleware. They read RouteHandlerPayload values from params and context, merge successful values into context.data, or terminate a successful Result with an HTTP response descriptor.
Inventoryโ
| Handler | Pipeline role | Inputs / context | Result / behavior / errors | Used by routes |
|---|---|---|---|---|
TARGET_CONFIRM_EMAIL | Constant | N/A | Exact 'confirm-email' target. | Custom composition only |
TARGET_CHANGE_EMAIL | Constant | N/A | Exact 'change-email' target. | Custom composition only |
loginTerminator | Deprecated terminator | context.data.identity, access token, refresh token | Returns the legacy Bearer login body or throws the prior error. | Custom composition only |
setResponseCookie | Deprecated handler | Response, tokens, configuration | Sets access/refresh cookies; missing response is 500. | loginWithCredentialsRoute, verifyMfaCodeRoute, refreshTokenRoute, loginWithOnetimeTokenRoute |
loginWithCredentials | Deprecated handler | Credentials, identities, failure configuration | Writes identity; locked or incorrect credentials are 401. | loginWithCredentialsRoute |
createAccessToken | Deprecated handler | Request security data, identity ID, access-token configuration | Writes accessToken; generation failure is 500. | loginWithCredentialsRoute, verifyMfaCodeRoute, loginWithOnetimeTokenRoute |
createRefreshToken | Deprecated handler | Request security data, identity ID, refresh-token configuration | Stores a refresh record and writes refreshToken; generation failure is 500. | loginWithCredentialsRoute, verifyMfaCodeRoute, loginWithOnetimeTokenRoute |
logoutTerminator | Deprecated terminator | Prior pipeline result | Returns {statusCode: 204} or throws the prior error. | logoutRoute |
logout | Deprecated handler | Request/response, selected authenticator, token configuration, identities | Clears cookies and revokes the presented refresh token. | logoutRoute |
registerTerminator | Deprecated terminator | Registered identity data | Returns {email, id, statusCode: 201} or throws. | registerCredentialsRoute |
registerCredentials | Deprecated handler | Registration/invitation email, password, identities | Creates and writes identity; returns 400, 422, or 500 failures. | registerCredentialsRoute |
refreshToken | Deprecated handler | Request, secrets, token lifetimes, identities | Revokes the old refresh record and writes a rotated token pair. | refreshTokenRoute |
checkToken | Deprecated handler | Body token, optional target, request security data, one-time-token store | Writes identityId or tokenInfo; may consume a one-time token. | registerCredentialsRoute, confirmEmailRoute |
deleteToken | Deprecated handler | Bearer/cookie token and requested identity ID | Soft-deletes identity/token records after transport and ownership checks. | Custom composition only |
loginWithOnetimeToken | Deprecated handler | Body token, secrets, identities, one-time-token store | Consumes a login-target token and writes identity. | loginWithOnetimeTokenRoute |
generateOnetimeToken | Deprecated handler | Token data/target/fingerprint, request, secrets, store | Stores and writes token; returns 400 or 500 failures. | generateOnetimeTokenRoute |
restoreOnetimeToken | Handler | Body token, secrets, one-time-token store | Requires a stateful token, clears invalid, and writes token. | restoreOnetimeTokenRoute |
invalidateOnetimeToken | Handler | Token/fingerprint, secrets, one-time-token store | Requires a stateful token, sets invalid, and writes token. | invalidateOnetimeTokenRoute |
confirmEmailTerminator | Terminator | context.data.confirmEmail | Returns {statusCode: 204}; missing confirmation is 500. | confirmEmailRoute |
confirmEmail | Deprecated handler | context.data.tokenInfo.identityId, identities | Sets emailVerified: true and writes confirmEmail. | confirmEmailRoute |
buildCheckConfirmEmailTokenPayload | Handler | Pipeline payload | Writes checkToken.target: 'confirm-email'. | confirmEmailRoute |
sendVerificationEmailTerminator | Deprecated terminator | Send result and generated token | Returns {statusCode: 204}; missing data is 500. | sendVerificationEmailRoute |
sendVerificationEmail | Deprecated handler | Identity ID, verification/mail configuration, request, stores | Generates, stores, and mails a token; writes send result and token. | sendVerificationEmailRoute |
Detailsโ
TARGET_CONFIRM_EMAILโ
Implementation
The handler-level literal 'confirm-email'. No exported Authentication route reads this export directly; buildCheckConfirmEmailTokenPayload closes over it. Prefer the block target helper in new custom compositions.
TARGET_CHANGE_EMAILโ
Implementation
The handler-level literal 'change-email'. No exported Authentication route composes it directly. Prefer the block target helper in new custom compositions.
loginTerminatorโ
Implementation
Deprecated signature: (Result<RouteHandlerPayload, Error>) => {accessToken, id, refreshToken}. It throws an error result and otherwise reads context.data.accessToken, refreshToken, and identity.id. No exported route uses it; mode-aware normalizers and orThrow now terminate login routes.
setResponseCookieโ
Implementation
Deprecated async handler. It reads context.response, context.data.accessToken, context.data.refreshToken, and cookie configuration through withCookieOptDefaults. An access token also sets Access-Control-Allow-Credentials: true; each present token is set in its named cookie. Missing response returns NodeblocksError(500), otherwise the payload is unchanged. Used by loginWithCredentialsRoute, verifyMfaCodeRoute, refreshTokenRoute, and loginWithOnetimeTokenRoute.
loginWithCredentialsโ
Implementation
Deprecated async handler. It reads email/password from params.requestBody, falling back to context.data, queries context.db.identities, and uses configuration.maxFailedLoginAttempts with a local default of 5. A valid unlocked identity resets attempts and locked, then writes context.data.identity. A valid but locked identity and incorrect credentials return 401; an incorrect password increments attempts and locks at the threshold. Used by loginWithCredentialsRoute.
createAccessTokenโ
Implementation
Deprecated async handler. It reads request host/IP/user-agent, fingerprint from body or pipeline data, and identity ID from body, pipeline data, context.identity, or context.data.identity. It signs with configuration.authSecrets and accessTokenSignOptions, then writes context.data.accessToken. A thrown generator is logged and returned as 500. Used by the credential-login, MFA-verification, and one-time-login routes linked in the inventory.
createRefreshTokenโ
Implementation
Deprecated async handler. It resolves identity ID and fingerprint from the same pipeline locations as createAccessToken, generates a JTI and refresh token, and inserts the refresh record into db.identities with the identity ID reused as the record id. It writes context.data.refreshToken; a false token result is 500, while source does not catch insert/generation exceptions. Used by the credential-login, MFA-verification, and one-time-login routes linked above.
logoutTerminatorโ
Implementation
Deprecated terminator. It throws an error result and returns exactly {statusCode: 204} for success. It is final in logoutRoute.
logoutโ
Implementation
Deprecated async handler. It clears both session cookies using configured defaults without maxAge/expires, calls context.authenticate or the Bearer fallback, and resolves the refresh token from the request. No refresh token is an idempotent success; a mismatch between access and refresh identities is 401. It marks the matching JTI record deleted, treats an already deleted record as success, and returns 500 when revocation cannot be applied or throws. Used by logoutRoute.
registerTerminatorโ
Implementation
Deprecated terminator. It throws an error result and otherwise reads context.data.email and id, returning {email, id, statusCode: 201}. registerCredentialsRoute uses it after registration and optional invitation acceptance.
registerCredentialsโ
Implementation
Deprecated async handler. Email comes from context.data.invitation.email or the request body; password comes from the body. Missing values are 400, an existing identity is 422, lookup failures are 500, a missing inserted ID is 400, and hashing/insertion failures are 500. Success creates a base identity with attempts: 0, locked: false, a hashed password, and writes {identity: {email, id}}. Used by registerCredentialsRoute.
refreshTokenโ
Implementation
Deprecated async handler. It derives request verification data, resolves a Bearer-body or cookie refresh token, requires identityId and JTI, rejects absent/reused/deleted records with 401, and returns 422 when no token is found. It revokes exactly one old record (400 if not modified), inserts a replacement record (500 if insertion throws), generates both tokens, and writes context.data.accessToken and refreshToken. Used by refreshTokenRoute.
checkTokenโ
Implementation
Deprecated handler; this is not the block with the same name. It reads params.requestBody.token, context.data.checkToken.target, request host/IP/user-agent/fingerprint, secrets, and db.onetimetokens. A valid access token must pass security checks with IP checking forced on and writes identityId. A matching active one-time token is invalidated and writes its data as tokenInfo. Verification/security/target failures are 400, final validation failure is 401, and database calls are not caught locally. Used by the invitation branch of registerCredentialsRoute and by confirmEmailRoute; checkTokenRoute instead calls the block export.
deleteTokenโ
Implementation
Deprecated custom-composition handler. It independently attempts cookie and Bearer extraction, requires at least one (401), and requires both decoded values to match when both exist (422). The target identity comes from pipeline data, request body, or query (400 if absent). App tokens may delete the requested identityโs records; user tokens may delete only their own (401 otherwise). It merges no new data and has no exported Authentication route consumer.
loginWithOnetimeTokenโ
Implementation
Deprecated async handler. It reads the body token, verifies an 'onetime' token, requires an active stored record, invalidates it, re-verifies the stored token, requires target 'login', and loads the referenced identity. Wrong type/target or missing/invalid stored token is 403, missing identity is 404, and any thrown operation is collapsed to 401. Success writes context.data.identity. Used by loginWithOnetimeTokenRoute.
generateOnetimeTokenโ
Implementation
Deprecated async handler. Fingerprint, target, and token data resolve from context.data, direct context, then request body; tokenData must be an object (400). It builds verification data from the request, generates the token, stores {invalid: false, token} in db.onetimetokens, and writes context.data.token. A false token or thrown insert is 500; a missing inserted ID is 400. Used by generateOnetimeTokenRoute.
restoreOnetimeTokenโ
Implementation
Async handler. It reads params.requestBody.token, decrypts it with configured secrets, and requires the decoded stateful flag. Decrypt failure is 401, a non-stateful token is 422, and a thrown database update is 500. It sets every matching stored token to invalid: false and writes context.data.token; zero matches still succeed. Used by restoreOnetimeTokenRoute.
invalidateOnetimeTokenโ
Implementation
Async handler. Token and fingerprint resolve from pipeline data, direct context, then request body. Either missing value, decrypt failure, or a non-stateful token is 422; a thrown update is 500. It sets every matching stored token to invalid: true and writes context.data.token; zero matches still succeed. Used by invalidateOnetimeTokenRoute.
confirmEmailTerminatorโ
Implementation
Terminator for confirmEmailRoute. It throws a prior error, requires truthy context.data.confirmEmail, throws NodeblocksError(500) when that result is missing, and otherwise returns exactly {statusCode: 204}.
confirmEmailโ
Implementation
Deprecated async handler. It reads context.data.tokenInfo.identityId, requiring a string (403), and sets emailVerified: true on the matching identity. No match is 404, no modification is 409, and a thrown update is 500. Success writes the update result as context.data.confirmEmail. Used by confirmEmailRoute.
buildCheckConfirmEmailTokenPayloadโ
Implementation
Async handler that cannot fail: it writes context.data.checkToken.target as the handler-level TARGET_CONFIRM_EMAIL constant and otherwise preserves the payload. It precedes the handler checkToken in confirmEmailRoute.
sendVerificationEmailTerminatorโ
Implementation
Deprecated terminator for sendVerificationEmailRoute. It throws a prior error, requires both truthy context.data.sendVerificationEmail and context.data.token, throws NodeblocksError(500) when either is absent, and otherwise returns {statusCode: 204}.
sendVerificationEmailโ
Implementation
Deprecated async handler. Identity ID resolves from context.data.identityId, path params, then context.data.identity.id. It requires the feature to be enabled, a mail service, and body/subject/URL configuration (400), loads an identity (404) with email (400), builds request-bound confirmation-token verification data, generates and stores the token, and sends the message. Token-generation failure is 501; false delivery or any caught operation is 500. Success writes context.data.sendVerificationEmail and token. Used by sendVerificationEmailRoute.