@suluk/better-auth 0.1.2 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 <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"><b>Wire Better Auth into the v4 contract — auth methods become <code>securitySchemes</code>, the session becomes a <code>principal</code>, and Better Auth's own OpenAPI surface is ingested, never re-typed.</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>
@@ -24,11 +24,193 @@
 bun add @suluk/better-auth
 ```
 
-## The Suluk cycle
+`better-auth` and `hono` are optional peers — everything here is duck-typed, so you only need the ones
+you actually use.
 
-`@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).
+## What it does
+
+[Better Auth](https://www.better-auth.com) is a **Contract input** (your auth settings). This package
+reflects it into the Suluk v4 document and closes the per-viewer loop, without you re-typing the auth surface:
+
+- **Auth methods → v4 `securitySchemes`** — `authSecuritySchemes({ session, bearer, apiKey, … })` derives the
+  `components.securitySchemes` block (session-cookie, HTTP bearer, API-key header).
+- **Better Auth's OpenAPI 3.0 → v4** — `ingestAuthOpenAPI` normalizes Better Auth's own
+  `generateOpenAPISchema()` output to JSON Schema 2020-12, lifts it to v4 (via `@suluk/openapi-compat`), and
+  `mergeAuth` folds the auth routes + schemes into your app's document. `/sign-up`, `/get-session`, … get
+  documented for free.
+- **Session → `{ scopes }` principal** — `principalFromSession` maps a Better Auth session (role, granted
+  scopes, 2FA state, org memberships) to the `{ scopes }` shape `@suluk/hono`'s `emitV4(routes, { principal })`
+  uses to project the doc each viewer is allowed to see. `verifyApiKey` produces the **same** shape for API-key
+  callers, so enforcement is identical for sessions and keys.
+- **Thin Hono mount + auth-flow plumbing** — `mountAuth` routes `/api/auth/*` to the Better Auth handler;
+  helpers cover open-redirect-safe redirects, frictionless email verification, a GDPR erasure cascade, and a
+  fail-closed role-preview login route.
+
+## When to reach for it
+
+Reach for it when your app uses Better Auth and you want **auth reflected in the contract** — its schemes and
+its endpoints in the v4 doc — plus a **principal** that drives per-viewer projection and `@suluk/hono` access
+enforcement. The session→principal shape is the seam many other packages key off; this is where it's produced.
+
+Don't reach for it to *render* the doc (that's `@suluk/reference` / `@suluk/scalar` / `@suluk/swagger`) or to
+build routes from entities (that's `@suluk/builder` / `@suluk/drizzle`). This package's job ends at handing
+those layers a contract that already knows about auth, and a principal to scope it.
+
+## Usage
+
+### Reflect auth into the contract
+
+The common case: derive the schemes, ingest Better Auth's own OpenAPI, and merge both into the app doc.
+
+```ts
+import { authSecuritySchemes, ingestAuthOpenAPI, mergeAuth } from "@suluk/better-auth";
+import { auth } from "./auth"; // your betterAuth({ … }) instance, with the openAPI() plugin enabled
+
+// 1. auth methods → v4 securitySchemes
+const { securitySchemes } = authSecuritySchemes({ session: true, bearer: true, apiKey: true });
+
+// 2. ingest Better Auth's own OpenAPI 3.0 surface, lifted to v4 and prefixed under its mount base
+const authSchema = await auth.api.generateOpenAPISchema(); // OpenAPI 3.0
+const authV4 = ingestAuthOpenAPI(authSchema, { basePath: "/api/auth" });
+
+// 3. fold auth routes + schemes into your app's v4 document
+const document = mergeAuth(appDocument, authV4, { securitySchemes });
+// → document.paths now has "api/auth/sign-up/email", …; components.securitySchemes has sessionCookie/bearerAuth/apiKey
+```
+
+`authSecuritySchemes` also reports session-based plugins that add **no** new wire scheme but gate into the
+session — `{ twoFactor, passkey, organization }` — via the returned `plugins` field.
+
+### Close the per-viewer loop (session → principal)
+
+```ts
+import { principalFromSession } from "@suluk/better-auth";
+import { emitV4 } from "@suluk/hono";
+
+const session = await auth.api.getSession({ headers: req.headers });
+const principal = principalFromSession(session, {
+  roleScopes: { admin: ["read:*", "write:*"], user: ["read:self"] },
+});
+
+// @suluk/hono projects only the operations this viewer's scopes allow
+const { document } = emitV4(routes, { principal });
+```
+
+`principalFromSession` also encodes plugin state **as scopes**: a 2FA-cleared session gains `mfa:verified`
+(the exported `MFA_SCOPE`), and each org membership contributes `org:<id>:<scope>` scopes (build/parse them with
+`orgScope` / `parseOrgScope`) — so 2FA and tenancy gate through the same scope check `@suluk/hono` already runs.
+
+### Scope-aware API-key verification
+
+Give API-key callers the **same** `{ scopes }` principal as sessions, so `@suluk/hono`'s `createGuard` /
+`enforceAccess` works for keys too:
+
+```ts
+import { verifyApiKey } from "@suluk/better-auth";
+
+const result = await verifyApiKey(auth.api, key, { requireScopes: ["orders:read"] });
+if (!result.ok) {
+  // result.reason is "invalid" | "insufficient_scope" | "error"
+  return new Response("unauthorized", { status: 401 });
+}
+result.principal; // { scopes: ["orders:read", …] } — feed this to @suluk/hono
+result.key;       // { id, userId, name, metadata } — metadata parsed past Better Auth's double-stringification
+```
+
+`scopesToPermissions` / `permissionsToScopes` convert between flat `"cart:read"` scopes and Better Auth's
+`{ cart: ["read"] }` permission shape.
+
+### Mount the handler on Hono
+
+```ts
+import { mountAuth } from "@suluk/better-auth";
+import { Hono } from "hono";
+
+const app = new Hono();
+mountAuth(app, auth); // routes POST/GET /api/auth/* → auth.handler(c.req.raw)
+```
+
+### Auth-flow UX: redirects + frictionless verification
+
+```ts
+import {
+  resolveRedirectTo, withRedirectTo, isSafeRelativePath, emailVerificationConfig,
+} from "@suluk/better-auth";
+
+resolveRedirectTo(location.search);        // read ?redirectTo, honored only if same-origin-relative (open-redirect-safe)
+withRedirectTo("/login", "/dashboard");    // "/login?redirectTo=%2Fdashboard" — return here post-auth
+
+// spread into betterAuth({ emailVerification: … }) — verify-on-sign-up + auto-sign-in after, by default
+const emailVerification = emailVerificationConfig({
+  sendVerificationEmail: async ({ user, url }) => { await sendVerifyEmail(user.email, url); },
+});
+```
+
+### GDPR erasure cascade
+
+`beforeDeleteCascade` builds Better Auth's `user.deleteUser.beforeDelete` hook from an ordered list of steps.
+The package orchestrates; you supply the steps and pick the posture (`deleteStep` hard-deletes, `anonymizeStep`
+scrubs PII, `step` is generic). Fail-closed by default — a failed cleanup aborts the delete so no rows are orphaned.
+
+```ts
+import { betterAuth } from "better-auth";
+import { beforeDeleteCascade, deleteStep } from "@suluk/better-auth";
+
+const steps = [
+  deleteStep("orders", (user) => db.delete(orders).where(eq(orders.customerId, user.id)).run()),
+  deleteStep("apiTokens", (user) => db.delete(apiToken).where(eq(apiToken.userId, user.id)).run()),
+];
+
+betterAuth({
+  user: { deleteUser: { enabled: true, beforeDelete: beforeDeleteCascade(steps) } },
+});
+```
+
+### Role-preview login (the one credentialed surface)
+
+`previewLoginHandler` mints a role-scoped session for the seeded demo user, for the generated preview Worker —
+fail-closed behind two independent locks (`env.SULUK_PREVIEW === "1"` **and** an `env.PREVIEW_DB` binding;
+absence of either ⇒ 404). The role comes from a server-side allow-list, never a client header.
+
+```ts
+import { previewLoginHandler } from "@suluk/better-auth";
+
+// inside the preview Worker, for GET /preview/login?role=…
+return previewLoginHandler(request, env, {
+  allowedRoles: ["user", "admin"],          // from the contract's preview roles, NEVER hardcoded loosely
+  mintSession: (role) => mintDemoSession(role), // binds to a seeded throwaway demo user for `role`
+});
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `authSecuritySchemes(methods)` | Auth methods → v4 `securitySchemes` + the enabled session-plugins (`AuthMethods` → `AuthSecurity`). |
+| `ingestAuthOpenAPI(schema30, opts?)` | Normalize Better Auth's OpenAPI 3.0 to 2020-12 and lift it to a v4 document. |
+| `normalizeOas30(node)` | Rewrite 3.0 Schema dialect (`nullable`, boolean `exclusiveMin/Max`) into JSON Schema 2020-12. |
+| `mergeAuth(app, auth, extra?)` | Deep-merge auth paths + schemas + `securitySchemes` into the app's v4 document. |
+| `principalFromSession(session, opts?)` | Better Auth session → `{ scopes }` `Principal` (role, scopes, MFA, org). |
+| `MFA_SCOPE`, `orgScope`, `parseOrgScope` | The `mfa:verified` scope + build/parse `org:<id>:<scope>` tenancy scopes. |
+| `verifyApiKey(verifier, key, opts?)` | Verify an API key (optionally `requireScopes`) → the same `{ scopes }` `Principal`. |
+| `scopesToPermissions` / `permissionsToScopes` | Convert between flat `"a:b"` scopes and Better Auth's `{ a: ["b"] }` permissions. |
+| `parseApiKeyMetadata(raw)` | Parse key metadata past Better Auth's double-stringification quirk. |
+| `beforeDeleteCascade(steps, opts?)` | Build the `beforeDelete` hook from an ordered, fail-closed erasure cascade. |
+| `step` / `anonymizeStep` / `deleteStep` | Cascade-step constructors (generic / scrub-PII / hard-delete). |
+| `isSafeRelativePath` / `resolveRedirectTo` / `withRedirectTo` | Open-redirect-safe `redirectTo` preservation. |
+| `emailVerificationConfig(opts)` | A Better Auth `emailVerification` block with frictionless-activation defaults. |
+| `mountAuth(app, auth, opts?)` | Mount the Better Auth handler onto a Hono app under `basePath/*`. |
+| `previewLoginHandler(req, env, opts)` / `isPreviewRuntime(env)` | Fail-closed role-preview login + its two-lock gate check. |
+
+## Boundary
+
+This package **reflects and reads** Better Auth — it never becomes the auth runtime. Better Auth owns sessions,
+storage, and the credential flows; Suluk turns its configuration into a v4 contract and a scope-bearing principal.
+The seams are injected, not assumed: `mountAuth` / `verifyApiKey` are duck-typed against `auth.handler` /
+`auth.api` (no hard `better-auth` or `hono` import); `beforeDeleteCascade` takes the steps that touch *your* db;
+`previewLoginHandler` takes the `mintSession` that owns the session lookup. The session→principal **shape** is a
+stable contract many other `@suluk/*` packages depend on — extend the method→scheme and session→scope mappings,
+but keep that shape steady. Rendering the resulting doc, and hosting the auth itself, stay outside this line.
 
 ## License
 

package/package.json

@@ -1,45 +1,45 @@
 {
   "name": "@suluk/better-auth",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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.",
   "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.6",
-  "@suluk/openapi-compat": "0.1.1"
-},
-"peerDependencies": {
-  "better-auth": "^1.0.0",
-  "hono": "^4.0.0"
-},
-"peerDependenciesMeta": {
-  "better-auth": {
-  "optional": true
-},
-"hono": {
-"optional": true
-}
-},
-"devDependencies": {
-  "@types/bun": "latest",
-  "@suluk/hono": "0.1.1"
-},
-"scripts": {
-"test": "bun test",
-"typecheck": "tsc --noEmit -p ."
-}
+    "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.13",
+    "@suluk/openapi-compat": "^0.1.3"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.0.0",
+    "hono": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@suluk/hono": "^0.1.5"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }

package/src/apikey.ts

@@ -0,0 +1,135 @@
+/**
+ * Scope-aware API-key verification (saastarter-parity Phase 0). Closes the key-auth hole the advisory-facet model
+ * leaves: @suluk/hono's enforceAccess works off a `{ scopes }` Principal, but only `principalFromSession` produced
+ * one — a caller authenticating with an API KEY had no Principal, so a scope-gated op was unreachable-or-undefended
+ * for key auth. `verifyApiKey` wraps Better Auth's server `verifyApiKey` and returns the SAME `{ scopes }` Principal,
+ * so enforceAccess / createGuard gate key callers and session callers identically.
+ *
+ * Ported from saastarter src/lib/api-key/ (scopes.ts, metadata.ts) + the scope-check in services/auth.ts:133-147.
+ */
+import type { Principal } from "./principal";
+
+/** Metadata stored on a key for delegation tracking (saastarter metadata.ts:4-8). */
+export interface ApiKeyMetadata {
+  parentKeyId?: string;
+  parentKeyName?: string;
+  createdVia?: "delegation";
+}
+
+/**
+ * Safely parse key metadata, handling Better Auth's potential DOUBLE-stringification of the JSON field.
+ * Ported verbatim from saastarter metadata.ts:14-39 (the double-JSON.parse guard is load-bearing — without it a
+ * double-stringified blob silently reads as a string, not the object).
+ */
+export function parseApiKeyMetadata(raw: unknown): ApiKeyMetadata | null {
+  if (!raw) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw as ApiKeyMetadata;
+  if (typeof raw === "string") {
+    try {
+      let parsed: unknown = JSON.parse(raw);
+      if (typeof parsed === "string") parsed = JSON.parse(parsed); // double-stringified
+      if (typeof parsed === "object" && parsed && !Array.isArray(parsed)) return parsed as ApiKeyMetadata;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Flat scopes → Better Auth permissions. `["cart:read","cart:write"]` → `{ cart: ["read","write"] }`.
+ * Ported from saastarter scopes.ts:150-161 — `split(":")` destructures only the first two segments, so a malformed
+ * `"a:b:c"` yields `{ a: ["b"] }` and a segment-less `"x"` is skipped (no action). Faithful to saastarter semantics.
+ */
+export function scopesToPermissions(scopes: string[]): Record<string, string[]> {
+  const perms: Record<string, string[]> = {};
+  for (const scope of scopes) {
+    const [resource, action] = scope.split(":");
+    if (!resource || !action) continue;
+    (perms[resource] ??= []).push(action);
+  }
+  return perms;
+}
+
+/**
+ * Better Auth permissions → flat scopes. `{ cart: ["read","write"] }` → `["cart:read","cart:write"]`.
+ * DEVIATION from saastarter scopes.ts:167-179 (receipted): the `if (scope in API_SCOPES)` catalog filter is REMOVED.
+ * The scope catalog is APP-domain vocabulary (saastarter's ecommerce products/cart/orders), not auth machinery —
+ * baking a fixed catalog into a candidate-spec package would couple it to one app's domain. An app that wants
+ * catalog-validation filters the result against its own catalog. Lowered ceiling: this is reusable-primitive intent,
+ * not a behavioral port.
+ */
+export function permissionsToScopes(perms: Record<string, string[]> | null | undefined): string[] {
+  if (!perms) return [];
+  const scopes: string[] = [];
+  for (const [resource, actions] of Object.entries(perms)) {
+    for (const action of actions ?? []) scopes.push(`${resource}:${action}`);
+  }
+  return scopes;
+}
+
+/** A duck-typed view of Better Auth's server `verifyApiKey` (the app injects `betterAuth.api`). */
+export interface ApiKeyVerifierLike {
+  verifyApiKey(args: { body: { key: string; permissions?: Record<string, string[]> } }): Promise<{
+    valid: boolean;
+    error?: { message?: string; code?: string } | null;
+    key?: { id?: string; userId?: string; name?: string; permissions?: Record<string, string[]> | null; metadata?: unknown } | null;
+  }>;
+}
+
+export type VerifyReason = "invalid" | "insufficient_scope" | "error";
+
+/** The verified key's identity surface (metadata parsed via the double-stringification guard). */
+export interface VerifiedKey {
+  id?: string;
+  userId?: string;
+  name?: string;
+  metadata: ApiKeyMetadata | null;
+}
+
+export interface VerifyApiKeyResult {
+  ok: boolean;
+  /** why verification failed (absent on success). */
+  reason?: VerifyReason;
+  /** the `{ scopes }` Principal — the SAME shape principalFromSession returns, so enforceAccess works identically. */
+  principal?: Principal;
+  key?: VerifiedKey;
+}
+
+export interface VerifyApiKeyOptions {
+  /** require the key to carry these scopes (checked in the SAME call via Better Auth `permissions`, services/auth.ts:133-147). */
+  requireScopes?: string[];
+}
+
+/**
+ * Verify an API key (optionally requiring scopes) and return a `{ scopes }` Principal.
+ *
+ * DEVIATION from saastarter (receipted): saastarter never derives IDENTITY from `verifyApiKey` — identity comes from
+ * the session, and `verifyApiKey` is used ONLY to check scopes (services/auth.ts:133-147). Suluk's key-auth-only
+ * path uses the verified key's `userId` + `permissions` AS the Principal — an invented composition for stateless API
+ * callers that have no session. Result-returning (not throwing) to match the package idiom (preview.ts/principal.ts).
+ */
+export async function verifyApiKey(
+  verifier: ApiKeyVerifierLike,
+  key: string,
+  opts: VerifyApiKeyOptions = {},
+): Promise<VerifyApiKeyResult> {
+  const want = opts.requireScopes?.length ? scopesToPermissions(opts.requireScopes) : undefined;
+  let res: Awaited<ReturnType<ApiKeyVerifierLike["verifyApiKey"]>>;
+  try {
+    res = await verifier.verifyApiKey({ body: want ? { key, permissions: want } : { key } });
+  } catch {
+    return { ok: false, reason: "error" };
+  }
+  if (!res?.valid || !res.key) {
+    // best-effort: distinguish a scope failure from a bad key via the error code/message (only when scopes were required).
+    const code = `${res?.error?.code ?? ""} ${res?.error?.message ?? ""}`;
+    if (want && /scope|permission|forbidden/i.test(code)) return { ok: false, reason: "insufficient_scope" };
+    return { ok: false, reason: "invalid" };
+  }
+  return {
+    ok: true,
+    principal: { scopes: permissionsToScopes(res.key.permissions) },
+    key: { id: res.key.id, userId: res.key.userId, name: res.key.name, metadata: parseApiKeyMetadata(res.key.metadata) },
+  };
+}

package/src/auth-flow.ts

@@ -0,0 +1,47 @@
+/**
+ * Auth-flow UX helpers (saastarter parity: "auth preserves where you came from", "frictionless activation").
+ * Two concerns, both library-owned so every builder's auth pages inherit them instead of re-deriving:
+ *   - redirect preservation with an OPEN-REDIRECT guard (a `redirectTo` is honored only when it's a same-origin
+ *     relative path), threaded into social/magic-link callbackURL + the post-sign-in redirect + sign-out return;
+ *   - a Better Auth emailVerification block with frictionless defaults (verify-on-sign-up + auto-sign-in after).
+ * Pure + dependency-free.
+ */
+
+/** A path is safe to redirect to iff it's a SINGLE-leading-slash relative path (rejects "//host", "http(s)://…",
+ *  backslash tricks, and protocol-relative URLs) — defends against open-redirect. */
+export function isSafeRelativePath(p: string | null | undefined): p is string {
+  return !!p && p.startsWith("/") && !p.startsWith("//") && !p.startsWith("/\\") && !p.includes("://") && !p.includes("\\");
+}
+
+/** Read `redirectTo` from a query string / URLSearchParams; return it only if same-origin-relative, else `fallback`. */
+export function resolveRedirectTo(search: string | URLSearchParams, fallback = "/"): string {
+  const params = typeof search === "string" ? new URLSearchParams(search.startsWith("?") ? search.slice(1) : search) : search;
+  const raw = params.get("redirectTo");
+  return isSafeRelativePath(raw) ? raw : fallback;
+}
+
+/** Append a (guarded) `redirectTo` to an href — e.g. point "/login" at the page the user was on, so post-auth
+ *  returns there. A non-safe target is dropped (the href is returned unchanged). */
+export function withRedirectTo(href: string, redirectTo: string | null | undefined): string {
+  if (!isSafeRelativePath(redirectTo)) return href;
+  return href + (href.includes("?") ? "&" : "?") + "redirectTo=" + encodeURIComponent(redirectTo);
+}
+
+export interface EmailVerificationOptions {
+  /** send the verification email — bind to your branded-email builder. */
+  sendVerificationEmail: (data: { user: { email: string }; url: string; token?: string }) => Promise<void> | void;
+  /** sign the user in automatically after they click the verification link (default true — frictionless). */
+  autoSignIn?: boolean;
+  /** send a verification email on sign-up (default true). */
+  sendOnSignUp?: boolean;
+}
+
+/** A Better Auth `emailVerification` block with frictionless-activation defaults. Spread into
+ *  `betterAuth({ emailVerification: emailVerificationConfig({ sendVerificationEmail }) })`. */
+export function emailVerificationConfig(opts: EmailVerificationOptions) {
+  return {
+    sendOnSignUp: opts.sendOnSignUp ?? true,
+    autoSignInAfterVerification: opts.autoSignIn ?? true,
+    sendVerificationEmail: opts.sendVerificationEmail,
+  };
+}

package/src/dev-login.ts

@@ -0,0 +1,57 @@
+/**
+ * devLoginHandler (C057) — the LOCAL-DEV any-email login: the mock for Google OAuth when no `GOOGLE_CLIENT_ID` is set,
+ * so you sign in as ANY email with no password. It mints a REAL Better Auth session via the PUBLIC server API
+ * (`signUpEmail` idempotently, then `signInEmail({ asResponse: true })` with a fixed internal dev password) — it never
+ * hand-forges a cookie or touches the internal adapter, so the session is exactly what a real login produces.
+ *
+ * The security control lives HERE (npm), so it flows to every consumer and an app can't weaken it by editing its wiring:
+ * it is FAIL-CLOSED behind an `armed` flag the caller must pass `true`, checked FIRST — before any request input is read.
+ * The registry wiring arms it only in dev-mock mode (non-production AND no Google key); a prod deploy (ENVIRONMENT=
+ * "production") passes `armed: false`, so the endpoint returns 404 as if it did not exist. The fixed dev password is an
+ * internal detail (never surfaced) used purely to drive the email/password flow; it is not a real credential.
+ */
+
+/** The Better Auth surface this needs — its public `signUpEmail`/`signInEmail` server endpoints. Duck-typed. */
+export interface DevLoginAuthLike {
+  api: {
+    signUpEmail(input: { body: { email: string; password: string; name: string } }): Promise<unknown>;
+    signInEmail(input: { body: { email: string; password: string }; asResponse: true }): Promise<Response>;
+  };
+}
+
+export interface DevLoginOptions {
+  /** FAIL-CLOSED gate — MUST be `true` to arm the endpoint. The registry passes its dev-mock condition; prod passes false. */
+  armed: boolean;
+  /** the Better Auth instance (its `api.signUpEmail`/`signInEmail`). */
+  auth: DevLoginAuthLike;
+  /** the incoming request — a JSON body `{ email }`. */
+  request: Request;
+  /** override the fixed internal dev password (dev only; never surfaced). */
+  devPassword?: string;
+}
+
+/** The fixed internal password the dev-login uses to drive email/password sign-up + sign-in. Not a real credential. */
+export const DEV_LOGIN_PASSWORD = "suluk-dev-login-fixed-pw-00000000";
+
+const isEmail = (s: string): boolean => /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(s);
+const json = (obj: unknown, status: number): Response => new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+
+/**
+ * Handle `POST /api/auth/dev-login` with `{ email }`. FAIL-CLOSED: 404 unless `armed` (checked before reading input);
+ * 400 for a missing/invalid email; else mint a real session for that email and return the sign-in Response (Set-Cookie).
+ * Never throws on a hostile request.
+ */
+export async function devLoginHandler(opts: DevLoginOptions): Promise<Response> {
+  // GATE first — before any client input is read — so a request to a non-armed deploy can never reach the mint path.
+  if (opts.armed !== true) return new Response("not found", { status: 404 });
+
+  let email = "";
+  try { email = String(((await opts.request.json()) as { email?: unknown }).email ?? "").trim().toLowerCase(); } catch { email = ""; }
+  if (!email || !isEmail(email)) return json({ error: "a valid `email` is required" }, 400);
+
+  const password = opts.devPassword ?? DEV_LOGIN_PASSWORD;
+  // find-or-create: sign up (idempotent — a re-login of an existing dev user throws "exists", which we ignore), then
+  // sign in AS A RESPONSE so the session Set-Cookie rides back exactly as a real login would set it.
+  try { await opts.auth.api.signUpEmail({ body: { email, password, name: email } }); } catch { /* user already exists */ }
+  return opts.auth.api.signInEmail({ body: { email, password }, asResponse: true });
+}

package/src/erasure.ts

@@ -0,0 +1,64 @@
+/**
+ * GDPR erasure cascade (saastarter-parity Phase 0). Closes the account-deletion hole: when a user is deleted their
+ * owned rows + external records (Stripe customer, addresses, …) must be erased too. Ported from saastarter's
+ * `user.deleteUser.beforeDelete` hook (src/lib/auth/options.ts:127) — but made a REUSABLE primitive: the package
+ * ORCHESTRATES an ordered cascade and the app supplies the concrete steps + PICKS the posture.
+ *
+ * Posture is the app's choice (the reviewer's hard fork): the package ships BOTH hard-DELETE (cascade-remove) and
+ * ANONYMIZE (keep the row, scrub PII — the FK-safe right-to-be-forgotten posture, the recommended default) as thin
+ * labeled step constructors, and imposes NEITHER. Recovery-WITHIN-a-step (e.g. saastarter's Stripe-already-deleted →
+ * delete-by-email fallback, options.ts:147-167) lives inside the step's `run`, never in this orchestrator.
+ */
+
+/** One step of the erasure cascade — the erasure of one subsystem for one user. */
+export interface CascadeStep<U> {
+  /** a label for logs/diagnostics. */
+  name: string;
+  /** perform the erasure. Put any in-step recovery (already-deleted → fallback) HERE, not in the orchestrator. */
+  run: (user: U) => Promise<void> | void;
+}
+
+export interface CascadeOptions {
+  /** if a step throws: log + continue (true), or ABORT the whole cascade (false — the fail-closed default, so a
+   *  failed cleanup never silently half-erases and then deletes the user). */
+  continueOnError?: boolean;
+  /** diagnostics sink (default console.error). */
+  log?: (step: string, error: unknown) => void;
+}
+
+/** A generic cascade step. */
+export function step<U>(name: string, run: (user: U) => Promise<void> | void): CascadeStep<U> {
+  return { name, run };
+}
+
+/** An ANONYMIZE step — keep the row, scrub its PII (the FK-safe posture; recommended default). */
+export function anonymizeStep<U>(name: string, run: (user: U) => Promise<void> | void): CascadeStep<U> {
+  return { name: `anonymize:${name}`, run };
+}
+
+/** A hard-DELETE step — cascade-remove a subsystem's rows for the user. */
+export function deleteStep<U>(name: string, run: (user: U) => Promise<void> | void): CascadeStep<U> {
+  return { name: `delete:${name}`, run };
+}
+
+/**
+ * Build the Better Auth `user.deleteUser.beforeDelete` hook (options.ts:127) from an ordered erasure cascade.
+ * Runs each step in order; on a step error it logs and — unless `continueOnError` — rethrows to ABORT (so the user
+ * is NOT deleted when cleanup failed, never orphaning their external records).
+ */
+export function beforeDeleteCascade<U>(
+  steps: CascadeStep<U>[],
+  opts: CascadeOptions = {},
+): (user: U) => Promise<void> {
+  const log = opts.log ?? ((s, e) => console.error(`erasure step "${s}" failed:`, e));
+  return async (user: U) => {
+    for (const s of steps) {
+      try {
+        await s.run(user);
+      } catch (e) {
+        log(s.name, e);
+        if (!opts.continueOnError) throw e; // fail-closed: abort rather than half-erase
+      }
+    }
+  };
+}

package/src/index.ts

@@ -1,16 +1,32 @@
 /**
- * @suluk/better-auth — official Better-Auth-on-Hono support for the Suluk derivation engine.
+ * `@suluk/better-auth` — official Better-Auth-on-Hono support for the Suluk derivation engine.
  *
  * Better Auth is a Contract input (auth settings). This package: (1) derives v4 securitySchemes from the
  * enabled auth methods; (2) ingests Better Auth's own OpenAPI 3.0 output (normalizing it to 2020-12) and
  * lifts it to v4 via @suluk/openapi-compat, then merges it into the app doc — so the auth surface is
  * documented without re-typing; (3) maps a Better Auth session to a { scopes } principal that feeds
- * @suluk/hono's per-viewer emitV4; (4) mounts the auth handler on Hono. CANDIDATE tooling.
+ * `@suluk/hono`'s per-viewer emitV4; (4) mounts the auth handler on Hono. CANDIDATE tooling.
  */
 export { authSecuritySchemes, type AuthMethods, type AuthSecurity } from "./security";
 export { normalizeOas30, ingestAuthOpenAPI, mergeAuth, type IngestOptions } from "./ingest";
-export { principalFromSession, type Principal, type SessionLike, type PrincipalOptions } from "./principal";
+export {
+  principalFromSession, MFA_SCOPE, orgScope, parseOrgScope,
+  type Principal, type SessionLike, type PrincipalOptions,
+} from "./principal";
 export { mountAuth, type AuthHandlerLike, type HonoLike, type MountAuthOptions } from "./mount";
+// scope-aware API-key verification (Phase 0): wraps Better Auth's verifyApiKey to return a { scopes } Principal,
+// so @suluk/hono enforcement works for key callers, not just sessions.
+export {
+  verifyApiKey, scopesToPermissions, permissionsToScopes, parseApiKeyMetadata,
+  type ApiKeyVerifierLike, type VerifyApiKeyResult, type VerifyApiKeyOptions, type VerifiedKey, type VerifyReason, type ApiKeyMetadata,
+} from "./apikey";
+// GDPR erasure cascade (Phase 0): the reusable beforeDelete orchestrator; the app supplies steps + picks the posture.
+export { beforeDeleteCascade, step, anonymizeStep, deleteStep, type CascadeStep, type CascadeOptions } from "./erasure";
+// auth-flow UX: open-redirect-safe redirect preservation + a frictionless emailVerification config.
+export { isSafeRelativePath, resolveRedirectTo, withRedirectTo, emailVerificationConfig, type EmailVerificationOptions } from "./auth-flow";
 // 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";
+// C057 local-dev any-email login (the Google mock when no GOOGLE_CLIENT_ID) — fail-closed behind an `armed` flag, mints
+// a REAL session via the public signUp/signIn API. The registry arms it only in dev-mock mode; a prod deploy 404s it.
+export { devLoginHandler, DEV_LOGIN_PASSWORD, type DevLoginAuthLike, type DevLoginOptions } from "./dev-login";

package/src/principal.ts

@@ -14,14 +14,39 @@ export interface SessionLike {
   /** apiKey plugin: a key carries its own permissions/scopes. */
   apiKey?: { scopes?: string[]; permissions?: Record<string, string[]> } | null;
   scopes?: string[];
+  /** twoFactor plugin: the session has cleared its second factor ⇒ the `mfa:verified` scope (Phase 1). */
+  twoFactorVerified?: boolean;
+  /** organization plugin: memberships → `org:<id>:<scope>` scopes (Phase 1, tenancy via scope-encoding). */
+  organizations?: { id: string; role?: string; scopes?: string[] }[];
 }
 
 export interface PrincipalOptions {
   /** Map a role name → the scopes it grants (e.g. { admin: ["read:*","write:*"], user: ["read:self"] }). */
   roleScopes?: Record<string, string[]>;
+  /** Map an ORG role → the scopes it grants WITHIN an org (each namespaced to `org:<id>:<scope>`). */
+  orgRoleScopes?: Record<string, string[]>;
 }
 
-/** Extract a { scopes } principal from a Better Auth session. Null/undefined session ⇒ anonymous (no scopes). */
+/** The scope a route requires to be sure the caller cleared their second factor (twoFactor plugin). */
+export const MFA_SCOPE = "mfa:verified" as const;
+
+/** Build the org-namespaced scope `org:<orgId>:<action>` (the tenancy encoding). */
+export function orgScope(orgId: string, action: string): string {
+  return `org:${orgId}:${action}`;
+}
+
+/** Parse an `org:<id>:<action>` scope back into its parts (null if it isn't one). */
+export function parseOrgScope(scope: string): { orgId: string; action: string } | null {
+  const m = /^org:([^:]+):(.+)$/.exec(scope);
+  return m ? { orgId: m[1], action: m[2] } : null;
+}
+
+/**
+ * Extract a { scopes } principal from a Better Auth session. Null/undefined session ⇒ anonymous (no scopes).
+ * Beyond the user/apiKey scopes, it encodes MFA + org state AS scopes (Phase 1): a 2FA-cleared session gains
+ * `mfa:verified`, and each org membership contributes `org:<id>:<scope>` (explicit + role-mapped) — so a route
+ * gates 2FA/tenancy through the same scope check enforceAccess already does, no richer Principal type required.
+ */
 export function principalFromSession(session: SessionLike | null | undefined, opts: PrincipalOptions = {}): Principal {
   if (!session) return { scopes: [] };
   const scopes = new Set<string>();
@@ -34,5 +59,14 @@ export function principalFromSession(session: SessionLike | null | undefined, op
   const roleList = Array.isArray(roles) ? roles : roles ? [roles] : [];
   for (const role of roleList) for (const s of opts.roleScopes?.[role] ?? []) scopes.add(s);
 
+  // MFA state → scope (the twoFactor plugin)
+  if (session.twoFactorVerified) scopes.add(MFA_SCOPE);
+
+  // org memberships → org-namespaced scopes (the organization plugin)
+  for (const org of session.organizations ?? []) {
+    for (const s of org.scopes ?? []) scopes.add(orgScope(org.id, s));
+    if (org.role) for (const s of opts.orgRoleScopes?.[org.role] ?? []) scopes.add(orgScope(org.id, s));
+  }
+
   return { scopes: [...scopes] };
 }

package/src/security.ts

@@ -15,6 +15,12 @@ export interface AuthMethods {
   bearer?: boolean;
   /** API key (the apiKey plugin). `true` ⇒ default "x-api-key" header; or pass a custom header. */
   apiKey?: boolean | { header?: string };
+  /** twoFactor plugin — MFA on top of the session (no new wire scheme; gates via the `mfa:verified` scope). */
+  twoFactor?: boolean;
+  /** passkey (WebAuthn) plugin — a credential method that authenticates INTO a session (no new wire scheme). */
+  passkey?: boolean;
+  /** organization plugin — multi-tenancy via `org:<id>:<scope>` scopes (no new wire scheme). */
+  organization?: boolean;
 }
 
 export interface AuthSecurity {
@@ -22,6 +28,8 @@ export interface AuthSecurity {
   securitySchemes: Record<string, SecurityScheme>;
   /** Convenience: the scheme names, to build by-name security requirements. */
   names: string[];
+  /** Enabled session-based plugins (NOT wire schemes — they gate into the session via scope-encoding). */
+  plugins: { twoFactor: boolean; passkey: boolean; organization: boolean };
 }
 
 const DEFAULT_SESSION_COOKIE = "better-auth.session_token";
@@ -41,5 +49,9 @@ export function authSecuritySchemes(methods: AuthMethods): AuthSecurity {
     const header = typeof methods.apiKey === "object" ? methods.apiKey.header ?? DEFAULT_APIKEY_HEADER : DEFAULT_APIKEY_HEADER;
     securitySchemes.apiKey = { type: "apiKey", in: "header", name: header };
   }
-  return { securitySchemes, names: Object.keys(securitySchemes) };
+  return {
+    securitySchemes,
+    names: Object.keys(securitySchemes),
+    plugins: { twoFactor: !!methods.twoFactor, passkey: !!methods.passkey, organization: !!methods.organization },
+  };
 }

package/test/apikey.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe } from "bun:test";
+import { Hono } from "hono";
+import { createGuard } from "@suluk/hono";
+import {
+  verifyApiKey, scopesToPermissions, permissionsToScopes, parseApiKeyMetadata,
+  type ApiKeyVerifierLike,
+} from "../src/index";
+
+describe("scope ⇄ permission conversion (ported from saastarter api-key/scopes.ts)", () => {
+  test("scopesToPermissions groups by resource (scopes.ts:150-161)", () => {
+    expect(scopesToPermissions(["cart:read", "cart:write", "products:read"])).toEqual({
+      cart: ["read", "write"], products: ["read"],
+    });
+  });
+
+  test("scopesToPermissions: a segment-less scope is skipped; 'a:b:c' keeps only resource:action (faithful destructure)", () => {
+    expect(scopesToPermissions(["bare", "a:b:c"])).toEqual({ a: ["b"] }); // 'c' dropped, 'bare' skipped
+  });
+
+  test("permissionsToScopes flattens; null ⇒ []", () => {
+    expect(permissionsToScopes({ cart: ["read", "write"] })).toEqual(["cart:read", "cart:write"]);
+    expect(permissionsToScopes(null)).toEqual([]);
+  });
+
+  test("permissionsToScopes is round-trip-stable and (DEVIATION) keeps non-catalog scopes", () => {
+    const perms = { anything: ["do"], orders: ["read"] };
+    // saastarter would filter `anything:do` against API_SCOPES; we keep it (the catalog is the app's concern).
+    expect(permissionsToScopes(perms)).toEqual(["anything:do", "orders:read"]);
+    expect(scopesToPermissions(permissionsToScopes(perms))).toEqual(perms);
+  });
+});
+
+describe("parseApiKeyMetadata (ported verbatim, metadata.ts:14-39)", () => {
+  test("object passthrough; single + double-stringified JSON; invalid ⇒ null", () => {
+    expect(parseApiKeyMetadata({ createdVia: "delegation" })).toEqual({ createdVia: "delegation" });
+    expect(parseApiKeyMetadata(JSON.stringify({ parentKeyId: "p1" }))).toEqual({ parentKeyId: "p1" });
+    expect(parseApiKeyMetadata(JSON.stringify(JSON.stringify({ parentKeyId: "p2" })))).toEqual({ parentKeyId: "p2" });
+    expect(parseApiKeyMetadata("not json")).toBeNull();
+    expect(parseApiKeyMetadata(null)).toBeNull();
+  });
+});
+
+describe("verifyApiKey — scope-aware, returns a { scopes } Principal", () => {
+  const verifier = (resp: unknown, capture?: (body: unknown) => void): ApiKeyVerifierLike => ({
+    verifyApiKey: async ({ body }) => { capture?.(body); return resp as never; },
+  });
+
+  test("a valid key yields ok + a Principal flattened from its permissions + the key identity", async () => {
+    const r = await verifyApiKey(verifier({ valid: true, key: { userId: "u1", permissions: { orders: ["read"] }, metadata: JSON.stringify({ createdVia: "delegation" }) } }), "k");
+    expect(r.ok).toBe(true);
+    expect(r.principal).toEqual({ scopes: ["orders:read"] });
+    expect(r.key).toMatchObject({ userId: "u1", metadata: { createdVia: "delegation" } });
+  });
+
+  test("requireScopes is checked in the SAME verify call via permissions (services/auth.ts:133-147)", async () => {
+    let sentBody: unknown;
+    await verifyApiKey(verifier({ valid: true, key: { userId: "u1", permissions: { orders: ["read"] } } }, (b) => (sentBody = b)), "k", { requireScopes: ["orders:read"] });
+    expect(sentBody).toEqual({ key: "k", permissions: { orders: ["read"] } });
+  });
+
+  test("an invalid key ⇒ ok:false reason 'invalid'; a scope error ⇒ 'insufficient_scope'; a throw ⇒ 'error'", async () => {
+    expect((await verifyApiKey(verifier({ valid: false, key: null }), "k")).reason).toBe("invalid");
+    expect((await verifyApiKey(verifier({ valid: false, error: { code: "INSUFFICIENT_PERMISSIONS" } }), "k", { requireScopes: ["orders:write"] })).reason).toBe("insufficient_scope");
+    const thrower: ApiKeyVerifierLike = { verifyApiKey: async () => { throw new Error("down"); } };
+    expect((await verifyApiKey(thrower, "k")).reason).toBe("error");
+  });
+});
+
+describe("integration: the key Principal makes @suluk/hono enforcement work for key auth", () => {
+  test("a key with orders:read passes requireScopes('orders:read') but is 403 for admin", async () => {
+    const verifier: ApiKeyVerifierLike = { verifyApiKey: async () => ({ valid: true, key: { userId: "u1", permissions: { orders: ["read"] } } }) };
+    const result = await verifyApiKey(verifier, "k");
+    const guard = createGuard({ principal: () => result.key!.userId, scopes: () => result.principal!.scopes });
+    const app = new Hono();
+    app.get("/orders", guard.requireScopes("orders:read"), (c) => c.text("ok"));
+    app.get("/admin", guard.requireScopes("admin"), (c) => c.text("ok"));
+    expect((await app.request("/orders")).status).toBe(200);
+    expect((await app.request("/admin")).status).toBe(403);
+  });
+});

package/test/auth-flow.test.ts

@@ -0,0 +1,39 @@
+import { test, expect, describe } from "bun:test";
+import { isSafeRelativePath, resolveRedirectTo, withRedirectTo, emailVerificationConfig } from "../src/auth-flow";
+
+describe("redirect preservation — open-redirect-safe", () => {
+  test("accepts same-origin relative paths, rejects everything that could escape origin", () => {
+    expect(isSafeRelativePath("/account")).toBe(true);
+    expect(isSafeRelativePath("/products?x=1#h")).toBe(true);
+    for (const bad of [null, undefined, "", "account", "//evil.com", "https://evil.com", "http://evil.com", "/\\evil.com", "javascript://%0aalert(1)", "/a\\b"]) {
+      expect(isSafeRelativePath(bad as any), `must reject: ${bad}`).toBe(false);
+    }
+  });
+  test("resolveRedirectTo reads ?redirectTo, falls back when absent/unsafe", () => {
+    expect(resolveRedirectTo("?redirectTo=/dashboard", "/account")).toBe("/dashboard");
+    expect(resolveRedirectTo("redirectTo=%2Fcart", "/account")).toBe("/cart"); // decoded by URLSearchParams
+    expect(resolveRedirectTo("?foo=1", "/account")).toBe("/account"); // absent → fallback
+    expect(resolveRedirectTo("?redirectTo=https://evil.com", "/account")).toBe("/account"); // unsafe → fallback
+    expect(resolveRedirectTo(new URLSearchParams("redirectTo=/x"))).toBe("/x");
+  });
+  test("withRedirectTo appends a guarded redirectTo (and drops an unsafe one)", () => {
+    expect(withRedirectTo("/login", "/checkout")).toBe("/login?redirectTo=%2Fcheckout");
+    expect(withRedirectTo("/login?x=1", "/cart")).toBe("/login?x=1&redirectTo=%2Fcart");
+    expect(withRedirectTo("/login", "//evil.com")).toBe("/login"); // unsafe dropped
+  });
+});
+
+describe("emailVerificationConfig — frictionless defaults", () => {
+  test("defaults to verify-on-sign-up + auto-sign-in, threads the sender", () => {
+    const send = () => {};
+    const cfg = emailVerificationConfig({ sendVerificationEmail: send });
+    expect(cfg.sendOnSignUp).toBe(true);
+    expect(cfg.autoSignInAfterVerification).toBe(true);
+    expect(cfg.sendVerificationEmail).toBe(send);
+  });
+  test("overrides are honored", () => {
+    const cfg = emailVerificationConfig({ sendVerificationEmail: () => {}, autoSignIn: false, sendOnSignUp: false });
+    expect(cfg.autoSignInAfterVerification).toBe(false);
+    expect(cfg.sendOnSignUp).toBe(false);
+  });
+});

package/test/dev-login.test.ts

@@ -0,0 +1,45 @@
+import { test, expect } from "bun:test";
+import { devLoginHandler } from "../src/dev-login";
+
+const req = (body: unknown) => new Request("http://localhost/api/auth/dev-login", { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json" } });
+
+function fakeAuth() {
+  const calls: any = { signUp: [], signIn: [] };
+  const auth = {
+    api: {
+      async signUpEmail(input: any) { calls.signUp.push(input.body); if (input.body.email === "exists@x.com") throw new Error("User already exists"); return {}; },
+      async signInEmail(input: any) { calls.signIn.push(input.body); return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { "set-cookie": "better-auth.session_token=abc; Path=/" } }); },
+    },
+  };
+  return { auth, calls };
+}
+
+test("FAIL-CLOSED: armed=false → 404 before any input is read", async () => {
+  const { auth, calls } = fakeAuth();
+  const res = await devLoginHandler({ armed: false, auth, request: req({ email: "a@b.com" }) });
+  expect(res.status).toBe(404);
+  expect(calls.signUp).toHaveLength(0); // never reached the mint path
+});
+
+test("armed + valid email → signs up + signs in, returns the session Response", async () => {
+  const { auth, calls } = fakeAuth();
+  const res = await devLoginHandler({ armed: true, auth, request: req({ email: "New@B.com" }) });
+  expect(res.status).toBe(200);
+  expect(res.headers.get("set-cookie")).toContain("session_token");
+  expect(calls.signUp[0].email).toBe("new@b.com"); // normalized lower-case
+  expect(calls.signIn[0].email).toBe("new@b.com");
+});
+
+test("armed + already-existing user → ignores signUp error, still signs in", async () => {
+  const { auth, calls } = fakeAuth();
+  const res = await devLoginHandler({ armed: true, auth, request: req({ email: "exists@x.com" }) });
+  expect(res.status).toBe(200);
+  expect(calls.signIn).toHaveLength(1);
+});
+
+test("armed + invalid/missing email → 400, no mint", async () => {
+  const { auth, calls } = fakeAuth();
+  expect((await devLoginHandler({ armed: true, auth, request: req({ email: "not-an-email" }) })).status).toBe(400);
+  expect((await devLoginHandler({ armed: true, auth, request: req({}) })).status).toBe(400);
+  expect(calls.signIn).toHaveLength(0);
+});

package/test/erasure.test.ts

@@ -0,0 +1,52 @@
+import { test, expect, describe } from "bun:test";
+import { beforeDeleteCascade, step, anonymizeStep, deleteStep } from "../src/index";
+
+type User = { id: string; email: string };
+const user: User = { id: "u1", email: "a@b.co" };
+
+describe("beforeDeleteCascade — the GDPR erasure orchestrator (ported from saastarter options.ts:127)", () => {
+  test("runs every step in order", async () => {
+    const order: string[] = [];
+    const hook = beforeDeleteCascade<User>([
+      step("stripe", () => { order.push("stripe"); }),
+      anonymizeStep("profile", () => { order.push("profile"); }),
+      deleteStep("addresses", () => { order.push("addresses"); }),
+    ]);
+    await hook(user);
+    expect(order).toEqual(["stripe", "profile", "addresses"]);
+  });
+
+  test("fail-closed by default: a throwing step ABORTS — later steps don't run, the hook rejects", async () => {
+    const order: string[] = [];
+    const hook = beforeDeleteCascade<User>([
+      step("ok", () => { order.push("ok"); }),
+      step("boom", () => { throw new Error("stripe down"); }),
+      step("never", () => { order.push("never"); }),
+    ], { log: () => {} });
+    await expect(hook(user)).rejects.toThrow("stripe down");
+    expect(order).toEqual(["ok"]); // "never" did not run; the user is NOT deleted
+  });
+
+  test("continueOnError logs + proceeds; the hook resolves", async () => {
+    const order: string[] = [];
+    const logged: string[] = [];
+    const hook = beforeDeleteCascade<User>([
+      step("boom", () => { throw new Error("already gone"); }),
+      step("addresses", () => { order.push("addresses"); }),
+    ], { continueOnError: true, log: (s) => logged.push(s) });
+    await hook(user);
+    expect(order).toEqual(["addresses"]);
+    expect(logged).toEqual(["boom"]);
+  });
+
+  test("recovery-within-a-step keeps the cascade clean (the saastarter Stripe-already-deleted → email fallback)", async () => {
+    const calls: string[] = [];
+    const deleteStripeCustomer = async (u: User) => {
+      try { calls.push("del-by-id"); throw new Error("no such customer"); }
+      catch { calls.push(`del-by-email:${u.email}`); } // recovery lives in the step, not the orchestrator
+    };
+    const hook = beforeDeleteCascade<User>([deleteStep("stripe", deleteStripeCustomer)]);
+    await hook(user); // resolves — the step handled its own recovery
+    expect(calls).toEqual(["del-by-id", "del-by-email:a@b.co"]);
+  });
+});

package/test/mfa-org.test.ts

@@ -0,0 +1,40 @@
+import { test, expect, describe } from "bun:test";
+import { principalFromSession, MFA_SCOPE, orgScope, parseOrgScope, authSecuritySchemes } from "../src/index";
+
+describe("2FA + org scope-encoding (Phase 1) — Principal extension via scopes", () => {
+  test("a 2FA-cleared session gains mfa:verified; an un-verified one does not", () => {
+    expect(principalFromSession({ twoFactorVerified: true }).scopes).toContain(MFA_SCOPE);
+    expect(principalFromSession({ twoFactorVerified: false }).scopes).not.toContain(MFA_SCOPE);
+    expect(principalFromSession({}).scopes).not.toContain(MFA_SCOPE);
+  });
+
+  test("org memberships → org:<id>:<scope> (explicit + role-mapped, namespaced per org)", () => {
+    const p = principalFromSession(
+      { organizations: [{ id: "123", scopes: ["read"], role: "owner" }, { id: "456", scopes: ["read"] }] },
+      { orgRoleScopes: { owner: ["write", "admin"] } },
+    );
+    expect(p.scopes).toEqual(expect.arrayContaining(["org:123:read", "org:123:write", "org:123:admin", "org:456:read"]));
+    // org 456 has no owner role → no write/admin there (tenancy isolation)
+    expect(p.scopes).not.toContain("org:456:write");
+  });
+
+  test("orgScope builds and parseOrgScope round-trips; a non-org scope parses null", () => {
+    expect(orgScope("123", "read")).toBe("org:123:read");
+    expect(parseOrgScope("org:123:read")).toEqual({ orgId: "123", action: "read" });
+    expect(parseOrgScope("admin")).toBeNull();
+  });
+
+  test("the encoded scopes work with a plain scope check (what enforceAccess does)", () => {
+    const p = principalFromSession({ twoFactorVerified: true, organizations: [{ id: "1", scopes: ["billing:write"] }] });
+    const has = (s: string) => p.scopes.includes(s);
+    expect(has(MFA_SCOPE)).toBe(true);          // a route can requireScopes("mfa:verified")
+    expect(has("org:1:billing:write")).toBe(true);
+  });
+
+  test("authSecuritySchemes surfaces the session-based plugins (no new wire scheme)", () => {
+    const sec = authSecuritySchemes({ session: true, twoFactor: true, passkey: true, organization: true });
+    expect(sec.plugins).toEqual({ twoFactor: true, passkey: true, organization: true });
+    // they add NO new securityScheme — they gate INTO the session
+    expect(Object.keys(sec.securitySchemes)).toEqual(["sessionCookie"]);
+  });
+});