@pathmx/auth 0.5.0

package/LICENSE.md

@@ -0,0 +1,172 @@
+# PathMX Proprietary Beta License
+
+Version 0.1 — July 21, 2026
+
+Copyright © 2026 DUO Interactive, LLC.
+All rights reserved.
+
+This license governs the first-party PathMX software distributed in the npm
+package `@pathmx/core`, including its command-line interface, bundled
+library surfaces, runtime and Player components, and accompanying
+documentation (the “Software”). DUO Interactive, LLC is the “Licensor.” This
+license does not cover the private PathMX source-code repository or separately
+identified third-party materials.
+
+“Project” means Paths, Sources, responses, data, and other content authored or
+processed with the Software.
+
+“Application” means software or a service created by you in which the Software
+supports product-specific functionality but is not itself offered as a
+general-purpose PathMX product.
+
+“Redistributable Components” means runtime, Player, or library portions of the
+Software incorporated into a Project, Application, or generated output through
+ordinary use of the Software or ordinary compilation and bundling tools.
+
+“Authorized Users” means your employees and individual contractors who use the
+Software on your behalf, and your hosting, continuous-integration, and other
+service providers that possess or run necessary copies solely to provide
+services to you.
+
+## 1. Agreement
+
+By installing, accessing, or using the Software, you agree to this license. If
+you use the Software on behalf of an organization, you represent that you have
+authority to accept this license for that organization. If you do not agree,
+do not install or use the Software.
+
+## 2. License grant
+
+Subject to this license, the Licensor grants you a non-exclusive, worldwide,
+royalty-free, non-transferable, and non-sublicensable license, perpetual for
+the version of the Software to which it applies unless terminated under
+Section 10, to:
+
+- install, execute, and use the Software for personal, educational,
+  internal-business, or commercial purposes;
+- use the Software to author, integrate, build, test, serve, play, host, and
+  operate Projects and Applications;
+- import, compile, bundle, configure, and integrate the Software through its
+  documented library and command-line interfaces;
+- create and distribute independent Projects, Applications, plugins, and
+  integrations that use those interfaces without modifying the Software
+  itself; and
+- make copies reasonably necessary for local development, testing, continuous
+  integration, backup, and hosted production environments.
+
+Your Authorized Users may exercise those rights solely on your behalf. You are
+responsible for their compliance with this license.
+
+You may reproduce and distribute Redistributable Components only as
+incorporated into your Project, Application, or generated output, and only when
+you preserve applicable license and proprietary notices. You may host and
+commercially provide access to that Project, Application, or output. You may
+not distribute Redistributable Components as a standalone package or as a
+general-purpose substitute for the Software.
+
+Each lawful recipient of a Redistributable Component may execute and use that
+component, display its output, and make technically necessary transitory copies
+solely as incorporated into the Project, Application, or output in which they
+received it. This limited recipient permission does not include a right to
+extract, modify, or redistribute the component separately.
+
+## 3. Restrictions
+
+Except where applicable law does not allow the restriction, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software, except
+  for the compilation, bundling, configuration, and integration expressly
+  permitted in Section 2;
+- redistribute, sublicense, sell, lease, or otherwise provide the Software to
+  another person as a standalone package, product, or service except to an
+  Authorized User or as a Redistributable Component under Section 2;
+- resell, rebrand, or provide the Software as a hosted or managed service that
+  gives third parties general-purpose access to substantial PathMX authoring,
+  building, serving, Player-administration, or library functionality for their
+  own unrelated projects;
+- reverse engineer, decompile, disassemble, or otherwise attempt to derive the
+  source code of the Software; or
+- remove or alter copyright, license, trademark, or other proprietary notices.
+
+For clarity, the managed-service restriction does not prohibit a hosted
+Project or Application in which PathMX supports the licensee's own
+product-specific experience and is not itself the general-purpose product
+offered to customers.
+
+## 4. Your content
+
+As between you and the Licensor, you retain ownership of the Paths, Sources,
+responses, data, independent application code, and other content that you
+author or provide while using the Software. You are responsible for that
+content and for having the rights needed to use it.
+
+Generated output may contain Redistributable Components or third-party
+materials. Your ownership of your content does not change the ownership or
+license terms of those components and materials.
+
+## 5. Ownership and trademarks
+
+The Software is licensed, not sold. The Licensor and its suppliers retain all
+rights in the Software not expressly granted by this license. This license
+does not grant permission to use the PathMX name, logos, or other marks except
+as reasonably necessary to identify the Software accurately.
+
+## 6. Beta status and changes
+
+The Software is a proprietary beta release. Its APIs, behavior, file formats,
+and features may change or be removed without notice. The Licensor has no
+obligation to provide support, maintenance, updates, continued availability,
+or backward compatibility. A later version may be offered under different
+license terms, including an open-source license. Different terms for a later
+version do not change the license previously granted for an earlier version.
+
+## 7. Third-party materials
+
+The Software and Redistributable Components may include or depend on
+third-party materials governed by their own license terms. Those terms control
+for the applicable third-party materials. You must preserve third-party notices
+when the applicable third-party terms require it.
+
+## 8. Disclaimer of warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+“AS AVAILABLE,” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS,
+IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+SECURE, ERROR-FREE, OR UNINTERRUPTED.
+
+## 9. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR AND ITS CONTRIBUTORS,
+SUPPLIERS, AND AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF DATA,
+PROFITS, REVENUE, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR RELATED TO
+THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF THOSE
+DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THEIR TOTAL LIABILITY FOR ALL CLAIMS
+ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE WILL NOT EXCEED THE
+GREATER OF THE AMOUNT YOU PAID FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE
+THE EVENT GIVING RISE TO THE CLAIM OR US$100.
+
+## 10. Termination
+
+This license terminates if you materially breach it and do not cure the breach
+within thirty days after receiving written notice from the Licensor. On
+termination, you and your Authorized Users must stop using and delete your
+copies of the Software. Sections 4, 5, 8, 9, 10, and 11 survive termination.
+Termination does not withdraw the limited permission already granted by
+Section 2 to lawful recipients of Redistributable Components distributed
+before termination.
+
+## 11. General
+
+If a provision of this license is unenforceable, it will be modified only to
+the minimum extent necessary to make it enforceable, and the remaining
+provisions will continue in effect. Failure to enforce a provision is not a
+waiver. You may not assign or transfer this license without the Licensor's
+written consent. The Licensor may assign this license together with ownership
+of the Software to a successor owner. This license binds and benefits the
+permitted successors and assigns of you and the Licensor. This license is the
+entire agreement concerning the Software unless you and the Licensor have
+signed a separate agreement that expressly replaces it.

package/README.md

@@ -0,0 +1,59 @@
+# `@pathmx/auth`
+
+Optional PathMX authentication with development Actor switching,
+production magic links, isolated SQLite state, React App View Components, and
+plugin-contributed administrator commands.
+
+## Install
+
+```sh
+bun run pmx plugins add auth
+```
+
+```ts
+// plugins/auth/index.plugin.ts
+export { default } from "@pathmx/auth"
+```
+
+Run `pmx auth setup`, copy `.env.example` to `.env`, and set:
+
+- `PATHMX_AUTH_MODE=magic-link`
+- `PATHMX_AUTH_ORIGIN` to the exact public origin
+- `PATHMX_AUTH_SECRET` to at least 32 characters
+- `PATHMX_AUTH_EMAIL_FROM` and `RESEND_API_KEY`
+
+The setup command installs the exported `AuthSetupPattern`. Different existing
+files are preserved, and the resulting Sources and configuration are ordinary
+user-owned project files with no runtime Pattern dependency.
+
+Only emails authored on User Sources may receive a link. GET requests to the
+confirmation page are inert; the token stays in the URL fragment and the React
+client submits it once by same-origin POST.
+
+Additional providers implement `AuthProviderFactory` and are passed with
+`AuthPlugin({ providers: [...] })`. Factories receive the isolated auth
+database and structured auth logger; provider resolution and `/api/auth/*`
+handling compose in declaration order.
+
+`pmx dev` binds to `127.0.0.1` because its development Actor switcher is local
+administrator tooling, not authentication for a shared server. Use a production
+provider when exposing PathMX through a tunnel, proxy, container port, or LAN.
+
+## UI
+
+- `<x-auth-sign-in />`
+- `<x-auth-confirm />`
+- `<x-auth-session />`
+
+The components render useful HTML before JavaScript, inherit the PathMX theme,
+and can be restyled with ordinary repository CSS. Override `--auth-accent`,
+`--auth-border`, or `--auth-surface` on `.pmx-auth`; authored attributes such as
+`email-label` and `submit-label` customize sign-in copy. Advanced provider UIs
+can replace the component set through `AuthPlugin({ components })`.
+
+## Commands
+
+- `pmx auth setup`
+- `pmx auth doctor`
+- `pmx auth users list`
+- `pmx auth sessions revoke-all`

package/commands.ts

@@ -0,0 +1,61 @@
+import type { Command } from "commander"
+import type { PluginCommandContext } from "@pathmx/core"
+import { AuthSetupPattern } from "./patterns/setup.ts"
+import { providersFromEnv, type AuthEnvironment } from "./providers/env.ts"
+
+async function setup(ctx: PluginCommandContext) {
+  const plan = await ctx.patterns.install(AuthSetupPattern, undefined, {
+    conflicts: "preserve",
+  })
+  const created = plan.files.filter((file) => file.status === "create")
+  for (const file of created) console.log(`created ${file.destination}`)
+  if (!created.length)
+    console.log("Authentication scaffold is already present.")
+}
+
+export function registerAuthCommands(
+  group: Command,
+  ctx: PluginCommandContext,
+  env?: AuthEnvironment,
+) {
+  group
+    .command("setup")
+    .description("Scaffold auth pages and environment configuration")
+    .action(() => setup(ctx))
+
+  group
+    .command("doctor")
+    .description("Validate auth configuration and database access")
+    .action(async () => {
+      if (!ctx.database) throw new Error("Auth database is unavailable.")
+      providersFromEnv({ database: ctx.database, log: ctx.log }, env)
+      await ctx.database.get("SELECT 1")
+      console.log("Authentication configuration is ready.")
+    })
+
+  const users = group
+    .command("users")
+    .description("Inspect authentication users")
+  users
+    .command("list")
+    .description("List provisioned authentication users")
+    .action(async () => {
+      if (!ctx.database) throw new Error("Auth database is unavailable.")
+      const rows = await ctx.database.all<{ name: string; email: string }>(
+        'SELECT name, email FROM "user" ORDER BY email',
+      )
+      for (const user of rows) console.log(`${user.email}\t${user.name}`)
+    })
+
+  const sessions = group
+    .command("sessions")
+    .description("Administer authentication sessions")
+  sessions
+    .command("revoke-all")
+    .description("Revoke every active session")
+    .action(async () => {
+      if (!ctx.database) throw new Error("Auth database is unavailable.")
+      const result = await ctx.database.run('DELETE FROM "session"')
+      console.log(`Revoked ${result.changes} sessions.`)
+    })
+}

package/components/client.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useState, type FormEvent } from "react"
+import { mountPathMXApps } from "@pathmx/react"
+import "./styles.css"
+
+type Status = "idle" | "pending" | "success" | "error"
+
+function SignIn(props: {
+  endpoint: string
+  emailLabel: string
+  submitLabel: string
+}) {
+  const [status, setStatus] = useState<Status>("idle")
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault()
+    setStatus("pending")
+    try {
+      const data = new FormData(event.currentTarget)
+      const email = data.get("email")
+      const response = await fetch(props.endpoint, {
+        method: "POST",
+        credentials: "same-origin",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          email: typeof email === "string" ? email : "",
+        }),
+      })
+      setStatus(response.ok ? "success" : "error")
+    } catch {
+      setStatus("error")
+    }
+  }
+  if (status === "success") {
+    return <p role="status">Check your email for a sign-in link.</p>
+  }
+  return (
+    <form onSubmit={submit}>
+      <label>
+        {props.emailLabel}
+        <input name="email" type="email" autoComplete="email" required />
+      </label>
+      <button type="submit" disabled={status === "pending"}>
+        {status === "pending" ? "Sending…" : props.submitLabel}
+      </button>
+      {status === "error" && (
+        <p className="pmx-auth__error" role="alert">
+          We couldn’t send the link. Please try again.
+        </p>
+      )}
+    </form>
+  )
+}
+
+function Confirm({ endpoint }: { endpoint: string }) {
+  const [status, setStatus] = useState<"pending" | "error">("pending")
+  useEffect(() => {
+    const token = new URLSearchParams(location.hash.slice(1)).get("token")
+    if (!token) {
+      setStatus("error")
+      return
+    }
+    history.replaceState(null, "", `${location.pathname}${location.search}`)
+    void fetch(endpoint, {
+      method: "POST",
+      credentials: "same-origin",
+      redirect: "manual",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token }),
+    }).then(
+      (response) => {
+        if (!response.ok && response.type !== "opaqueredirect") {
+          setStatus("error")
+          return
+        }
+        location.replace("/")
+      },
+      () => setStatus("error"),
+    )
+  }, [endpoint])
+  return (
+    <p role={status === "error" ? "alert" : "status"}>
+      {status === "error"
+        ? "This sign-in link is invalid or has expired."
+        : "Confirming your sign in…"}
+    </p>
+  )
+}
+
+function Session(props: {
+  authenticated: boolean
+  name?: string
+  home?: string
+  signIn?: string
+  signOut?: string
+}) {
+  if (!props.authenticated) {
+    return <a href={props.signIn ?? "/sign-in"}>Sign in</a>
+  }
+  return (
+    <>
+      <a href={props.home ?? "/"}>{props.name}</a>
+      <form method="post" action={props.signOut ?? "/api/auth/sign-out"}>
+        <button type="submit">Sign out</button>
+      </form>
+    </>
+  )
+}
+
+mountPathMXApps('[data-component="auth:sign-in"]', (element) => (
+  <SignIn
+    endpoint={element.dataset.endpoint ?? "/api/auth/magic-link/request"}
+    emailLabel={element.dataset.emailLabel ?? "Email address"}
+    submitLabel={element.dataset.submitLabel ?? "Email me a sign-in link"}
+  />
+))
+
+mountPathMXApps('[data-component="auth:confirm"]', (element) => (
+  <Confirm
+    endpoint={element.dataset.endpoint ?? "/api/auth/magic-link/confirm"}
+  />
+))
+
+mountPathMXApps('[data-component="auth:session"]', (element) => (
+  <Session
+    authenticated={element.dataset.authenticated === "true"}
+    name={element.dataset.name}
+    home={element.dataset.home}
+    signIn={element.dataset.signIn}
+    signOut={element.dataset.signOut}
+  />
+))

package/components/index.ts

@@ -0,0 +1,77 @@
+import { defineAppComponent, html } from "@pathmx/core"
+import { authRoutes } from "../providers/magic-link.ts"
+
+const client = new URL("./client.tsx", import.meta.url)
+
+export const SignIn = defineAppComponent({
+  tag: "auth:sign-in",
+  client,
+  render(use) {
+    return html`<div
+      class="pmx-auth"
+      data-component="auth:sign-in"
+      data-endpoint="${authRoutes.requestLink}"
+      data-email-label="${use.props["email-label"] ?? "Email address"}"
+      data-submit-label="${use.props["submit-label"] ?? "Email me a sign-in link"}"
+    >
+      <form method="post" action="${authRoutes.requestLink}">
+        <label>
+          ${use.props["email-label"] ?? "Email address"}
+          <input name="email" type="email" autocomplete="email" required />
+        </label>
+        <button type="submit">
+          ${use.props["submit-label"] ?? "Email me a sign-in link"}
+        </button>
+      </form>
+    </div>`
+  },
+})
+
+export const Confirm = defineAppComponent({
+  tag: "auth:confirm",
+  client,
+  render() {
+    return html`<div
+      class="pmx-auth"
+      data-component="auth:confirm"
+      data-endpoint="${authRoutes.confirm}"
+    >
+      <p role="status">Confirming your sign in…</p>
+    </div>`
+  },
+})
+
+export const Session = defineAppComponent({
+  tag: "auth:session",
+  client,
+  render(_use, _compiled, ctx) {
+    if (ctx.session.type === "anonymous") {
+      return html`<div
+        class="pmx-auth pmx-auth--session"
+        data-component="auth:session"
+        data-authenticated="false"
+        data-sign-in="${ctx.session.signIn?.href ?? "/sign-in"}"
+      >
+        <a href="${ctx.session.signIn?.href ?? "/sign-in"}">Sign in</a>
+      </div>`
+    }
+    return html`<div
+      class="pmx-auth pmx-auth--session"
+      data-component="auth:session"
+      data-authenticated="true"
+      data-name="${ctx.session.actor.profile.name}"
+      data-home="${ctx.session.actor.home}"
+      data-sign-out="${ctx.session.signOut?.href ?? authRoutes.signOut}"
+    >
+      <a href="${ctx.session.actor.home}">${ctx.session.actor.profile.name}</a>
+      <form
+        method="post"
+        action="${ctx.session.signOut?.href ?? authRoutes.signOut}"
+      >
+        <button type="submit">Sign out</button>
+      </form>
+    </div>`
+  },
+})
+
+export const authComponents = Object.freeze([SignIn, Confirm, Session])

package/components/styles.css

@@ -0,0 +1,62 @@
+:where(.pmx-auth) {
+  --auth-accent: var(--pmx-color-accent, #4f46e5);
+  --auth-border: var(--pmx-color-border, #d4d4d8);
+  --auth-surface: var(--pmx-color-surface, Canvas);
+  display: grid;
+  gap: 0.75rem;
+  max-width: 30rem;
+  padding: 1rem;
+  border: 1px solid var(--auth-border);
+  border-radius: var(--pmx-radius-xl, 0.75rem);
+  background: var(--auth-surface);
+}
+
+:where(.pmx-auth form, .pmx-auth label) {
+  display: grid;
+  gap: 0.5rem;
+}
+
+:where(.pmx-auth input, .pmx-auth button) {
+  box-sizing: border-box;
+  min-height: 2.75rem;
+  padding: 0.625rem 0.75rem;
+  border: 1px solid var(--auth-border);
+  border-radius: var(--pmx-radius-md, 0.35rem);
+  color: var(--pmx-color-fg, CanvasText);
+  font: inherit;
+}
+
+:where(.pmx-auth input) {
+  background: var(--pmx-color-bg, Canvas);
+}
+
+:where(.pmx-auth button) {
+  cursor: pointer;
+  border-color: var(--auth-accent);
+  background: var(--auth-accent);
+  color: var(--pmx-color-bg, Canvas);
+}
+
+:where(.pmx-auth button:disabled) {
+  cursor: wait;
+  opacity: 0.65;
+}
+
+:where(.pmx-auth :focus-visible) {
+  outline: 2px solid var(--pmx-color-focus, var(--auth-accent));
+  outline-offset: 2px;
+}
+
+:where(.pmx-auth--session) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  max-width: none;
+  padding: 0;
+  border: 0;
+  background: transparent;
+}
+
+:where(.pmx-auth__error) {
+  color: var(--pmx-color-danger, #b91c1c);
+}

package/database.ts

@@ -0,0 +1,56 @@
+import type { PluginDatabase } from "@pathmx/core"
+
+export const authDatabase: PluginDatabase = Object.freeze({
+  migrations: [
+    {
+      id: "001-better-auth",
+      sql: `
+CREATE TABLE "user" (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "name" TEXT NOT NULL,
+  "email" TEXT NOT NULL UNIQUE,
+  "emailVerified" INTEGER NOT NULL,
+  "image" TEXT,
+  "createdAt" DATE NOT NULL,
+  "updatedAt" DATE NOT NULL
+);
+CREATE TABLE "session" (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "expiresAt" DATE NOT NULL,
+  "token" TEXT NOT NULL UNIQUE,
+  "createdAt" DATE NOT NULL,
+  "updatedAt" DATE NOT NULL,
+  "ipAddress" TEXT,
+  "userAgent" TEXT,
+  "userId" TEXT NOT NULL REFERENCES "user" ("id") ON DELETE CASCADE
+);
+CREATE TABLE "account" (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "accountId" TEXT NOT NULL,
+  "providerId" TEXT NOT NULL,
+  "userId" TEXT NOT NULL REFERENCES "user" ("id") ON DELETE CASCADE,
+  "accessToken" TEXT,
+  "refreshToken" TEXT,
+  "idToken" TEXT,
+  "accessTokenExpiresAt" DATE,
+  "refreshTokenExpiresAt" DATE,
+  "scope" TEXT,
+  "password" TEXT,
+  "createdAt" DATE NOT NULL,
+  "updatedAt" DATE NOT NULL
+);
+CREATE TABLE "verification" (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "identifier" TEXT NOT NULL,
+  "value" TEXT NOT NULL,
+  "expiresAt" DATE NOT NULL,
+  "createdAt" DATE NOT NULL,
+  "updatedAt" DATE NOT NULL
+);
+CREATE INDEX "session_userId_idx" ON "session" ("userId");
+CREATE INDEX "account_userId_idx" ON "account" ("userId");
+CREATE INDEX "verification_identifier_idx" ON "verification" ("identifier");
+`,
+    },
+  ],
+})