Skip to content

auth-email-password

Provides email+password authentication: the always-on handlers are login, changePassword, and logout; optional flows — password reset, email verification, magic-link self-signup, tenant invite, and account-unlock — are registered only when you pass their respective option objects (passwordReset, emailVerification, signup, invite, accountUnlock) to createAuthEmailPasswordFeature(opts). All five magic-link flows dispatch their mail through the delivery feature via ctx.notify, so mounting any of them additionally requires delivery. Tokens are HMAC-signed (reset/verify/unlock) or opaque-random in Redis (signup/invite). accountUnlock is the self-service escape hatch for accountLockout’s monotonic failure-counter (#1266): confirming the mailed token clears the Redis lockout state without touching the user entity. Requires the user and tenant features, and declares JWT_SECRET (≥ 32 chars) in authEmailPasswordEnvSchema so a missing secret surfaces at boot validation rather than on the first login attempt.

From recipes-apex-surface-auth — the smallest working mount:

// apex-surface-auth recipe — the evident way for public apex content.
//
// A Kumiko app has a public apex presence (landing/login) AND a
// schema-driven admin UI. The admin UI mounts via createKumikoApp (full
// schema). The apex mounts via createPublicSurface — schema-LESS, anonymously
// reachable, no admin nav/topology leak. Both share locale + primitives.
//
// This recipe shows:
// 1. Server: the feature composition for the 4 account flows + the anonymous,
// email-verified deletion flow (lockout-safe).
// 2. Client (comment below + README): how createPublicSurface + AuthShell
// mount the screens in the apex chrome.
//
// CLIENT-WIRING (the app's apex.tsx — renderer/web, only a reference here, since
// recipes pull in no browser deps):
//
// import {
// ForgotPasswordScreen, SignupScreen, createLoginRoute,
// AuthShellProvider, emailPasswordClient,
// } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
// import {
// RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
// defaultTranslations as deletionI18n,
// } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
// import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
//
// // AuthShell: the auth card renders inside the marketing chrome instead of
// // fullscreen. Default (without a provider) stays the fullscreen wrapper.
// const shell = ({ children }) => (
// <MarketingChrome>
// <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
// {children}
// </AuthShellProvider>
// </MarketingChrome>
// );
//
// // createLoginRoute — do NOT render LoginScreen directly: the route
// // needs the challenge-swap logic for a second factor. Without it
// // (e.g. a raw <LoginScreen />) an MFA-enrolled user gets stuck at login
// // as soon as the app mounts auth-mfa at some point. If the app mounts
// // auth-mfa, add `mfaVerifyScreen: MfaVerifyScreen` (from
// // "@cosmicdrift/kumiko-bundled-features/auth-mfa/web").
// const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
//
// createPublicSurface({
// clientFeatures: [emailPasswordClient()], // bringt SessionProvider + i18n
// shell,
// routes: [
// { path: "/login", component: <LoginRoute /> },
// { path: "/signup", component: <SignupScreen loginHref="/login" /> },
// { path: "/forgot-password", component: <ForgotPasswordScreen loginHref="/login" /> },
// { path: "/delete-account", component: <RequestAccountDeletionScreen /> },
// { path: "/delete-account/confirm", component: <ConfirmAccountDeletionScreen /> },
// ],
// fallback: <LoginRoute />,
// });
//
//
// SERVER-WIRING: the app enables `anonymousAccess` (defaultTenantId = the
// apex host tenant) so /api/write reaches the anonymous deletion handlers:
//
// runProdApp({ features: composeApexAccountApp({ ..., mailTransport }), envSchema,
// anonymousAccess: { defaultTenantId: APEX_TENANT_ID } })
//
// The deletion verify mail is sent by user-data-rights itself through delivery
// + channel-email (after commit, localized template); the app only supplies the
// mail transport.
import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
import {
createChannelEmailFeature,
type EmailTransport,
} from "@cosmicdrift/kumiko-bundled-features/channel-email";
import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
import { createRendererMailHtmlFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-mail-html";
import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
export type ApexAccountAppOptions = {
/** HMAC secret for the deletion verify token. */
readonly deletionTokenSecret: string;
/** Apex route of the confirm screen; the handler appends the token as a
* URL fragment (`#token=`). */
readonly deletionVerifyUrl: string;
/** Transport for the deletion verify mail (SMTP in prod, createInMemoryTransport in tests). */
readonly mailTransport: EmailTransport;
};
// Full feature composition for the public account flows. The
// user-data-rights options enable the anonymous deletion flow; the remaining
// features provide login/register/PW (auth-email-password) + the
// require chain (user-data-rights → data-retention + compliance-profiles +
// sessions).
export function composeApexAccountApp(opts: ApexAccountAppOptions): FeatureDefinition[] {
return [
createConfigFeature(),
createUserFeature(),
createTenantFeature(),
createAuthEmailPasswordFeature(),
createDataRetentionFeature(),
createComplianceProfilesFeature(),
createAuthFoundationFeature(),
createPersonalAccessTokensFeature({ scopes: {} }),
createSessionsFeature(),
createUserDataRightsFeature({
deletionTokenSecret: opts.deletionTokenSecret,
deletionVerifyUrl: opts.deletionVerifyUrl,
mailDefaults: { appName: "Apex Account" },
}),
createDeliveryFeature(),
createChannelEmailFeature({ transport: opts.mailTransport, resolveEmail: async () => null }),
createTemplateResolverFeature(),
createRendererFoundationFeature(),
createRendererMailHtmlFeature(),
];
}

📄 On GitHub: samples/recipes/apex-surface-auth/src/feature.ts

auth-email-password feature preview

What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).

flowchart TB
  n_auth_email_password["auth-email-password"]
  subgraph how_reqs["Requires"]
    n_user["user"]
    n_tenant["tenant"]
    n_delivery["delivery"]
  end
  subgraph how_provides["Provides"]
    n_cmd_auth_email_password_write_change_password(["change-password"])
    n_cmd_auth_email_password_write_confirm_account_unlock(["confirm-account-unlock"])
    n_cmd_auth_email_password_write_invite_accept(["invite-accept"])
    n_cmd_auth_email_password_write_invite_accept_with_login(["invite-accept-with-login"])
    n_cmd_auth_email_password_write_invite_create(["invite-create"])
    n_cmd_auth_email_password_write_invite_signup_complete(["invite-signup-complete"])
    n_cmd_more(["+11 more"])
  end
  n_user --> n_auth_email_password
  n_tenant --> n_auth_email_password
  n_delivery --> n_auth_email_password
  n_auth_email_password --> n_cmd_auth_email_password_write_change_password
  n_auth_email_password --> n_cmd_auth_email_password_write_confirm_account_unlock
  n_auth_email_password --> n_cmd_auth_email_password_write_invite_accept
  n_auth_email_password --> n_cmd_auth_email_password_write_invite_accept_with_login
  n_auth_email_password --> n_cmd_auth_email_password_write_invite_create
  n_auth_email_password --> n_cmd_auth_email_password_write_invite_signup_complete
  n_auth_email_password --> n_cmd_more

Provides — write commands this feature registers (dispatch them through the command bus):

Start with recipes-apex-surface-auth for a step-by-step walkthrough with runnable code and integration tests.