feat: magic link auth tools — request, verify, set-password, auth-settings

- 4 new MCP tools: request_magic_link, verify_magic_link, set_user_password, auth_settings
- CLI: run402 auth (magic-link, verify, set-password, settings, providers)
- OpenClaw shim: openclaw/scripts/auth.mjs
- sync.test.ts: updated SURFACE + module lists for parity

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: volinskey

cli/cli.mjs

@@ -37,6 +37,7 @@ Commands:
   image       Generate AI images via x402 or MPP micropayments
   email       Send template-based emails from your project
   message     Send messages to Run402 developers
+  auth        Manage project user authentication (magic link, passwords, settings)
   agent       Manage agent identity (contact info)
 
 Run 'run402 <command> --help' for detailed usage of each command.
@@ -159,6 +160,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "auth": {
+    const { run } = await import("./lib/auth.mjs");
+    await run(sub, rest);
+    break;
+  }
   default:
     console.error(`Unknown command: ${cmd}\n`);
     console.log(HELP);

cli/lib/auth.mjs

@@ -0,0 +1,153 @@
+import { findProject, resolveProjectId, API } from "./config.mjs";
+
+const HELP = `run402 auth — Manage project user authentication
+
+Usage:
+  run402 auth <subcommand> [args...]
+
+Subcommands:
+  magic-link --email <addr> --redirect <url> [--project <id>]
+    Send a passwordless login link to the given email. Auto-creates user on first use.
+
+  verify --token <token> [--project <id>]
+    Exchange a magic link token for access_token + refresh_token.
+
+  set-password --token <bearer> --new <password> [--current <password>] [--project <id>]
+    Change, reset, or set a user's password. Requires the user's access_token.
+
+  settings --allow-password-set <true|false> [--project <id>]
+    Update project auth settings (requires service_key).
+
+  providers [--project <id>]
+    List available auth providers for the project.
+
+Examples:
+  run402 auth magic-link --email user@example.com --redirect https://myapp.run402.com/cb
+  run402 auth verify --token abc123def456
+  run402 auth set-password --token eyJ... --new "new-pass" --current "old-pass"
+  run402 auth settings --allow-password-set true
+  run402 auth providers
+`;
+
+function parseFlag(args, flag) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === flag && args[i + 1]) return args[i + 1];
+  }
+  return null;
+}
+
+async function magicLink(args) {
+  const email = parseFlag(args, "--email");
+  const redirect = parseFlag(args, "--redirect");
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  if (!email) { console.error(JSON.stringify({ status: "error", message: "Missing --email" })); process.exit(1); }
+  if (!redirect) { console.error(JSON.stringify({ status: "error", message: "Missing --redirect <url>" })); process.exit(1); }
+
+  const res = await fetch(`${API}/auth/v1/magic-link`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.anon_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ email, redirect_url: redirect }),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ status: "ok", ...data }));
+}
+
+async function verify(args) {
+  const token = parseFlag(args, "--token");
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  if (!token) { console.error(JSON.stringify({ status: "error", message: "Missing --token" })); process.exit(1); }
+
+  const res = await fetch(`${API}/auth/v1/token?grant_type=magic_link`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.anon_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ token }),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ status: "ok", ...data }));
+}
+
+async function setPassword(args) {
+  const accessToken = parseFlag(args, "--token");
+  const newPassword = parseFlag(args, "--new");
+  const currentPassword = parseFlag(args, "--current");
+
+  if (!accessToken) { console.error(JSON.stringify({ status: "error", message: "Missing --token <bearer_token>" })); process.exit(1); }
+  if (!newPassword) { console.error(JSON.stringify({ status: "error", message: "Missing --new <password>" })); process.exit(1); }
+
+  const body = { new_password: newPassword };
+  if (currentPassword) body.current_password = currentPassword;
+
+  const res = await fetch(`${API}/auth/v1/user/password`, {
+    method: "PUT",
+    headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ status: "ok", ...data }));
+}
+
+async function settings(args) {
+  const allowPasswordSet = parseFlag(args, "--allow-password-set");
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  if (allowPasswordSet === null) { console.error(JSON.stringify({ status: "error", message: "Missing --allow-password-set <true|false>" })); process.exit(1); }
+
+  const res = await fetch(`${API}/auth/v1/settings`, {
+    method: "PATCH",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ allow_password_set: allowPasswordSet === "true" }),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ status: "ok", ...data }));
+}
+
+async function providers(args) {
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
+
+  const res = await fetch(`${API}/auth/v1/providers`, {
+    headers: { "Authorization": `Bearer ${p.anon_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "magic-link": await magicLink(args); break;
+    case "verify": await verify(args); break;
+    case "set-password": await setPassword(args); break;
+    case "settings": await settings(args); break;
+    case "providers": await providers(args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

openclaw/scripts/auth.mjs

@@ -0,0 +1 @@
+export { run } from "../../cli/lib/auth.mjs";

src/index.ts

@@ -74,6 +74,12 @@ import { listEmailsSchema, handleListEmails } from "./tools/list-emails.js";
 import { getEmailSchema, handleGetEmail } from "./tools/get-email.js";
 import { getMailboxSchema, handleGetMailbox } from "./tools/get-mailbox.js";
 
+// New tools — magic link auth
+import { requestMagicLinkSchema, handleRequestMagicLink } from "./tools/request-magic-link.js";
+import { verifyMagicLinkSchema, handleVerifyMagicLink } from "./tools/verify-magic-link.js";
+import { setUserPasswordSchema, handleSetUserPassword } from "./tools/set-user-password.js";
+import { authSettingsSchema, handleAuthSettings } from "./tools/auth-settings.js";
+
 // New tools — AI
 import { aiTranslateSchema, handleAiTranslate } from "./tools/ai-translate.js";
 import { aiModerateSchema, handleAiModerate } from "./tools/ai-moderate.js";
@@ -611,5 +617,35 @@ server.tool(
   async (args) => handleProjectKeys(args),
 );
 
+// --- Magic link auth ---
+
+server.tool(
+  "request_magic_link",
+  "Send a passwordless login email (magic link) to a project user. Auto-creates the user on first verification. Rate limited per email (5/hr) and per project (by tier).",
+  requestMagicLinkSchema,
+  async (args) => handleRequestMagicLink(args),
+);
+
+server.tool(
+  "verify_magic_link",
+  "Exchange a magic link token for access_token + refresh_token. Creates the user if they don't exist. Token is single-use and expires in 15 minutes.",
+  verifyMagicLinkSchema,
+  async (args) => handleVerifyMagicLink(args),
+);
+
+server.tool(
+  "set_user_password",
+  "Change, reset, or set a user's password. Change: provide current_password + new_password. Reset (via magic link login): just new_password. Set (passwordless user): requires allow_password_set=true on project.",
+  setUserPasswordSchema,
+  async (args) => handleSetUserPassword(args),
+);
+
+server.tool(
+  "auth_settings",
+  "Update project auth settings. Currently supports allow_password_set (boolean) to control whether passwordless users can add a password. Requires service_key.",
+  authSettingsSchema,
+  async (args) => handleAuthSettings(args),
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

src/tools/auth-settings.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { apiRequest } from "../client.js";
+import { getProject } from "../keystore.js";
+import { formatApiError, projectNotFound } from "../errors.js";
+
+export const authSettingsSchema = {
+  project_id: z.string().describe("The project ID"),
+  allow_password_set: z.boolean().describe("Allow passwordless users (magic link / OAuth) to set a password. Default: false."),
+};
+
+export async function handleAuthSettings(args: {
+  project_id: string;
+  allow_password_set: boolean;
+}): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const project = getProject(args.project_id);
+  if (!project) return projectNotFound(args.project_id);
+
+  const res = await apiRequest(`/auth/v1/settings`, {
+    method: "PATCH",
+    headers: { Authorization: `Bearer ${project.service_key}` },
+    body: {
+      allow_password_set: args.allow_password_set,
+    },
+  });
+
+  if (!res.ok) return formatApiError(res, "updating auth settings");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `## Auth Settings Updated\n\n- **allow_password_set:** ${args.allow_password_set}\n\n${args.allow_password_set ? "Passwordless users can now set a password via PUT /auth/v1/user/password." : "Passwordless users cannot set a password. They must use magic link or OAuth to sign in."}`,
+      },
+    ],
+  };
+}

src/tools/request-magic-link.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { apiRequest } from "../client.js";
+import { getProject } from "../keystore.js";
+import { formatApiError, projectNotFound } from "../errors.js";
+
+export const requestMagicLinkSchema = {
+  project_id: z.string().describe("The project ID"),
+  email: z.string().describe("Email address to send the magic link to"),
+  redirect_url: z.string().describe("URL to redirect to after clicking the magic link. Must be an allowed origin for this project (localhost, claimed subdomain, or custom domain)."),
+};
+
+export async function handleRequestMagicLink(args: {
+  project_id: string;
+  email: string;
+  redirect_url: string;
+}): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const project = getProject(args.project_id);
+  if (!project) return projectNotFound(args.project_id);
+
+  const res = await apiRequest(`/auth/v1/magic-link`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${project.anon_key}` },
+    body: {
+      email: args.email,
+      redirect_url: args.redirect_url,
+    },
+  });
+
+  if (!res.ok) return formatApiError(res, "requesting magic link");
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `## Magic Link Sent\n\n- **Email:** ${args.email}\n- **Redirect:** ${args.redirect_url}\n\nThe user will receive an email with a login link. The link expires in 15 minutes. If they don't have an account, one will be created automatically when they verify the link.`,
+      },
+    ],
+  };
+}

src/tools/set-user-password.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { apiRequest } from "../client.js";
+import { getProject } from "../keystore.js";
+import { formatApiError, projectNotFound } from "../errors.js";
+
+export const setUserPasswordSchema = {
+  project_id: z.string().describe("The project ID"),
+  access_token: z.string().describe("The user's access_token (Bearer token from login)"),
+  new_password: z.string().describe("The new password to set"),
+  current_password: z.string().optional().describe("Current password (required for password change, omit for reset via magic link or initial set)"),
+};
+
+export async function handleSetUserPassword(args: {
+  project_id: string;
+  access_token: string;
+  new_password: string;
+  current_password?: string;
+}): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const project = getProject(args.project_id);
+  if (!project) return projectNotFound(args.project_id);
+
+  const body: Record<string, string> = { new_password: args.new_password };
+  if (args.current_password) body.current_password = args.current_password;
+
+  const res = await apiRequest(`/auth/v1/user/password`, {
+    method: "PUT",
+    headers: { Authorization: `Bearer ${args.access_token}` },
+    body,
+  });
+
+  if (!res.ok) return formatApiError(res, "setting user password");
+
+  const mode = args.current_password ? "changed" : "set";
+  return {
+    content: [
+      {
+        type: "text",
+        text: `## Password ${mode.charAt(0).toUpperCase() + mode.slice(1)}\n\nPassword successfully ${mode} for the authenticated user. They can now log in with email + password.`,
+      },
+    ],
+  };
+}

src/tools/verify-magic-link.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { apiRequest } from "../client.js";
+import { getProject } from "../keystore.js";
+import { formatApiError, projectNotFound } from "../errors.js";
+
+export const verifyMagicLinkSchema = {
+  project_id: z.string().describe("The project ID"),
+  token: z.string().describe("The magic link token from the email link URL (?token=...)"),
+};
+
+export async function handleVerifyMagicLink(args: {
+  project_id: string;
+  token: string;
+}): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const project = getProject(args.project_id);
+  if (!project) return projectNotFound(args.project_id);
+
+  const res = await apiRequest(`/auth/v1/token?grant_type=magic_link`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${project.anon_key}` },
+    body: {
+      token: args.token,
+    },
+  });
+
+  if (!res.ok) return formatApiError(res, "verifying magic link");
+
+  const body = res.body as {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    user: { id: string; email: string };
+  };
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `## Magic Link Verified\n\n- **User ID:** \`${body.user.id}\`\n- **Email:** ${body.user.email}\n- **Access Token:** \`${body.access_token.slice(0, 20)}...\`\n- **Refresh Token:** \`${body.refresh_token.slice(0, 8)}...\`\n- **Expires In:** ${body.expires_in}s\n\nThe user is now authenticated. Use the access_token as a Bearer token for authenticated API calls.`,
+      },
+    ],
+  };
+}