feat(cli,mcp): run402 auth scaffold-roles — role-table + requireRole gate generator (#422)

* feat(cli,mcp): run402 auth scaffold-roles — role-table + requireRole gate generator

Offline, deterministic generator (CLI subcommand + scaffold_roles MCP tool) that emits the conventional app_roles(user_id uuid, role text) migration, a matching requireRole deploy-spec gate snippet, and a first-operator service-role bootstrap INSERT. No project/network. Docs (cli/llms-cli.txt, SKILL.md) document auth.role() (@run402/functions 3.4.0) and the requireRole(x in allowed) vs auth.role() (branch-friendly read) distinction, plus the tenant-user-id (not wallet) keying. Implements the public-repo follow-ups for the improve-role-gate-ergonomics change. 339 CLI tests pass; new files typecheck clean (pre-existing unrelated tsc error in src/tools/jobs.ts re: Jobs.downloadArtifact SDK lag).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test: register scaffold_roles + auth:scaffold-roles in the sync surface map

Adds the auth_scaffold_roles capability to SURFACE (mcp/cli/openclaw) and SDK_BY_CAPABILITY (null — offline generator, no SDK method) so the MCP/CLI/OpenClaw inventory guards pass. The remaining sync.test.ts failure (SDK mapping → real method) is the pre-existing jobs.ts downloadArtifact SDK-lag, unrelated to this change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: MajorTal

SKILL.md

@@ -411,6 +411,8 @@ Rules and footnotes:
 - **Deploy-time validation.** Missing table or column at activation fails with `DEPLOY_INVALID_ROLE_GATE` (422) *before* flipping the live release.
 - **Cache TTL.** Default 60s, max 600s. A demoted user keeps the cached role until expiry — for instant revocation, set `cacheTtl: 0` (fresh lookup per request).
 - **Gate applies to both** routed (`/your/route`) and direct (`POST /functions/v1/:name` with API key) invocation. Direct invocation still requires the API key at the edge; the gate runs after API-key auth, against the user JWT.
+- **Reading the role (`@run402/functions` 3.4.0+).** `await auth.requireRole("operator")` returns `{ user, role }`; it throws a distinct `RoleGateNotConfiguredError` (500) when no `requireRole` gate is declared (vs `InsufficientRoleError` 403 for a real mismatch). For multi-role gates, `await auth.role()` returns the resolved role (or `null`, never throws) so you branch instead of re-asserting.
+- **Scaffold + first-operator bootstrap.** `run402 auth scaffold-roles --roles operator` emits the `app_roles` migration, the `requireRole` snippet, and a service-role `INSERT` for the FIRST operator — the table starts empty, so the first grant bypasses RLS with the service key. The gate keys on the tenant user id (JWT `sub`), not a wallet.
 
 ### Astro SSR runtime + ISR cache (v1.52+)
 

cli-help.test.mjs

@@ -101,6 +101,7 @@ const MATRIX = {
       "magic-link", "verify", "create-user", "invite-user", "set-password", "settings",
       "passkey-register-options", "passkey-register-verify", "passkey-login-options",
       "passkey-login-verify", "passkeys", "delete-passkey", "providers",
+      "scaffold-roles",
     ],
   },
   "sender-domain": {

cli/lib/auth.mjs

@@ -48,13 +48,17 @@ Subcommands:
   providers [--project <id>]
     List available auth providers for the project.
 
+  scaffold-roles [--table <name>] [--user-col <col>] [--role-col <col>] [--roles <csv>] [--cache-ttl <secs>]
+    Generate a role-table migration + requireRole gate snippet (offline; no project or network).
+
 Examples:
   run402 auth magic-link --email user@example.com --redirect https://myapp.run402.com/cb
   run402 auth verify --token abc123def456
   run402 auth invite-user --email admin@example.com --redirect https://myapp.run402.com/cb --admin true
   run402 auth set-password --token eyJ... --new "new-pass" --current "old-pass"
   run402 auth settings --preferred passkey --require-admin-passkey true
   run402 auth providers
+  run402 auth scaffold-roles --roles operator,editor | jq -r .migration
 `;
 
 const SUB_HELP = {
@@ -233,6 +237,31 @@ Options:
 Examples:
   run402 auth providers
   run402 auth providers --project prj_abc123
+`,
+  "scaffold-roles": `run402 auth scaffold-roles — Generate a role-table migration + requireRole gate snippet
+
+Usage:
+  run402 auth scaffold-roles [options]
+
+Generates (offline — no project or network):
+  - migration: idempotent CREATE TABLE for the conventional role table
+  - gate:      a requireRole deploy-spec snippet pointing at it
+  - bootstrap: a service-role INSERT to grant the first role
+
+Options:
+  --table <name>      Role table name (default: app_roles)
+  --user-col <col>    User-id column (default: user_id) — matches the tenant user id (JWT 'sub')
+  --role-col <col>    Role column (default: role)
+  --roles <csv>       Allowed roles, comma-separated (default: operator)
+  --cache-ttl <secs>  Role-lookup cache seconds, 0-600 (default: 60; 0 = instant revocation)
+
+Output is a single JSON object; pipe through jq to extract a part:
+  run402 auth scaffold-roles --roles operator | jq -r .migration
+  run402 auth scaffold-roles --roles operator,editor | jq .gate
+
+Notes:
+  requireRole(x) requires x in 'allowed'; for multi-role gates read auth.role() and branch.
+  The gate accepts any table/columns — this is just the blessed default.
 `,
 };
 
@@ -289,6 +318,10 @@ const AUTH_FLAGS = {
     known: ["--project", "--help", "-h"],
     values: ["--project"],
   },
+  "scaffold-roles": {
+    known: ["--table", "--user-col", "--role-col", "--roles", "--cache-ttl", "--help", "-h"],
+    values: ["--table", "--user-col", "--role-col", "--roles", "--cache-ttl"],
+  },
 };
 
 function parseFlag(args, flag) {
@@ -629,6 +662,74 @@ async function providers(args) {
   }
 }
 
+const ROLE_SCAFFOLD_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function scaffoldIdent(args, flag, def) {
+  const value = parseFlag(args, flag) || def;
+  if (!ROLE_SCAFFOLD_IDENT.test(value)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${flag} must be an unquoted SQL identifier matching ${ROLE_SCAFFOLD_IDENT.source}`,
+    });
+  }
+  return value;
+}
+
+// Pure, offline generator — no SDK / network / project. Emits the conventional
+// role-table migration, the matching requireRole gate snippet, and a
+// first-operator bootstrap. (Keep in sync with the MCP `scaffold_roles` tool in
+// src/tools/scaffold-roles.ts — same artifacts, different presentation.)
+function scaffoldRoles(args) {
+  const table = scaffoldIdent(args, "--table", "app_roles");
+  const userCol = scaffoldIdent(args, "--user-col", "user_id");
+  const roleCol = scaffoldIdent(args, "--role-col", "role");
+  const allowed = (parseFlag(args, "--roles") || "operator")
+    .split(",")
+    .map((r) => r.trim())
+    .filter(Boolean);
+  if (allowed.length === 0) {
+    fail({ code: "BAD_FLAG", message: "--roles must list at least one role (comma-separated)" });
+  }
+  let cacheTtl = 60;
+  const ttlRaw = parseFlag(args, "--cache-ttl");
+  if (ttlRaw !== null) {
+    const n = Number(ttlRaw);
+    if (!Number.isInteger(n) || n < 0 || n > 600) {
+      fail({ code: "BAD_FLAG", message: "--cache-ttl must be an integer in [0, 600]" });
+    }
+    cacheTtl = n;
+  }
+  const firstRole = allowed[0];
+  const migration = `-- Conventional Run402 role table: single role per user, keyed on the tenant user id.
+CREATE TABLE IF NOT EXISTS ${table} (
+  ${userCol} uuid NOT NULL,
+  ${roleCol} text NOT NULL,
+  PRIMARY KEY (${userCol})
+);`;
+  const gate = { table, idColumn: userCol, roleColumn: roleCol, allowed, cacheTtl };
+  const bootstrap = `-- First-operator bootstrap: run ONCE with the SERVICE key (bypasses RLS).
+-- Replace <FIRST_OPERATOR_USER_ID> with the tenant user id (internal.users.id /
+-- the JWT 'sub') of the first '${firstRole}' — NOT a wallet address.
+INSERT INTO ${table} (${userCol}, ${roleCol})
+VALUES ('<FIRST_OPERATOR_USER_ID>', '${firstRole}')
+ON CONFLICT (${userCol}) DO NOTHING;`;
+  console.log(
+    JSON.stringify({
+      table,
+      migration,
+      gate,
+      bootstrap,
+      notes: [
+        `Put 'gate' on the function's requireRole deploy-spec field, then call auth.requireRole('${firstRole}') in the function — or auth.role() to branch when 'allowed' has multiple roles.`,
+        "requireRole(x) requires x in 'allowed'; for multi-role gates read auth.role() and branch instead of re-asserting.",
+        "cacheTtl is the role-lookup cache in seconds; set it to 0 for instant revocation (fresh DB read per request).",
+        "The gate keys on the tenant USER id (internal.users.id / JWT 'sub'), NOT a wallet address.",
+        `The gate accepts any table/columns — '${table}'(${userCol},${roleCol}) is the blessed default; point requireRole at your own table if you already have one.`,
+      ],
+    }),
+  );
+}
+
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") { console.log(HELP); process.exit(0); }
   args = normalizeArgv(args);
@@ -654,6 +755,7 @@ export async function run(sub, args) {
     case "passkeys": await passkeys(args); break;
     case "delete-passkey": await deletePasskey(args); break;
     case "providers": await providers(args); break;
+    case "scaffold-roles": scaffoldRoles(args); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

cli/llms-cli.txt

@@ -639,6 +639,10 @@ Validation rules:
 - Empty `allowed`. Rejected with `INVALID_SPEC` — set the role values explicitly.
 - Deploy-time validation. Missing table or column at activation fails with `DEPLOY_INVALID_ROLE_GATE` (HTTP 422) *before* flipping the live release. `run402 deploy apply` surfaces the structured envelope on stderr.
 
+Reading the role in-function (`@run402/functions` 3.4.0+). `await auth.requireRole("operator")` returns `{ user, role }` or throws — and throws a *distinct* `RoleGateNotConfiguredError` (server-class 500) when the function declares no `requireRole` gate, vs `InsufficientRoleError` (403) for a real role mismatch. When a gate allows more than one role, read `await auth.role()` (returns the resolved role or `null`, never throws) and branch instead of re-asserting — `requireRole(x)` requires `x` to be one of `allowed`.
+
+Scaffolding + first-operator bootstrap. `run402 auth scaffold-roles --roles operator` emits the conventional `app_roles(user_id uuid, role text)` migration, the matching `requireRole` snippet, and a service-role `INSERT` to grant the FIRST role — the table starts empty, so the first grant must bypass RLS with the service key. The gate keys on the tenant user id (`internal.users.id` / JWT `sub`), NOT a wallet. The conventional table is a default — `requireRole` accepts any `(table, idColumn, roleColumn)`.
+
 The gate applies to both routed (`/your/route`) and direct (`POST /functions/v1/:name` with API key plus user JWT) invocation. Direct invocation still requires the API key at the edge; the gate runs after API-key auth, against the user JWT.
 
 Binary files (images, fonts, PDFs): Set `"encoding": "base64"` and provide base64-encoded data. MIME types are auto-detected from the file extension (`.png` → `image/png`, `.woff2` → `font/woff2`, etc.). Text files use `"encoding": "utf-8"` (the default — can be omitted).
@@ -1301,6 +1305,7 @@ Manage project user authentication: magic links, trusted invites, passwords, pas
 - `run402 auth passkeys --token <bearer> [--project <id>]` — list authenticated user's passkeys
 - `run402 auth delete-passkey --token <bearer> --id <passkey_id> [--project <id>]` — delete one passkey
 - `run402 auth providers [--project <id>]` — list available auth providers
+- `run402 auth scaffold-roles [--table <name>] [--user-col <col>] [--role-col <col>] [--roles <csv>] [--cache-ttl <secs>]` — offline generator: emits a role-table migration + `requireRole` gate snippet + first-operator bootstrap (JSON out; no project/network). Pipe through `jq` (e.g. `| jq -r .migration`).
 
 Magic link flow: request → user clicks email link → frontend extracts token → verify → authenticated. Token expires in 15 minutes, single-use. Rate limited: 5 per email/hour, plus per-project limits by tier.
 

src/index.ts

@@ -160,6 +160,7 @@ import { requestMagicLinkSchema, handleRequestMagicLink } from "./tools/request-
 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";
+import { scaffoldRolesSchema, handleScaffoldRoles } from "./tools/scaffold-roles.js";
 import {
   createAuthUserSchema,
   handleCreateAuthUser,
@@ -1146,6 +1147,13 @@ server.tool(
   async (args) => handleAuthSettings(args),
 );
 
+server.tool(
+  "scaffold_roles",
+  "Generate a role-table migration + requireRole gate snippet + first-operator bootstrap for Run402 function role gates. Offline and deterministic (no project or network). Inputs: table, user_col, role_col, roles[], cache_ttl.",
+  scaffoldRolesSchema,
+  async (args) => handleScaffoldRoles(args),
+);
+
 server.tool(
   "passkey_register_options",
   "Create WebAuthn passkey registration options for the authenticated user.",

src/tools/scaffold-roles.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+// Pure, offline generator — no SDK / network / project. Emits the conventional
+// role-table migration, the matching requireRole gate snippet, and a
+// first-operator bootstrap. (Keep in sync with the CLI `auth scaffold-roles`
+// command in cli/lib/auth.mjs — same artifacts, different presentation.)
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export const scaffoldRolesSchema = {
+  table: z
+    .string()
+    .regex(IDENT)
+    .optional()
+    .describe("Role table name (unquoted SQL identifier). Default: app_roles."),
+  user_col: z
+    .string()
+    .regex(IDENT)
+    .optional()
+    .describe("User-id column — matches the tenant user id (internal.users.id / JWT 'sub'). Default: user_id."),
+  role_col: z
+    .string()
+    .regex(IDENT)
+    .optional()
+    .describe("Role column. Default: role."),
+  roles: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Allowed roles. Default: ["operator"].'),
+  cache_ttl: z
+    .number()
+    .int()
+    .min(0)
+    .max(600)
+    .optional()
+    .describe("Role-lookup cache seconds (0-600). Default: 60. 0 = instant revocation (fresh DB read per request)."),
+};
+
+export function handleScaffoldRoles(args: {
+  table?: string;
+  user_col?: string;
+  role_col?: string;
+  roles?: string[];
+  cache_ttl?: number;
+}): { content: Array<{ type: "text"; text: string }>; isError?: boolean } {
+  const table = args.table ?? "app_roles";
+  const userCol = args.user_col ?? "user_id";
+  const roleCol = args.role_col ?? "role";
+  const allowed = (args.roles && args.roles.length > 0 ? args.roles : ["operator"])
+    .map((r) => r.trim())
+    .filter(Boolean);
+  if (allowed.length === 0) {
+    return { isError: true, content: [{ type: "text", text: "roles must contain at least one non-empty role" }] };
+  }
+  const cacheTtl = args.cache_ttl ?? 60;
+  const firstRole = allowed[0];
+
+  const migration = `-- Conventional Run402 role table: single role per user, keyed on the tenant user id.
+CREATE TABLE IF NOT EXISTS ${table} (
+  ${userCol} uuid NOT NULL,
+  ${roleCol} text NOT NULL,
+  PRIMARY KEY (${userCol})
+);`;
+  const gate = { table, idColumn: userCol, roleColumn: roleCol, allowed, cacheTtl };
+  const bootstrap = `-- First-operator bootstrap: run ONCE with the SERVICE key (bypasses RLS).
+-- Replace <FIRST_OPERATOR_USER_ID> with the tenant user id (internal.users.id /
+-- the JWT 'sub') of the first '${firstRole}' — NOT a wallet address.
+INSERT INTO ${table} (${userCol}, ${roleCol})
+VALUES ('<FIRST_OPERATOR_USER_ID>', '${firstRole}')
+ON CONFLICT (${userCol}) DO NOTHING;`;
+
+  const text = [
+    "## Role-gate scaffold",
+    "",
+    "**1. Migration** (apply once, or via your deploy spec's database migrations):",
+    "```sql",
+    migration,
+    "```",
+    "",
+    "**2. `requireRole` gate** — put this on the function in your deploy spec (`spec.functions[].requireRole`):",
+    "```json",
+    JSON.stringify(gate, null, 2),
+    "```",
+    "",
+    `**3. In the function:** \`await auth.requireRole(${JSON.stringify(firstRole)})\` — or \`await auth.role()\` to branch when \`allowed\` has multiple roles.`,
+    "",
+    "**4. First-operator bootstrap** (the table starts empty — grant the first role once with the service key):",
+    "```sql",
+    bootstrap,
+    "```",
+    "",
+    "Notes:",
+    "- `requireRole(x)` requires `x` to be in `allowed`; for multi-role gates read `auth.role()` and branch instead of re-asserting.",
+    "- `cacheTtl` is the role-lookup cache in seconds; set it to `0` for instant revocation (fresh DB read per request).",
+    "- The gate keys on the tenant **user id** (`internal.users.id` / JWT `sub`), NOT a wallet address.",
+    `- The gate accepts any table/columns — \`${table}(${userCol}, ${roleCol})\` is the blessed default; point \`requireRole\` at your own table if you already have one.`,
+  ].join("\n");
+
+  return { content: [{ type: "text", text }] };
+}

sync.test.ts

@@ -400,6 +400,7 @@ const SURFACE: Capability[] = [
   { id: "list_passkeys",            endpoint: "GET /auth/v1/passkeys",                   mcp: "list_passkeys",            cli: "auth:passkeys",                 openclaw: "auth:passkeys" },
   { id: "delete_passkey",           endpoint: "DELETE /auth/v1/passkeys/:id",             mcp: "delete_passkey",           cli: "auth:delete-passkey",           openclaw: "auth:delete-passkey" },
   { id: "auth_providers",    endpoint: "GET /auth/v1/providers",              mcp: null,                 cli: "auth:providers",     openclaw: "auth:providers" },
+  { id: "auth_scaffold_roles", endpoint: "(local)",                           mcp: "scaffold_roles",     cli: "auth:scaffold-roles", openclaw: "auth:scaffold-roles" },
 
   // ── Custom sender domains ─────────────────────────────────────────────
   { id: "register_sender_domain", endpoint: "POST /email/v1/domains",    mcp: "register_sender_domain", cli: "sender-domain:register", openclaw: "sender-domain:register" },
@@ -659,6 +660,7 @@ const SDK_BY_CAPABILITY: Record<string, string | null> = {
   list_passkeys: "auth.listPasskeys",
   delete_passkey: "auth.deletePasskey",
   auth_providers: "auth.providers",
+  auth_scaffold_roles: null, // offline CLI/MCP generator — no SDK method
 
   // Sender domains
   register_sender_domain: "senderDomain.register",