@suluk/better-auth 0.1.1 → 0.1.3

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.3",
   "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.7",
+  "@suluk/openapi-compat": "^0.1.2"
 },
 "peerDependencies": {
   "better-auth": "^1.0.0",
@@ -25,7 +36,7 @@
 },
 "devDependencies": {
   "@types/bun": "latest",
-  "@suluk/hono": "0.1.0"
+  "@suluk/hono": "^0.1.2"
 },
 "scripts": {
 "test": "bun test",

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/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

@@ -9,5 +9,21 @@
  */
 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";

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/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/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"]);
+  });
+});

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);
+  });
+});