@jxsuite/auth 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/auth",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Better Auth sessions, sign-in flows, and table permissions for Jx sites over /_jx/auth",
   "license": "MIT",
   "repository": {
@@ -38,13 +38,14 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/connector": "^0.6.2",
-    "@jxsuite/schema": "^3.0.0",
-    "better-auth": "^1.7.7",
-    "kysely": "^0.29.6"
+    "@jxsuite/connector": "^0.7.0",
+    "@jxsuite/schema": "^4.0.0",
+    "better-auth": "^1.7.11",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.14.5",
+    "@happy-dom/global-registrator": "^21.0.3",
+    "@jxsuite/test-support": "^0.0.0",
     "ajv": "^8.20.0"
   },
   "jx": "./jx-extension.json"

package/src/actions.ts

@@ -9,9 +9,12 @@
  * `"onsubmit": { "$ref": "auth.signInEmail" }` on a form with email/password fields.
  */
 
+import { isFunction, isString } from "@jxsuite/schema/guards";
 import { getAuthClient } from "./client.ts";
 import { clearSession, fetchSession } from "./session.ts";
-import type { AuthClientResult } from "./client.ts";
+import type { ActionScope } from "@jxsuite/connector/table-actions";
+import type { AuthClientResult, SocialSignInInput } from "./client.ts";
+import type { AuthSection } from "./config.ts";
 
 /** Redirect paths applied after auth state changes. */
 export interface AuthRedirects {
@@ -26,34 +29,48 @@ export interface AuthActionsConfig {
   provider?: string;
   baseUrl?: string;
   /** Injected by hosts (compiler/dev server): the project sections, including `auth`. */
-  _project?: { auth?: { redirects?: AuthRedirects }; [key: string]: unknown };
-  [key: string]: unknown;
+  _project?: { auth?: AuthSection };
 }
 
-type Scope = Record<string, unknown>;
-
 /** A `(scope, event)`-callable auth handler resolving true when the call succeeded. */
-export type AuthActionHandler = (scope: Scope, event?: Event) => Promise<boolean>;
+export type AuthActionHandler = (scope: ActionScope, event?: Event) => Promise<boolean>;
+
+/** The handler map `AuthActions.resolve()` returns, one entry per `$ref`-able action. */
+export interface AuthActionHandlers {
+  signInEmail: AuthActionHandler;
+  signInSocial: AuthActionHandler;
+  signOut: AuthActionHandler;
+  signUpEmail: AuthActionHandler;
+}
+
+/** String field values of a submitted form, keyed by field name. */
+type FormFields = Record<string, string>;
 
 /** The submitting form: the event target itself, or the target control's owner form. */
 function formOf(event?: Event): HTMLFormElement | null {
-  const target = event?.target as (HTMLElement & { form?: HTMLFormElement | null }) | null;
+  const target = event?.target;
   if (!target) {
     return null;
   }
-  return target.tagName === "FORM" ? (target as HTMLFormElement) : (target.form ?? null);
+  if (target instanceof HTMLFormElement) {
+    return target;
+  }
+  // Form-associated controls (input, button, select, …) expose their owner form as `.form`.
+  if (target instanceof Element && "form" in target && target.form instanceof HTMLFormElement) {
+    return target.form;
+  }
+  return null;
 }
 
 /** String field values of the submitting form (files are ignored). */
-function formValues(event?: Event): Record<string, string> {
+function formValues(event?: Event) {
+  const out: FormFields = {};
   const form = formOf(event);
-  if (!form) {
-    return {};
-  }
-  const out: Record<string, string> = {};
-  for (const [key, value] of new FormData(form)) {
-    if (typeof value === "string") {
-      out[key] = value;
+  if (form) {
+    for (const [key, value] of new FormData(form)) {
+      if (isString(value)) {
+        out[key] = value;
+      }
     }
   }
   return out;
@@ -67,8 +84,8 @@ function navigate(path: string | undefined): void {
 }
 
 /** Bump the read-after-write version so owner-scoped queries re-run under the new session. */
-function bumpVersion(scope: Scope): void {
-  scope._v = ((scope._v as number) || 0) + 1;
+function bumpVersion(scope: ActionScope): void {
+  scope._v = (scope._v || 0) + 1;
 }
 
 export class AuthActions {
@@ -84,7 +101,7 @@ export class AuthActions {
   }
 
   /** The handler map, wired via $ref (e.g. `onsubmit: { "$ref": "auth.signInEmail" }`). */
-  resolve(): Record<string, AuthActionHandler> {
+  resolve(): AuthActionHandlers {
     return {
       signInEmail: this.#authCall((values, client) =>
         client.signIn.email({ email: values.email ?? "", password: values.password ?? "" }),
@@ -93,16 +110,19 @@ export class AuthActions {
         (values, client) => {
           const provider = values.provider ?? this.config.provider ?? "";
           const callbackURL = this.redirects().afterSignIn;
-          return client.signIn.social({
-            provider,
-            ...(callbackURL === undefined ? {} : { callbackURL }),
-          });
+          const input: SocialSignInInput = { provider };
+          if (callbackURL !== undefined) {
+            input.callbackURL = callbackURL;
+          }
+          return client.signIn.social(input);
           // Social sign-in redirects the whole page itself — no local navigation.
         },
         { redirect: false },
       ),
-      signOut: async (scope: Scope, event?: Event): Promise<boolean> => {
-        event?.preventDefault?.();
+      signOut: async (scope: ActionScope, event?: Event): Promise<boolean> => {
+        if (event && isFunction(event.preventDefault)) {
+          event.preventDefault();
+        }
         const { error } = await getAuthClient(this.config.baseUrl).signOut();
         if (error) {
           return false;
@@ -126,13 +146,15 @@ export class AuthActions {
   /** Build a form-reading handler around one auth client call. */
   #authCall(
     call: (
-      values: Record<string, string>,
+      values: FormFields,
       client: ReturnType<typeof getAuthClient>,
     ) => Promise<AuthClientResult>,
     options: { redirect?: boolean } = {},
   ): AuthActionHandler {
-    return async (scope: Scope, event?: Event): Promise<boolean> => {
-      event?.preventDefault?.();
+    return async (scope: ActionScope, event?: Event): Promise<boolean> => {
+      if (event && isFunction(event.preventDefault)) {
+        event.preventDefault();
+      }
       const client = getAuthClient(this.config.baseUrl);
       const { error } = await call(formValues(event), client);
       if (error) {

package/src/client.ts

@@ -10,11 +10,22 @@
 
 import { createAuthClient } from "better-auth/client";
 import { AUTH_BASE_PATH } from "./config.ts";
+import type { AuthSessionPayload } from "./config.ts";
 
-/** The `{ data, error }` envelope every client call resolves to. */
+/** The `{ data, error }` envelope every client call resolves to (only `error` is consumed). */
 export interface AuthClientResult {
-  data?: unknown;
-  error?: { message?: string; status?: number } | null;
+  error?: { message?: string | undefined; status?: number | undefined } | null;
+}
+
+/** The `getSession()` envelope: `data` is the parsed `{ user, session }` payload, or null. */
+export interface AuthSessionResult extends AuthClientResult {
+  data?: AuthSessionPayload | null;
+}
+
+/** The `signIn.social` input: the provider id, plus where to land after the OAuth round trip. */
+export interface SocialSignInInput {
+  provider: string;
+  callbackURL?: string;
 }
 
 /** The Better Auth client slice consumed by the session store and the auth actions. */
@@ -25,13 +36,13 @@ export interface JxAuthClient {
       password: string;
       callbackURL?: string;
     }) => Promise<AuthClientResult>;
-    social: (input: { provider: string; callbackURL?: string }) => Promise<AuthClientResult>;
+    social: (input: SocialSignInInput) => Promise<AuthClientResult>;
   };
   signUp: {
     email: (input: { email: string; password: string; name: string }) => Promise<AuthClientResult>;
   };
   signOut: () => Promise<AuthClientResult>;
-  getSession: () => Promise<AuthClientResult>;
+  getSession: () => Promise<AuthSessionResult>;
 }
 
 let client: JxAuthClient | null = null;
@@ -63,7 +74,7 @@ export function getAuthClient(baseUrl?: string): JxAuthClient {
   }
   const base = resolveAuthBaseUrl(baseUrl);
   if (!client || clientBase !== base) {
-    client = createAuthClient({ baseURL: base }) as unknown as JxAuthClient;
+    client = createAuthClient({ baseURL: base });
     clientBase = base;
   }
   return client;

package/src/config.ts

@@ -4,11 +4,15 @@
  * The section carries identifiers and env-var NAMES only (specs/extensions.md §13): the signing
  * secret comes from `env[secretEnv]` (default BETTER_AUTH_SECRET), social-provider credentials from
  * their `clientIdEnv`/`clientSecretEnv` vars (defaults <ID>_CLIENT_ID / <ID>_CLIENT_SECRET). This
- * module is pure and dependency-free so browser bundles (session store, actions) can share the
- * section types and the SessionInfo mapping without pulling the Better Auth server in.
+ * module is pure (its only runtime import is the schema guards) so browser bundles (session store,
+ * actions) can share the section types and the SessionInfo mapping without pulling the Better Auth
+ * server in.
  */
 
-import type { SessionInfo } from "@jxsuite/connector/types";
+import { isString } from "@jxsuite/schema/guards";
+import type { Dialect } from "kysely";
+import type { HostEnv } from "@jxsuite/connector/provider-utils";
+import type { AuthRecord, ConnectionDef, SessionInfo } from "@jxsuite/connector/types";
 
 /** The Better Auth route subtree (specs/extensions.md §11: the auth mount's basePath). */
 export const AUTH_BASE_PATH = "/_jx/auth";
@@ -46,12 +50,12 @@ const COOKIE_IDS = ["session_token", "session_data", "dont_remember", "account_d
  * genuinely serves auth over plain HTTP is the local dev server, and it pins `BETTER_AUTH_URL` to
  * its own origin so this reads `http:` there rather than guessing.
  *
- * @param {Env} env
+ * @param {HostEnv} env
  * @returns {boolean}
  */
-export function cookiesAreSecure(env: Env): boolean {
+export function cookiesAreSecure(env: HostEnv): boolean {
   const baseURL = env["BETTER_AUTH_URL"];
-  if (typeof baseURL === "string" && baseURL !== "") {
+  if (isString(baseURL) && baseURL !== "") {
     return !baseURL.startsWith("http://");
   }
   return true;
@@ -78,14 +82,14 @@ export function cookiesAreSecure(env: Env): boolean {
  * whenever the embedding page changed.
  *
  * @param {boolean} secure
- * @returns {Record<string, unknown>}
+ * @returns {AuthAdvancedOptions}
  */
-function advancedCookieOptions(secure: boolean): Record<string, unknown> {
+function advancedCookieOptions(secure: boolean): AuthAdvancedOptions {
   if (!secure) {
     // Plain-HTTP dev origin: a prefixed cookie without `Secure` is rejected outright.
     return { cookiePrefix: COOKIE_PREFIX, useSecureCookies: false };
   }
-  const cookies: Record<string, { name: string }> = {};
+  const cookies: AuthCookieNames = {};
   for (const id of COOKIE_IDS) {
     cookies[id] = { name: `__Host-${COOKIE_PREFIX}.${id}` };
   }
@@ -97,6 +101,17 @@ function advancedCookieOptions(secure: boolean): Record<string, unknown> {
   };
 }
 
+/** Cookie names keyed by Better Auth cookie id (`session_token`, …). */
+export type AuthCookieNames = Record<string, { name: string }>;
+
+/** The `advanced` block of BetterAuthOptions this module sets (cookie names and attributes). */
+export interface AuthAdvancedOptions {
+  cookiePrefix: string;
+  cookies?: AuthCookieNames;
+  defaultCookieAttributes?: { secure: boolean };
+  useSecureCookies: boolean;
+}
+
 /** One social provider entry: env-var NAMES for the OAuth credentials, never values. */
 export interface AuthProviderDef {
   clientIdEnv?: string;
@@ -113,18 +128,14 @@ export interface AuthSection {
   redirects?: { afterSignIn?: string; afterSignOut?: string };
   roles?: string[];
   trustedOrigins?: string[];
-  [key: string]: unknown;
 }
 
 /** The `connections`-bearing slice of a project config (the connector owns the full type). */
 export interface AuthProjectConfig {
-  connections?: Record<string, { provider: string; [key: string]: unknown }>;
+  connections?: Record<string, ConnectionDef>;
   auth?: AuthSection;
-  [key: string]: unknown;
 }
 
-type Env = Record<string, unknown>;
-
 /** The connection name the auth tables live on: declared, else the first-declared connection. */
 export function resolveAuthConnectionName(
   section: AuthSection,
@@ -141,10 +152,10 @@ export function resolveAuthConnectionName(
 }
 
 /** The signing secret from `env[secretEnv]`, failing closed with the env-var name when unset. */
-export function resolveAuthSecret(section: AuthSection, env: Env): string {
+export function resolveAuthSecret(section: AuthSection, env: HostEnv): string {
   const name = section.secretEnv ?? DEFAULT_SECRET_ENV;
   const value = env[name];
-  if (typeof value !== "string" || value === "") {
+  if (!isString(value) || value === "") {
     throw new Error(
       `Auth is not configured: set the ${name} secret (in .dev.vars locally, ` +
         `or \`wrangler secret put ${name}\` in production)`,
@@ -158,48 +169,77 @@ function defaultProviderEnv(providerId: string, suffix: "CLIENT_ID" | "CLIENT_SE
   return `${providerId.toUpperCase().replaceAll(/[^A-Z0-9]+/g, "_")}_${suffix}`;
 }
 
+/** Resolved OAuth credentials per social provider id (Better Auth's `socialProviders` shape). */
+export type AuthSocialProviders = Record<string, { clientId: string; clientSecret: string }>;
+
 /**
  * Social providers with resolvable credentials, in Better Auth's `socialProviders` shape. Providers
  * whose env vars are unset are omitted (fail-closed: no half-configured OAuth).
  */
-export function resolveSocialProviders(
-  section: AuthSection,
-  env: Env,
-): Record<string, { clientId: string; clientSecret: string }> {
-  const out: Record<string, { clientId: string; clientSecret: string }> = {};
+export function resolveSocialProviders(section: AuthSection, env: HostEnv) {
+  const out: AuthSocialProviders = {};
   for (const [id, def] of Object.entries(section.providers ?? {})) {
     const clientId = env[def.clientIdEnv ?? defaultProviderEnv(id, "CLIENT_ID")];
     const clientSecret = env[def.clientSecretEnv ?? defaultProviderEnv(id, "CLIENT_SECRET")];
-    if (typeof clientId === "string" && clientId !== "" && typeof clientSecret === "string") {
+    if (isString(clientId) && clientId !== "" && isString(clientSecret)) {
       out[id] = { clientId, clientSecret };
     }
   }
   return out;
 }
 
+/** Better Auth's Kysely database config: the connection's dialect and its SQL family. */
+export interface AuthDatabaseConfig {
+  dialect: Dialect;
+  type: "sqlite" | "postgres";
+}
+
 /**
- * Map the auth section + env onto BetterAuthOptions (typed structurally — the exact
- * BetterAuthOptions type lives in better-auth, which this pure module never imports).
+ * The BetterAuthOptions this module produces (typed structurally — the exact BetterAuthOptions type
+ * lives in better-auth, which this pure module never imports).
+ */
+export interface JxAuthOptions {
+  baseURL?: string;
+  advanced: AuthAdvancedOptions;
+  basePath: string;
+  emailAndPassword: { enabled: boolean };
+  rateLimit: { enabled: boolean; max: number; window: number };
+  session: { expiresIn: number; updateAge: number };
+  socialProviders?: AuthSocialProviders;
+  user?: {
+    additionalFields: { role: { input: boolean; required: boolean; type: "string" } };
+  };
+  trustedOrigins?: string[];
+  database?: AuthDatabaseConfig;
+  secret?: string;
+}
+
+/**
+ * Map the auth section + env onto BetterAuthOptions. Optional keys are present only when set.
  *
  * @param {AuthSection} section
- * @param {Env} env
+ * @param {HostEnv} env
  * @param {object} [extras]
- * @param {unknown} [extras.database] - Better Auth database config ({ dialect, type })
+ * @param {AuthDatabaseConfig} [extras.database] - Better Auth database config ({ dialect, type })
  * @param {string} [extras.secret] - Signing secret (omit for secret-free uses like migrations)
- * @returns {Record<string, unknown>} Options for `betterAuth()` / `getMigrations()`
+ * @returns {JxAuthOptions} Options for `betterAuth()` / `getMigrations()`
  */
 export function buildAuthOptions(
   section: AuthSection,
-  env: Env,
-  extras: { database?: unknown; secret?: string } = {},
-): Record<string, unknown> {
+  env: HostEnv,
+  extras: { database?: AuthDatabaseConfig; secret?: string } = {},
+): JxAuthOptions {
   const socialProviders = resolveSocialProviders(section, env);
   const roles = section.roles ?? [];
   const baseURL = env["BETTER_AUTH_URL"];
-  return {
-    // Without BETTER_AUTH_URL Better Auth derives the origin from each incoming request, which
-    // Is correct for same-origin /_jx/auth mounts; setting it pins callbacks for OAuth flows.
-    ...(typeof baseURL === "string" && baseURL !== "" ? { baseURL } : {}),
+  const pinned: Pick<JxAuthOptions, "baseURL"> = {};
+  // Without BETTER_AUTH_URL Better Auth derives the origin from each incoming request, which
+  // Is correct for same-origin /_jx/auth mounts; setting it pins callbacks for OAuth flows.
+  if (isString(baseURL) && baseURL !== "") {
+    pinned.baseURL = baseURL;
+  }
+  const options: JxAuthOptions = {
+    ...pinned,
     advanced: advancedCookieOptions(cookiesAreSecure(env)),
     basePath: AUTH_BASE_PATH,
     emailAndPassword: { enabled: section.methods?.emailPassword ?? true },
@@ -213,43 +253,61 @@ export function buildAuthOptions(
      */
     rateLimit: { enabled: true, max: RATE_LIMIT_MAX, window: RATE_LIMIT_WINDOW_SECONDS },
     session: { expiresIn: SESSION_EXPIRES_SECONDS, updateAge: SESSION_UPDATE_SECONDS },
-    ...(Object.keys(socialProviders).length > 0 ? { socialProviders } : {}),
-    ...(roles.length > 0
-      ? {
-          user: {
-            additionalFields: {
-              // Roles are assigned via the data grid, never by sign-up input.
-              role: { input: false, required: false, type: "string" },
-            },
-          },
-        }
-      : {}),
-    ...(section.trustedOrigins && section.trustedOrigins.length > 0
-      ? { trustedOrigins: section.trustedOrigins }
-      : {}),
-    ...(extras.database === undefined ? {} : { database: extras.database }),
-    ...(extras.secret === undefined ? {} : { secret: extras.secret }),
   };
+  if (Object.keys(socialProviders).length > 0) {
+    options.socialProviders = socialProviders;
+  }
+  if (roles.length > 0) {
+    options.user = {
+      additionalFields: {
+        // Roles are assigned via the data grid, never by sign-up input.
+        role: { input: false, required: false, type: "string" },
+      },
+    };
+  }
+  if (section.trustedOrigins && section.trustedOrigins.length > 0) {
+    options.trustedOrigins = section.trustedOrigins;
+  }
+  if (extras.database !== undefined) {
+    options.database = extras.database;
+  }
+  if (extras.secret !== undefined) {
+    options.secret = extras.secret;
+  }
+  return options;
+}
+
+/**
+ * A Better Auth session payload: `auth.api.getSession`'s result on the server (records carry `Date`
+ * fields), or the client's parsed `getSession().data` (dates revived from ISO strings).
+ */
+export interface AuthSessionPayload {
+  user?: AuthRecord | null;
+  session?: AuthRecord | null;
 }
 
 /**
  * Map a Better Auth session payload ({ user, session }) onto the connector's SessionInfo shape.
  *
- * @param {unknown} data - `auth.api.getSession` result or the client's `getSession().data`
+ * @param {AuthSessionPayload | null | undefined} data - `auth.api.getSession` result or the
+ *   client's `getSession().data`
  * @returns {SessionInfo | null}
  */
-export function toSessionInfo(data: unknown): SessionInfo | null {
-  if (!data || typeof data !== "object") {
+export function toSessionInfo(data: AuthSessionPayload | null | undefined): SessionInfo | null {
+  if (!data) {
     return null;
   }
-  const { user, session } = data as { user?: Record<string, unknown>; session?: unknown };
-  if (!user || typeof user.id !== "string") {
+  const { user, session } = data;
+  if (!user || !isString(user.id)) {
     return null;
   }
-  return {
-    userId: user.id,
-    ...(typeof user.role === "string" && user.role !== "" ? { role: user.role } : {}),
-    user,
-    ...(session === undefined ? {} : { session }),
-  };
+  const info: SessionInfo = { userId: user.id };
+  if (isString(user.role) && user.role !== "") {
+    info.role = user.role;
+  }
+  info.user = user;
+  if (session !== undefined) {
+    info.session = session;
+  }
+  return info;
 }

package/src/server.ts

@@ -20,21 +20,25 @@ import {
   toSessionInfo,
 } from "./config.ts";
 import type { Dialect } from "kysely";
+import type { HostEnv } from "@jxsuite/connector/provider-utils";
 import type { ConnectionDef, SessionInfo } from "@jxsuite/connector/types";
-import type { AuthProjectConfig, AuthSection } from "./config.ts";
-
-type Env = Record<string, unknown>;
+import type {
+  AuthDatabaseConfig,
+  AuthProjectConfig,
+  AuthSection,
+  AuthSessionPayload,
+} from "./config.ts";
 
 /** The provider surface the auth extension needs (a slice of ConnectorProvider). */
 export interface AuthConnectorProvider {
   kind: "sqlite" | "postgres";
-  dialect: (connection: ConnectionDef, env: Env) => Dialect | Promise<Dialect>;
+  dialect: (connection: ConnectionDef, env: HostEnv) => Dialect | Promise<Dialect>;
 }
 
 /** The Better Auth surface consumed here (structural — betterAuth() returns a far larger type). */
 export interface JxAuthInstance {
   handler: (request: Request) => Promise<Response>;
-  api: { getSession: (input: { headers: Headers }) => Promise<unknown> };
+  api: { getSession: (input: { headers: Headers }) => Promise<AuthSessionPayload | null> };
 }
 
 export interface CreateJxAuthOptions {
@@ -48,9 +52,9 @@ export interface CreateJxAuthOptions {
 async function resolveAuthDatabase(
   section: AuthSection,
   projectConfig: AuthProjectConfig,
-  env: Env,
+  env: HostEnv,
   connectors?: Record<string, AuthConnectorProvider>,
-): Promise<{ dialect: Dialect; type: "sqlite" | "postgres"; connection: string }> {
+): Promise<AuthDatabaseConfig & { connection: string }> {
   const connection = resolveAuthConnectionName(section, projectConfig);
   const def = projectConfig.connections?.[connection];
   if (!def) {
@@ -58,7 +62,7 @@ async function resolveAuthDatabase(
   }
   const provider = connectors?.[def.provider];
   if (provider) {
-    const dialect = await provider.dialect({ ...def, $name: connection } as ConnectionDef, env);
+    const dialect = await provider.dialect({ ...def, $name: connection }, env);
     return { connection, dialect, type: provider.kind };
   }
   const resolved = await resolveDialect(connection, projectConfig, env);
@@ -70,14 +74,14 @@ async function resolveAuthDatabase(
  *
  * @param {AuthSection} section - The project.json `auth` section
  * @param {AuthProjectConfig} projectConfig - Project config (connections lookup)
- * @param {Env} env - Host environment (bindings + env vars; the secret lives here)
+ * @param {HostEnv} env - Host environment (bindings + env vars; the secret lives here)
  * @param {CreateJxAuthOptions} [options]
  * @returns {Promise<JxAuthInstance>}
  */
 export async function createJxAuth(
   section: AuthSection,
   projectConfig: AuthProjectConfig,
-  env: Env,
+  env: HostEnv,
   options: CreateJxAuthOptions = {},
 ): Promise<JxAuthInstance> {
   const secret = resolveAuthSecret(section, env);
@@ -92,10 +96,10 @@ export async function createJxAuth(
     secret,
   });
   if (options.autoSync) {
-    const migrations = await getMigrations(authOptions as Parameters<typeof getMigrations>[0]);
+    const migrations = await getMigrations(authOptions);
     await migrations.runMigrations();
   }
-  return betterAuth(authOptions as Parameters<typeof betterAuth>[0]) as JxAuthInstance;
+  return betterAuth(authOptions);
 }
 
 /**
@@ -182,7 +186,7 @@ export function classifyAuthStatement(statement: string, connection: string): Au
  *
  * @param {AuthSection} section
  * @param {AuthProjectConfig} projectConfig
- * @param {Env} env
+ * @param {HostEnv} env
  * @param {object} [options]
  * @param {Record<string, AuthConnectorProvider>} [options.connectors] - Provider stand-ins
  * @returns {Promise<AuthMigrationsResult>}
@@ -190,7 +194,7 @@ export function classifyAuthStatement(statement: string, connection: string): Au
 export async function getAuthMigrations(
   section: AuthSection,
   projectConfig: AuthProjectConfig,
-  env: Env,
+  env: HostEnv,
   options: { connectors?: Record<string, AuthConnectorProvider> | undefined } = {},
 ): Promise<AuthMigrationsResult> {
   const { dialect, type, connection } = await resolveAuthDatabase(
@@ -200,7 +204,7 @@ export async function getAuthMigrations(
     options.connectors,
   );
   const authOptions = buildAuthOptions(section, env, { database: { dialect, type } });
-  const migrations = await getMigrations(authOptions as Parameters<typeof getMigrations>[0]);
+  const migrations = await getMigrations(authOptions);
   const sqlBlob = await migrations.compileMigrations();
   const steps = splitSqlStatements(sqlBlob).map((statement) =>
     classifyAuthStatement(statement, connection),

package/src/session.ts

@@ -8,6 +8,7 @@
  * returns null, keeping statically generated pages on the signed-out state.
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { getAuthClient } from "./client.ts";
 import { toSessionInfo } from "./config.ts";
 import type { SessionInfo } from "@jxsuite/connector/types";
@@ -20,7 +21,7 @@ const listeners = new Set<SessionListener>();
 
 /** True when running in a browser (session fetching is a client-only concern). */
 export function inBrowser(): boolean {
-  return typeof document !== "undefined" && typeof fetch === "function";
+  return typeof document !== "undefined" && isFunction(globalThis.fetch);
 }
 
 function notify(): void {
@@ -89,7 +90,6 @@ export function resetSessionStore(): void {
 /** Config of the Session state class. */
 export interface SessionConfig {
   baseUrl?: string;
-  [key: string]: unknown;
 }
 
 export class Session {

package/src/worker.ts

@@ -12,25 +12,24 @@
 
 import { evaluatePermission } from "./authorize.ts";
 import { createJxAuth, getAuthMigrations, getSessionContext } from "./server.ts";
+import type { HostEnv } from "@jxsuite/connector/provider-utils";
 import type {
   AuthorizeDecision,
   AuthorizeInput,
+  ConnectionDef,
   JxServerContext,
   SessionInfo,
 } from "@jxsuite/connector/types";
 import type { AuthConnectorProvider, JxAuthInstance } from "./server.ts";
 import type { AuthProjectConfig, AuthSection } from "./config.ts";
 
-type Env = Record<string, unknown>;
-
 export interface AuthMountOptions {
   /** Route subtree this mount owns. Defaults to "/_jx/auth". */
   basePath?: string;
   /** Extension-contributed project sections (needs `auth` and `connections`). */
   sections: {
     auth?: AuthSection;
-    connections?: Record<string, { provider: string; [key: string]: unknown }>;
-    [key: string]: unknown;
+    connections?: Record<string, ConnectionDef>;
   };
   /** Provider implementations keyed by `connector.provider` id (dev stand-ins applied by hosts). */
   connectors?: Record<string, AuthConnectorProvider>;
@@ -40,7 +39,7 @@ export interface AuthMountOptions {
 
 /** Per-isolate mount state: Better Auth instances memoized per env identity. */
 export interface AuthMountState {
-  auths: WeakMap<object, Promise<JxAuthInstance>>;
+  auths: WeakMap<HostEnv, Promise<JxAuthInstance>>;
 }
 
 /** Create fresh mount state (exported for hosts that dispatch without `Auth.mount`). */
@@ -48,11 +47,14 @@ export function createAuthMountState(): AuthMountState {
   return { auths: new WeakMap() };
 }
 
-/** The project-config slice the auth modules need, rebuilt from the mount's section manifest. */
-function configFromSections(options: AuthMountOptions): {
+/** The auth section plus the project-config slice the auth modules resolve it against. */
+interface AuthMountConfig {
   section: AuthSection;
   projectConfig: AuthProjectConfig;
-} {
+}
+
+/** The project-config slice the auth modules need, rebuilt from the mount's section manifest. */
+function configFromSections(options: AuthMountOptions): AuthMountConfig {
   const section = options.sections.auth ?? {};
   return {
     projectConfig: { auth: section, connections: options.sections.connections ?? {} },
@@ -64,7 +66,7 @@ function configFromSections(options: AuthMountOptions): {
 export function getAuthForEnv(
   state: AuthMountState,
   options: AuthMountOptions,
-  env: Env,
+  env: HostEnv,
 ): Promise<JxAuthInstance> {
   const memo = state.auths.get(env);
   if (memo) {
@@ -84,14 +86,14 @@ export function getAuthForEnv(
  * Handle one /_jx/auth request by delegating to Better Auth's fetch handler.
  *
  * @param {Request} request
- * @param {Env} env - Worker env (bindings + vars; the signing secret lives here)
+ * @param {HostEnv} env - Worker env (bindings + vars; the signing secret lives here)
  * @param {AuthMountOptions} options
  * @param {AuthMountState} [state] - Memoized instances; omit for a throwaway state
  * @returns {Promise<Response>}
  */
 export async function handleAuthRequest(
   request: Request,
-  env: Env,
+  env: HostEnv,
   options: AuthMountOptions,
   state: AuthMountState = createAuthMountState(),
 ): Promise<Response> {
@@ -115,7 +117,7 @@ export const Auth = {
     ctx.auth = {
       authorize: (input: AuthorizeInput): Promise<AuthorizeDecision> =>
         Promise.resolve(evaluatePermission(input)),
-      getSession: async (request: Request, env: Env): Promise<SessionInfo | null> => {
+      getSession: async (request: Request, env: HostEnv): Promise<SessionInfo | null> => {
         try {
           const auth = await getAuthForEnv(state, options, env);
           return await getSessionContext(auth, request);
@@ -128,37 +130,37 @@ export const Auth = {
         }
       },
     };
-    return (request: Request, env: Env): Promise<Response> =>
+    return (request: Request, env: HostEnv): Promise<Response> =>
       handleAuthRequest(request, env, options, state);
   },
 
   /** Static `projectData` capability: expose the auth section as `_project.auth`. */
-  projectData(sectionValue: unknown): AuthSection {
-    const section = (sectionValue ?? {}) as AuthSection;
-    return { ...section };
+  projectData(sectionValue: AuthSection | null | undefined): AuthSection {
+    return { ...sectionValue };
   },
 
   /**
    * Static `deploySchema` capability (section-owner variant): compile Better Auth's additive
    * system-table migration into push steps the host composes after the connector plan.
    *
-   * @param {unknown} sectionValue - The project.json `auth` section value
-   * @param {unknown} projectConfig - The full project config (connection lookup)
+   * @param {AuthSection | null | undefined} sectionValue - The project.json `auth` section value
+   * @param {AuthProjectConfig | null | undefined} projectConfig - The full project config
+   *   (connection lookup)
    * @param {object} options - { env, dryRun?, connection?, connectors? }
    * @returns {Promise<object>} { steps, applied, warnings, connection }
    */
   async deploySchema(
-    sectionValue: unknown,
-    projectConfig: unknown,
+    sectionValue: AuthSection | null | undefined,
+    projectConfig: AuthProjectConfig | null | undefined,
     options: {
-      env: Env;
+      env: HostEnv;
       dryRun?: boolean;
       connection?: string;
       connectors?: Record<string, AuthConnectorProvider>;
     },
   ) {
-    const section = (sectionValue ?? {}) as AuthSection;
-    const config = (projectConfig ?? {}) as AuthProjectConfig;
+    const section = sectionValue ?? {};
+    const config = projectConfig ?? {};
     const dryRun = options.dryRun === true;
     const migrations = await getAuthMigrations(section, config, options.env, {
       connectors: options.connectors,