@jxsuite/auth 0.1.0

package/src/authorize.ts

@@ -0,0 +1,92 @@
+/**
+ * Authorize — the pure permission evaluator implementing the connector's auth contract
+ * (specs/extensions.md §11, @jxsuite/connector/types).
+ *
+ * The data mount resolves each request's rule (declared permissions over the defaults: reads
+ * public, writes closed), handles `public`/`none` itself, and hands every other rule to
+ * `ctx.auth.authorize` — this function. Grants may carry `setColumns` (owner id forced onto
+ * insert/update payloads) and `whereOwner` (row scoping for owner reads/writes/deletes). Unknown
+ * rules fail closed. No I/O: the session was already resolved by `getSession`.
+ */
+
+import type {
+  AuthorizeDecision,
+  AuthorizeInput,
+  PermissionRule,
+  SessionInfo,
+} from "@jxsuite/connector/types";
+
+/** A 401/403 denial with a wire-friendly message. */
+function deny(session: SessionInfo | null, error: string, status?: number): AuthorizeDecision {
+  return { allow: false, error, status: status ?? (session ? 403 : 401) };
+}
+
+/**
+ * A grant for a session-backed rule. Declaring an `ownerField` makes that column authoritative:
+ * EVERY session-granted insert stamps it with the user id (not just `owner`-rule inserts) —
+ * otherwise an `insert: "authenticated"` table would accept payload-forged owner ids, poisoning
+ * later owner-scoped reads and writes.
+ */
+function grant(input: AuthorizeInput, session: SessionInfo): AuthorizeDecision {
+  const { action, ownerField } = input;
+  if (action === "insert" && ownerField) {
+    return { allow: true, setColumns: { [ownerField]: session.userId } };
+  }
+  return { allow: true };
+}
+
+/** The role a rule requires, or null for non-role rules. */
+export function ruleRole(rule: PermissionRule): string | null {
+  return rule.startsWith("role:") ? rule.slice("role:".length) : null;
+}
+
+/**
+ * Evaluate one permission rule against a resolved session (pure, synchronous).
+ *
+ * @param {AuthorizeInput} input - Table, action, resolved rule, session, and optional ownerField
+ * @returns {AuthorizeDecision} The grant (with setColumns/whereOwner for owner rules) or denial
+ */
+export function evaluatePermission(input: AuthorizeInput): AuthorizeDecision {
+  const { table, action, rule, session } = input;
+
+  if (rule === "public") {
+    return { allow: true };
+  }
+  if (rule === "none") {
+    return deny(session, `${action} is disabled for "${table}"`, 403);
+  }
+  if (rule === "authenticated") {
+    return session
+      ? grant(input, session)
+      : deny(session, `${action} on "${table}" requires authentication`);
+  }
+  if (rule === "owner") {
+    const { ownerField } = input;
+    if (!ownerField) {
+      // Configuration error: an owner rule is unenforceable without an ownerField column.
+      return deny(
+        session,
+        `"${table}" uses an "owner" rule for ${action} but declares no ownerField`,
+        403,
+      );
+    }
+    if (!session) {
+      return deny(session, `${action} on "${table}" requires authentication`);
+    }
+    if (action === "insert") {
+      return grant(input, session);
+    }
+    return { allow: true, whereOwner: { field: ownerField, value: session.userId } };
+  }
+  const role = ruleRole(rule);
+  if (role !== null) {
+    if (!session) {
+      return deny(session, `${action} on "${table}" requires authentication`);
+    }
+    return session.role === role
+      ? grant(input, session)
+      : deny(session, `${action} on "${table}" requires the "${role}" role`, 403);
+  }
+  // Fail closed on rules this evaluator does not understand.
+  return deny(session, `Unknown permission rule "${String(rule)}" for "${table}"`, 403);
+}

package/src/client.ts

@@ -0,0 +1,76 @@
+/**
+ * Client — the browser-safe Better Auth client wrapper.
+ *
+ * Wraps `createAuthClient` from better-auth/client (verified against 1.6.23: `signIn.email`,
+ * `signUp.email`, `signIn.social`, `signOut`, `getSession`, each returning `{ data, error }`)
+ * behind a module-level singleton pointed at the site's own /_jx/auth mount. Everything here is
+ * typed structurally against the narrow slice the session store and auth actions consume, so
+ * bundles never depend on Better Auth's inferred mega-types.
+ */
+
+import { createAuthClient } from "better-auth/client";
+import { AUTH_BASE_PATH } from "./config.ts";
+
+/** The `{ data, error }` envelope every client call resolves to. */
+export interface AuthClientResult {
+  data?: unknown;
+  error?: { message?: string; status?: number } | null;
+}
+
+/** The Better Auth client slice consumed by the session store and the auth actions. */
+export interface JxAuthClient {
+  signIn: {
+    email: (input: {
+      email: string;
+      password: string;
+      callbackURL?: string;
+    }) => Promise<AuthClientResult>;
+    social: (input: { provider: string; callbackURL?: string }) => Promise<AuthClientResult>;
+  };
+  signUp: {
+    email: (input: { email: string; password: string; name: string }) => Promise<AuthClientResult>;
+  };
+  signOut: () => Promise<AuthClientResult>;
+  getSession: () => Promise<AuthClientResult>;
+}
+
+let client: JxAuthClient | null = null;
+let clientBase: string | null = null;
+
+/** Sentinel base marking a host/test-injected client (always returned as-is). */
+const INJECTED = "__injected__";
+
+/** The auth route base URL: explicit, else the page's own origin + /_jx/auth. */
+export function resolveAuthBaseUrl(baseUrl?: string): string {
+  if (baseUrl) {
+    return baseUrl;
+  }
+  if (typeof location === "undefined") {
+    throw new TypeError("The jx auth client needs an explicit baseUrl outside browsers");
+  }
+  return `${location.origin}${AUTH_BASE_PATH}`;
+}
+
+/**
+ * The shared auth client (created on first use, re-created when the base URL changes).
+ *
+ * @param {string} [baseUrl] - Auth route base URL; defaults to <origin>/_jx/auth
+ * @returns {JxAuthClient}
+ */
+export function getAuthClient(baseUrl?: string): JxAuthClient {
+  if (client !== null && clientBase === INJECTED) {
+    return client;
+  }
+  const base = resolveAuthBaseUrl(baseUrl);
+  if (!client || clientBase !== base) {
+    client = createAuthClient({ baseURL: base }) as unknown as JxAuthClient;
+    clientBase = base;
+  }
+  return client;
+}
+
+/** Inject a client instance (host/test hook; pass null to restore the default factory). */
+export function setAuthClient(next: JxAuthClient | null): void {
+  client = next;
+  clientBase = next === null ? null : INJECTED;
+}

package/src/config.ts

@@ -0,0 +1,163 @@
+/**
+ * Config — the project.json `auth` section and its mapping onto BetterAuthOptions.
+ *
+ * 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.
+ */
+
+import type { 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";
+
+/** Default NAME of the env var holding the Better Auth signing secret. */
+export const DEFAULT_SECRET_ENV = "BETTER_AUTH_SECRET";
+
+/** One social provider entry: env-var NAMES for the OAuth credentials, never values. */
+export interface AuthProviderDef {
+  clientIdEnv?: string;
+  clientSecretEnv?: string;
+}
+
+/** The project.json `auth` section (identifiers and env-var names only). */
+export interface AuthSection {
+  /** Connection holding the auth system tables; defaults to the first-declared connection. */
+  connection?: string;
+  secretEnv?: string;
+  methods?: { emailPassword?: boolean };
+  providers?: Record<string, AuthProviderDef>;
+  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 }>;
+  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,
+  projectConfig: AuthProjectConfig,
+): string {
+  const name = section.connection ?? Object.keys(projectConfig.connections ?? {})[0];
+  if (!name) {
+    throw new Error(
+      'The "auth" section needs a database connection, but the project declares none ' +
+        '(add a "connections" entry, or set auth.connection)',
+    );
+  }
+  return name;
+}
+
+/** The signing secret from `env[secretEnv]`, failing closed with the env-var name when unset. */
+export function resolveAuthSecret(section: AuthSection, env: Env): string {
+  const name = section.secretEnv ?? DEFAULT_SECRET_ENV;
+  const value = env[name];
+  if (typeof value !== "string" || value === "") {
+    throw new Error(
+      `Auth is not configured: set the ${name} secret (in .dev.vars locally, ` +
+        `or \`wrangler secret put ${name}\` in production)`,
+    );
+  }
+  return value;
+}
+
+/** Default env-var NAME for a provider credential (`github` → `GITHUB_CLIENT_ID`). */
+function defaultProviderEnv(providerId: string, suffix: "CLIENT_ID" | "CLIENT_SECRET"): string {
+  return `${providerId.toUpperCase().replaceAll(/[^A-Z0-9]+/g, "_")}_${suffix}`;
+}
+
+/**
+ * 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 }> = {};
+  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") {
+      out[id] = { clientId, clientSecret };
+    }
+  }
+  return out;
+}
+
+/**
+ * Map the auth section + env onto BetterAuthOptions (typed structurally — the exact
+ * BetterAuthOptions type lives in better-auth, which this pure module never imports).
+ *
+ * @param {AuthSection} section
+ * @param {Env} env
+ * @param {object} [extras]
+ * @param {unknown} [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()`
+ */
+export function buildAuthOptions(
+  section: AuthSection,
+  env: Env,
+  extras: { database?: unknown; secret?: string } = {},
+): Record<string, unknown> {
+  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 } : {}),
+    basePath: AUTH_BASE_PATH,
+    emailAndPassword: { enabled: section.methods?.emailPassword ?? true },
+    ...(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 }),
+  };
+}
+
+/**
+ * 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`
+ * @returns {SessionInfo | null}
+ */
+export function toSessionInfo(data: unknown): SessionInfo | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const { user, session } = data as { user?: Record<string, unknown>; session?: unknown };
+  if (!user || typeof user.id !== "string") {
+    return null;
+  }
+  return {
+    userId: user.id,
+    ...(typeof user.role === "string" && user.role !== "" ? { role: user.role } : {}),
+    user,
+    ...(session === undefined ? {} : { session }),
+  };
+}

package/src/server.ts

@@ -0,0 +1,218 @@
+/**
+ * Server — the Better Auth instance factory and migration planner (node/Bun/Workers only).
+ *
+ * `createJxAuth` resolves the auth database through the connector: a host-provided provider map
+ * (`options.connectors`, carrying the dev server's `local: "sqlite"` stand-ins) when available,
+ * else `resolveDialect` over the first-party providers — either way yielding Better Auth's
+ * `database: { dialect, type }` Kysely config. `getAuthMigrations` compiles Better Auth's additive
+ * system-table sync (verified against better-auth 1.6.23: `getMigrations` from
+ * `better-auth/db/migration` returns { toBeCreated, toBeAdded, runMigrations, compileMigrations })
+ * into push steps of kind "auth", composed by the host after the connector plan — the connector
+ * never special-cases auth.
+ */
+
+import { betterAuth } from "better-auth";
+import { getMigrations } from "better-auth/db/migration";
+import { resolveDialect } from "@jxsuite/connector";
+import {
+  buildAuthOptions,
+  resolveAuthConnectionName,
+  resolveAuthSecret,
+  toSessionInfo,
+} from "./config.ts";
+import type { Dialect } from "kysely";
+import type { ConnectionDef, SessionInfo } from "@jxsuite/connector/types";
+import type { AuthProjectConfig, AuthSection } from "./config.ts";
+
+type Env = Record<string, unknown>;
+
+/** 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>;
+}
+
+/** 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> };
+}
+
+export interface CreateJxAuthOptions {
+  /** Provider implementations keyed by `connector.provider` id (dev stand-ins applied by hosts). */
+  connectors?: Record<string, AuthConnectorProvider> | undefined;
+  /** Run Better Auth's additive migrations before serving (dev-server first-touch sync). */
+  autoSync?: boolean | undefined;
+}
+
+/** Resolve the auth connection's Kysely dialect + type, preferring host-provided stand-ins. */
+async function resolveAuthDatabase(
+  section: AuthSection,
+  projectConfig: AuthProjectConfig,
+  env: Env,
+  connectors?: Record<string, AuthConnectorProvider>,
+): Promise<{ dialect: Dialect; type: "sqlite" | "postgres"; connection: string }> {
+  const connection = resolveAuthConnectionName(section, projectConfig);
+  const def = projectConfig.connections?.[connection];
+  if (!def) {
+    throw new Error(`Auth names unknown connection "${connection}" (no such connections entry)`);
+  }
+  const provider = connectors?.[def.provider];
+  if (provider) {
+    const dialect = await provider.dialect({ ...def, $name: connection } as ConnectionDef, env);
+    return { connection, dialect, type: provider.kind };
+  }
+  const resolved = await resolveDialect(connection, projectConfig, env);
+  return { connection, dialect: resolved.dialect, type: resolved.type };
+}
+
+/**
+ * Create a Better Auth instance for a project's auth section.
+ *
+ * @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 {CreateJxAuthOptions} [options]
+ * @returns {Promise<JxAuthInstance>}
+ */
+export async function createJxAuth(
+  section: AuthSection,
+  projectConfig: AuthProjectConfig,
+  env: Env,
+  options: CreateJxAuthOptions = {},
+): Promise<JxAuthInstance> {
+  const secret = resolveAuthSecret(section, env);
+  const { dialect, type } = await resolveAuthDatabase(
+    section,
+    projectConfig,
+    env,
+    options.connectors,
+  );
+  const authOptions = buildAuthOptions(section, env, {
+    database: { dialect, type },
+    secret,
+  });
+  if (options.autoSync) {
+    const migrations = await getMigrations(authOptions as Parameters<typeof getMigrations>[0]);
+    await migrations.runMigrations();
+  }
+  return betterAuth(authOptions as Parameters<typeof betterAuth>[0]) as JxAuthInstance;
+}
+
+/**
+ * Resolve a request's session through Better Auth into the connector's SessionInfo shape.
+ *
+ * @param {JxAuthInstance} auth
+ * @param {Request} request
+ * @returns {Promise<SessionInfo | null>}
+ */
+export async function getSessionContext(
+  auth: JxAuthInstance,
+  request: Request,
+): Promise<SessionInfo | null> {
+  const data = await auth.api.getSession({ headers: request.headers });
+  return toSessionInfo(data);
+}
+
+// ─── Migrations (push plan) ───────────────────────────────────────────────────
+
+/** One push step of the auth migration plan (protocol DataPushStep shape, kind "auth"). */
+export interface AuthPushStep {
+  kind: "auth";
+  table?: string;
+  summary: string;
+  sql: string;
+  connection: string;
+}
+
+export interface AuthMigrationsResult {
+  steps: AuthPushStep[];
+  /** Execute the compiled migration (no-op when steps is empty). */
+  apply: () => Promise<void>;
+  /** The connection the auth tables live on. */
+  connection: string;
+}
+
+/** Split a compiled migration blob into single SQL statements. */
+export function splitSqlStatements(sqlBlob: string): string[] {
+  return sqlBlob
+    .split(";")
+    .map((statement) => statement.trim())
+    .filter((statement) => statement !== "");
+}
+
+/** Classify one auth DDL statement into a push step (kind "auth" throughout). */
+export function classifyAuthStatement(statement: string, connection: string): AuthPushStep {
+  const createTable = statement.match(/^create table "?([\w.]+)"?/i);
+  if (createTable) {
+    return {
+      connection,
+      kind: "auth",
+      sql: statement,
+      summary: `Create auth table "${createTable[1]!}"`,
+      table: createTable[1]!,
+    };
+  }
+  const addColumn = statement.match(/^alter table "?([\w.]+)"? add column "?([\w.]+)"?/i);
+  if (addColumn) {
+    return {
+      connection,
+      kind: "auth",
+      sql: statement,
+      summary: `Add auth column "${addColumn[2]!}" to "${addColumn[1]!}"`,
+      table: addColumn[1]!,
+    };
+  }
+  const index = statement.match(/^create (?:unique )?index "?([\w.]+)"? on "?([\w.]+)"?/i);
+  if (index) {
+    return {
+      connection,
+      kind: "auth",
+      sql: statement,
+      summary: `Create auth index "${index[1]!}" on "${index[2]!}"`,
+      table: index[2]!,
+    };
+  }
+  return { connection, kind: "auth", sql: statement, summary: statement };
+}
+
+/**
+ * Compile Better Auth's additive system-table migration into push steps plus an apply function. The
+ * secret is intentionally not required here — planning and pushing schemas must work before the
+ * signing secret is provisioned.
+ *
+ * @param {AuthSection} section
+ * @param {AuthProjectConfig} projectConfig
+ * @param {Env} env
+ * @param {object} [options]
+ * @param {Record<string, AuthConnectorProvider>} [options.connectors] - Provider stand-ins
+ * @returns {Promise<AuthMigrationsResult>}
+ */
+export async function getAuthMigrations(
+  section: AuthSection,
+  projectConfig: AuthProjectConfig,
+  env: Env,
+  options: { connectors?: Record<string, AuthConnectorProvider> | undefined } = {},
+): Promise<AuthMigrationsResult> {
+  const { dialect, type, connection } = await resolveAuthDatabase(
+    section,
+    projectConfig,
+    env,
+    options.connectors,
+  );
+  const authOptions = buildAuthOptions(section, env, { database: { dialect, type } });
+  const migrations = await getMigrations(authOptions as Parameters<typeof getMigrations>[0]);
+  const sqlBlob = await migrations.compileMigrations();
+  const steps = splitSqlStatements(sqlBlob).map((statement) =>
+    classifyAuthStatement(statement, connection),
+  );
+  return {
+    apply: async () => {
+      if (steps.length > 0) {
+        await migrations.runMigrations();
+      }
+    },
+    connection,
+    steps,
+  };
+}

package/src/session.ts

@@ -0,0 +1,118 @@
+/**
+ * Session — the module-level session store and the `Session` state class.
+ *
+ * One store per page: the first `Session.resolve()` fetches the session through the auth client,
+ * later resolves reuse the in-flight/last value, and every auth action refresh notifies subscribers
+ * — `subscribe()` rides the runtime's existing ref machinery, so any `state` entry with
+ * `"$prototype": "Session"` updates live across sign-in/sign-out. Outside browsers `resolve()`
+ * returns null, keeping statically generated pages on the signed-out state.
+ */
+
+import { getAuthClient } from "./client.ts";
+import { toSessionInfo } from "./config.ts";
+import type { SessionInfo } from "@jxsuite/connector/types";
+
+export type SessionListener = (session: SessionInfo | null) => void;
+
+let current: SessionInfo | null = null;
+let pending: Promise<SessionInfo | null> | null = null;
+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";
+}
+
+function notify(): void {
+  for (const listener of listeners) {
+    listener(current);
+  }
+}
+
+/** The last-known session (synchronous access; null when signed out or never fetched). */
+export function currentSession(): SessionInfo | null {
+  return current;
+}
+
+/**
+ * Fetch the session through the auth client, update the store, and notify subscribers.
+ *
+ * @param {string} [baseUrl] - Auth route base URL; defaults to <origin>/_jx/auth
+ * @returns {Promise<SessionInfo | null>}
+ */
+export async function fetchSession(baseUrl?: string): Promise<SessionInfo | null> {
+  const run = (async () => {
+    try {
+      const { data } = await getAuthClient(baseUrl).getSession();
+      current = toSessionInfo(data);
+    } catch {
+      // Fail-closed: an unreachable auth backend reads as signed out.
+      current = null;
+    }
+    notify();
+    return current;
+  })();
+  pending = run;
+  return run;
+}
+
+/** Refresh the store in the background (auth actions call this after every state change). */
+export function refreshSession(baseUrl?: string): void {
+  void fetchSession(baseUrl);
+}
+
+/** Drop the session locally (sign-out) and notify subscribers. */
+export function clearSession(): void {
+  current = null;
+  pending = Promise.resolve(null);
+  notify();
+}
+
+/**
+ * Subscribe to session changes.
+ *
+ * @param {SessionListener} listener
+ * @returns {() => void} Unsubscribe
+ */
+export function subscribeSession(listener: SessionListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Reset the store (test hook). */
+export function resetSessionStore(): void {
+  current = null;
+  pending = null;
+  listeners.clear();
+}
+
+/** Config of the Session state class. */
+export interface SessionConfig {
+  baseUrl?: string;
+  [key: string]: unknown;
+}
+
+export class Session {
+  config: SessionConfig;
+
+  constructor(config: SessionConfig = {}) {
+    this.config = config;
+  }
+
+  /** SessionInfo for the signed-in user, or null — always null outside browsers (SSG-safe). */
+  async resolve(): Promise<SessionInfo | null> {
+    if (!inBrowser()) {
+      return null;
+    }
+    pending ??= fetchSession(this.config.baseUrl);
+    return pending;
+  }
+
+  /** Ride the runtime ref machinery: push every session change into the wrapping signal. */
+  subscribe(callback: SessionListener): void {
+    subscribeSession(callback);
+    if (pending === null && inBrowser()) {
+      pending = fetchSession(this.config.baseUrl);
+    }
+  }
+}