@mandujs/core 0.20.10 → 0.22.0

package/README.md

@@ -162,7 +162,7 @@ watcher.start();
 listPresets().forEach(p => console.log(p.name, p.description));
 ```
 
-### Presets
+### Presets (6)
 
 | Preset | Layers | Use Case |
 |--------|--------|----------|
@@ -171,6 +171,7 @@ listPresets().forEach(p => console.log(p.name, p.description));
 | `clean` | api, application, domain, infra, shared | Backend |
 | `hexagonal` | adapters, ports, application, domain | DDD |
 | `atomic` | pages, templates, organisms, molecules, atoms | UI |
+| `cqrs` | commands, queries, events, dto, application, domain | Event-sourced apps |
 
 ### AST-based Analysis
 

package/package.json

@@ -1,18 +1,35 @@
 {
   "name": "@mandujs/core",
-  "version": "0.20.10",
+  "version": "0.22.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/login": "./src/auth/login.ts",
+    "./auth/password": "./src/auth/password.ts",
+    "./auth/reset": "./src/auth/reset.ts",
+    "./auth/verification": "./src/auth/verification.ts",
     "./client": "./src/client/index.ts",
+    "./db": "./src/db/index.ts",
+    "./desktop": "./src/desktop/index.ts",
+    "./desktop/worker": "./src/desktop/worker.ts",
+    "./email": "./src/email/index.ts",
+    "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
     "./middleware": "./src/middleware/index.ts",
+    "./middleware/oauth": "./src/middleware/oauth/index.ts",
+    "./middleware/secure": "./src/middleware/secure/index.ts",
+    "./middleware/rate-limit": "./src/middleware/rate-limit/index.ts",
     "./testing": "./src/testing/index.ts",
     "./plugins": "./src/plugins/index.ts",
     "./error": "./src/error/index.ts",
+    "./id": "./src/id/index.ts",
     "./observability": "./src/observability/index.ts",
+    "./perf": "./src/perf/index.ts",
+    "./scheduler": "./src/scheduler/index.ts",
+    "./storage/s3": "./src/storage/s3/index.ts",
     "./bundler/prerender": "./src/bundler/prerender.ts",
     "./*": "./src/*"
   },
@@ -46,16 +63,24 @@
     "access": "public"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.12"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@tailwindcss/cli": ">=4.0.0"
+    "react-refresh": ">=0.18.0",
+    "@tailwindcss/cli": ">=4.0.0",
+    "webview-bun": "^2.4.0"
   },
   "peerDependenciesMeta": {
     "@tailwindcss/cli": {
       "optional": true
+    },
+    "react-refresh": {
+      "optional": true
+    },
+    "webview-bun": {
+      "optional": true
     }
   },
   "dependencies": {

package/src/auth/__tests__/login.test.ts

@@ -0,0 +1,419 @@
+/**
+ * @mandujs/core/auth/login tests
+ *
+ * Covers ergonomic login helpers that wrap Phase 2.3's session middleware.
+ * Fixture style mirrors `tests/middleware/session.test.ts` — real Request /
+ * Response objects, real `createCookieSessionStorage`, no mocks.
+ *
+ * What we verify:
+ *   - `loginUser` writes userId + loggedAt + extras and commits in one shot
+ *   - Custom keys are honored
+ *   - Missing session middleware throws `AuthenticationError`
+ *   - `logoutUser` emits expiring Set-Cookie and is idempotent
+ *   - `currentUserId` / `loggedAt` are non-throwing read paths
+ *   - End-to-end roundtrip through `ManduFilling`
+ *   - Composition with `requireUser` via a `loadUser` beforeHandle bridge
+ *     (executable documentation for the common real-world pattern)
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+  loginUser,
+  logoutUser,
+  currentUserId,
+  loggedAt,
+} from "../login";
+import { session } from "../../middleware/session";
+import {
+  Session,
+  createCookieSessionStorage,
+  type SessionStorage,
+} from "../../filling/session";
+import { ManduContext } from "../../filling/context";
+import { ManduFilling } from "../../filling/filling";
+import {
+  AuthenticationError,
+  requireUser,
+  type BaseUser,
+} from "../../filling/auth";
+
+// ========== Helpers ==========
+
+const SECRET = "login-helper-test-secret-32bytes!";
+
+function makeReq(url: string, init: RequestInit & { cookie?: string } = {}): Request {
+  const { cookie, headers: rawHeaders, ...rest } = init;
+  const headers = new Headers(rawHeaders as HeadersInit | undefined);
+  if (cookie) headers.set("cookie", cookie);
+  return new Request(url, { ...rest, headers });
+}
+
+function makeCtx(req: Request): ManduContext {
+  return new ManduContext(req);
+}
+
+function makeStorage(): SessionStorage {
+  return createCookieSessionStorage({
+    cookie: { secrets: [SECRET] },
+  });
+}
+
+/** Extract the first Set-Cookie line matching `name=`. */
+function readSetCookieLine(res: Response, name: string): string | null {
+  const headers = res.headers.getSetCookie?.() ?? [];
+  const needle = `${name}=`;
+  for (const line of headers) {
+    if (line.startsWith(needle)) return line;
+  }
+  return null;
+}
+
+/** Extract just the raw (encoded) cookie value from a Set-Cookie line. */
+function readSetCookieRawValue(res: Response, name: string): string | null {
+  const line = readSetCookieLine(res, name);
+  if (!line) return null;
+  const [nv] = line.split(";");
+  const eq = nv.indexOf("=");
+  if (eq <= 0) return null;
+  return nv.slice(eq + 1).trim();
+}
+
+// ========== loginUser ==========
+
+describe("loginUser — stores userId + loggedAt and commits", () => {
+  it("writes userId + loggedAt and emits Set-Cookie via saveSession", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await loginUser(ctx, "user-123");
+
+    // In-memory session state is visible immediately.
+    const s = ctx.get<Session>("session")!;
+    expect(s.get<string>("userId")).toBe("user-123");
+    expect(typeof s.get<number>("loginAt")).toBe("number");
+
+    // Set-Cookie lands on the next response built from this ctx.
+    const res = ctx.ok({ ok: true });
+    const line = readSetCookieLine(res, "__session");
+    expect(line).toBeTruthy();
+    expect(line!).toContain("HttpOnly");
+  });
+
+  it("honors a custom userIdKey", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await loginUser(ctx, "u-42", { userIdKey: "uid" });
+
+    const s = ctx.get<Session>("session")!;
+    expect(s.get<string>("uid")).toBe("u-42");
+    // Default key is NOT populated when custom key is supplied.
+    expect(s.get<string>("userId")).toBeUndefined();
+  });
+
+  it("writes extras atomically with userId + loggedAt", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await loginUser(ctx, "u-1", {
+      extras: {
+        role: "admin",
+        tenantId: "acme",
+        remember: true,
+        seat: 7,
+      },
+    });
+
+    const s = ctx.get<Session>("session")!;
+    expect(s.get<string>("userId")).toBe("u-1");
+    expect(s.get<string>("role")).toBe("admin");
+    expect(s.get<string>("tenantId")).toBe("acme");
+    expect(s.get<boolean>("remember")).toBe(true);
+    expect(s.get<number>("seat")).toBe(7);
+  });
+
+  it("throws AuthenticationError when session middleware is not installed", async () => {
+    // No `session()` middleware — ctx has no attached session.
+    const ctx = makeCtx(makeReq("http://localhost/"));
+
+    let thrown: unknown = null;
+    try {
+      await loginUser(ctx, "u-1");
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(AuthenticationError);
+    expect((thrown as AuthenticationError).statusCode).toBe(401);
+    expect(String(thrown)).toContain("Session middleware not installed");
+  });
+
+  it("rejects empty userId with AuthenticationError (never silently stores '')", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await expect(loginUser(ctx, "")).rejects.toBeInstanceOf(AuthenticationError);
+  });
+});
+
+// ========== logoutUser ==========
+
+describe("logoutUser — expiring cookie, idempotent", () => {
+  it("emits an expiring Set-Cookie (Max-Age=0)", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+    await loginUser(ctx, "u-1");
+
+    // Now log out on a fresh ctx with the just-issued cookie — but for a unit
+    // test we can call logoutUser on the same ctx; destroySession will emit a
+    // new Set-Cookie line. There will be multiple Set-Cookie lines for
+    // __session because the first loginUser already queued one; we're checking
+    // that at least one Max-Age=0 line is present.
+    await logoutUser(ctx);
+    const res = ctx.ok({ ok: true });
+
+    const headers = res.headers.getSetCookie?.() ?? [];
+    const sessionLines = headers.filter((l) => l.startsWith("__session="));
+    expect(sessionLines.length).toBeGreaterThan(0);
+    const hasExpiring = sessionLines.some((l) => l.includes("Max-Age=0"));
+    expect(hasExpiring).toBe(true);
+  });
+
+  it("is idempotent — two successive calls do not throw", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    // No prior login — session is empty. Two back-to-back logout calls must
+    // not throw. This exercises the "already logged out" code path.
+    await logoutUser(ctx);
+    await logoutUser(ctx);
+
+    const res = ctx.ok({ ok: true });
+    const line = readSetCookieLine(res, "__session");
+    expect(line).toBeTruthy();
+    expect(line!).toContain("Max-Age=0");
+  });
+
+  it("throws AuthenticationError when session middleware is not installed", async () => {
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await expect(logoutUser(ctx)).rejects.toBeInstanceOf(AuthenticationError);
+  });
+});
+
+// ========== currentUserId ==========
+
+describe("currentUserId — non-throwing reader", () => {
+  it("returns the userId after loginUser", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    expect(currentUserId(ctx)).toBeNull();
+    await loginUser(ctx, "abc-999");
+    expect(currentUserId(ctx)).toBe("abc-999");
+  });
+
+  it("returns null WITHOUT throwing when session middleware is absent", () => {
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    expect(() => currentUserId(ctx)).not.toThrow();
+    expect(currentUserId(ctx)).toBeNull();
+  });
+
+  it("returns null after logoutUser (in-memory wipe)", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await loginUser(ctx, "u-1");
+    expect(currentUserId(ctx)).toBe("u-1");
+
+    await logoutUser(ctx);
+    // destroySession wipes in-memory state → currentUserId sees no user.
+    expect(currentUserId(ctx)).toBeNull();
+  });
+
+  it("honors a custom userIdKey", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    await loginUser(ctx, "u-custom", { userIdKey: "uid" });
+    expect(currentUserId(ctx)).toBeNull(); // default key empty
+    expect(currentUserId(ctx, { userIdKey: "uid" })).toBe("u-custom");
+  });
+});
+
+// ========== loggedAt ==========
+
+describe("loggedAt — numeric timestamp reader", () => {
+  it("returns a timestamp close to Date.now() after login (within 1s)", async () => {
+    const storage = makeStorage();
+    const mw = session({ storage });
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    await mw(ctx);
+
+    const before = Date.now();
+    await loginUser(ctx, "u-1");
+    const after = Date.now();
+
+    const ts = loggedAt(ctx);
+    expect(ts).not.toBeNull();
+    expect(typeof ts).toBe("number");
+    expect(ts!).toBeGreaterThanOrEqual(before);
+    expect(ts!).toBeLessThanOrEqual(after);
+  });
+
+  it("returns null when session middleware is absent", () => {
+    const ctx = makeCtx(makeReq("http://localhost/"));
+    expect(loggedAt(ctx)).toBeNull();
+  });
+});
+
+// ========== End-to-end roundtrip through ManduFilling ==========
+
+describe("roundtrip — login → cookie → read → logout", () => {
+  it("completes a full login/read/logout flow across three requests", async () => {
+    const storage = makeStorage();
+
+    // Single filling pipeline handles all three paths via ?action=.
+    const filling = new ManduFilling()
+      .use(session({ storage }))
+      .get(async (ctx) => {
+        const action = new URL(ctx.request.url).searchParams.get("action");
+        if (action === "login") {
+          await loginUser(ctx, "roundtrip-user");
+          return ctx.ok({ stage: "login" });
+        }
+        if (action === "logout") {
+          await logoutUser(ctx);
+          return ctx.ok({ stage: "logout" });
+        }
+        // Default: read side.
+        return ctx.ok({ uid: currentUserId(ctx) });
+      });
+
+    // 1. Login — capture the Set-Cookie the browser would keep.
+    const loginRes = await filling.handle(makeReq("http://localhost/?action=login"));
+    expect(loginRes.status).toBe(200);
+    const cookieLine = readSetCookieLine(loginRes, "__session");
+    expect(cookieLine).toBeTruthy();
+    const cookieValue = readSetCookieRawValue(loginRes, "__session");
+    expect(cookieValue).toBeTruthy();
+
+    // 2. Read — re-attach the issued cookie and verify currentUserId finds
+    //    the id we stored.
+    const readRes = await filling.handle(
+      makeReq("http://localhost/", { cookie: `__session=${cookieValue}` }),
+    );
+    expect(readRes.status).toBe(200);
+    const readBody = (await readRes.json()) as { uid: string | null };
+    expect(readBody.uid).toBe("roundtrip-user");
+
+    // 3. Logout — issues expiring cookie; subsequent read with *that* cookie
+    //    returns null userId because the client would drop the cookie on
+    //    Max-Age=0. We simulate this by not passing any cookie on the fourth
+    //    request (emulating what the browser does after receiving the
+    //    expiring Set-Cookie).
+    const logoutRes = await filling.handle(
+      makeReq("http://localhost/?action=logout", { cookie: `__session=${cookieValue}` }),
+    );
+    expect(logoutRes.status).toBe(200);
+    const logoutLine = readSetCookieLine(logoutRes, "__session");
+    expect(logoutLine).toBeTruthy();
+    expect(logoutLine!).toContain("Max-Age=0");
+
+    // 4. Post-logout read with NO cookie — currentUserId is null.
+    const postLogoutRes = await filling.handle(makeReq("http://localhost/"));
+    const postLogoutBody = (await postLogoutRes.json()) as { uid: string | null };
+    expect(postLogoutBody.uid).toBeNull();
+  });
+});
+
+// ========== Composition with requireUser from filling/auth ==========
+
+describe("composition with requireUser — the loadUser bridge pattern", () => {
+  it("a loadUser beforeHandle bridges session.userId → ctx.set('user', ...) for requireUser", async () => {
+    // This is the common real-world pattern worth documenting as a test:
+    //
+    //   - `loginUser` writes `userId` to the SESSION (persisted across
+    //     requests via cookie).
+    //   - `requireUser` reads the USER OBJECT from ctx.store at key "user"
+    //     (a request-scoped store, wiped every request).
+    //   - A tiny middleware placed AFTER `session()` reads the session
+    //     userId, fetches the user record from your data layer, and calls
+    //     `ctx.set("user", user)`. That's the bridge.
+
+    interface User extends BaseUser {
+      id: string;
+      name: string;
+    }
+
+    // Fake user store.
+    const users = new Map<string, User>([
+      ["u-1", { id: "u-1", name: "Alice" }],
+      ["u-2", { id: "u-2", name: "Bob" }],
+    ]);
+
+    const storage = makeStorage();
+
+    const filling = new ManduFilling()
+      .use(session({ storage }))
+      // ⭐️ The bridge: after session() installs the Session, hydrate the
+      //    request-scoped `user` from the session's userId. Placed in
+      //    beforeHandle so ALL subsequent handler code can rely on
+      //    `requireUser(ctx)`.
+      .beforeHandle(async (ctx) => {
+        const uid = currentUserId(ctx);
+        if (uid) {
+          const user = users.get(uid);
+          if (user) ctx.set("user", user);
+        }
+      })
+      .get(async (ctx) => {
+        const action = new URL(ctx.request.url).searchParams.get("action");
+        if (action === "login") {
+          await loginUser(ctx, "u-1");
+          return ctx.ok({ stage: "login" });
+        }
+        // requireUser reads ctx.get("user") — the bridge populated it above
+        // IFF the session had a valid userId.
+        const user = requireUser<User>(ctx);
+        return ctx.ok({ id: user.id, name: user.name });
+      });
+
+    // 1. Login issues the cookie.
+    const loginRes = await filling.handle(makeReq("http://localhost/?action=login"));
+    expect(loginRes.status).toBe(200);
+    const cookieValue = readSetCookieRawValue(loginRes, "__session");
+    expect(cookieValue).toBeTruthy();
+
+    // 2. Second request re-attaches cookie → bridge hydrates → requireUser
+    //    returns the full user record.
+    const res = await filling.handle(
+      makeReq("http://localhost/", { cookie: `__session=${cookieValue}` }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { id: string; name: string };
+    expect(body.id).toBe("u-1");
+    expect(body.name).toBe("Alice");
+
+    // 3. Third request with NO cookie → no session userId → bridge does
+    //    nothing → requireUser throws → filling maps to 401.
+    const unauthRes = await filling.handle(makeReq("http://localhost/"));
+    expect(unauthRes.status).toBe(401);
+  });
+});

package/src/auth/__tests__/password.test.ts

@@ -0,0 +1,122 @@
+/**
+ * @mandujs/core/auth/password tests
+ *
+ * These tests exercise real argon2id and bcrypt hashing through `Bun.password`.
+ * They are CPU-bound (~50-200ms per hash op on laptop hardware); the suite
+ * uses the minimum cost parameters Bun accepts whenever the test does not
+ * care about actual KDF strength. Total runtime ~2-5s is expected.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { hashPassword, verifyPassword } from "../password";
+
+// Argon2 hashes start with "$argon2id$", "$argon2d$", or "$argon2i$".
+const ARGON2ID_PREFIX = "$argon2id$";
+// bcrypt hashes use $2a$/$2b$/$2y$ prefixes; Bun emits $2b$.
+const BCRYPT_PREFIX_RE = /^\$2[aby]\$/;
+
+// Minimum argon2 cost params — keep tests fast without changing behavior.
+const FAST_ARGON2 = {
+  algorithm: "argon2id",
+  memoryCost: 4,
+  timeCost: 2,
+} as const;
+
+describe("@mandujs/core/auth/password — hashPassword", () => {
+  it("produces an argon2id hash by default", async () => {
+    const h = await hashPassword("hunter2", FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("produces a bcrypt hash when algorithm=bcrypt is requested", async () => {
+    const h = await hashPassword("hunter2", { algorithm: "bcrypt", cost: 4 });
+    expect(h).toMatch(BCRYPT_PREFIX_RE);
+  });
+
+  it("throws on empty plaintext", async () => {
+    await expect(hashPassword("", FAST_ARGON2)).rejects.toThrow(
+      /non-empty string/,
+    );
+  });
+
+  it("throws when bcrypt input exceeds 72 bytes", async () => {
+    // 73 ASCII bytes (each char = 1 UTF-8 byte).
+    const tooLong = "a".repeat(73);
+    await expect(
+      hashPassword(tooLong, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("accepts >72-byte input when using argon2id (bcrypt-only limit)", async () => {
+    const longButFine = "a".repeat(100);
+    const h = await hashPassword(longButFine, FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("counts UTF-8 bytes (not code points) when enforcing the bcrypt limit", async () => {
+    // "é" is 2 bytes in UTF-8 — 40 of them = 80 bytes, over the 72 limit.
+    const multibyte = "é".repeat(40);
+    await expect(
+      hashPassword(multibyte, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("honors non-default argon2 timeCost via option pass-through", async () => {
+    // Bun embeds the cost parameters in the hash string:
+    //   $argon2id$v=19$m=<memoryCost>,t=<timeCost>,p=1$<salt>$<hash>
+    // We assert the timeCost is preserved end-to-end.
+    const h = await hashPassword("same-password", {
+      algorithm: "argon2id",
+      memoryCost: 4,
+      timeCost: 3,
+    });
+    expect(h).toMatch(/\$argon2id\$v=\d+\$m=4,t=3,p=\d+\$/);
+  });
+});
+
+describe("@mandujs/core/auth/password — verifyPassword", () => {
+  it("returns true for a matching argon2id roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", FAST_ARGON2);
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns true for a matching bcrypt roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", {
+      algorithm: "bcrypt",
+      cost: 4,
+    });
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns false for wrong plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("incorrect", h)).toBe(false);
+  });
+
+  it("returns false for a tampered hash (one char mutated)", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    // Flip the last character of the base64 hash segment.
+    const last = h.charAt(h.length - 1);
+    const replacement = last === "A" ? "B" : "A";
+    const tampered = h.slice(0, -1) + replacement;
+    expect(tampered).not.toBe(h);
+    expect(await verifyPassword("correct", tampered)).toBe(false);
+  });
+
+  it("returns false (never throws) for a malformed hash string", async () => {
+    // Bun.password.verify throws on unparseable hashes; our wrapper collapses
+    // every failure mode to `false` so login handlers stay branchless.
+    expect(await verifyPassword("anything", "not-a-hash")).toBe(false);
+  });
+
+  it("returns false for empty plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("", h)).toBe(false);
+  });
+
+  it("returns false for empty hash", async () => {
+    expect(await verifyPassword("correct", "")).toBe(false);
+  });
+});