cauthy-auth 0.15.0 → 0.17.0

package/README.md

@@ -101,7 +101,7 @@ import 'cauthy-auth/styles.css'
 
 Or draw them with your own `components` and `classNames`, and pass `unstyled`. The dashboard can start the look from your stylesheet (shadcn/ui and Tailwind, Stackmyth, or variables of your own); `npx cauthy-auth theme --css src/app/globals.css` reads it the same way from a terminal.
 
-Connect your application to Cauthy in one step, from Cauthy's dashboard ("Connect a System") or from a terminal. In the application's folder, `init` reads its framework (Next.js, TanStack Start, SvelteKit, Express, Hono, Fastify), makes the client, writes every variable to its env file, `CAUTHY_SECRET` included, and lays down the route and a sign-in page, never over a file that is there:
+Connect your application to Cauthy in one step, from Cauthy's dashboard ("Connect a System") or from a terminal. In the application's folder, `init` reads its framework (Next.js, TanStack Start, React Router or Remix, SvelteKit, Vite + React, Express, Hono, Fastify), makes the client, writes every variable to its env file, `CAUTHY_SECRET` included, and lays down the route and a sign-in page, never over a file that is there:
 
 ```bash
 npx cauthy-auth init
@@ -131,6 +131,13 @@ const auth = mcpAuth({ resource: 'https://mcp.example.com/mcp', scopes: ['books:
 app.use(auth.middleware())                    // or auth.protect(handler) for Request/Response
 ```
 
+When that server calls another of your servers for the person, it trades the agent's token for one for that server (token exchange, RFC 8693). Delegate the call and create the server's credentials in the dashboard first:
+
+```ts
+const auth = mcpAuth({ resource, clientId: process.env.CAUTHY_MCP_CLIENT_ID, clientSecret: process.env.CAUTHY_MCP_CLIENT_SECRET })
+const { accessToken } = await auth.exchange(req.agent, 'https://api.example.com', ['orders:read'])
+```
+
 The full guide is in Cauthy's documentation, under "Auth SDK".
 
 ## License

package/dist/cli.js

@@ -57,33 +57,41 @@ var import_node_path = require("path");
 var FRAMEWORK_NAMES = {
   next: "Next.js",
   "tanstack-start": "TanStack Start",
+  "react-router": "React Router",
   sveltekit: "SvelteKit",
   express: "Express",
   hono: "Hono",
-  fastify: "Fastify"
+  fastify: "Fastify",
+  "vite-react": "Vite + React"
 };
 function detect(pkg, has) {
   const deps = { ...pkg.devDependencies, ...pkg.dependencies };
-  const framework = deps.next ? "next" : deps["@tanstack/react-start"] ? "tanstack-start" : deps["@sveltejs/kit"] ? "sveltekit" : deps.hono ? "hono" : deps.fastify ? "fastify" : deps.express ? "express" : null;
-  const port = framework === "sveltekit" ? 5173 : 3e3;
+  const remix = Boolean(deps["@remix-run/react"] || deps["@remix-run/node"]);
+  const framework = deps.next ? "next" : deps["@tanstack/react-start"] ? "tanstack-start" : deps["@react-router/dev"] || remix ? "react-router" : deps["@sveltejs/kit"] ? "sveltekit" : deps.vite && deps.react && !deps.express && !deps.fastify ? "vite-react" : deps.hono ? "hono" : deps.fastify ? "fastify" : deps.express ? "express" : null;
+  const port = framework === "sveltekit" || framework === "vite-react" || framework === "react-router" && !(remix && !deps.vite) ? 5173 : 3e3;
   let root = has("src") ? "src" : "";
   let nextPagesOnly = false;
   if (framework === "next") {
     root = has("src/app") ? "src" : has("app") ? "" : has("src/pages") ? "src" : "";
     nextPagesOnly = !has("src/app") && !has("app");
   }
-  if (framework === "tanstack-start" || framework === "sveltekit") root = "src";
+  if (framework === "tanstack-start" || framework === "sveltekit" || framework === "vite-react") root = "src";
+  if (framework === "react-router") root = "app";
   const major = /(\d+)/.exec(deps.next ?? "");
+  const needs = ["cauthy-auth", ...framework === "vite-react" ? ["hono", "@hono/node-server"] : []];
   return {
     framework,
     ...nextPagesOnly ? { nextPagesOnly } : {},
     root,
+    ...framework === "react-router" && remix ? { remix } : {},
+    ...framework === "react-router" ? { fileRoutes: remix || Boolean(deps["@react-router/fs-routes"]) } : {},
     typescript: has("tsconfig.json") || Boolean(deps.typescript),
     esm: pkg.type === "module",
     ...framework === "next" && major ? { nextMajor: Number(major[1]) } : {},
     devUrl: `http://localhost:${port}`,
     system: systemName(pkg.name),
     installed: Boolean(deps["cauthy-auth"]),
+    toInstall: needs.filter((name) => !deps[name]),
     packageManager: has("pnpm-lock.yaml") ? "pnpm" : has("yarn.lock") ? "yarn" : has("bun.lockb") || has("bun.lock") ? "bun" : "npm"
   };
 }
@@ -100,9 +108,9 @@ function importPath(from, to) {
 function scaffold(d) {
   const ext = d.typescript ? "ts" : "js";
   const jsx = d.typescript ? "tsx" : "jsx";
-  const install = `${d.packageManager === "npm" ? "npm install" : `${d.packageManager} add`} cauthy-auth`;
+  const install = `${d.packageManager === "npm" ? "npm install" : `${d.packageManager} add`} ${d.toInstall.join(" ")}`;
   const dev = `${d.packageManager === "npm" ? "npm run" : d.packageManager} dev`;
-  const steps = d.installed ? [] : [`Install the package: ${install}`];
+  const steps = d.toInstall.length === 0 ? [] : [`Install the ${d.toInstall.length === 1 ? "package" : "packages"}: ${install}`];
   const files = [];
   const signIn = `${d.devUrl}/sign-in`;
   const hosted = `${d.devUrl}/api/auth/login`;
@@ -159,6 +167,49 @@ export const Route = createFileRoute('/sign-in')({ component: SignInPage })
       steps.push(`Start the application: ${dev}`, `Open ${signIn}`);
       return { files, steps, envFile: ".env", open: signIn };
     }
+    case "react-router": {
+      const authFile = join(d.root, `auth.server.${ext}`);
+      files.push({ path: authFile, content: PLAIN_AUTH });
+      const route = join(d.root, "routes", `api.auth.$.${ext}`);
+      const param = d.typescript ? "{ request }: { request: Request }" : "{ request }";
+      files.push({ path: route, content: `// Serves cauthy-auth: sign-in, return, session, sign-out.
+import { auth } from '${importPath(route, authFile)}'
+
+export const loader = (${param}) => auth.handler(request)
+export const action = (${param}) => auth.handler(request)
+` });
+      const page = join(d.root, "routes", `sign-in.${jsx}`);
+      files.push({ path: page, content: reactSignInPage("", "export default function SignInPage") });
+      if (!d.fileRoutes) {
+        const rel = (p) => import_node_path.posix.relative(d.root, p);
+        steps.push(`Add the two routes to ${join(d.root, `routes.${ext}`)}:
+
+  route('api/auth/*', '${rel(route)}'),
+  route('sign-in', '${rel(page)}'),`);
+      }
+      steps.push(`Start the application: ${dev}`, `Open ${signIn}`);
+      return { files, steps, envFile: ".env", open: signIn };
+    }
+    case "vite-react": {
+      const app = join("server", `app.${ext}`);
+      files.push({ path: join("server", `auth.${ext}`), content: PLAIN_AUTH });
+      files.push({ path: app, content: viteApp(d.typescript) });
+      files.push({ path: join("server", `index.${ext}`), content: VITE_SERVER });
+      files.push({ path: join("server", `vite.${ext}`), content: viteDev(d.typescript, `/${app}`) });
+      const page = join(d.root, `SignInPage.${jsx}`);
+      files.push({ path: page, content: reactSignInPage("", "export function SignInPage") });
+      const run = d.typescript ? "npx tsx server/index.ts" : "node server/index.js";
+      steps.push(
+        `Add the plugin that serves /api while developing to vite.config.${ext}:
+
+  import { cauthyDev } from './server/vite'
+  plugins: [react(), cauthyDev()]`,
+        `Start the application: ${dev}`,
+        `Open ${hosted}: Cauthy's sign-in page, and back. For a screen of your own, show <SignInPage /> from ${page} at /sign-in.`,
+        `In production, build the pages (vite build) and run ${run}: it serves them and /api.`
+      );
+      return { files, steps, envFile: ".env", open: hosted };
+    }
     case "sveltekit": {
       const authFile = join(d.root, "lib/server", `auth.${ext}`);
       files.push({ path: authFile, content: PLAIN_AUTH });
@@ -231,6 +282,62 @@ const { createCauthy } = require('cauthy-auth')
 
 exports.auth = createCauthy()
 `;
+function viteApp(ts) {
+  return `// The application's server side: cauthy-auth's routes under /api/auth, and
+// c.get('session') on every other /api request. While developing it runs
+// inside Vite (server/vite); in production server/index serves it with the
+// built pages.
+import { Hono } from 'hono'
+import { cauthyHono, requireSession${ts ? ", type CauthyVariables" : ""} } from 'cauthy-auth/hono'
+import { auth } from './auth.js'
+
+export const app = new Hono${ts ? "<{ Variables: CauthyVariables }>" : ""}()
+app.use('/api/*', cauthyHono(auth))
+
+// An API only a signed-in person may call: a 401 for anybody else.
+app.get('/api/me', requireSession, (c) => c.json(c.get('session')${ts ? "!" : ""}.user))
+`;
+}
+var VITE_SERVER = `// The application in production: the pages Vite built, and the API.
+import { serve } from '@hono/node-server'
+import { serveStatic } from '@hono/node-server/serve-static'
+import { app } from './app.js'
+
+app.use('/*', serveStatic({ root: './dist' }))
+// Any other path is a page of the single-page app.
+app.get('*', serveStatic({ path: './dist/index.html' }))
+
+const port = Number(process.env.PORT ?? 3000)
+serve({ fetch: app.fetch, port }, () => console.log(\`http://localhost:\${port}\`))
+`;
+function viteDev(ts, app) {
+  return `// While developing, Vite serves the pages and hands /api to the server's
+// app, on the same address: no proxy, and Cauthy sends people back to the
+// address the browser is on.
+//
+//   import { cauthyDev } from './server/vite'
+//   plugins: [react(), cauthyDev()]
+import { getRequestListener } from '@hono/node-server'
+import { loadEnv${ts ? ", type Plugin" : ""} } from 'vite'
+
+export function cauthyDev()${ts ? ": Plugin" : ""} {
+  return {
+    name: 'cauthy-dev',
+    configureServer(server) {
+      // The variables in the env file, which createCauthy() reads from the environment.
+      Object.assign(process.env, loadEnv(server.config.mode, server.config.envDir || server.config.root, 'CAUTHY_'))
+      server.middlewares.use((req, res, next) => {
+        if (!req.url?.startsWith('/api/')) return next()
+        // Loaded through Vite: a change to the server's files applies on the next request.
+        server.ssrLoadModule('${app}')
+          .then(({ app }) => getRequestListener(app.fetch)(req, res))
+          .catch(next)
+      })
+    },
+  }
+}
+`;
+}
 function reactSignInPage(head, declaration, tail = "") {
   return `${head}// The application's own sign-in page. <SignIn /> is the ready-made form: the
 // workspace's providers, passkeys, the second step and a sign-in link, drawn
@@ -912,9 +1019,10 @@ var INIT_HELP = `cauthy-auth init [options]
 
 Connects an application to Cauthy and leaves signing in working. Run it in
 the application's folder: it reads which framework the application is made
-with (Next.js, TanStack Start, SvelteKit, Express, Hono, Fastify), makes its
-client in Cauthy, writes the variables to its env file, and lays down the
-route and a sign-in page. A file that is already there is never written over.
+with (Next.js, TanStack Start, React Router or Remix, SvelteKit, Vite + React,
+Express, Hono, Fastify), makes its client in Cauthy, writes the variables to
+its env file, and lays down the route and a sign-in page. A file that is
+already there is never written over.
 
   --system <name>         The system's name: lowercase letters, digits, - or _.
                           Default: the package's name.
@@ -976,7 +1084,7 @@ ${INIT_HELP}`);
   const system = given["--system"] ?? found?.system;
   const appUrl = given["--app-url"] ?? found?.devUrl;
   if (!system || !appUrl) fail("no package.json here: give --system and --app-url\n\n" + INIT_HELP);
-  if (found?.framework) process.stdout.write(`Found ${FRAMEWORK_NAMES[found.framework]}.
+  if (found?.framework) process.stdout.write(`Found ${found.remix ? "Remix" : FRAMEWORK_NAMES[found.framework]}.
 `);
   const target = given["--write"] ?? plan?.envFile;
   let had = "";

package/dist/client.d.mts

@@ -319,10 +319,19 @@ interface AuthClient {
             sentTo: string;
             channel: string;
         }>>;
-        /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
+        /**
+         * Mails a link (and a code) that signs the person in. The answer is the
+         * same whether or not the address has an account. `create`: an address
+         * with no account gets one when the link or code is used, if the
+         * workspace accepts new accounts — one screen signs people in and up.
+         * `returnTo` (a path of this site) travels in the link: the page it opens
+         * gets it as `?return_to=`, and `emailCode` answers it.
+         */
         magicLink(form: {
             email: string;
             captchaToken?: string;
+            create?: boolean;
+            returnTo?: string;
         }): Promise<AuthResult<'sent'>>;
         /** Signs in with the token the mailed link opened the page with (`ml_token`). */
         magicLinkVerify(form: {
@@ -335,6 +344,7 @@ interface AuthClient {
             code: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
+            returnTo?: string;
         }>>;
         /**
          * Signs in with a passkey, on this page: the browser asks the person for

package/dist/client.d.ts

@@ -319,10 +319,19 @@ interface AuthClient {
             sentTo: string;
             channel: string;
         }>>;
-        /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
+        /**
+         * Mails a link (and a code) that signs the person in. The answer is the
+         * same whether or not the address has an account. `create`: an address
+         * with no account gets one when the link or code is used, if the
+         * workspace accepts new accounts — one screen signs people in and up.
+         * `returnTo` (a path of this site) travels in the link: the page it opens
+         * gets it as `?return_to=`, and `emailCode` answers it.
+         */
         magicLink(form: {
             email: string;
             captchaToken?: string;
+            create?: boolean;
+            returnTo?: string;
         }): Promise<AuthResult<'sent'>>;
         /** Signs in with the token the mailed link opened the page with (`ml_token`). */
         magicLinkVerify(form: {
@@ -335,6 +344,7 @@ interface AuthClient {
             code: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
+            returnTo?: string;
         }>>;
         /**
          * Signs in with a passkey, on this page: the browser asks the person for

package/dist/client.js

@@ -379,7 +379,7 @@ function createAuthClient(options = {}) {
       mfa: (f) => post("/sign-in/mfa", { code: f.code }, checkCode(f.code)),
       mfaMethods: () => post("/sign-in/mfa/methods", {}, null),
       mfaSendCode: () => post("/sign-in/mfa/send", {}, null),
-      magicLink: (f) => post("/sign-in/magic-link", { email: f.email }, checkEmail(f.email), f.captchaToken),
+      magicLink: (f) => post("/sign-in/magic-link", { email: f.email, ...f.create ? { create: true } : {}, ...f.returnTo ? { returnTo: f.returnTo } : {} }, checkEmail(f.email), f.captchaToken),
       magicLinkVerify: (f) => post("/sign-in/magic-link/verify", { token: f.token }, null),
       emailCode: (f) => post("/sign-in/email-code", { code: f.code }, checkCode(f.code)),
       passkeyUrl,