@suluk/better-auth 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<h1 align="center">@suluk/better-auth</h1>
+
+<p align="center"><b>Official Better-Auth-on-Hono support for Suluk: auth methods -> v4 securitySchemes; ingest Better Auth's OpenAPI 3.0 -> v4; session -> principal for per-viewer docs.</b></p>
+
+<p align="center">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/better-auth
+```
+
+## The Suluk cycle
+
+`@suluk/better-auth` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
+preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
+[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,15 +1,26 @@
 {
   "name": "@suluk/better-auth",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Official Better-Auth-on-Hono support for Suluk: auth methods -> v4 securitySchemes; ingest Better Auth's OpenAPI 3.0 -> v4; session -> principal for per-viewer docs. CANDIDATE tooling.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-  ".": "./src/index.ts"
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/better-auth"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
 },
 "dependencies": {
-  "@suluk/core": "0.1.0",
-  "@suluk/openapi-compat": "0.1.0"
+  "@suluk/core": "0.1.6",
+  "@suluk/openapi-compat": "0.1.1"
 },
 "peerDependencies": {
   "better-auth": "^1.0.0",
@@ -25,7 +36,7 @@
 },
 "devDependencies": {
   "@types/bun": "latest",
-  "@suluk/hono": "0.1.0"
+  "@suluk/hono": "0.1.1"
 },
 "scripts": {
 "test": "bun test",

package/src/index.ts

@@ -11,3 +11,6 @@ export { authSecuritySchemes, type AuthMethods, type AuthSecurity } from "./secu
 export { normalizeOas30, ingestAuthOpenAPI, mergeAuth, type IngestOptions } from "./ingest";
 export { principalFromSession, type Principal, type SessionLike, type PrincipalOptions } from "./principal";
 export { mountAuth, type AuthHandlerLike, type HonoLike, type MountAuthOptions } from "./mount";
+// live role-preview (charter-bounded by C020): the fail-closed, deploy-gated role-login handler. The extension
+// holds NO token — it deep-links this route in the browser; the credentialed mint happens here, server-side.
+export { previewLoginHandler, isPreviewRuntime, type PreviewRequestLike, type PreviewEnvLike, type MintedSession, type PreviewLoginOptions } from "./preview";

package/src/preview.ts

@@ -0,0 +1,83 @@
+/**
+ * previewLoginHandler — the ONE credentialed surface in the whole cockpit, and the only place a session is
+ * minted for role-preview (the LAST roadmap slice, charter-bounded by C020). It runs INSIDE the generated
+ * PREVIEW Worker, never in the IDE: the extension merely deep-links `GET /preview/login?role=…` in the system
+ * browser, so no auth token ever lives in the editor.
+ *
+ * It is FAIL-CLOSED behind TWO INDEPENDENT LOCKS — both must say "preview":
+ *   1. a deploy-time var  `env.SULUK_PREVIEW === "1"`   (a prod wrangler config never sets it)
+ *   2. a binding          `env.PREVIEW_DB` is present    (a D1 only the preview deploy declares; prod has none)
+ * Absence of EITHER ⇒ 404, as if the route did not exist. A prod deploy that copy-pastes the var still lacks
+ * the binding; a stray binding without the var still 404s. The role is decided SERVER-SIDE from the verified
+ * gate + the request's `role` query param checked against an allow-list — never a client-trusted header, and
+ * the session binds ONLY to a seeded throwaway demo user (the injected mintSession owns that lookup), never a
+ * real row. Dependency-injected (env, allowedRoles, mintSession, now) so it is hermetically unit-testable with
+ * a plain Request + a fake env — no Worker, no D1, no wrangler, no creds.
+ *
+ * TTL / single-use is the deployed Worker's Better Auth SESSION policy (a preview session should be short and
+ * the env ephemeral) — not a Suluk artifact; previewDeployPlan's DEPLOY.md notes it and the teardown. This
+ * handler owns the GATE + the role-binding, which is Suluk's responsibility.
+ */
+
+/** A minimal view of the Worker request — only `.url` (to read the `role` query param) is needed. Web `Request` satisfies it. */
+export interface PreviewRequestLike {
+  url: string;
+}
+
+/** The two independent locks live on the Worker env: a var and a binding. Duck-typed; extra keys ignored. */
+export interface PreviewEnvLike {
+  /** lock 1 — the deploy-time preview flag. */
+  SULUK_PREVIEW?: string;
+  /** lock 2 — a D1 binding only the preview deploy declares (presence is the lock; we never read prod's DB here). */
+  PREVIEW_DB?: unknown;
+}
+
+/** What a successful mint returns: the headers to set on the redirect (e.g. the session Set-Cookie). */
+export interface MintedSession {
+  setCookie: string;
+}
+
+export interface PreviewLoginOptions {
+  /** The roles a preview may assume — derive from the contract (cockpit previewRoles), NEVER a hardcoded list.
+   *  A requested role MUST be a member; "anonymous" is handled by the launcher (it opens the app with no login). */
+  allowedRoles: string[];
+  /** Establish a role-scoped session for the SEEDED demo user of `role` (looks it up in env.PREVIEW_DB).
+   *  This is the only code that touches a session; it must bind to a seeded throwaway row, never a real user. */
+  mintSession: (role: string) => MintedSession | Promise<MintedSession>;
+  /** Where to land after login (default "/"). */
+  redirectTo?: string;
+}
+
+/** True iff BOTH independent locks say "preview". Exported so callers/tests can assert the gate in isolation. */
+export function isPreviewRuntime(env: PreviewEnvLike): boolean {
+  return env.SULUK_PREVIEW === "1" && env.PREVIEW_DB != null;
+}
+
+/**
+ * Handle `GET /preview/login?role=…`. Fail-closed: 404 unless both locks pass; 403 for a role not in the
+ * allow-list; else mint the seeded demo session and 302 to the app. Never throws on a hostile request.
+ */
+export async function previewLoginHandler(
+  req: PreviewRequestLike,
+  env: PreviewEnvLike,
+  opts: PreviewLoginOptions,
+): Promise<Response> {
+  // LOCK: both must say preview, or the route does not exist. Checked FIRST — before reading any client input —
+  // so a forged ?role= or x-role header can never reach the mint path on a non-preview deploy.
+  if (!isPreviewRuntime(env)) return new Response("not found", { status: 404 });
+
+  let role = "";
+  try { role = new URL(req.url).searchParams.get("role") ?? ""; } catch { role = ""; }
+
+  // "anonymous" is login-less by definition — never a mintable session, regardless of the allow-list (the launcher
+  // opens the app with no login for anonymous). Reject it explicitly so a caller can never mint an "anonymous" user.
+  if (role === "anonymous") return new Response("anonymous is not a preview login", { status: 403 });
+  // the role must be one the contract declares; membership is the only thing trusted from the client.
+  if (!opts.allowedRoles.includes(role)) return new Response("unknown preview role", { status: 403 });
+
+  const minted = await opts.mintSession(role); // binds to the SEEDED demo user for `role` (mintSession owns the lookup)
+  return new Response(null, {
+    status: 302,
+    headers: { Location: opts.redirectTo ?? "/", "Set-Cookie": minted.setCookie },
+  });
+}

package/test/preview.test.ts

@@ -0,0 +1,82 @@
+import { test, expect, describe } from "bun:test";
+import { previewLoginHandler, isPreviewRuntime, type PreviewEnvLike } from "../src/preview";
+
+const ALLOWED = ["user", "admin", "superadmin"];
+// a mintSession spy that records the role it was asked to bind to (and never runs unless the gate passes).
+function spy() {
+  const calls: string[] = [];
+  const mintSession = (role: string) => { calls.push(role); return { setCookie: `session=preview-${role}; HttpOnly` }; };
+  return { calls, mintSession };
+}
+const req = (role?: string) => ({ url: `https://app-preview.example.com/preview/login${role === undefined ? "" : `?role=${encodeURIComponent(role)}`}` });
+const previewEnv: PreviewEnvLike = { SULUK_PREVIEW: "1", PREVIEW_DB: {} };
+
+describe("previewLoginHandler — fail-closed behind TWO independent locks (INV-01)", () => {
+  test("flag unset ⇒ 404, mint NEVER called", async () => {
+    const { calls, mintSession } = spy();
+    const res = await previewLoginHandler(req("admin"), { PREVIEW_DB: {} }, { allowedRoles: ALLOWED, mintSession });
+    expect(res.status).toBe(404);
+    expect(calls).toHaveLength(0);
+  });
+  test("flag set but NO PREVIEW_DB binding ⇒ 404 (the second lock), mint NEVER called", async () => {
+    const { calls, mintSession } = spy();
+    const res = await previewLoginHandler(req("admin"), { SULUK_PREVIEW: "1" }, { allowedRoles: ALLOWED, mintSession });
+    expect(res.status).toBe(404);
+    expect(calls).toHaveLength(0);
+  });
+  test("a non-'1' flag value does not pass (no truthiness slop)", async () => {
+    const { calls, mintSession } = spy();
+    for (const v of ["0", "true", "yes", "preview", " 1"]) {
+      const res = await previewLoginHandler(req("admin"), { SULUK_PREVIEW: v, PREVIEW_DB: {} }, { allowedRoles: ALLOWED, mintSession });
+      expect(res.status).toBe(404);
+    }
+    expect(calls).toHaveLength(0);
+  });
+  test("BOTH locks + a valid seeded role ⇒ 302 to '/' with the role-scoped session cookie", async () => {
+    const { calls, mintSession } = spy();
+    const res = await previewLoginHandler(req("admin"), previewEnv, { allowedRoles: ALLOWED, mintSession });
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toBe("/");
+    expect(res.headers.get("set-cookie")).toContain("preview-admin");
+    expect(calls).toEqual(["admin"]); // bound exactly to the requested seeded role
+  });
+});
+
+describe("previewLoginHandler — role allow-list, never client-trusted (INV-04)", () => {
+  test("a role outside the contract's set ⇒ 403, mint NEVER called", async () => {
+    const { calls, mintSession } = spy();
+    for (const r of ["root", "", "ADMIN", "superadmin "]) {
+      const res = await previewLoginHandler(req(r), previewEnv, { allowedRoles: ALLOWED, mintSession });
+      expect(res.status).toBe(403);
+    }
+    expect(calls).toHaveLength(0);
+  });
+  test("missing role param ⇒ 403, mint NEVER called", async () => {
+    const { calls, mintSession } = spy();
+    const res = await previewLoginHandler(req(undefined), previewEnv, { allowedRoles: ALLOWED, mintSession });
+    expect(res.status).toBe(403);
+    expect(calls).toHaveLength(0);
+  });
+  test("'anonymous' is rejected even if a caller smuggles it into allowedRoles (login-less by definition)", async () => {
+    const { calls, mintSession } = spy();
+    const res = await previewLoginHandler(req("anonymous"), previewEnv, { allowedRoles: [...ALLOWED, "anonymous"], mintSession });
+    expect(res.status).toBe(403);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("previewLoginHandler — the gate precedes input (INV-07: server-side, not a client header)", () => {
+  test("with the flag OFF, a forged x-role header cannot reach the mint — still 404", async () => {
+    const { calls, mintSession } = spy();
+    // the handler only reads env + the role QUERY param; a header is meaningless. Gate is checked first.
+    const res = await previewLoginHandler({ url: "https://x/preview/login?role=admin" }, { PREVIEW_DB: {} }, { allowedRoles: ALLOWED, mintSession });
+    expect(res.status).toBe(404);
+    expect(calls).toHaveLength(0);
+  });
+  test("isPreviewRuntime requires BOTH a '1' flag and a PREVIEW_DB binding", () => {
+    expect(isPreviewRuntime({ SULUK_PREVIEW: "1", PREVIEW_DB: {} })).toBe(true);
+    expect(isPreviewRuntime({ SULUK_PREVIEW: "1" })).toBe(false);
+    expect(isPreviewRuntime({ PREVIEW_DB: {} })).toBe(false);
+    expect(isPreviewRuntime({})).toBe(false);
+  });
+});