@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -0,0 +1,143 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Credential-carrying auth handlers are hidden from the agent catalog; additionalAssignableRoles rejects framework-ranked roles",
+    "detail": "The credential-carrying handlers `auth-email-password:login`, `change-password`, `user-profile:change-email`, `auth-mfa:verify` and `auth-mfa:enable-confirm-preauth` are now opted out of the agent tool catalog with `agent: { expose: false }`, so passwords, TOTP codes and setup tokens no longer reach an LLM transcript. `invite.additionalAssignableRoles` now throws at construction when it lists a framework-ranked role such as `TenantAdmin`, instead of silently disabling the elevation guard for it."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Invite accept handles MFA responses, bootstrap error screen offers Sign out",
+    "detail": "`InviteAcceptScreen` no longer redirects to a tenant URL when the accept route answers with an MFA challenge or setup requirement (no session cookie was minted); it sends the user to `loginHref` instead. `SessionBootstrapErrorScreen` accepts an optional `onSignOut` and the auth gate wires it, so a permanent bootstrap failure no longer traps the user behind \"Try again\" (new i18n key `auth.sessionBootstrap.signOut`). Cap bookings back off with a small random delay between version-conflict retries."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Ended session leads back to the login screen",
+    "detail": "When the server ends a session (revoked, expired), the app now shows the login screen with a short hint instead of a raw error banner. After signing in again the user lands on the same screen as before."
+  },
+  {
+    "version": "0.328.1",
+    "type": "fix",
+    "title": "Accepting an invitation grants the invited role to existing members of the tenant",
+    "detail": "`invite-accept` and `invite-accept-with-login` used to skip the membership write when the user already belonged to the invited tenant, so a member without roles who accepted an invitation kept no roles and saw no accessible screen. The invited role is now added to the existing membership through the event-store executor. Existing roles are kept, because accepting an invitation never demotes. `invite-accept-with-login` builds the session from the resulting membership roles and rejects a reserved invitation role on this path with 403, the same as the other invite branches. An invitation issued before a later change to the membership is rejected with 409 and `TenantErrors.invitationSuperseded`; re-sending the invitation issues it anew. Removing a member cancels their open invitations in that tenant."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "User menu and tenant menu items fit the new shell",
+    "detail": "The web user menu and tenant menu items are adapted to the sidebar footer user block, which now hosts the tenant, language and theme controls."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "New anonymous invite-info lookup route; invite-accept-with-login now returns invalid_credentials for a wrong or missing password",
+    "detail": "POST /auth/invite-info ({token} -> {email, hasAccount}) lets an invite-acceptance page pre-fill the email and show a login-vs-signup form without consuming the token; it 422s invalid_invite_token for any unknown/non-pending token, same as the accept routes. invite-accept-with-login's wrong-password and no-password-set branches now return 422 invalid_credentials instead of collapsing into invalid_invite_token — safe to reveal because reaching that branch already required a valid, open invite token plus the matching invitation email.",
+    "migration": "No action needed for apps using createAuthEmailPasswordFeature's default wiring via runProdApp/runDevApp — the new route only mounts when the host app's auth-routes config sets invite.infoHandler (runProdApp/runDevApp now do this automatically when the invite feature is enabled). A client that special-cased invite-accept-with-login's invalid_invite_token response to also mean \"wrong password\" should switch to matching invalid_credentials for that case."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "AuthPaths entries accept a locale function, not just a plain path",
+    "detail": "AuthPaths (and DEFAULT_AUTH_PATHS/makeAuthPaths) previously typed every entry as a plain string, so an app needing a locale-in-path reset link (/de/reset-password) had to set auth.passwordReset explicitly instead of auth.mail.paths — and since that block requires its own hmacSecret, the app ended up threading its own secret instead of the one auth.mail resolves, decoupling reset-token signing from that secret's rotation. Each AuthPaths entry now accepts a plain path or a (locale) => path function, mirroring the appUrl shape every flow's options already take, so a locale-aware reset link needs only auth.mail.paths.resetPassword, never a hand-rolled passwordReset block."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "auth routes return a server-computed landingPath from auth.postAuthLanding",
+    "detail": "`AuthRoutesConfig.postAuthLanding` lets an app resolve, in one server-side place, where a user lands after auth instead of every frontend screen re-deriving it from roles/tenantId. The resolver runs for login, mfa-verify, mfa-preauth-confirm, signup-confirm, and all three invite-accept branches, and its result is validated (root-relative only, no protocol-relative/backslash/control-character paths, no cross-origin resolution) before it is ever added to the response as `landingPath`. An invalid path or a throwing resolver just omits the field — auth never fails because of it.\n`run-prod-app`'s and `run-dev-app`'s auth options now accept `postAuthLanding` and thread it through to the framework config unchanged.\n`SignupCompleteScreen` and `InviteAcceptScreen` now prefer the server's `landingPath` over their `loggedInHref` prop, which becomes a deprecated per-app fallback for apps that haven't configured a resolver yet.\nCloses #3320."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "SignupCompleteScreen passes the claimed handover to loggedInHref",
+    "detail": "The function form of `loggedInHref` on `SignupCompleteScreen` now receives\nan optional `handover: { entityType, id }` next to `tenantKey`/`roles`,\nmirroring the `handover` field `confirmSignup` already returns when a\ntry-first tenant-handover grant was claimed during signup. Apps can route a\nfreshly activated user straight to the entity they claimed (offlot-app#454)\ninstead of a fixed landing page. The string form and callers that ignore the\nextra field are unaffected."
+  },
+  {
+    "version": "0.313.0",
+    "type": "improvement",
+    "title": "magic-link self-signup can now claim a try-first tenant-handover grant across devices",
+    "detail": "An anonymous visitor's tenant-handover grant (packages/bundled-features/src/\ntenant-handover) lives only in the browser that minted it, but the signup\nactivation link is often opened somewhere else (a different device, or the\nmail app's in-app browser) — the grant never reaches signup-confirm there.\nrequestSignup(email, handover?) can now pass { entityType, token } alongside\nthe email; signup-request verifies the grant against its anchor row\n(read-only, tenant-handover's own redeemRowBoundGrant with commitAnchor\nskipped) and binds only { entityType, rowId, sourceTenantId } to the signup\ntoken in Redis — never the grant token or the email. A resend without a\nfresh grant carries the previous verified binding to the new token instead\nof dropping it. signup-confirm reads the binding after provisioning the new\ntenant, mints a fresh short-lived (5 min) grant server-side, and redeems it\nvia the same claim write tenant-handover already exposes — riding the\nconfirm handler's own transaction. A benign rejection (already claimed\nelsewhere, forged grant, row gone) never fails the signup; any other claim\nfailure (e.g. a non-transferable child row) rolls the whole signup back and\nleaves the activation link retryable, instead of committing a partial move\nnext to a new account. On success\nthe signup-confirm response gains an optional `handover: { entityType, id }`\nfield; auth-client's confirmSignup result type reflects it. New extension\npoint `signupHandover` (packages/bundled-features/src/shared/signup-handover.ts)\nlets tenant-handover provide this without auth-email-password importing it\ndirectly; tenant-handover self-registers as its own provider."
+  },
+  {
+    "version": "0.309.0",
+    "type": "fix",
+    "title": "Boot admin seed no longer duplicates the admin when the email blind-index lookup misses (fw#3101)",
+    "detail": "runProdApp and runDevApp used to call the unguarded `seedAdmin`, whose idempotency check is a plain email fetchOne that the query layer rewrites into `(email = $plaintext OR email_bidx = $hmac)` once a blind-index key is configured. Under KMS encryption `email` holds per-row ciphertext, so only the bidx arm can ever match — and it misses whenever a row's `email_bidx` is NULL (written before the key existed, or after a subject-key erase), silently inserting a second admin account for the same email. Both boot paths now call `seedAdminGuarded`, which under KMS decrypt-scans the active users for the email and reuses the oldest matching row instead of duplicating it. `seedAdminGuarded` also now aborts with a named error if a PII KMS is configured but no blind-index key is — that combination makes the lookup blind by construction — and reconciles `emailVerified: true` onto the existing row it resolves through the decrypt-scan branch, matching the existing-row reconcile `seedUser` already does on its own idempotency hit."
+  },
+  {
+    "version": "0.307.0",
+    "type": "improvement",
+    "title": "Anonymous signup-confirm and invite-signup-complete (auth-email-password) and verify / enable-confirm-preauth (auth-mfa) declare personalData: public-intake, since they write personal data through a TenantDb derived from ctx.db.unsafeRaw (fw#3185)"
+  },
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "Session bootstrap failures now render a retryable error screen instead of hanging on \"loading\"",
+    "detail": "fetchTenants()/fetchCurrentUser() failures (rate limit, 5xx, network)\nused to reject out of the session bootstrap effect and leave the UI on\nthe loading placeholder forever. SessionStatus gained an \"error\" value\nand SessionState gained a bootstrapFailure field; the auth gate now\nrenders SessionBootstrapErrorScreen with a Retry-After-aware retry\nbutton for this case.",
+    "migration": "Code with an exhaustive switch over SessionStatus, or tests/stories that\nhand-build a SessionState literal, needs to add the \"error\" case and the\nbootstrapFailure field. refresh() no longer rejects on bootstrap\nfailures; it resolves and sets status to \"error\" instead."
+  },
+  {
+    "version": "0.300.0",
+    "type": "breaking",
+    "title": "auth handlers switch from GUEST_USER (roles: [\"all\"]) to the anonymous identity with a per-IP rateLimit",
+    "migration": "The auth-email-password and auth-mfa handlers reachable from unauthenticated /auth/* routes (login, invite-accept-with-login, invite-signup-complete, reset-password, signup-confirm, verify-email, confirm-account-unlock, signup-request, the token-request handlers, mfa verify, mfa enable-start-preauth, mfa enable-confirm-preauth) now declare access: { roles: [\"anonymous\"] } instead of access: { roles: [\"all\"] }, each with its own rateLimit: { per: \"ip+handler\", limit, windowSeconds }. Enforcing that rateLimit on a request that carries a client IP requires a RateLimitResolver (Redis), same as the already rate-limited self-registration-status query; without one these handlers fail with InternalError (fail-closed, #1467). The password-reset, email-verification and account-unlock request routes keep answering 200 for anti-enumeration, so there the failure shows up as a \"[kumiko] token request handler ... failed\" error log line and no mail is sent. Wire Redis (or context.rateLimit) before relying on these routes. Test fixtures that hand-roll a guest SessionUser with roles: [\"all\"] must switch to roles: [\"anonymous\"] (or createAnonymousUser from @cosmicdrift/kumiko-framework/engine)."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "loggedInHref callbacks on SignupCompleteScreen and InviteAcceptScreen now receive the roles granted by the flow",
+    "detail": "Apps can route a freshly activated user to a screen their role can actually open, instead of a fixed path that may render Access denied. The string form of loggedInHref is unchanged; the function form gains a roles field next to the existing tenantKey/tenantId."
+  },
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "lockout-store and signup/invite-token-store now delegate to shared/lockout-counter and shared/single-use-token-store",
+    "detail": "No behavior change — same exported function/type names and Redis key prefixes as before the extraction."
+  },
+  {
+    "version": "0.218.0",
+    "type": "improvement",
+    "title": "Self-signup provisions TenantAdmin on the new tenant",
+    "detail": "INITIAL_SIGNUP_ROLES is TenantAdmin (was Admin) so the first user on a new tenant can invite peers and manage memberships without elevation dead-ends."
+  },
+  {
+    "version": "0.167.1",
+    "type": "improvement",
+    "title": "accountLockout is reachable through runProdApp/runDevApp (fw#1627).",
+    "detail": "accountLockout was an option on createAuthEmailPasswordFeature, but both wrappers mount auth-email-password themselves and their auth options only knew accountUnlock — an app on either entrypoint had no way to turn brute-force protection on. RunProdAppAuthOptions and RunDevAppAuthOptions now carry accountLockout and composeFeatures passes it through.",
+    "migration": "Opt-in, nothing breaks without it. Two things to know before relying on it: without ctx.redis the lockout is silently skipped in login.write.ts — no error, no warning, no protection — so treat Redis as a deploy invariant, and prove the lockout with a behavioural test instead of assuming the mount is enough."
+  },
+  {
+    "version": "0.165.1",
+    "type": "breaking",
+    "title": "makeAuthGate / makeSessionAuthGate take a single LoginRouteOptions object (fw#1545).",
+    "detail": "The four positional args (LoginComponent, loginProps, MfaVerifyComponent, MfaSetupComponent) did not scale past two optional MFA params. Shipped in the stranded 2.0.0 major and carried into the 0.165.1 line.",
+    "migration": "Rewrite call sites as makeAuthGate({ loginScreen, loginScreenProps, mfaVerifyScreen, mfaSetupScreen }). Type-check catches every occurrence."
+  },
+  {
+    "version": "0.162.0",
+    "type": "improvement",
+    "title": "auth-email-password: runtime toggle for self-registration.",
+    "detail": "auth-email-password: runtime toggle for self-registration. A new handler-less companion feature (`auth-self-registration`, toggleable, default on) lets an operator flip self-signup off at runtime via feature-toggles without redeploying. `signup-request` silently no-ops when off (matching its always-200 anti-enumeration contract), and a new anonymous-readable query (`auth-email-password:query:signup-registration-status`) lets the public signup page hide its own link/form."
+  },
+  {
+    "version": "0.154.1",
+    "type": "fix",
+    "title": "Export `LoginScreen`/`LoginScreenProps`/`AuthLegalLink` from `@cosmicdrift/kumiko-bundled…",
+    "detail": "Export `LoginScreen`/`LoginScreenProps`/`AuthLegalLink` from `@cosmicdrift/kumiko-bundled-features/auth-email-password/web`. Every other auth screen (ForgotPasswordScreen, SignupScreen, ResetPasswordScreen, …) was already exported from the barrel with its props type; `LoginScreen` was missed. `makeAuthGate`'s second parameter is typed `LoginScreenProps`, so consumers passing a typed `loginScreenProps` override (e.g. `@cosmicdriftgamestudio/kumiko-designer`) couldn't import the type at all. - @cosmicdrift/kumiko-framework@0.154.1 - @cosmicdrift/kumiko-dispatcher-live@0.154.1 - @cosmicdrift/kumiko-headless@0.154.1 - @cosmicdrift/kumiko-renderer@0.154.1 - @cosmicdrift/kumiko-renderer-web@0.154.1"
+  },
+  {
+    "version": "0.151.0",
+    "type": "improvement",
+    "title": "`auth-email-password/web` no longer exports `LoginScreen`/`LoginScreenProps` directly — u…",
+    "detail": "`auth-email-password/web` no longer exports `LoginScreen`/`LoginScreenProps` directly — use the new `createLoginRoute({ loginScreenProps, mfaVerifyScreen, unaffected (they already build on the same logic internally now). Why: a raw `<LoginScreen />` render has no MFA-challenge handling unless the caller remembers to hand-wire `onMfaChallenge` + swap in a verify screen itself — exactly how kumiko-framework#266's login-time MFA step went missing in a real app's standalone apex/marketing login route (it renders outside `emailPasswordClient`'s own gate, which already handled this correctly). `createLoginRoute` is the one place this logic lives now, for both the gated and standalone cases — there's no lower-level piece left to misuse. The `apex-surface-auth` recipe is updated to match."
+  },
+  {
+    "version": "0.131.0",
+    "type": "improvement",
+    "title": "App-Mounting 2.0 Säule A: Mid-Level-Widget-Kit in renderer-web (StatCard, MiniStat, Secti…",
+    "detail": "App-Mounting 2.0 Säule A: Mid-Level-Widget-Kit in renderer-web (StatCard, MiniStat, SectionCard, StatusBadge, ProgressBar, CollapsibleSection, DetailList, ModeSwitch, StatusBarChart, TimeseriesChart, EmptyState/LoadingState/ErrorState, QueryTable) + Status-Farb-Tokens (--color-status-\\*). Neue Hooks useMutation + useDisclosure. Neues Core-Primitive Link (default/button/muted), Button-Variant \"link\", Text-Variant \"muted\"; auth-email-password nutzt sie (authButtonClass/authMutedLinkClass entfernt)."
+  }
+]

package/packages/bundled-features/src/auth-email-password/constants.ts

@@ -0,0 +1,146 @@
+// @runtime client
+// Pure string constants — no DB/Node builtins. Marked `@runtime client` so
+// browser code (Members screen etc.) can import them too without the
+// runtime-isolation guard complaining. Runtime may import "client" files
+// (see RUNTIME_RULES), so server-side access (handlers, dispatcher) stays
+// intact as well.
+export const AUTH_EMAIL_PASSWORD_FEATURE = "auth-email-password" as const;
+
+// Minimum length for reset/verify hmacSecret — mirrors the ≥32-char
+// JWT_SECRET env check (HMAC-SHA256 key material).
+export const MIN_HMAC_SECRET_LENGTH = 32;
+
+// Qualified handler names. Non-CRUD handlers, no entity prefix.
+export const AuthHandlers = {
+  login: "auth-email-password:write:login",
+  logout: "auth-email-password:write:logout",
+  changePassword: "auth-email-password:write:change-password",
+  requestPasswordReset: "auth-email-password:write:request-password-reset",
+  resetPassword: "auth-email-password:write:reset-password",
+  requestEmailVerification: "auth-email-password:write:request-email-verification",
+  verifyEmail: "auth-email-password:write:verify-email",
+  // Account-Unlock Magic-Link (fixes the lockout-DoS where the monotonic
+  // failure-counter re-locks immediately after expiry, #1266). Mirrors
+  // reset: request mints an HMAC token + mails it, confirm clears the
+  // Redis lockout state.
+  requestAccountUnlock: "auth-email-password:write:request-account-unlock",
+  confirmAccountUnlock: "auth-email-password:write:confirm-account-unlock",
+  // Magic-link self-signup (pre-activation-token pattern). Request mints an
+  // opaque random token, stores it bidirectionally in Redis and sends an
+  // activation email. Confirm redeems the token and creates
+  // user + tenant + Admin membership atomically. emailVerified=true from
+  // second 0 — clicking the mail link IS the proof.
+  signupRequest: "auth-email-password:write:signup-request",
+  signupConfirm: "auth-email-password:write:signup-confirm",
+  // Tenant-invite magic-link (admin invites a user into an existing tenant).
+  // Three separate accept endpoints for clear branch separation:
+  //   inviteCreate: admin → POST email + role
+  //   inviteAccept: logged-in user → POST token (membership-add)
+  //   inviteAcceptWithLogin: anon user with existing email → POST token + email + password
+  //   inviteSignupComplete: anon user with new email → POST token + password
+  //   inviteCancel: admin cancels a pending invite
+  inviteCreate: "auth-email-password:write:invite-create",
+  inviteAccept: "auth-email-password:write:invite-accept",
+  inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
+  inviteSignupComplete: "auth-email-password:write:invite-signup-complete",
+  inviteCancel: "auth-email-password:write:invite-cancel",
+} as const;
+
+// Qualified query names. Anonymous-readable status so the (unauthenticated)
+// signup page can decide whether to show its own link/form.
+export const AuthQueries = {
+  signupRegistrationStatus: "auth-email-password:query:signup-registration-status",
+  // Anonymous, read-only invite lookup for the invite-acceptance page —
+  // see invite-info.query.ts. Does not consume the token.
+  inviteInfo: "auth-email-password:query:invite-info",
+} as const;
+
+// Error codes — kept intentionally generic so clients can't distinguish
+// "email doesn't exist" from "password wrong". Both surface as invalid_credentials.
+// Soft-deleted users also collapse into invalid_credentials to avoid enumeration.
+export const AuthErrors = {
+  invalidCredentials: "invalid_credentials",
+  noMembership: "no_membership",
+  // Reset-flow: the route maps every reset-token verify failure (malformed,
+  // bad signature, expired) to this single code so a probing client can't
+  // learn whether a token was tampered with or just stale.
+  invalidResetToken: "invalid_reset_token",
+  resetNotConfigured: "password_reset_not_configured",
+  // Verification-flow: mirrors the reset-token handling. The login path
+  // uses `emailNotVerified` which IS a deliberate enumeration leak —
+  // UX benefit (explicit "check your email") outweighs the marginal
+  // signal ("this email exists in our system"). Signup already surfaces
+  // that.
+  invalidVerificationToken: "invalid_verification_token",
+  verificationNotConfigured: "email_verification_not_configured",
+  emailNotVerified: "email_not_verified",
+  // Account-Unlock: mirrors the reset-token handling — every verify
+  // failure (malformed/bad-signature/expired) collapses to this single
+  // code so a probing client can't distinguish tampered from stale.
+  invalidUnlockToken: "invalid_unlock_token",
+  unlockNotConfigured: "account_unlock_not_configured",
+  // Self-signup: all confirm failures (unknown token, already
+  // consumed, expired) collapse onto this code — same
+  // anti-enumeration trade-off as reset/verify.
+  invalidSignupToken: "invalid_signup_token",
+  signupNotConfigured: "signup_not_configured",
+  // Self-signup: confirm rejects an already-registered email instead of
+  // reusing the existing user (account takeover, #365). NO
+  // anti-enumeration collapse like invalidSignupToken: whoever gets here
+  // controls the inbox (has the magic link), so revealing "email exists"
+  // is not new information.
+  signupEmailAlreadyRegistered: "signup_email_already_registered",
+  // Invite flow: all token failures collapse onto invalidInviteToken
+  // (anti-enumeration). emailMismatch when the invitee tries to accept the
+  // link with a different email than the one invited.
+  invalidInviteToken: "invalid_invite_token",
+  inviteEmailMismatch: "invite_email_mismatch",
+  inviteAlreadyMember: "invite_already_member",
+  // Account-lockout: login refuses with this code when the user's streak of
+  // failed attempts has crossed the configured threshold. The error detail
+  // carries `retryAfterSeconds` so the UI can show a countdown. Returning a
+  // distinct code (rather than hiding it inside invalid_credentials) is a
+  // deliberate enumeration trade-off: the lockout event itself is already
+  // observable to the attacker, and legit users benefit from a clear signal.
+  accountLocked: "account_locked",
+  // S2.U6 (GDPR Art. 18) — account is in Restricted status. Login is
+  // explicitly refused with its own code (not collapsed into
+  // invalid_credentials) so the UI can say "account is currently paused,
+  // click here to lift it". Enumeration leak accepted: restriction is
+  // user-initiated, the user already knows their account is restricted.
+  accountRestricted: "account_restricted",
+  // Account is in DeletionRequested or Deleted status. Unlike
+  // Restricted, this is not reversible via login → we collapse onto
+  // invalid_credentials so the forget-path isn't enumerable via login
+  // (a user who clicked "delete account" shouldn't see again that their
+  // email address still exists in the DB).
+} as const;
+
+// Account-lockout defaults — overridable via
+// AuthEmailPasswordOptions.accountLockout on the feature. Defaults track the
+// industry norm (NIST 800-63B) for password-only logins: a small streak
+// threshold, a short cooldown.
+export const AUTH_LOCKOUT_DEFAULT_MAX_FAILED_ATTEMPTS = 5;
+export const AUTH_LOCKOUT_DEFAULT_DURATION_MINUTES = 15;
+
+// Account-unlock token TTL — same as reset (15min): short-lived, the user
+// clicks it right after hitting the lockout screen.
+export const AUTH_UNLOCK_DEFAULT_TTL_MINUTES = 15;
+
+export const AUTH_RESET_DEFAULT_TTL_MINUTES = 15;
+// Verification tokens live longer by default because the user may not be
+// at their computer the moment they sign up — 24h covers "verify after
+// I've got home from work". The HMAC-signed token is still single-use
+// because flipping emailVerified=true is an idempotent state change:
+// replaying the same token re-sets the same flag.
+export const AUTH_VERIFY_DEFAULT_TTL_MINUTES = 24 * 60;
+
+// Self-signup: 24h default. Long enough that the user doesn't have to
+// think "activate quickly" — a mail link that still works tomorrow morning
+// is user-friendly. Shorter TTLs cause resend-spam because users forget.
+export const AUTH_SIGNUP_DEFAULT_TTL_MINUTES = 24 * 60;
+
+// Tenant invite: 7 days default. Industry standard (GitHub, Linear,
+// Slack); invitees often need longer to respond than in self-signup,
+// where the user's intent is fresh.
+export const AUTH_INVITE_DEFAULT_TTL_MINUTES = 7 * 24 * 60;

package/packages/bundled-features/src/auth-email-password/email-templates.ts

@@ -0,0 +1,198 @@
+// Default renderers for the transactional auth mails. All four magic-link flows
+// (password-reset, email-verification, signup-activation, invite) emit
+// structured AuthMailContent that the handler hands to delivery (ctx.notify) —
+// renderer-simple turns it into HTML. Apps wanting their own branding swap the
+// renderer; these templates are deliberately plain so the renderer (and the
+// operator reading the mailer log) can rely on them.
+//
+// English ships here. Other languages register via @cosmicdrift/kumiko-locale-*
+// (localeDe() / localeEs() call registerMailTranslations).
+
+import { mailT, registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+import { Temporal } from "temporal-polyfill";
+
+export type AuthMailLocale = string;
+
+export const AUTH_MAIL_EN: Readonly<Record<string, string>> = {
+  "auth.mail.appNameDefault": "Account",
+  "auth.mail.reset.subject": "{app} — Reset your password",
+  "auth.mail.reset.greeting": "Hi,",
+  "auth.mail.reset.intro":
+    "you requested a password reset for {app}. Click the link below to set a new password:",
+  "auth.mail.reset.button": "Reset password",
+  "auth.mail.reset.expiry": "The link expires on {when}.",
+  "auth.mail.reset.ignore":
+    "If you didn't request a reset, you can safely ignore this email — your password won't change.",
+  "auth.mail.verify.subject": "{app} — Verify your email",
+  "auth.mail.verify.greeting": "Welcome,",
+  "auth.mail.verify.intro": "please verify your email address for {app} to activate your account:",
+  "auth.mail.verify.button": "Verify email",
+  "auth.mail.verify.expiry": "The link expires on {when}.",
+  "auth.mail.verify.ignore": "If you didn't create this account, you can ignore this email.",
+  "auth.mail.activation.subject": "{app} — Activate your account",
+  "auth.mail.activation.greeting": "Welcome,",
+  "auth.mail.activation.intro":
+    "click the link below to activate your {app} account. The next step is choosing your password:",
+  "auth.mail.activation.button": "Activate account",
+  "auth.mail.activation.expiry": "The link expires on {when}.",
+  "auth.mail.activation.ignore":
+    "If you didn't sign up, you can ignore this email — no account is created until you open the link.",
+  "auth.mail.invite.subject": "{app} — Workspace invitation",
+  "auth.mail.invite.greeting": "Hi,",
+  "auth.mail.invite.intro":
+    "you've been invited to a {app} workspace as {role}. Click the link below to accept:",
+  "auth.mail.invite.button": "Accept invitation",
+  "auth.mail.invite.expiry": "The link expires on {when}.",
+  "auth.mail.invite.ignore": "If you weren't expecting this invitation, you can ignore this email.",
+  "auth.mail.unlock.subject": "{app} — Unlock your account",
+  "auth.mail.unlock.greeting": "Hi,",
+  "auth.mail.unlock.intro":
+    "your {app} account was temporarily locked after several failed sign-in attempts. Click the link below to unlock it immediately:",
+  "auth.mail.unlock.button": "Unlock account",
+  "auth.mail.unlock.expiry": "The link expires on {when}.",
+  "auth.mail.unlock.ignore":
+    "If you didn't trigger this lock, you can ignore this email — the lock expires on its own.",
+};
+
+registerMailTranslations("en", AUTH_MAIL_EN);
+
+export type RenderTokenContentArgs = {
+  readonly url: string;
+  readonly expiresAt: string;
+  readonly locale?: AuthMailLocale;
+  /** Optional app name for subject + intro. Default from auth.mail.appNameDefault. */
+  readonly appName?: string;
+};
+
+export type RenderInviteEmailArgs = RenderTokenContentArgs & { readonly role: string };
+
+export type AuthMailSection =
+  | { readonly text: string }
+  | { readonly button: { readonly label: string; readonly url: string } };
+
+export type AuthMailContent = {
+  readonly subject: string;
+  readonly header: string;
+  readonly sections: readonly AuthMailSection[];
+  readonly footer: string;
+};
+
+function tokenMailContent(spec: {
+  readonly subject: string;
+  readonly header: string;
+  readonly greeting: string;
+  readonly intro: string;
+  readonly buttonLabel: string;
+  readonly buttonUrl: string;
+  readonly expiry: string;
+  readonly ignore: string;
+}): AuthMailContent {
+  return {
+    subject: spec.subject,
+    header: spec.header,
+    sections: [
+      { text: spec.greeting },
+      { text: spec.intro },
+      { button: { label: spec.buttonLabel, url: spec.buttonUrl } },
+      { text: spec.expiry },
+    ],
+    footer: spec.ignore,
+  };
+}
+
+function t(locale: string, key: string, params?: Readonly<Record<string, string>>): string {
+  return mailT(locale, key, params);
+}
+
+function appNameFor(args: RenderTokenContentArgs): string {
+  const locale = args.locale ?? "en";
+  return args.appName ?? t(locale, "auth.mail.appNameDefault");
+}
+
+export function renderResetPasswordEmail(args: RenderTokenContentArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const app = appNameFor(args);
+  return tokenMailContent({
+    subject: t(locale, "auth.mail.reset.subject", { app }),
+    header: t(locale, "auth.mail.reset.button"),
+    greeting: t(locale, "auth.mail.reset.greeting"),
+    intro: t(locale, "auth.mail.reset.intro", { app }),
+    buttonLabel: t(locale, "auth.mail.reset.button"),
+    buttonUrl: args.url,
+    expiry: t(locale, "auth.mail.reset.expiry", { when: formatExpiry(args.expiresAt) }),
+    ignore: t(locale, "auth.mail.reset.ignore"),
+  });
+}
+
+export function renderUnlockAccountEmail(args: RenderTokenContentArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const app = appNameFor(args);
+  return tokenMailContent({
+    subject: t(locale, "auth.mail.unlock.subject", { app }),
+    header: t(locale, "auth.mail.unlock.button"),
+    greeting: t(locale, "auth.mail.unlock.greeting"),
+    intro: t(locale, "auth.mail.unlock.intro", { app }),
+    buttonLabel: t(locale, "auth.mail.unlock.button"),
+    buttonUrl: args.url,
+    expiry: t(locale, "auth.mail.unlock.expiry", { when: formatExpiry(args.expiresAt) }),
+    ignore: t(locale, "auth.mail.unlock.ignore"),
+  });
+}
+
+export function renderVerifyEmail(args: RenderTokenContentArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const app = appNameFor(args);
+  return tokenMailContent({
+    subject: t(locale, "auth.mail.verify.subject", { app }),
+    header: t(locale, "auth.mail.verify.button"),
+    greeting: t(locale, "auth.mail.verify.greeting"),
+    intro: t(locale, "auth.mail.verify.intro", { app }),
+    buttonLabel: t(locale, "auth.mail.verify.button"),
+    buttonUrl: args.url,
+    expiry: t(locale, "auth.mail.verify.expiry", { when: formatExpiry(args.expiresAt) }),
+    ignore: t(locale, "auth.mail.verify.ignore"),
+  });
+}
+
+export function renderActivationEmail(args: RenderTokenContentArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const app = appNameFor(args);
+  return tokenMailContent({
+    subject: t(locale, "auth.mail.activation.subject", { app }),
+    header: t(locale, "auth.mail.activation.button"),
+    greeting: t(locale, "auth.mail.activation.greeting"),
+    intro: t(locale, "auth.mail.activation.intro", { app }),
+    buttonLabel: t(locale, "auth.mail.activation.button"),
+    buttonUrl: args.url,
+    expiry: t(locale, "auth.mail.activation.expiry", { when: formatExpiry(args.expiresAt) }),
+    ignore: t(locale, "auth.mail.activation.ignore"),
+  });
+}
+
+export function renderInviteEmail(args: RenderInviteEmailArgs): AuthMailContent {
+  const locale = args.locale ?? "en";
+  const app = args.appName ?? "Workspace";
+  return tokenMailContent({
+    subject: t(locale, "auth.mail.invite.subject", { app }),
+    header: t(locale, "auth.mail.invite.button"),
+    greeting: t(locale, "auth.mail.invite.greeting"),
+    intro: t(locale, "auth.mail.invite.intro", { app, role: args.role }),
+    buttonLabel: t(locale, "auth.mail.invite.button"),
+    buttonUrl: args.url,
+    expiry: t(locale, "auth.mail.invite.expiry", { when: formatExpiry(args.expiresAt) }),
+    ignore: t(locale, "auth.mail.invite.ignore"),
+  });
+}
+
+function formatExpiry(iso: string): string {
+  try {
+    const z = Temporal.Instant.from(iso).toZonedDateTimeISO("UTC");
+    return `${z.year}-${pad2(z.month)}-${pad2(z.day)} ${pad2(z.hour)}:${pad2(z.minute)} UTC`;
+  } catch {
+    return iso;
+  }
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}

package/packages/bundled-features/src/auth-email-password/errors.ts

@@ -0,0 +1,112 @@
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { AuthErrors } from "./constants.js";
+
+// @wrapper-known error-helper
+export function invalidCredentials() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidCredentials, {
+      i18nKey: "auth.errors.invalidCredentials",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function invalidInviteToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidInviteToken, {
+      i18nKey: "auth.errors.invalidInviteToken",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function inviteEmailMismatch() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.inviteEmailMismatch, {
+      i18nKey: "auth.errors.inviteEmailMismatch",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function invalidResetToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidResetToken, {
+      i18nKey: "auth.errors.invalidResetToken",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function invalidUnlockToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidUnlockToken, {
+      i18nKey: "auth.errors.invalidUnlockToken",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function invalidVerificationToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidVerificationToken, {
+      i18nKey: "auth.errors.invalidVerificationToken",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function invalidSignupToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidSignupToken, {
+      i18nKey: "auth.errors.invalidSignupToken",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function signupEmailAlreadyRegistered() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.signupEmailAlreadyRegistered, {
+      i18nKey: "auth.errors.signupEmailAlreadyRegistered",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function noMembership() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.noMembership, {
+      i18nKey: "auth.errors.noMembership",
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function emailNotVerified() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.emailNotVerified, {
+      i18nKey: "auth.errors.emailNotVerified",
+    }),
+  );
+}
+
+// retryAfterSeconds drives the login/signup UI countdown — must stay > 0.
+// @wrapper-known error-helper
+export function accountLocked(retryAfterSeconds: number) {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.accountLocked, {
+      i18nKey: "auth.errors.accountLocked",
+      details: { retryAfterSeconds },
+    }),
+  );
+}
+
+// @wrapper-known error-helper
+export function accountRestricted() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.accountRestricted, {
+      i18nKey: "auth.errors.accountRestricted",
+    }),
+  );
+}