@jxsuite/auth 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# `@jxsuite/auth`
+
+> Better Auth sessions, sign-in flows, and table permissions for Jx sites.
+
+## Overview
+
+`@jxsuite/auth` is the Jx extension putting users behind the connector's data tables. It owns the
+project.json `auth` section and mounts [Better Auth](https://better-auth.com) (pinned 1.6.23) at
+`/_jx/auth` — **order 10**, ahead of the connector's `/_jx/data` mount (order 20) — publishing the
+`ctx.auth = { getSession, authorize }` hooks on the shared server context
+(specs/extensions.md §11). With this mount active, table permission rules beyond
+`public`/`none` come alive:
+
+| Rule            | Grants                                                                                            |
+| --------------- | ------------------------------------------------------------------------------------------------- |
+| `authenticated` | Any signed-in user.                                                                               |
+| `owner`         | Inserts stamp the table's `ownerField` with the user id; reads/updates/deletes scope to that row. |
+| `role:<r>`      | Users whose `role` column equals `<r>`.                                                           |
+
+Without the auth mount the data mount **fails closed**: only `public` rules pass.
+
+Declaring an `ownerField` makes that column authoritative: **every** session-granted insert
+(`authenticated`, `owner`, `role:<r>`) stamps it with the signed-in user's id, so clients can
+never forge ownership.
+
+The auth system tables (`user`, `session`, `account`, `verification`) live on an ordinary
+connector connection — `auth.connection`, defaulting to the project's first-declared connection —
+and are created by Better Auth's additive migrations: `jx db push` (or the Studio's push button)
+plans them as `kind: "auth"` steps after the connector plan, and the dev server also syncs them on
+first touch of `/_jx/auth`.
+
+## Enable it
+
+```json
+{
+  "extensions": ["@jxsuite/parser", "@jxsuite/connector", "@jxsuite/auth"],
+  "connections": { "main": { "provider": "sqlite" } },
+  "auth": {
+    "connection": "main",
+    "methods": { "emailPassword": true },
+    "redirects": { "afterSignIn": "/", "afterSignOut": "/" }
+  },
+  "data": {
+    "comments": {
+      "connection": "main",
+      "permissions": { "read": "public", "insert": "authenticated", "update": "owner" },
+      "ownerField": "author_id",
+      "schema": {
+        "type": "object",
+        "properties": { "message": { "type": "string" }, "author_id": { "type": "string" } },
+        "required": ["message"]
+      }
+    }
+  }
+}
+```
+
+Secrets never enter project.json (specs/extensions.md §13): set the signing secret under the env
+var named by `auth.secretEnv` (default `BETTER_AUTH_SECRET`) in `.dev.vars` locally and via
+`wrangler secret put` in production. Social providers name their credential env vars the same way
+(`providers.github.clientIdEnv`, defaulting to `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`).
+
+## Page UX
+
+```json
+{
+  "state": {
+    "session": { "$prototype": "Session" },
+    "auth": { "$prototype": "AuthActions" }
+  }
+}
+```
+
+- **`Session`** resolves to `{ userId, role?, user }` or `null` and updates live via
+  `subscribe()`. Outside browsers it resolves to `null`, so statically generated pages always
+  render the signed-out state.
+- **`AuthActions`** resolves to `{ signInEmail, signUpEmail, signInSocial, signOut }` — wire a
+  form's `onsubmit` to `{ "$ref": "auth.signInEmail" }` and the handler reads the form's
+  `email`/`password` fields, refreshes the session store, bumps the `_v` read-after-write version,
+  and applies `auth.redirects`.
+
+## v1 cuts
+
+- **No email transport**: no verification or password-reset emails ship in v1 — email/password
+  accounts are live immediately after sign-up.
+- **Roles are edited via the data grid**: declare role names in `auth.roles` (this adds the
+  `role` column to the user table); assign them by editing user rows in the Studio's data grid.
+  Sign-up input can never set a role.
+- **Public-insert abuse**: a table with `insert: "public"` accepts writes from anyone on the
+  internet. Prefer `authenticated` inserts, or accept the risk knowingly (rate limiting /
+  Turnstile are future work).
+
+## Versioning
+
+Published to npm as `@jxsuite/auth` — TypeScript source, like every `@jxsuite` package, following
+the monorepo's release train. Depends on `@jxsuite/connector` (the `resolveDialect` seam and the
+permission/hook types it publishes for dependents); core packages never depend on this extension.

package/jx-extension.json

@@ -0,0 +1,13 @@
+{
+  "name": "@jxsuite/auth",
+  "title": "Authentication",
+  "description": "Better Auth sessions, sign-in flows, and table permissions served over /_jx/auth",
+  "classes": {
+    "Auth": "./src/Auth.class.json",
+    "Session": "./src/Session.class.json",
+    "AuthActions": "./src/AuthActions.class.json"
+  },
+  "schemas": {
+    "project": "./schemas/project.fragment.schema.json"
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@jxsuite/auth",
+  "version": "0.1.0",
+  "description": "Better Auth sessions, sign-in flows, and table permissions for Jx sites over /_jx/auth",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "extensions/auth"
+  },
+  "files": [
+    "src/",
+    "jx-extension.json",
+    "schemas/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/server.ts",
+    "./authorize": "./src/authorize.ts",
+    "./config": "./src/config.ts",
+    "./server": "./src/server.ts",
+    "./worker": "./src/worker.ts",
+    "./client": "./src/client.ts",
+    "./session": "./src/session.ts",
+    "./actions": "./src/actions.ts",
+    "./jx-extension.json": "./jx-extension.json",
+    "./schemas/project.fragment.schema.json": "./schemas/project.fragment.schema.json",
+    "./Auth.class.json": "./src/Auth.class.json",
+    "./Session.class.json": "./src/Session.class.json",
+    "./AuthActions.class.json": "./src/AuthActions.class.json"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "@jxsuite/connector": "workspace:^",
+    "@jxsuite/schema": "workspace:^",
+    "better-auth": "1.6.23",
+    "kysely": "^0.28.17"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "ajv": "^8.20.0"
+  },
+  "jx": "./jx-extension.json"
+}

package/schemas/project.fragment.schema.json

@@ -0,0 +1,76 @@
+{
+  "$id": "https://jxsuite.com/schema/ext/auth/project/v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Auth project fragment",
+  "description": "Project-schema fragment contributed by @jxsuite/auth: the `auth` section configuring Better Auth over a connector connection. Entries carry identifiers and env-var NAMES only — secret values live in .dev.vars locally and the platform secret store in production (specs/extensions.md §13).",
+  "type": "object",
+  "properties": {
+    "auth": {
+      "description": "Authentication configuration. Enables the /_jx/auth mount (Better Auth) and the permission rules beyond \"public\"/\"none\" on data tables.",
+      "type": "object",
+      "properties": {
+        "connection": {
+          "description": "Name of a `connections` entry holding the auth system tables (user, session, account, verification). Defaults to the project's first-declared connection.",
+          "type": "string"
+        },
+        "secretEnv": {
+          "description": "NAME of the env var holding the Better Auth signing secret. The value itself is a secret and never enters project.json.",
+          "type": "string",
+          "default": "BETTER_AUTH_SECRET"
+        },
+        "methods": {
+          "description": "Enabled first-party sign-in methods.",
+          "type": "object",
+          "properties": {
+            "emailPassword": {
+              "description": "Email + password sign-up/sign-in (enabled by default).",
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
+        "providers": {
+          "description": "Social sign-in providers keyed by Better Auth provider id (\"github\", \"google\", …). Values name the env vars carrying each provider's OAuth credentials; defaults are <ID>_CLIENT_ID / <ID>_CLIENT_SECRET.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "clientIdEnv": {
+                "description": "NAME of the env var holding the OAuth client id.",
+                "type": "string"
+              },
+              "clientSecretEnv": {
+                "description": "NAME of the env var holding the OAuth client secret.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "redirects": {
+          "description": "Site paths the auth actions navigate to after auth state changes.",
+          "type": "object",
+          "properties": {
+            "afterSignIn": {
+              "description": "Path to navigate to after a successful sign-in/sign-up.",
+              "type": "string"
+            },
+            "afterSignOut": {
+              "description": "Path to navigate to after sign-out.",
+              "type": "string"
+            }
+          }
+        },
+        "roles": {
+          "description": "Role names usable in table permission rules (\"role:<name>\"). Declaring any role adds a `role` column to the user table; assignments are edited via the data grid.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "trustedOrigins": {
+          "description": "Extra origins allowed to call the auth routes (Better Auth trustedOrigins passthrough).",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/Auth.class.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/auth/Auth.class.json",
+  "title": "Auth",
+  "description": "Owner of the project.json `auth` section and the /_jx/auth server mount: Better Auth over a connector connection, publishing the ctx.auth hooks the data mount authorizes against",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./worker.js",
+
+  "project": {
+    "key": "auth",
+    "title": "Authentication",
+    "description": "Better Auth sessions and sign-in methods served at /_jx/auth"
+  },
+
+  "server": {
+    "basePath": "/_jx/auth",
+    "order": 10,
+    "module": "@jxsuite/auth/worker"
+  },
+
+  "$studio": {
+    "settings": {
+      "icon": "sp-icon-lock-closed",
+      "label": "Authentication",
+      "order": 58,
+      "layout": "form",
+      "entry": {
+        "ui": {
+          "connection": { "enum": { "$ref": "#/$context/connections" } },
+          "secretEnv": { "control": "secret" }
+        }
+      }
+    }
+  },
+
+  "$defs": {
+    "returnTypes": {
+      "SectionData": {
+        "type": "object",
+        "description": "The auth section value (identifiers and env-var names only), stored as _project.auth"
+      }
+    },
+
+    "methods": {
+      "projectData": {
+        "role": "projectData",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "projectData",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `auth` section value"
+          },
+          {
+            "identifier": "ctx",
+            "type": { "type": "object" },
+            "description": "Host context: { projectConfig, root, registry, io }"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/SectionData" },
+        "description": "Expose the auth configuration under _project.auth (redirects for the auth actions; never secrets)"
+      },
+      "mount": {
+        "role": "mount",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "mount",
+        "timing": ["server"],
+        "parameters": [
+          {
+            "identifier": "options",
+            "type": {
+              "type": "object",
+              "properties": {
+                "basePath": { "type": "string" },
+                "sections": { "type": "object" },
+                "connectors": { "type": "object" },
+                "autoSync": { "type": "boolean" }
+              }
+            },
+            "description": "Inlined mount options: project sections, provider constructors, sync mode"
+          },
+          {
+            "identifier": "ctx",
+            "type": { "type": "object" },
+            "description": "Shared JxServerContext — this mount (order 10) publishes ctx.auth for later mounts"
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Fetch-style handler (request, env) → Response serving the Better Auth routes under /_jx/auth; sets ctx.auth = { getSession, authorize }"
+      },
+      "deploySchema": {
+        "role": "deploySchema",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "deploySchema",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `auth` section value"
+          },
+          {
+            "identifier": "projectConfig",
+            "type": { "type": "object" },
+            "description": "The full project config (connection lookup)"
+          },
+          {
+            "identifier": "options",
+            "type": {
+              "type": "object",
+              "properties": {
+                "env": { "type": "object" },
+                "dryRun": { "type": "boolean" },
+                "connection": { "type": "string" },
+                "connectors": { "type": "object" }
+              }
+            },
+            "description": "Push options: env, dry-run, optional connection filter, provider stand-ins"
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Additive Better Auth system-table sync: { statements, applied, warnings, connection }"
+      }
+    }
+  }
+}

package/src/AuthActions.class.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/auth/AuthActions.class.json",
+  "title": "AuthActions",
+  "description": "Form-friendly auth handlers: resolves to { signInEmail, signUpEmail, signInSocial, signOut }, each (scope, event)-callable reading the enclosing form's FormData, bumping the session store, and applying the configured redirects",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./actions.js",
+
+  "$studio": {
+    "stateDefaults": { "timing": "client" }
+  },
+
+  "$defs": {
+    "parameters": {
+      "redirects": {
+        "identifier": "redirects",
+        "type": { "type": "object" },
+        "description": "{ afterSignIn?, afterSignOut? } paths (defaults to the project auth section's redirects)"
+      },
+      "provider": {
+        "identifier": "provider",
+        "type": { "type": "string" },
+        "description": "Default social provider id for signInSocial (a form field or the def may override)"
+      },
+      "baseUrl": {
+        "identifier": "baseUrl",
+        "type": { "type": "string" },
+        "description": "Auth route base URL (defaults to <origin>/_jx/auth)"
+      }
+    },
+    "constructor": {
+      "role": "constructor",
+      "parameters": [
+        { "$ref": "#/$defs/parameters/redirects" },
+        { "$ref": "#/$defs/parameters/provider" },
+        { "$ref": "#/$defs/parameters/baseUrl" }
+      ],
+      "body": ["this.config = config;"]
+    },
+    "methods": {
+      "resolve": {
+        "role": "method",
+        "scope": "instance",
+        "identifier": "resolve",
+        "returnType": { "type": "object" },
+        "description": "The handler map: signInEmail / signUpEmail / signInSocial / signOut, wired via $ref (e.g. onsubmit: { \"$ref\": \"auth.signInEmail\" })"
+      }
+    }
+  }
+}

package/src/Session.class.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/auth/Session.class.json",
+  "title": "Session",
+  "description": "The signed-in user's session as reactive state: resolves to { userId, role?, user } or null, updating live as auth actions sign the user in and out. Resolves to null outside browsers, so statically generated pages render the signed-out state",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./session.js",
+
+  "$studio": {
+    "stateDefaults": { "timing": "client" }
+  },
+
+  "$defs": {
+    "parameters": {
+      "baseUrl": {
+        "identifier": "baseUrl",
+        "type": { "type": "string" },
+        "description": "Auth route base URL (defaults to <origin>/_jx/auth)"
+      }
+    },
+    "constructor": {
+      "role": "constructor",
+      "parameters": [{ "$ref": "#/$defs/parameters/baseUrl" }],
+      "body": ["this.config = config;"]
+    },
+    "methods": {
+      "resolve": {
+        "role": "method",
+        "scope": "instance",
+        "identifier": "resolve",
+        "returnType": { "type": ["object", "null"] },
+        "description": "SessionInfo { userId, role?, user } for the signed-in user, or null (always null outside browsers)"
+      },
+      "subscribe": {
+        "role": "method",
+        "scope": "instance",
+        "identifier": "subscribe",
+        "parameters": [
+          {
+            "identifier": "callback",
+            "type": { "type": "object" },
+            "description": "Called with the new SessionInfo|null whenever the session store changes"
+          }
+        ],
+        "description": "Subscribe to session changes (auth actions bump the store after sign-in/out)"
+      }
+    }
+  }
+}

package/src/actions.ts

@@ -0,0 +1,149 @@
+/**
+ * Actions — the `AuthActions` state class: form-friendly sign-in/sign-up/sign-out handlers.
+ *
+ * `resolve()` returns `{ signInEmail, signUpEmail, signInSocial, signOut }`; each handler is
+ * `(scope, event)`-callable — the same shape the connector's table actions use — reading the
+ * submitting form's FormData, calling the Better Auth client, refreshing the session store, and
+ * applying the configured redirects. Successful calls also bump `scope._v`, re-running lowered
+ * table queries whose visible rows may change with the auth state (owner-scoped reads). Wire via
+ * `"onsubmit": { "$ref": "auth.signInEmail" }` on a form with email/password fields.
+ */
+
+import { getAuthClient } from "./client.ts";
+import { clearSession, fetchSession } from "./session.ts";
+import type { AuthClientResult } from "./client.ts";
+
+/** Redirect paths applied after auth state changes. */
+export interface AuthRedirects {
+  afterSignIn?: string;
+  afterSignOut?: string;
+}
+
+/** Config of the AuthActions state class. */
+export interface AuthActionsConfig {
+  redirects?: AuthRedirects;
+  /** Default social provider id for signInSocial (a form field named "provider" overrides). */
+  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;
+}
+
+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>;
+
+/** 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;
+  if (!target) {
+    return null;
+  }
+  return target.tagName === "FORM" ? (target as HTMLFormElement) : (target.form ?? null);
+}
+
+/** String field values of the submitting form (files are ignored). */
+function formValues(event?: Event): Record<string, string> {
+  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;
+    }
+  }
+  return out;
+}
+
+/** Navigate to a redirect path when one is configured (browser only). */
+function navigate(path: string | undefined): void {
+  if (path && typeof location !== "undefined") {
+    location.assign(path);
+  }
+}
+
+/** 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;
+}
+
+export class AuthActions {
+  config: AuthActionsConfig;
+
+  constructor(config: AuthActionsConfig = {}) {
+    this.config = config;
+  }
+
+  /** Effective redirects: the def's own, else the project auth section's. */
+  redirects(): AuthRedirects {
+    return this.config.redirects ?? this.config._project?.auth?.redirects ?? {};
+  }
+
+  /** The handler map, wired via $ref (e.g. `onsubmit: { "$ref": "auth.signInEmail" }`). */
+  resolve(): Record<string, AuthActionHandler> {
+    return {
+      signInEmail: this.#authCall((values, client) =>
+        client.signIn.email({ email: values.email ?? "", password: values.password ?? "" }),
+      ),
+      signInSocial: this.#authCall(
+        (values, client) => {
+          const provider = values.provider ?? this.config.provider ?? "";
+          const callbackURL = this.redirects().afterSignIn;
+          return client.signIn.social({
+            provider,
+            ...(callbackURL === undefined ? {} : { callbackURL }),
+          });
+          // Social sign-in redirects the whole page itself — no local navigation.
+        },
+        { redirect: false },
+      ),
+      signOut: async (scope: Scope, event?: Event): Promise<boolean> => {
+        event?.preventDefault?.();
+        const { error } = await getAuthClient(this.config.baseUrl).signOut();
+        if (error) {
+          return false;
+        }
+        clearSession();
+        bumpVersion(scope);
+        navigate(this.redirects().afterSignOut);
+        return true;
+      },
+      signUpEmail: this.#authCall((values, client) =>
+        client.signUp.email({
+          email: values.email ?? "",
+          // Better Auth requires a name; fall back to the email's local part.
+          name: values.name ?? (values.email ?? "").split("@")[0] ?? "",
+          password: values.password ?? "",
+        }),
+      ),
+    };
+  }
+
+  /** Build a form-reading handler around one auth client call. */
+  #authCall(
+    call: (
+      values: Record<string, string>,
+      client: ReturnType<typeof getAuthClient>,
+    ) => Promise<AuthClientResult>,
+    options: { redirect?: boolean } = {},
+  ): AuthActionHandler {
+    return async (scope: Scope, event?: Event): Promise<boolean> => {
+      event?.preventDefault?.();
+      const client = getAuthClient(this.config.baseUrl);
+      const { error } = await call(formValues(event), client);
+      if (error) {
+        return false;
+      }
+      await fetchSession(this.config.baseUrl);
+      bumpVersion(scope);
+      if (options.redirect !== false) {
+        navigate(this.redirects().afterSignIn);
+      }
+      return true;
+    };
+  }
+}