@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -0,0 +1,192 @@
+// Tenant-Invite Step 2 — Branch 3 (anon User, Email NICHT registriert).
+//
+// Anders als signup-confirm: KEIN neuer Tenant entsteht. Der Tenant
+// existiert schon (im invitation-row), wir legen NUR User+Membership an.
+//
+// Flow:
+//   1. User klickt Invite-Link → /invite/signup?token=...
+//   2. Frontend zeigt Password-Form (email kommt aus invitation, kein
+//      User-Input damit kein Email-Mismatch möglich)
+//   3. User submitted password + token
+//   4. Server:
+//      a. Token → invitationId → invitation row
+//      b. User-Existence-Check: invitation.email darf NICHT in userTable
+//         existieren (sonst soll Branch 2 oder Branch 1 genutzt werden)
+//      c. Create user (emailVerified=true wegen Magic-Link)
+//      d. Add membership im invited Tenant
+//      e. Invitation → accepted, Token gelöscht
+//   5. Response: SessionUser + tenantId für Auto-Login
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+// kumiko-lint-ignore cross-feature-import invite-flow
+import {
+  INVITATION_STATUS,
+  tenantInvitationEntity,
+  tenantInvitationsTable,
+} from "../../tenant/invitation-table";
+// kumiko-lint-ignore cross-feature-import membership-seed-helper für privilegierten cross-tenant-add
+import { seedTenantMembership } from "../../tenant/seeding";
+// kumiko-lint-ignore cross-feature-import existence-check
+import { userTable } from "../../user/schema/user";
+import { AuthErrors } from "../constants";
+import {
+  burnInviteToken,
+  deleteInviteToken,
+  getInvitationIdForToken,
+  unburnInviteToken,
+} from "../invite-token-store";
+// kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
+import { seedUserWithPassword } from "../seeding";
+
+const InviteSignupCompleteSchema = z.object({
+  token: z.string().min(1),
+  password: z.string().min(8).max(200),
+});
+
+export type InviteSignupCompleteData = {
+  readonly kind: "auth-session";
+  readonly session: SessionUser;
+  readonly tenantId: TenantId;
+  readonly role: string;
+};
+
+const invitationExecutor = createEventStoreExecutor(
+  tenantInvitationsTable,
+  tenantInvitationEntity,
+  { entityName: "tenant-invitation" },
+);
+
+function invalidInviteToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidInviteToken, {
+      i18nKey: "auth.errors.invalidInviteToken",
+    }),
+  );
+}
+
+export function createInviteSignupCompleteHandler() {
+  return defineWriteHandler<
+    "invite-signup-complete",
+    typeof InviteSignupCompleteSchema,
+    InviteSignupCompleteData
+  >({
+    name: "invite-signup-complete",
+    schema: InviteSignupCompleteSchema,
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({ message: "invite-signup-complete requires ctx.redis" }),
+        );
+      }
+
+      const invitationId = await getInvitationIdForToken(ctx.redis, event.payload.token);
+      if (!invitationId) return invalidInviteToken();
+
+      const burn = await burnInviteToken(ctx.redis, event.payload.token);
+      if (burn === "already-used") return invalidInviteToken();
+
+      let committed = false;
+      try {
+        const invitation = await fetchOne(
+          ctx.db.raw,
+          tenantInvitationsTable,
+          eq(tenantInvitationsTable.id, invitationId),
+        );
+        if (!invitation || invitation["status"] !== INVITATION_STATUS.pending)
+          return invalidInviteToken();
+
+        const invitationTenantId = invitation["tenantId"] as TenantId;
+        const invitationEmail = invitation["email"] as string;
+        const invitationRole = invitation["role"] as string;
+        const invitationVersion = invitation["version"] as number;
+
+        // User-Not-Exists-Check: wenn die Email schon registriert ist,
+        // muss der User Branch 2 (acceptWithLogin) nutzen. Hier ist
+        // explizit "neue Email" — sonst hätten wir zwei Wege ein
+        // Password zu setzen für denselben User.
+        const existingUser = await fetchOne(
+          ctx.db.raw,
+          userTable,
+          eq(userTable.email, invitationEmail),
+        );
+        if (existingUser) return invalidInviteToken();
+
+        // User anlegen via seedUserWithPassword (gleiches Pattern wie
+        // signup-confirm), emailVerified=true wegen Magic-Link.
+        // @cast-boundary db-runner — TenantDb.raw is DbRunner; seed-helpers
+        // operate on plain drizzle-API which both shapes expose identically.
+        const dbConn = ctx.db.raw as DbConnection;
+        const userId = await seedUserWithPassword(dbConn, {
+          email: invitationEmail,
+          password: event.payload.password,
+          displayName: invitationEmail.split("@")[0] ?? invitationEmail,
+          emailVerified: true,
+        });
+
+        // Membership-Add via seed-helper (gleiches Pattern wie
+        // provisionSignupAccount — bypassed addMember access-check
+        // weil createSystemUser nicht ["SystemAdmin"] matcht).
+        await seedTenantMembership(dbConn, {
+          userId,
+          tenantId: invitationTenantId,
+          roles: [invitationRole],
+        });
+
+        // Invitation → accepted: TenantDb für invitation-tenant
+        const invitationTdb = createTenantDb(dbConn, invitationTenantId, "system");
+        const updateResult = await invitationExecutor.update(
+          {
+            id: invitationId,
+            version: invitationVersion,
+            changes: { status: INVITATION_STATUS.accepted },
+          },
+          createSystemUser(invitationTenantId),
+          invitationTdb,
+        );
+        if (!updateResult.isSuccess) return updateResult;
+
+        await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
+
+        const session: SessionUser = {
+          id: userId,
+          tenantId: invitationTenantId,
+          roles: [invitationRole],
+        };
+
+        committed = true;
+        return {
+          isSuccess: true,
+          data: {
+            kind: "auth-session",
+            session,
+            tenantId: invitationTenantId,
+            role: invitationRole,
+          },
+        };
+      } finally {
+        if (!committed && ctx.redis) {
+          await unburnInviteToken(ctx.redis, event.payload.token);
+        }
+      }
+    },
+  });
+}

package/src/auth-email-password/handlers/login.write.ts

@@ -0,0 +1,208 @@
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { UserQueries } from "../../user";
+import { parseAuthUserRow } from "../auth-user-row";
+import {
+  AUTH_LOCKOUT_DEFAULT_DURATION_MINUTES,
+  AUTH_LOCKOUT_DEFAULT_MAX_FAILED_ATTEMPTS,
+  AuthErrors,
+} from "../constants";
+import { clearLockoutState, getLockoutState, recordFailedAttempt } from "../lockout-store";
+import { verifyPassword } from "../password-hashing";
+
+function invalidCredentials() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidCredentials, {
+      i18nKey: "auth.errors.invalidCredentials",
+    }),
+  );
+}
+
+function noMembership() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.noMembership, {
+      i18nKey: "auth.errors.noMembership",
+    }),
+  );
+}
+
+function emailNotVerified() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.emailNotVerified, {
+      i18nKey: "auth.errors.emailNotVerified",
+    }),
+  );
+}
+
+function accountLocked(retryAfterSeconds: number) {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.accountLocked, {
+      i18nKey: "auth.errors.accountLocked",
+      // Seconds until auto-unlock — UI renders a countdown, clients can
+      // schedule a retry. Rounded up so the UI never shows 0 while the
+      // lock is still active.
+      details: { retryAfterSeconds },
+    }),
+  );
+}
+
+export type LoginHandlerOptions = {
+  // When true, a valid (email + password) login fails with email_not_verified
+  // if the user row's emailVerified flag is false. Enumeration-leak is
+  // accepted: UX benefit ("check your email") outweighs the marginal
+  // signal since signup already surfaces the same fact.
+  readonly strictEmailVerification?: boolean;
+  // Brute-force protection: after N wrong-password attempts the account
+  // locks for the configured duration. State lives in Redis (see
+  // lockout-store.ts) — if ctx.redis is unset, lockout is skipped and the
+  // handler falls back to classic invalid-credentials. Counter is monotonic
+  // and only resets on a successful login, so a re-lock after the cooldown
+  // happens on the FIRST miss, not the Nth (strict semantic — favours
+  // brute-force resistance over UX).
+  readonly accountLockout?: {
+    readonly maxFailedAttempts?: number;
+    readonly lockoutDurationMinutes?: number;
+  };
+};
+
+const SYSTEM_USER_ID = "00000000-0000-4000-8000-000000000000";
+
+// Login — unauthenticated entry point. The route is wired public (no JWT
+// middleware), synthesising a guest SessionUser for the handler's access
+// check. Everything inside the handler goes through ctx.queryAs(system, ...)
+// so the user feature stays the single owner of its table.
+export function createLoginHandler(opts: LoginHandlerOptions = {}) {
+  const strictVerification = opts.strictEmailVerification === true;
+  const maxFailedAttempts =
+    opts.accountLockout?.maxFailedAttempts ?? AUTH_LOCKOUT_DEFAULT_MAX_FAILED_ATTEMPTS;
+  const lockoutDurationMinutes =
+    opts.accountLockout?.lockoutDurationMinutes ?? AUTH_LOCKOUT_DEFAULT_DURATION_MINUTES;
+
+  return defineWriteHandler({
+    name: "login",
+    schema: z.object({
+      email: z.email(),
+      password: z.string().min(1),
+    }),
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      const systemUser = createSystemUser(SYSTEM_USER_ID);
+
+      const found = parseAuthUserRow(
+        await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+          email: event.payload.email,
+        }),
+      );
+
+      // Uniform response on any credential mismatch (no user, wrong password,
+      // soft-deleted user) — prevents email enumeration.
+      if (!found?.passwordHash || found.isDeleted) {
+        return invalidCredentials();
+      }
+
+      // Lockout gate — runs BEFORE password verification so a locked account
+      // can't be bruteforce-probed for passwords (and also can't be probed
+      // for a timing-oracle on the bcrypt verify). If Redis isn't wired,
+      // lockout is silently skipped — login still works, brute-force
+      // protection just degrades to the IP-rate-limiter at the edge.
+      if (ctx.redis) {
+        const state = await getLockoutState(ctx.redis, found.id);
+        if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
+          const now = Date.now();
+          if (state.lockedUntil > now) {
+            const retryAfterSeconds = Math.max(1, Math.ceil((state.lockedUntil - now) / 1000));
+            return accountLocked(retryAfterSeconds);
+          }
+          // lockedUntil in the past — shouldn't normally happen because the
+          // Redis TTL on the until-key expires the key at the same moment
+          // as the value. Clock skew / replication lag could surface this;
+          // fall through to password verification. The counter is NOT
+          // reset — next miss re-locks immediately (strict-semantic, see
+          // lockout-store.ts).
+        }
+      }
+
+      const passwordOk = await verifyPassword(found.passwordHash, event.payload.password);
+      if (!passwordOk) {
+        if (ctx.redis) {
+          await recordFailedAttempt(ctx.redis, found.id, maxFailedAttempts, lockoutDurationMinutes);
+        }
+        return invalidCredentials();
+      }
+
+      // Strict verification gate — runs AFTER password check so an attacker
+      // probing "email_not_verified" needs valid credentials first. The
+      // remaining enumeration surface is "valid-cred + unverified" → accepted
+      // leak because the signup flow already told the user "check your email".
+      if (strictVerification && found.emailVerified !== true) {
+        return emailNotVerified();
+      }
+
+      // Resolve tenant + roles via the tenant feature's memberships query.
+      // Returns [] if the user has no memberships — MVP: no login without an
+      // invitation, so we refuse with a dedicated error.
+      const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
+        userId: found.id,
+      })) as Array<{ tenantId: TenantId; roles: readonly string[] }>;
+
+      if (memberships.length === 0) {
+        return noMembership();
+      }
+
+      const preferred =
+        found.lastActiveTenantId !== null && found.lastActiveTenantId !== undefined
+          ? memberships.find((m) => m.tenantId === found.lastActiveTenantId)
+          : undefined;
+      const chosen = preferred ?? memberships[0];
+      if (!chosen) {
+        return noMembership();
+      }
+
+      // Clear the lockout state on success. DEL is idempotent, so no need
+      // to gate on "was there a counter?" — skipping the Redis round-trip
+      // entirely for users who never failed a login would optimise the hot
+      // path, but the call is microseconds and the branch isn't free either.
+      if (ctx.redis) {
+        await clearLockoutState(ctx.redis, found.id);
+      }
+
+      // Globale Rollen aus user.roles + tenant-membership-roles mergen.
+      // Globale Rollen (SystemAdmin etc.) bleiben so über alle tenants
+      // gleich; tenant-spezifische Rollen (Admin, User) kommen aus der
+      // membership. Dedupe via Set damit eine Rolle die in beiden Quellen
+      // steht nicht doppelt im Session-Roles landet.
+      const globalRoles = parseRoles(found.roles ?? null);
+      const mergedRoles = Array.from(new Set([...globalRoles, ...chosen.roles]));
+      const baseSession: SessionUser = {
+        id: found.id,
+        tenantId: chosen.tenantId,
+        roles: mergedRoles,
+      };
+
+      // Features can contribute identity facts (team IDs, feature flags, ...)
+      // via r.authClaims(). ctx.resolveAuthClaims is a thin pass-through to
+      // dispatcher.resolveAuthClaims — same impl also used by the switch-tenant
+      // route, so login + tenant-switch stay in sync.
+      //
+      // Best-effort: if no feature registered a hook, we get an empty record
+      // back and simply omit the `claims` field from the session (keeps the
+      // shape clean for the JWT layer, which already spreads claims
+      // conditionally based on presence).
+      const claims = await ctx.resolveAuthClaims(baseSession);
+      const session: SessionUser =
+        Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
+
+      return {
+        isSuccess: true,
+        data: { kind: "auth-session", session },
+      };
+    },
+  });
+}

package/src/auth-email-password/handlers/logout.write.ts

@@ -0,0 +1,12 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// Logout — JWT is stateless, so server-side we only return OK. A future
+// revocation list / session table can land here without changing the
+// route or client API. Keeping the handler makes the API shape stable.
+export const logoutWrite = defineWriteHandler({
+  name: "logout",
+  schema: z.object({}),
+  access: { roles: access.authenticated },
+  handler: async () => ({ isSuccess: true, data: { kind: "logged-out" } }),
+});

package/src/auth-email-password/handlers/request-email-verification.write.ts

@@ -0,0 +1,29 @@
+import { AUTH_VERIFY_DEFAULT_TTL_MINUTES, AuthErrors } from "../constants";
+import { signVerificationToken } from "../verification-token";
+import {
+  createTokenRequestHandler,
+  type TokenRequestData,
+  type TokenRequestOptions,
+} from "./token-request-handler";
+
+export type RequestEmailVerificationOptions = TokenRequestOptions;
+
+export type RequestVerificationData = TokenRequestData<"verification-requested">;
+
+export function createRequestEmailVerificationHandler(opts: RequestEmailVerificationOptions) {
+  return createTokenRequestHandler(
+    {
+      handlerName: "request-email-verification",
+      successKind: "verification-requested",
+      defaultTtlMinutes: AUTH_VERIFY_DEFAULT_TTL_MINUTES,
+      sign: signVerificationToken,
+      notConfiguredError: AuthErrors.verificationNotConfigured,
+      notConfiguredI18nKey: "auth.errors.verificationNotConfigured",
+      // Silent no-op for already-verified users. Flipped-together with
+      // unknown/deleted to keep the enumeration surface symmetric — the
+      // caller sees the same 200 regardless of whether a token was minted.
+      extraSilentSkip: (user) => user.emailVerified === true,
+    },
+    opts,
+  );
+}

package/src/auth-email-password/handlers/request-password-reset.write.ts

@@ -0,0 +1,31 @@
+import { AUTH_RESET_DEFAULT_TTL_MINUTES, AuthErrors } from "../constants";
+import { signResetToken } from "../reset-token";
+import {
+  createTokenRequestHandler,
+  type TokenRequestData,
+  type TokenRequestOptions,
+} from "./token-request-handler";
+
+export type RequestPasswordResetOptions = TokenRequestOptions;
+
+// Public shape re-exported for callers that build custom routes on top of
+// the dispatcher (bypassing the framework's auth-routes).
+export type RequestResetData = TokenRequestData<"reset-requested">;
+
+export function createRequestPasswordResetHandler(opts: RequestPasswordResetOptions) {
+  return createTokenRequestHandler(
+    {
+      handlerName: "request-password-reset",
+      successKind: "reset-requested",
+      defaultTtlMinutes: AUTH_RESET_DEFAULT_TTL_MINUTES,
+      sign: signResetToken,
+      notConfiguredError: AuthErrors.resetNotConfigured,
+      notConfiguredI18nKey: "auth.errors.resetNotConfigured",
+      // Password-reset has no extra skip condition — every existing,
+      // non-deleted user can initiate a reset regardless of verification
+      // state. The sessions feature handles the post-change revocation.
+      extraSilentSkip: () => false,
+    },
+    opts,
+  );
+}

package/src/auth-email-password/handlers/reset-password.write.ts

@@ -0,0 +1,61 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { AuthErrors } from "../constants";
+import { hashPassword } from "../password-hashing";
+import { verifyResetToken } from "../reset-token";
+import { runConfirmTokenFlow } from "./confirm-token-flow";
+
+export type ResetPasswordOptions = {
+  readonly hmacSecret: string;
+};
+
+function invalidToken() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidResetToken, {
+      i18nKey: "auth.errors.invalidResetToken",
+    }),
+  );
+}
+
+// Confirm step of the reset flow. Token-verify happens inline; the
+// post-verify pipeline (burn, load user, memberships, try-all-tenants,
+// burn-release-on-failure) lives in confirm-token-flow to stay in sync
+// with verify-email. Session revocation on password change is wired
+// cross-feature via the sessions feature's r.entityHook("postSave",
+// "user", ...) — no explicit revoke call needed here.
+export function createResetPasswordHandler(opts: ResetPasswordOptions) {
+  return defineWriteHandler({
+    name: "reset-password",
+    schema: z.object({
+      token: z.string().min(1),
+      newPassword: z.string().min(8).max(200),
+    }),
+    access: { roles: ["all"] },
+    handler: async (event, ctx) => {
+      if (!opts.hmacSecret) {
+        return writeFailure(
+          new UnprocessableError(AuthErrors.resetNotConfigured, {
+            i18nKey: "auth.errors.resetNotConfigured",
+          }),
+        );
+      }
+
+      // All verify failures (malformed / bad_signature / expired) fold into
+      // the same invalid_reset_token error — a probing caller can't
+      // distinguish tampered from stale from random-string.
+      const verify = verifyResetToken(event.payload.token, opts.hmacSecret);
+      if (!verify.ok) return invalidToken();
+
+      return runConfirmTokenFlow(ctx, verify.userId, verify.expiresAtMs, {
+        purpose: "reset",
+        redisRequiredMessage: "password-reset requires ctx.redis to enforce token single-use",
+        invalidToken,
+        buildChanges: async () => ({
+          passwordHash: await hashPassword(event.payload.newPassword),
+        }),
+        successData: { kind: "password-reset" as const },
+      });
+    },
+  });
+}