@pathmx/auth 0.5.0

package/host.ts

@@ -0,0 +1,108 @@
+import {
+  anonymousCredentialHost,
+  createCredentialHost,
+  type CredentialHost,
+  type CredentialProvider,
+  type PluginLog,
+} from "@pathmx/core"
+import type { AuthProviderFactory } from "./providers/types.ts"
+import { providersFromEnv, type AuthEnvironment } from "./providers/env.ts"
+import type { SqlDatabase } from "@pathmx/core"
+import { developmentCredentialHost } from "./providers/development.ts"
+
+function combinedProvider(
+  providers: readonly CredentialProvider[],
+): CredentialProvider {
+  return {
+    signIn: providers.find((provider) => provider.signIn)?.signIn ?? null,
+    async ready(directory) {
+      await Promise.all(providers.map((provider) => provider.ready(directory)))
+    },
+    async resolve(request) {
+      for (const provider of providers) {
+        const identity = await provider.resolve(request)
+        if (identity) return identity
+      }
+    },
+    async fetch(request, directory) {
+      for (const provider of providers) {
+        const response = await provider.fetch(request, directory)
+        if (response.status !== 404) return response
+      }
+      return new Response("Not Found", { status: 404 })
+    },
+    async close() {
+      const results = await Promise.allSettled(
+        providers.map((provider) => provider.close()),
+      )
+      const errors = results.flatMap((result) =>
+        result.status === "rejected" ? [result.reason] : [],
+      )
+      if (errors.length) {
+        throw new AggregateError(
+          errors,
+          "Authentication provider shutdown failed.",
+        )
+      }
+    },
+  }
+}
+
+export function productionCredentialHost(options: {
+  database: SqlDatabase
+  log: PluginLog
+  providers?: readonly AuthProviderFactory[]
+  env?: AuthEnvironment
+  allowAnonymous?: boolean
+}) {
+  const factories = options.providers
+  const env = options.env ?? process.env
+  if (!factories?.length && options.allowAnonymous && !env.PATHMX_AUTH_MODE) {
+    return anonymousCredentialHost()
+  }
+  const providers = factories?.length
+    ? factories.map((provider) =>
+        provider({ database: options.database, log: options.log }),
+      )
+    : providersFromEnv({ database: options.database, log: options.log }, env)
+  return createCredentialHost(combinedProvider(providers))
+}
+
+export function runtimeCredentialHost(options: {
+  development: boolean
+  database: SqlDatabase
+  log: PluginLog
+  providers?: readonly AuthProviderFactory[]
+  env?: AuthEnvironment
+  allowAnonymous?: boolean
+}) {
+  return options.development
+    ? developmentCredentialHost()
+    : productionCredentialHost(options)
+}
+
+export function deferredCredentialHost() {
+  let current: CredentialHost | undefined
+  const required = () => {
+    if (!current) throw new Error("Authentication plugin is not initialized.")
+    return current
+  }
+  return {
+    host: Object.freeze({
+      ready: (...args: Parameters<CredentialHost["ready"]>) =>
+        required().ready(...args),
+      resolve: (...args: Parameters<CredentialHost["resolve"]>) =>
+        required().resolve(...args),
+      fetch: (...args: Parameters<CredentialHost["fetch"]>) =>
+        required().fetch(...args),
+      async close() {
+        await current?.close()
+        current = undefined
+      },
+    }) satisfies CredentialHost,
+    set(host: CredentialHost) {
+      if (current) throw new Error("Authentication plugin already initialized.")
+      current = host
+    },
+  }
+}

package/index.plugin.ts

@@ -0,0 +1,83 @@
+import {
+  definePlugin,
+  privateResponse,
+  route,
+  type CredentialHost,
+  type Plugin,
+} from "@pathmx/core"
+import { authComponents } from "./components/index.ts"
+import { registerAuthCommands } from "./commands.ts"
+import { authDatabase } from "./database.ts"
+import { deferredCredentialHost, runtimeCredentialHost } from "./host.ts"
+import type { AuthEnvironment } from "./providers/env.ts"
+import type { AuthProviderFactory } from "./providers/types.ts"
+
+export type AuthPluginOptions = Readonly<{
+  providers?: readonly AuthProviderFactory[]
+  env?: AuthEnvironment
+  /** Permit an anonymous production host when no provider is configured. */
+  allowAnonymous?: boolean
+  /** Supply an already composed host for custom providers and tests. */
+  credentials?: CredentialHost
+  /** Replace the stock magic-link UI while retaining auth state and routes. */
+  components?: Plugin["components"]
+}>
+
+export function AuthPlugin(options: AuthPluginOptions = {}): Plugin {
+  const credentials = deferredCredentialHost()
+  if (options.credentials) credentials.set(options.credentials)
+  return definePlugin({
+    id: "auth",
+    name: "PathMX Auth",
+    database: authDatabase,
+    credentials: credentials.host,
+    components: options.components ?? authComponents,
+    commands(group, ctx) {
+      registerAuthCommands(group, ctx, options.env)
+    },
+    setup(ctx) {
+      if (options.credentials) return
+      if (!ctx.database) throw new Error("Auth database is unavailable.")
+      credentials.set(
+        runtimeCredentialHost({
+          development: ctx.runtime.mode === "development",
+          database: ctx.database,
+          log: ctx.log,
+          providers: options.providers,
+          env: options.env,
+          allowAnonymous: options.allowAnonymous,
+        }),
+      )
+    },
+    routes: [
+      route.all("*", async (ctx) =>
+        privateResponse(await ctx.handleCredentials()),
+      ),
+    ],
+  })
+}
+
+export { authRoutes } from "./providers/magic-link.ts"
+export {
+  Confirm as AuthConfirm,
+  Session as AuthSession,
+  SignIn as AuthSignIn,
+  authComponents,
+} from "./components/index.ts"
+export type { AuthEnvironment } from "./providers/env.ts"
+export type {
+  AuthProviderContext,
+  AuthProviderFactory,
+} from "./providers/types.ts"
+export type {
+  MagicLinkDelivery,
+  MagicLinkMailer,
+  MagicLinkProviderOptions,
+} from "./providers/magic-link.ts"
+export { magicLinkProvider } from "./providers/magic-link.ts"
+export { AuthSetupPattern } from "./patterns/setup.ts"
+export {
+  developmentCredentialHost,
+  type DevelopmentCredentialHost,
+} from "./providers/development.ts"
+export default AuthPlugin

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pathmx/auth",
+  "description": "Authentication and account UI for PathMX applications.",
+  "version": "0.5.0",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathmx/pathmx-beta.git",
+    "directory": "paths/auth"
+  },
+  "homepage": "https://github.com/pathmx/pathmx-beta#readme",
+  "bugs": "https://github.com/pathmx/pathmx-beta/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.plugin.ts",
+    "./providers": "./providers/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "peerDependencies": {
+    "@pathmx/core": "^0.5.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "dependencies": {
+    "@pathmx/react": "0.5.0",
+    "better-auth": "1.6.29"
+  }
+}

package/patterns/setup.ts

@@ -0,0 +1,30 @@
+import { definePattern } from "@pathmx/core"
+
+export const AuthSetupPattern = definePattern({
+  id: "auth:setup",
+  description: "Add the stock authentication pages and environment example.",
+  generate() {
+    return [
+      {
+        root: "paths",
+        path: "sign-in/index.page.md",
+        content: "# Sign in\n\n<x-auth-sign-in />\n",
+      },
+      {
+        root: "paths",
+        path: "auth/confirm/index.page.md",
+        content: "# Confirm sign in\n\n<x-auth-confirm />\n",
+      },
+      {
+        root: "project",
+        path: ".env.example",
+        content: `PATHMX_AUTH_MODE=magic-link
+PATHMX_AUTH_ORIGIN=http://localhost:3000
+PATHMX_AUTH_SECRET=
+PATHMX_AUTH_EMAIL_FROM=PathMX <auth@example.com>
+RESEND_API_KEY=
+`,
+      },
+    ] as const
+  },
+})

package/providers/database.ts

@@ -0,0 +1,96 @@
+import type { SqlDatabase, SqlValue } from "@pathmx/core"
+
+function sqlValues(values: readonly unknown[]): SqlValue[] {
+  return values.map((value) => {
+    if (
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "bigint" ||
+      value instanceof Uint8Array
+    ) {
+      return value
+    }
+    if (typeof value === "boolean") return value ? 1 : 0
+    throw new Error(
+      `Unsupported authentication database value: ${typeof value}`,
+    )
+  })
+}
+
+function mutates(sql: string) {
+  return /^\s*(?:insert|update|delete|replace)\b/i.test(sql)
+}
+
+class PathMXD1Statement {
+  private values: SqlValue[] = []
+
+  constructor(
+    private database: SqlDatabase,
+    private sql: string,
+  ) {}
+
+  bind(...values: unknown[]) {
+    this.values = sqlValues(values)
+    return this
+  }
+
+  private async execute(database: SqlDatabase) {
+    const mutation = mutates(this.sql)
+    if (mutation && !/\breturning\b/i.test(this.sql)) {
+      const result = await database.run(this.sql, this.values)
+      return {
+        success: true,
+        results: [],
+        meta: {
+          changes: result.changes,
+          last_row_id: result.lastInsertRowId,
+        },
+      }
+    }
+    const results = await database.all(this.sql, this.values)
+    if (!mutation) {
+      return { success: true, results, meta: { changes: 0 } }
+    }
+    const meta = await database.get<{ changes: number; lastRowId: number }>(
+      "SELECT changes() AS changes, last_insert_rowid() AS lastRowId",
+    )
+    return {
+      success: true,
+      results,
+      meta: {
+        changes: meta?.changes ?? 0,
+        last_row_id: meta?.lastRowId,
+      },
+    }
+  }
+
+  all() {
+    return mutates(this.sql) && /\breturning\b/i.test(this.sql)
+      ? this.database.transaction((database) => this.execute(database))
+      : this.execute(this.database)
+  }
+
+  executeIn(database: SqlDatabase) {
+    return this.execute(database)
+  }
+}
+
+/** Adapt PathMX's portable SQL contract to Better Auth's supported D1 shape. */
+export function betterAuthDatabase(database: SqlDatabase) {
+  return {
+    prepare: (sql: string) => new PathMXD1Statement(database, sql),
+    batch: (statements: PathMXD1Statement[]) =>
+      database.transaction(async (transaction) => {
+        const results = []
+        for (const statement of statements) {
+          results.push(await statement.executeIn(transaction))
+        }
+        return results
+      }),
+    async exec(sql: string) {
+      await database.exec(sql)
+      return { count: 1, duration: 0 }
+    },
+  }
+}

package/providers/development.ts

@@ -0,0 +1,144 @@
+import type { CredentialHost, CredentialSession, UserActor } from "@pathmx/core"
+
+const COOKIE = "pathmx-dev-session"
+
+function escapeHtml(value: string) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+}
+
+function cookieValue(header: string | null) {
+  if (!header) return
+  for (const part of header.split(";")) {
+    const equals = part.indexOf("=")
+    if (equals === -1 || part.slice(0, equals).trim() !== COOKIE) continue
+    try {
+      return decodeURIComponent(part.slice(equals + 1).trim())
+    } catch {
+      return
+    }
+  }
+}
+
+function loopback(hostname: string) {
+  return (
+    hostname === "localhost" ||
+    hostname === "::1" ||
+    hostname === "[::1]" ||
+    hostname.startsWith("127.")
+  )
+}
+
+function devRequest(request: Request) {
+  const url = new URL(request.url)
+  if (!loopback(url.hostname)) return
+  const origin = request.headers.get("origin")
+  if (origin && origin !== url.origin) return
+  return url
+}
+
+function authenticated(actor: UserActor): CredentialSession {
+  return {
+    type: "authenticated",
+    actor,
+    signOut: { method: "post", href: "/api/auth/dev/sign-out" },
+  }
+}
+
+export type DevelopmentCredentialHost = CredentialHost &
+  Readonly<{
+    createSession(actorId: string): string
+    cookie(sessionId: string): string
+  }>
+
+export function developmentCredentialHost(): DevelopmentCredentialHost {
+  const sessions = new Map<string, string>()
+  const createSession = (actorId: string) => {
+    const sessionId = crypto.randomUUID()
+    sessions.set(sessionId, actorId)
+    return sessionId
+  }
+  const cookie = (sessionId: string) =>
+    `${COOKIE}=${encodeURIComponent(sessionId)}`
+
+  return {
+    async ready() {},
+    createSession,
+    cookie,
+    async resolve(request, actors) {
+      const url = devRequest(request)
+      if (!url) return { type: "anonymous", signIn: null }
+      const sessionId = cookieValue(request.headers.get("cookie"))
+      const actorId = sessionId ? sessions.get(sessionId) : undefined
+      const actor = actorId ? actors.findActorById(actorId) : undefined
+      return actor?.type === "user"
+        ? authenticated(actor)
+        : {
+            type: "anonymous",
+            signIn: { method: "get", href: "/api/auth/dev" },
+          }
+    },
+    async fetch(request, actors) {
+      const url = devRequest(request)
+      if (!url) return new Response("Not Found", { status: 404 })
+      if (request.method === "GET" && url.pathname === "/api/auth/dev") {
+        const users = actors
+          .all()
+          .filter((actor): actor is UserActor => actor.type === "user")
+          .map(
+            (actor) =>
+              `<form method="post" action="/api/auth/dev/session"><input type="hidden" name="actor" value="${escapeHtml(actor.id)}"><button type="submit">${escapeHtml(actor.profile.name)}</button></form>`,
+          )
+          .join("\n")
+        return new Response(
+          `<!doctype html><title>Choose Actor</title>${users}`,
+          {
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+          },
+        )
+      }
+      if (
+        request.method === "POST" &&
+        url.pathname === "/api/auth/dev/session"
+      ) {
+        const actorId = (await request.formData()).get("actor")
+        const actor =
+          typeof actorId === "string"
+            ? actors.findActorById(actorId)
+            : undefined
+        if (!actor || actor.type !== "user") {
+          return new Response("Unknown Actor", { status: 400 })
+        }
+        const sessionId = createSession(actor.id)
+        return new Response(null, {
+          status: 303,
+          headers: {
+            Location: "/",
+            "Set-Cookie": `${cookie(sessionId)}; Path=/; HttpOnly; SameSite=Lax`,
+          },
+        })
+      }
+      if (
+        request.method === "POST" &&
+        url.pathname === "/api/auth/dev/sign-out"
+      ) {
+        const sessionId = cookieValue(request.headers.get("cookie"))
+        if (sessionId) sessions.delete(sessionId)
+        return new Response(null, {
+          status: 303,
+          headers: {
+            Location: "/",
+            "Set-Cookie": `${COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`,
+          },
+        })
+      }
+      return new Response("Not Found", { status: 404 })
+    },
+    async close() {
+      sessions.clear()
+    },
+  }
+}

package/providers/env.ts

@@ -0,0 +1,54 @@
+import { magicLinkProvider, type MagicLinkMailer } from "./magic-link.ts"
+import type { AuthProviderContext, AuthProviderFactory } from "./types.ts"
+
+export type AuthEnvironment = Readonly<Record<string, string | undefined>>
+
+function required(env: AuthEnvironment, name: string) {
+  const value = env[name]?.trim()
+  if (!value) throw new Error(`${name} is required for magic-link auth.`)
+  return value
+}
+
+function resendMailer(apiKey: string, from: string): MagicLinkMailer {
+  return {
+    async send({ email, confirmUrl, expiresAt }) {
+      const response = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          from,
+          to: [email],
+          subject: "Sign in to PathMX",
+          text: `Confirm your PathMX sign in:\n\n${confirmUrl}\n\nThis link expires at ${expiresAt.toISOString()}.`,
+        }),
+      })
+      if (!response.ok) throw new Error("Magic-link delivery failed.")
+    },
+  }
+}
+
+export function providersFromEnv(
+  context: AuthProviderContext,
+  env: AuthEnvironment = process.env,
+): ReturnType<AuthProviderFactory>[] {
+  const mode = required(env, "PATHMX_AUTH_MODE")
+  if (mode !== "magic-link") {
+    throw new Error("PATHMX_AUTH_MODE must be magic-link.")
+  }
+  const secret = required(env, "PATHMX_AUTH_SECRET")
+  if (secret.length < 32) {
+    throw new Error("PATHMX_AUTH_SECRET must be at least 32 characters.")
+  }
+  const provider = magicLinkProvider({
+    origin: required(env, "PATHMX_AUTH_ORIGIN"),
+    secret,
+    mailer: resendMailer(
+      required(env, "RESEND_API_KEY"),
+      required(env, "PATHMX_AUTH_EMAIL_FROM"),
+    ),
+  })
+  return [provider(context)]
+}

package/providers/index.ts

@@ -0,0 +1,12 @@
+export {
+  authRoutes,
+  magicLinkProvider,
+  type MagicLinkDelivery,
+  type MagicLinkMailer,
+  type MagicLinkProviderOptions,
+} from "./magic-link.ts"
+export type { AuthProviderContext, AuthProviderFactory } from "./types.ts"
+export {
+  developmentCredentialHost,
+  type DevelopmentCredentialHost,
+} from "./development.ts"