@suluk/better-auth 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@suluk/better-auth",
+  "version": "0.1.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.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+  "@suluk/core": "0.1.0",
+  "@suluk/openapi-compat": "0.1.0"
+},
+"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.0"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @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.
+ */
+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 { mountAuth, type AuthHandlerLike, type HonoLike, type MountAuthOptions } from "./mount";

package/src/ingest.ts

@@ -0,0 +1,72 @@
+/**
+ * Ingest Better Auth's own OpenAPI output (from auth.api.generateOpenAPISchema(), which emits OpenAPI 3.0)
+ * and lift it into the v4 "Suluk" model — so the auth surface (/sign-up, /sign-in, /get-session, …) is
+ * documented in the app's v4 doc without re-typing it.
+ *
+ * Two steps: (1) normalize 3.0-isms to JSON Schema 2020-12 (nullable, boolean exclusiveMin/Max), since
+ * compat.upgrade passes Schema Objects through verbatim and v4 schemas must be 2020-12; (2) compat.upgrade.
+ */
+import { upgrade } from "@suluk/openapi-compat";
+import type { OpenAPIv4Document, PathItem, Components, SecurityScheme } from "@suluk/core";
+
+/** Recursively rewrite OpenAPI-3.0 Schema-Object dialect into JSON Schema 2020-12. */
+export function normalizeOas30(node: unknown): unknown {
+  if (Array.isArray(node)) return node.map(normalizeOas30);
+  if (node && typeof node === "object") {
+    const o = { ...(node as Record<string, unknown>) };
+    // nullable: true → add "null" to the type (or fold into enum); drop the 3.0-only keyword.
+    if (o.nullable === true) {
+      delete o.nullable;
+      if (typeof o.type === "string") o.type = [o.type, "null"];
+      else if (Array.isArray(o.type) && !o.type.includes("null")) o.type = [...o.type, "null"];
+      else if (Array.isArray(o.enum) && !o.enum.includes(null)) o.enum = [...o.enum, null];
+    } else if (o.nullable === false) {
+      delete o.nullable;
+    }
+    // boolean exclusiveMinimum/Maximum (3.0) → numeric form (2020-12).
+    if (o.exclusiveMinimum === true && typeof o.minimum === "number") { o.exclusiveMinimum = o.minimum; delete o.minimum; }
+    else if (o.exclusiveMinimum === false) delete o.exclusiveMinimum;
+    if (o.exclusiveMaximum === true && typeof o.maximum === "number") { o.exclusiveMaximum = o.maximum; delete o.maximum; }
+    else if (o.exclusiveMaximum === false) delete o.exclusiveMaximum;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(o)) out[k] = normalizeOas30(v);
+    return out;
+  }
+  return node;
+}
+
+export interface IngestOptions {
+  /** Prefix every ingested path with this base (Better Auth mounts under "/api/auth"). */
+  basePath?: string;
+}
+
+/** Normalize + upgrade Better Auth's OpenAPI 3.0 schema to a v4 document (the auth surface). */
+export function ingestAuthOpenAPI(schema30: Record<string, unknown>, opts: IngestOptions = {}): OpenAPIv4Document {
+  const normalized = normalizeOas30(schema30) as Record<string, unknown>;
+  const v4 = upgrade(normalized);
+  if (opts.basePath) {
+    const prefix = opts.basePath.replace(/\/$/, "");
+    const reKeyed: Record<string, PathItem> = {};
+    for (const [path, pi] of Object.entries(v4.paths)) {
+      const clean = path.replace(/^\//, "");
+      reKeyed[`${prefix.replace(/^\//, "")}/${clean}`] = pi as PathItem;
+    }
+    v4.paths = reKeyed;
+  }
+  return v4;
+}
+
+/** Deep-merge auth paths + components (schemas + securitySchemes) into an app's v4 document. */
+export function mergeAuth(
+  app: OpenAPIv4Document,
+  auth: Partial<OpenAPIv4Document>,
+  extra: { securitySchemes?: Record<string, SecurityScheme> } = {},
+): OpenAPIv4Document {
+  const out: OpenAPIv4Document = { ...app, paths: { ...app.paths, ...(auth.paths ?? {}) } };
+  const components: Components = { ...(app.components ?? {}) };
+  if (auth.components?.schemas) components.schemas = { ...(components.schemas ?? {}), ...auth.components.schemas };
+  const mergedSchemes = { ...(components.securitySchemes ?? {}), ...(auth.components?.securitySchemes ?? {}), ...(extra.securitySchemes ?? {}) };
+  if (Object.keys(mergedSchemes).length) components.securitySchemes = mergedSchemes;
+  if (Object.keys(components).length) out.components = components;
+  return out;
+}

package/src/mount.ts

@@ -0,0 +1,28 @@
+/**
+ * mountAuth — the thin Hono adapter for Better Auth (the documented integration:
+ * app.on(["POST","GET"], "/api/auth/*", c => auth.handler(c.req.raw))). Duck-typed so it needs neither a
+ * hard better-auth nor hono import — it only relies on app.on(...) and auth.handler(Request).
+ */
+
+export interface AuthHandlerLike {
+  handler(request: Request): Response | Promise<Response>;
+}
+
+export interface HonoLike {
+  on(methods: string[], path: string, handler: (c: { req: { raw: Request } }) => unknown): unknown;
+}
+
+export interface MountAuthOptions {
+  /** Base path Better Auth is mounted at (default "/api/auth"). */
+  basePath?: string;
+  /** HTTP methods to route (default ["POST","GET"]). */
+  methods?: string[];
+}
+
+/** Mount the Better Auth handler onto a Hono app under basePath/* (default /api/auth/*). */
+export function mountAuth<T extends HonoLike>(app: T, auth: AuthHandlerLike, opts: MountAuthOptions = {}): T {
+  const basePath = (opts.basePath ?? "/api/auth").replace(/\/$/, "");
+  const methods = opts.methods ?? ["POST", "GET"];
+  app.on(methods, `${basePath}/*`, (c) => auth.handler(c.req.raw));
+  return app;
+}

package/src/principal.ts

@@ -0,0 +1,38 @@
+/**
+ * The principal extractor — the loop-closer for per-viewer docs. A Better Auth session (its user role,
+ * granted permissions, or an apiKey's scopes) is mapped to a { scopes } principal that @suluk/hono's
+ * emitV4(routes, { principal }) uses to project the doc each viewer is allowed to see.
+ */
+
+export interface Principal {
+  scopes: string[];
+}
+
+/** A minimal view of a Better Auth session (duck-typed; works with the real Session shape). */
+export interface SessionLike {
+  user?: { role?: string | string[]; scopes?: string[] } | null;
+  /** apiKey plugin: a key carries its own permissions/scopes. */
+  apiKey?: { scopes?: string[]; permissions?: Record<string, string[]> } | null;
+  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[]>;
+}
+
+/** Extract a { scopes } principal from a Better Auth session. Null/undefined session ⇒ anonymous (no scopes). */
+export function principalFromSession(session: SessionLike | null | undefined, opts: PrincipalOptions = {}): Principal {
+  if (!session) return { scopes: [] };
+  const scopes = new Set<string>();
+  for (const s of session.scopes ?? []) scopes.add(s);
+  for (const s of session.user?.scopes ?? []) scopes.add(s);
+  for (const s of session.apiKey?.scopes ?? []) scopes.add(s);
+  for (const list of Object.values(session.apiKey?.permissions ?? {})) for (const s of list) scopes.add(s);
+
+  const roles = session.user?.role;
+  const roleList = Array.isArray(roles) ? roles : roles ? [roles] : [];
+  for (const role of roleList) for (const s of opts.roleScopes?.[role] ?? []) scopes.add(s);
+
+  return { scopes: [...scopes] };
+}

package/src/security.ts

@@ -0,0 +1,45 @@
+/**
+ * Derive v4 securitySchemes (C014) from a declarative description of the Better Auth methods in use.
+ * Better Auth's standard mechanisms map onto OpenAPI security schemes as:
+ *   - session   → an apiKey-in-cookie (default cookie "better-auth.session_token")
+ *   - bearer    → http bearer (Authorization: Bearer <token>; the bearer plugin)
+ *   - apiKey    → apiKey-in-header (default "x-api-key"; the apiKey plugin)
+ * The exact names are Better Auth conventions and are overridable.
+ */
+import type { SecurityScheme } from "@suluk/core";
+
+export interface AuthMethods {
+  /** Session cookie (default). `true` ⇒ default cookie name; or pass a custom cookie name. */
+  session?: boolean | { cookieName?: string };
+  /** Bearer token (the bearer plugin). */
+  bearer?: boolean;
+  /** API key (the apiKey plugin). `true` ⇒ default "x-api-key" header; or pass a custom header. */
+  apiKey?: boolean | { header?: string };
+}
+
+export interface AuthSecurity {
+  /** v4 components.securitySchemes entries, keyed by scheme name. */
+  securitySchemes: Record<string, SecurityScheme>;
+  /** Convenience: the scheme names, to build by-name security requirements. */
+  names: string[];
+}
+
+const DEFAULT_SESSION_COOKIE = "better-auth.session_token";
+const DEFAULT_APIKEY_HEADER = "x-api-key";
+
+/** Build v4 securitySchemes from the enabled Better Auth methods. */
+export function authSecuritySchemes(methods: AuthMethods): AuthSecurity {
+  const securitySchemes: Record<string, SecurityScheme> = {};
+  if (methods.session) {
+    const cookieName = typeof methods.session === "object" ? methods.session.cookieName ?? DEFAULT_SESSION_COOKIE : DEFAULT_SESSION_COOKIE;
+    securitySchemes.sessionCookie = { type: "apiKey", in: "cookie", name: cookieName };
+  }
+  if (methods.bearer) {
+    securitySchemes.bearerAuth = { type: "http", scheme: "bearer" };
+  }
+  if (methods.apiKey) {
+    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) };
+}

package/test/better-auth.test.ts

@@ -0,0 +1,121 @@
+import { test, expect, describe } from "bun:test";
+import { validateDocument } from "@suluk/core";
+import { emitV4, contract } from "@suluk/hono";
+import * as z from "zod";
+import { authSecuritySchemes, normalizeOas30, ingestAuthOpenAPI, mergeAuth, principalFromSession } from "../src/index";
+
+/** A realistic slice of what Better Auth's generateOpenAPISchema() emits (OpenAPI 3.0, with a nullable field). */
+const betterAuthOpenAPI30: Record<string, unknown> = {
+  openapi: "3.0.3",
+  info: { title: "Better Auth", version: "1.0.0" },
+  paths: {
+    "/sign-up/email": {
+      post: {
+        operationId: "signUpEmail",
+        requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/SignUpBody" } } } },
+        responses: { "200": { description: "Session", content: { "application/json": { schema: { $ref: "#/components/schemas/Session" } } } } },
+      },
+    },
+    "/get-session": {
+      get: {
+        operationId: "getSession",
+        responses: { "200": { description: "Current session", content: { "application/json": { schema: { $ref: "#/components/schemas/Session" } } } } },
+      },
+    },
+  },
+  components: {
+    schemas: {
+      SignUpBody: { type: "object", required: ["email", "password"], properties: { email: { type: "string", format: "email" }, password: { type: "string" }, name: { type: "string", nullable: true } } },
+      Session: { type: "object", properties: { token: { type: "string" }, user: { type: "object", properties: { id: { type: "string" }, image: { type: "string", nullable: true } } } } },
+    },
+  },
+};
+
+describe("authSecuritySchemes — auth methods → v4 securitySchemes (C014)", () => {
+  test("session → cookie, bearer → http bearer, apiKey → header", () => {
+    const { securitySchemes, names } = authSecuritySchemes({ session: true, bearer: true, apiKey: true });
+    expect(securitySchemes.sessionCookie).toEqual({ type: "apiKey", in: "cookie", name: "better-auth.session_token" });
+    expect(securitySchemes.bearerAuth).toEqual({ type: "http", scheme: "bearer" });
+    expect(securitySchemes.apiKey).toEqual({ type: "apiKey", in: "header", name: "x-api-key" });
+    expect(names.sort()).toEqual(["apiKey", "bearerAuth", "sessionCookie"]);
+  });
+  test("custom names are honored", () => {
+    const { securitySchemes } = authSecuritySchemes({ session: { cookieName: "myapp.sid" }, apiKey: { header: "X-Key" } });
+    expect((securitySchemes.sessionCookie as any).name).toBe("myapp.sid");
+    expect((securitySchemes.apiKey as any).name).toBe("X-Key");
+  });
+});
+
+describe("normalizeOas30 — 3.0 Schema dialect → JSON Schema 2020-12", () => {
+  test("nullable:true folds 'null' into the type", () => {
+    expect(normalizeOas30({ type: "string", nullable: true })).toEqual({ type: ["string", "null"] });
+  });
+  test("boolean exclusiveMinimum → numeric form", () => {
+    expect(normalizeOas30({ type: "number", minimum: 0, exclusiveMinimum: true })).toEqual({ type: "number", exclusiveMinimum: 0 });
+  });
+});
+
+describe("ingestAuthOpenAPI — Better Auth 3.0 → v4", () => {
+  const v4 = ingestAuthOpenAPI(betterAuthOpenAPI30, { basePath: "/api/auth" });
+
+  test("lifts to a structurally valid v4 document", () => {
+    const r = validateDocument(v4);
+    if (!r.valid) console.error(r.errors);
+    expect(r.valid).toBe(true);
+  });
+  test("prefixes auth paths under the mount base", () => {
+    expect(Object.keys(v4.paths)).toContain("api/auth/sign-up/email");
+    expect(Object.keys(v4.paths)).toContain("api/auth/get-session");
+  });
+  test("the nullable 3.0 field became a 2020-12 type array (no leftover 'nullable')", () => {
+    const name = (v4.components!.schemas!.SignUpBody as any).properties.name;
+    expect(name.type).toEqual(["string", "null"]);
+    expect(name.nullable).toBeUndefined();
+  });
+  test("preserves the operation by-name handle (operationId → request name)", () => {
+    const reqs = v4.paths["api/auth/sign-up/email"].requests;
+    expect(Object.keys(reqs)).toContain("signUpEmail");
+  });
+});
+
+describe("mergeAuth — fold the auth surface into an app's v4 doc", () => {
+  test("merged document (app routes + auth routes + securitySchemes) is valid v4", () => {
+    const appRoutes = contract([
+      { method: "get", path: "/pet", name: "listPets", summary: "List", responses: [{ status: 200, description: "ok", schema: z.array(z.object({ name: z.string() })) }] },
+    ]);
+    const { document: appDoc } = emitV4(appRoutes, { info: { title: "Pets", version: "1.0.0" } });
+    const authV4 = ingestAuthOpenAPI(betterAuthOpenAPI30, { basePath: "/api/auth" });
+    const { securitySchemes } = authSecuritySchemes({ session: true, bearer: true });
+
+    const merged = mergeAuth(appDoc, authV4, { securitySchemes });
+    expect(validateDocument(merged).valid).toBe(true);
+    // both surfaces present
+    expect(Object.keys(merged.paths)).toContain("pet");
+    expect(Object.keys(merged.paths)).toContain("api/auth/sign-up/email");
+    // securitySchemes carried (C014 anchor)
+    expect(merged.components!.securitySchemes!.sessionCookie).toBeDefined();
+    expect(merged.components!.schemas!.Session).toBeDefined();
+  });
+});
+
+describe("principalFromSession — the per-viewer loop closer", () => {
+  test("maps role → scopes via the provided map", () => {
+    const p = principalFromSession({ user: { role: "admin" } }, { roleScopes: { admin: ["read:pets", "write:pets"] } });
+    expect(p.scopes.sort()).toEqual(["read:pets", "write:pets"]);
+  });
+  test("collects scopes from session, user, and apiKey permissions", () => {
+    const p = principalFromSession({ scopes: ["a"], user: { scopes: ["b"] }, apiKey: { permissions: { pets: ["write:pets"] } } });
+    expect(p.scopes.sort()).toEqual(["a", "b", "write:pets"]);
+  });
+  test("a writer principal sees a scope-gated operation that an anonymous viewer does not", () => {
+    const routes = contract([
+      { method: "post", path: "/pet", name: "createPet", scopes: ["write:pets"], request: { json: z.object({ name: z.string() }) }, responses: [{ status: 201, description: "created" }] },
+    ]);
+    const anon = principalFromSession(null);
+    const writer = principalFromSession({ user: { role: "admin" } }, { roleScopes: { admin: ["write:pets"] } });
+    const anonNames = Object.values(emitV4(routes, { principal: anon }).document.paths).flatMap((pi) => Object.keys(pi.requests));
+    const writerNames = Object.values(emitV4(routes, { principal: writer }).document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(anonNames).not.toContain("createPet");
+    expect(writerNames).toContain("createPet");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "types": ["bun"] },
+  "include": ["src", "test"]
+}