@cosmicdrift/kumiko-framework 0.383.1 → 0.385.0

package/dist/api/auth-routes-shared.d.ts

@@ -0,0 +1,33 @@
+import type { Context, Hono } from "hono";
+import * as z from "zod";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+export type PublicAuthErrorStatus = 400 | 401 | 403 | 422 | 429 | 500;
+export declare const SignupRequestBody: z.ZodObject<{
+    email: z.ZodEmail;
+    handover: z.ZodOptional<z.ZodObject<{
+        entityType: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function isUnknownHandlerError(e: unknown): boolean;
+export type PendingMfaStep = {
+    kind: "mfa-challenge";
+    challengeToken: string;
+} | {
+    kind: "mfa-setup-required";
+    preauthSetupToken: string;
+};
+export declare function pendingMfaStepResponse(c: Context, step: PendingMfaStep, landing?: {
+    readonly landingPath?: string;
+}): Response;
+export declare function registerTokenRequestRoute(opts: {
+    api: Hono;
+    dispatcher: Dispatcher;
+    path: string;
+    requestHandler: string;
+    schema?: typeof RequestTokenBody | typeof SignupRequestBody;
+}): void;
+declare const RequestTokenBody: z.ZodObject<{
+    email: z.ZodEmail;
+}, z.core.$strip>;
+export {};

package/dist/api/auth-routes-shared.js

@@ -0,0 +1,81 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { NotFoundError } from "../errors/index.js";
+// Cross-device try-first handover (kumiko-framework#3035 follow-up,
+// offlot-app#454): an optional tenant-handover grant the signup-request
+// route forwards to the handler for server-side verification and binding —
+// the grant itself never appears anywhere else (URL, mail, log, response).
+export const SignupRequestBody = z.object({
+    email: z.email(),
+    handover: z
+        .object({
+        entityType: z.string().min(1).max(200),
+        token: z.string().min(1).max(4096),
+    })
+        .optional(),
+});
+// Shape guard for "handler not registered" — the only legitimate reason to
+// fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
+// Every other error (DB down, revoker throws, access denied, …) has to
+// propagate — otherwise we'd silently paper over outages.
+export function isUnknownHandlerError(e) {
+    if (!(e instanceof NotFoundError))
+        return false;
+    // @cast-boundary error-details — KumikoError.details shape is per-error
+    const details = e.details;
+    return details?.entity === "handler";
+}
+export function pendingMfaStepResponse(c, step, landing = {}) {
+    if (step.kind === "mfa-setup-required") {
+        return c.json({
+            isSuccess: true,
+            mfaSetupRequired: true,
+            preauthSetupToken: step.preauthSetupToken,
+            ...landing,
+        });
+    }
+    return c.json({
+        isSuccess: true,
+        mfaRequired: true,
+        challengeToken: step.challengeToken,
+        ...landing,
+    });
+}
+// --- shared route builders for token flows ---------------------------------
+// Password-reset, email-verification and signup share the exact same request
+// HTTP-shape: parse body → dispatch the request handler → always-200 (no
+// enumeration). The handler mints the token AND dispatches the magic-link mail
+// via delivery (ctx.notify); the route never sees the token. confirm-route
+// validates the token + does the state change → typed failure or 200. Keeping
+// the silent-success invariant in one place means changing how the framework
+// handles "invalid_body" on a public token endpoint is one edit, not three.
+export function registerTokenRequestRoute(opts) {
+    const body = opts.schema ?? RequestTokenBody;
+    opts.api.post(opts.path, async (c) => {
+        const raw = await c.req.json().catch(() => null);
+        const parsed = body.safeParse(raw);
+        // Malformed body → silent success. A probing client mustn't learn
+        // anything from the shape of their input.
+        if (!parsed.success)
+            return c.json({ isSuccess: true });
+        // The handler dispatches the magic-link mail via delivery before returning.
+        // Handler-level failures (misconfiguration, e.g. no RateLimitResolver) stay
+        // out of the response so it is uniform for unknown vs. known emails, but
+        // they are logged — otherwise the mail silently never goes out. No email in
+        // the log line (PII).
+        const result = await opts.dispatcher.write(opts.requestHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
+        // rate_limited is an expected, attacker-triggerable outcome; logging it
+        // would flood the sink and bury real misconfiguration errors.
+        if (!result.isSuccess && result.error.code !== "rate_limited") {
+            console.error(`[kumiko] token request handler "${opts.requestHandler}" failed: ${result.error.code}`);
+        }
+        return c.json({ isSuccess: true });
+    });
+}
+// Shared request-body shape for request-password-reset + request-email-
+// verification. Extracted so the two flows stay in sync when the schema
+// gains optional fields (locale, deviceId, …).
+const RequestTokenBody = z.object({
+    email: z.email(),
+});

package/dist/api/auth-routes-signup.d.ts

@@ -0,0 +1,2 @@
+import type { AuthRouteContext } from "./auth-routes-context.ts";
+export declare function registerSignupRoutes(ctx: AuthRouteContext): void;

package/dist/api/auth-routes-signup.js

@@ -0,0 +1,75 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { Routes } from "./api-constants.js";
+import { pendingMfaStepResponse, registerTokenRequestRoute, SignupRequestBody, } from "./auth-routes-shared.js";
+const SignupConfirmBody = z.object({
+    token: z.string().min(1),
+    password: z.string().min(8).max(200),
+});
+export function registerSignupRoutes(ctx) {
+    const { api, dispatcher, config, mintSessionAndRespond, landingPathFragment } = ctx;
+    // Signup confirm mints the session (auto-login) unless the MFA gate applies;
+    // then it answers with the MFA step only, no session or cookies.
+    if (config.signup) {
+        const sg = config.signup;
+        registerTokenRequestRoute({
+            api,
+            dispatcher,
+            path: Routes.authSignupRequest,
+            requestHandler: sg.requestHandler,
+            schema: SignupRequestBody,
+        });
+        api.post(Routes.authSignupConfirm, async (c) => {
+            const raw = await c.req.json().catch(() => null);
+            const parsed = SignupConfirmBody.safeParse(raw);
+            if (!parsed.success) {
+                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+            }
+            const result = await dispatcher.write(sg.confirmHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
+            if (!result.isSuccess) {
+                // 422 for invalid_signup_token (handler-level UnprocessableError).
+                // @cast-boundary engine-payload — KumikoError.httpStatus narrows to the http-status union
+                const status = result.error.httpStatus;
+                return c.json({ isSuccess: false, error: result.error }, status);
+            }
+            // @cast-boundary engine-payload — generic dispatcher.write result for signup-confirm
+            const data = result.data;
+            if (data.kind !== "auth-session") {
+                // No session yet, but the account and a claimed handover exist: hand
+                // the signup landing to the client so the login that follows lands
+                // where a signup without the MFA gate would have.
+                return pendingMfaStepResponse(c, data, landingPathFragment({ flow: "signup", ...data.signup }));
+            }
+            // Session creation + JWT sign + cookies — see mintSessionAndRespond.
+            const token = await mintSessionAndRespond(c, data.session);
+            const signupOutcome = {
+                roles: data.session.roles,
+                tenantId: data.session.tenantId,
+                tenantKey: data.tenantKey,
+                ...(data.handover !== undefined && { handover: data.handover }),
+            };
+            const landingPath = landingPathFragment({ flow: "signup", ...signupOutcome });
+            return c.json({
+                isSuccess: true,
+                token,
+                user: {
+                    id: data.session.id,
+                    tenantId: data.session.tenantId,
+                    roles: data.session.roles,
+                },
+                // tenantKey for the post-signup redirect to /<tenantKey>/. Unlike the
+                // login response, which only needs `tenants[]` (the user picks in the
+                // switcher), signup knows exactly ONE membership — the frontend UI uses
+                // it directly as the redirect target.
+                tenantKey: data.tenantKey,
+                // Cross-device try-first handover (kumiko-framework#3035 follow-up):
+                // present only when signup-confirm actually claimed a bound grant —
+                // absent, not null, so a client that doesn't know the field sees
+                // nothing unusual.
+                ...(data.handover !== undefined && { handover: data.handover }),
+                ...landingPath,
+            });
+        });
+    }
+}

package/dist/api/auth-routes-token-flows.d.ts

@@ -0,0 +1,4 @@
+import type { AuthRouteContext } from "./auth-routes-context.ts";
+export declare function registerPasswordResetRoutes(ctx: AuthRouteContext): void;
+export declare function registerEmailVerificationRoutes(ctx: AuthRouteContext): void;
+export declare function registerAccountUnlockRoutes(ctx: AuthRouteContext): void;

package/dist/api/auth-routes-token-flows.js

@@ -0,0 +1,91 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { Routes } from "./api-constants.js";
+import { registerTokenRequestRoute } from "./auth-routes-shared.js";
+const ResetPasswordBody = z.object({
+    token: z.string().min(1),
+    newPassword: z.string().min(8).max(200),
+});
+const VerifyEmailBody = z.object({
+    token: z.string().min(1),
+});
+function registerTokenConfirmRoute(opts) {
+    opts.api.post(opts.path, async (c) => {
+        const raw = await c.req.json().catch(() => null);
+        const parsed = opts.schema.safeParse(raw);
+        if (!parsed.success) {
+            return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+        }
+        const result = await opts.dispatcher.write(opts.confirmHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
+        if (!result.isSuccess) {
+            const status = result.error.httpStatus; // @cast-boundary engine-payload
+            return c.json({ isSuccess: false, error: result.error }, status);
+        }
+        return c.json({ isSuccess: true });
+    });
+}
+export function registerPasswordResetRoutes(ctx) {
+    const { api, dispatcher, config } = ctx;
+    // POST /auth/request-password-reset + /auth/reset-password — public.
+    // Silent-success on request (no enumeration), typed failure on confirm.
+    // Rate-limit covered via config.rateLimit.auth (Sprint G.5 L2, /auth/*).
+    if (config.passwordReset) {
+        const pr = config.passwordReset;
+        registerTokenRequestRoute({
+            api,
+            dispatcher,
+            path: Routes.authRequestPasswordReset,
+            requestHandler: pr.requestHandler,
+        });
+        registerTokenConfirmRoute({
+            api,
+            dispatcher,
+            path: Routes.authResetPassword,
+            confirmHandler: pr.confirmHandler,
+            schema: ResetPasswordBody,
+        });
+    }
+}
+export function registerEmailVerificationRoutes(ctx) {
+    const { api, dispatcher, config } = ctx;
+    // Email-verification mirrors password-reset.
+    if (config.emailVerification) {
+        const ev = config.emailVerification;
+        registerTokenRequestRoute({
+            api,
+            dispatcher,
+            path: Routes.authRequestEmailVerification,
+            requestHandler: ev.requestHandler,
+        });
+        registerTokenConfirmRoute({
+            api,
+            dispatcher,
+            path: Routes.authVerifyEmail,
+            confirmHandler: ev.confirmHandler,
+            schema: VerifyEmailBody,
+        });
+    }
+}
+export function registerAccountUnlockRoutes(ctx) {
+    const { api, dispatcher, config } = ctx;
+    // Account-unlock mirrors email-verification (token-only confirm body) —
+    // clears the Redis lockout state instead of an entity field, see
+    // confirm-account-unlock.write.ts.
+    if (config.accountUnlock) {
+        const au = config.accountUnlock;
+        registerTokenRequestRoute({
+            api,
+            dispatcher,
+            path: Routes.authRequestAccountUnlock,
+            requestHandler: au.requestHandler,
+        });
+        registerTokenConfirmRoute({
+            api,
+            dispatcher,
+            path: Routes.authConfirmAccountUnlock,
+            confirmHandler: au.confirmHandler,
+            schema: VerifyEmailBody,
+        });
+    }
+}

package/dist/api/auth-routes-types.d.ts

@@ -0,0 +1,76 @@
+import type { SessionUser } from "../engine/types/index.ts";
+import type { AuthSessionChecker, TokenVerifier } from "./auth-middleware.ts";
+import type { ClientIpResolver } from "./client-ip.ts";
+import type { PostAuthLandingResolver } from "./post-auth-landing.ts";
+export type LoginRateLimiter = {
+    check(key: string): Promise<boolean>;
+    reset(key: string): Promise<void>;
+};
+export type SessionMetadata = {
+    readonly ip: string;
+    readonly userAgent: string;
+};
+export type SessionCreator = (user: SessionUser, meta: SessionMetadata) => Promise<string>;
+export type SessionRevoker = (sid: string) => Promise<void>;
+export type SessionMassRevoker = (userId: string) => Promise<number>;
+export type SessionChecker = AuthSessionChecker;
+export type AuthRoutesConfig = {
+    membershipQuery: string;
+    userQuery?: string;
+    loginHandler?: string;
+    loginErrorStatusMap?: Readonly<Record<string, number>>;
+    loginRateLimit?: LoginRateLimiter | null;
+    mfaVerifyHandler?: string;
+    switchTenantMfaGateHandler?: string;
+    mfaVerifyErrorStatusMap?: Readonly<Record<string, number>>;
+    mfaVerifyRateLimit?: LoginRateLimiter | null;
+    mfaPreauthEnableStartHandler?: string;
+    mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
+    mfaPreauthEnableStartRateLimit?: LoginRateLimiter | null;
+    mfaPreauthConfirmHandler?: string;
+    mfaPreauthConfirmErrorStatusMap?: Readonly<Record<string, number>>;
+    mfaPreauthConfirmRateLimit?: LoginRateLimiter | null;
+    sessionCreator?: SessionCreator;
+    sessionRevoker?: SessionRevoker;
+    sessionChecker?: SessionChecker;
+    tokenVerifier?: TokenVerifier;
+    patRateLimiter?: LoginRateLimiter;
+    resolveTenantLifecycleStatus?: import("./auth-middleware.ts").TenantLifecycleStatusResolver;
+    passwordReset?: PasswordResetConfig;
+    emailVerification?: EmailVerificationConfig;
+    accountUnlock?: AccountUnlockConfig;
+    signup?: SignupConfig;
+    invite?: InviteConfig;
+    cookieSameSite?: "lax" | "strict";
+    cookieDomain?: string;
+    secureCookies?: boolean;
+    retiredCookieDomains?: readonly string[];
+    allowedOrigins?: readonly string[];
+    publicOrigin?: string;
+    unsafeSkipOriginCheck?: boolean;
+    trustedProxyHops?: number;
+    postAuthLanding?: PostAuthLandingResolver;
+    resolver?: ClientIpResolver;
+};
+export type PasswordResetConfig = {
+    requestHandler: string;
+    confirmHandler: string;
+};
+export type EmailVerificationConfig = {
+    requestHandler: string;
+    confirmHandler: string;
+};
+export type AccountUnlockConfig = {
+    requestHandler: string;
+    confirmHandler: string;
+};
+export type InviteConfig = {
+    readonly acceptHandler: string;
+    readonly acceptWithLoginHandler: string;
+    readonly signupCompleteHandler: string;
+    readonly infoHandler?: string;
+};
+export type SignupConfig = {
+    requestHandler: string;
+    confirmHandler: string;
+};

package/dist/api/auth-routes-types.js

@@ -0,0 +1 @@
+export {};

package/dist/api/auth-routes.d.ts

@@ -1,89 +1,9 @@
-import { Hono } from "hono";
-import type { Redis } from "ioredis";
-import { type SessionUser } from "../engine/types/index.ts";
+import type { Hono } from "hono";
 import type { Dispatcher } from "../pipeline/dispatcher.ts";
-import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } from "./auth-middleware.ts";
-import { type ClientIpResolver } from "./client-ip.ts";
+import type { AuthRoutesConfig } from "./auth-routes-types.ts";
 import type { JwtHelper } from "./jwt.ts";
-import type { PostAuthLandingResolver } from "./post-auth-landing.ts";
-export type LoginRateLimiter = {
-    check(key: string): Promise<boolean>;
-    reset(key: string): Promise<void>;
-};
-export type SessionMetadata = {
-    readonly ip: string;
-    readonly userAgent: string;
-};
-export type SessionCreator = (user: SessionUser, meta: SessionMetadata) => Promise<string>;
-export type SessionRevoker = (sid: string) => Promise<void>;
-export type SessionMassRevoker = (userId: string) => Promise<number>;
-export type SessionChecker = AuthSessionChecker;
-export type { AuthSessionStatus };
+export type { AuthSessionStatus } from "./auth-middleware.ts";
+export { createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, inMemoryLoginRateLimiterFallback, } from "./auth-rate-limiters.ts";
+export type { AccountUnlockConfig, AuthRoutesConfig, EmailVerificationConfig, InviteConfig, LoginRateLimiter, PasswordResetConfig, SessionChecker, SessionCreator, SessionMassRevoker, SessionMetadata, SessionRevoker, SignupConfig, } from "./auth-routes-types.ts";
 export declare function assertSessionCallbacksPaired(auth: Pick<AuthRoutesConfig, "sessionCreator" | "sessionRevoker" | "sessionChecker"> | undefined): void;
-export type AuthRoutesConfig = {
-    membershipQuery: string;
-    userQuery?: string;
-    loginHandler?: string;
-    loginErrorStatusMap?: Readonly<Record<string, number>>;
-    loginRateLimit?: LoginRateLimiter | null;
-    mfaVerifyHandler?: string;
-    switchTenantMfaGateHandler?: string;
-    mfaVerifyErrorStatusMap?: Readonly<Record<string, number>>;
-    mfaVerifyRateLimit?: LoginRateLimiter | null;
-    mfaPreauthEnableStartHandler?: string;
-    mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
-    mfaPreauthEnableStartRateLimit?: LoginRateLimiter | null;
-    mfaPreauthConfirmHandler?: string;
-    mfaPreauthConfirmErrorStatusMap?: Readonly<Record<string, number>>;
-    mfaPreauthConfirmRateLimit?: LoginRateLimiter | null;
-    sessionCreator?: SessionCreator;
-    sessionRevoker?: SessionRevoker;
-    sessionChecker?: SessionChecker;
-    tokenVerifier?: TokenVerifier;
-    patRateLimiter?: LoginRateLimiter;
-    resolveTenantLifecycleStatus?: import("./auth-middleware.ts").TenantLifecycleStatusResolver;
-    passwordReset?: PasswordResetConfig;
-    emailVerification?: EmailVerificationConfig;
-    accountUnlock?: AccountUnlockConfig;
-    signup?: SignupConfig;
-    invite?: InviteConfig;
-    cookieSameSite?: "lax" | "strict";
-    cookieDomain?: string;
-    secureCookies?: boolean;
-    retiredCookieDomains?: readonly string[];
-    allowedOrigins?: readonly string[];
-    publicOrigin?: string;
-    unsafeSkipOriginCheck?: boolean;
-    trustedProxyHops?: number;
-    postAuthLanding?: PostAuthLandingResolver;
-    resolver?: ClientIpResolver;
-};
-export type PasswordResetConfig = {
-    requestHandler: string;
-    confirmHandler: string;
-};
-export type EmailVerificationConfig = {
-    requestHandler: string;
-    confirmHandler: string;
-};
-export type AccountUnlockConfig = {
-    requestHandler: string;
-    confirmHandler: string;
-};
-export type InviteConfig = {
-    readonly acceptHandler: string;
-    readonly acceptWithLoginHandler: string;
-    readonly signupCompleteHandler: string;
-    readonly infoHandler?: string;
-};
-export type SignupConfig = {
-    requestHandler: string;
-    confirmHandler: string;
-};
-export declare function inMemoryLoginRateLimiterFallback(): LoginRateLimiter;
-export declare function createInMemoryLoginRateLimiter(maxAttempts?: number, windowMs?: number, { maxEntries, sweepThreshold, }?: {
-    maxEntries?: number;
-    sweepThreshold?: number;
-}): LoginRateLimiter;
-export declare function createRedisLoginRateLimiter(redis: Redis, maxAttempts?: number, windowMs?: number, namespace?: string): LoginRateLimiter;
 export declare function createAuthRoutes(dispatcher: Dispatcher, jwt: JwtHelper, config: AuthRoutesConfig): Hono;