Add promote_user and demote_user tools (MCP, CLI, OpenClaw)

New admin tools to manage the project_admin role. promote_user sets
is_admin=true, demote_user sets is_admin=false — both by email,
using service_key auth. Closes #18.

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

Author: MajorTal

cli/lib/projects.mjs

@@ -20,6 +20,8 @@ Subcommands:
   rls   <id> <template> <tables_json>     Apply Row-Level Security policies
   delete <id>                             Delete a project and remove it from local state
   pin   <id>                              Pin a project (prevents expiry/GC)
+  promote-user <id> <email>               Promote a user to project_admin role
+  demote-user  <id> <email>               Demote a user from project_admin role
 
 Examples:
   run402 projects quote
@@ -190,6 +192,32 @@ async function pin(projectId) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+async function promoteUser(projectId, email) {
+  if (!email) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 projects promote-user <project_id> <email>" })); process.exit(1); }
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/projects/v1/admin/${projectId}/promote-user`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  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));
+}
+
+async function demoteUser(projectId, email) {
+  if (!email) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 projects demote-user <project_id> <email>" })); process.exit(1); }
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/projects/v1/admin/${projectId}/demote-user`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  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));
+}
+
 async function deleteProject(projectId) {
   const p = findProject(projectId);
   const res = await fetch(`${API}/projects/v1/${projectId}`, { method: "DELETE", headers: { "Authorization": `Bearer ${p.service_key}` } });
@@ -220,7 +248,9 @@ export async function run(sub, args) {
     case "schema":    await schema(args[0]); break;
     case "rls":       await rls(args[0], args[1], args[2]); break;
     case "delete":    await deleteProject(args[0]); break;
-    case "pin":       await pin(args[0]); break;
+    case "pin":          await pin(args[0]); break;
+    case "promote-user": await promoteUser(args[0], args[1]); break;
+    case "demote-user":  await demoteUser(args[0], args[1]); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

openspec/changes/archive/2026-03-30-add-promote-demote-user/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-30

openspec/changes/archive/2026-03-30-add-promote-demote-user/design.md

@@ -0,0 +1,33 @@
+## Context
+
+The Run402 gateway added a `project_admin` role with two admin endpoints for promoting/demoting users. These endpoints follow the same pattern as other admin endpoints (`/projects/v1/admin/:id/...`) and require `service_key` auth. Currently, these endpoints are listed in `IGNORED_ENDPOINTS` in sync.test.ts with the comment "not yet exposed as CLI/MCP tools."
+
+All three interfaces (MCP, CLI, OpenClaw) need to be extended. The existing `set_secret` tool is the closest pattern — a simple admin endpoint with service_key auth, project_id + one additional parameter.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Expose `promote-user` and `demote-user` across all three interfaces (MCP, CLI, OpenClaw)
+- Follow existing tool/command patterns exactly (same error handling, auth, output format)
+- Keep sync.test.ts passing with the new entries
+
+**Non-Goals:**
+- Adding `--admin` flag to CLI auth signup (the issue mentions this but there is no existing `auth signup` CLI command or MCP signup tool — this would be a separate change)
+- Listing or viewing project admin users (no endpoint exists for this)
+- Changing the auth or keystore system
+
+## Decisions
+
+**One MCP tool file per action** — `promote-user.ts` and `demote-user.ts` as separate files, matching the project convention (each tool is its own file). Alternative: a single `user-role.ts` with two exports. Rejected because every existing tool follows the one-file-per-action pattern.
+
+**CLI subcommands under `projects`** — `promote-user` and `demote-user` as subcommands of `run402 projects`, matching the endpoint path structure (`/projects/v1/admin/:id/...`). The CLI convention is that admin operations on a project live under `projects:*`.
+
+**service_key auth, not allowance auth** — These endpoints require service_key (stored in keystore per project), not wallet-based allowance auth. This matches other admin endpoints like `sql`, `schema`, `usage`.
+
+**No separate OpenClaw module** — OpenClaw's `projects.mjs` is already a thin re-export of CLI's `projects.mjs`. Since the new subcommands are added directly to the CLI's run() switch, OpenClaw gets them for free with no changes needed.
+
+## Risks / Trade-offs
+
+**[Risk] Email not found returns error** → The API may return 404 or similar if the email doesn't correspond to a signed-up user. The tools will surface this via `formatApiError` in MCP and JSON error output in CLI, giving actionable feedback.
+
+**[Risk] Demoting the last admin** → The gateway should handle this constraint, not the client tools. No client-side validation needed.

openspec/changes/archive/2026-03-30-add-promote-demote-user/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+The Run402 gateway now supports a `project_admin` role — app-level admins who can manage secrets from the browser. Two new admin endpoints (`promote-user`, `demote-user`) exist in the API but have no MCP tools, CLI commands, or OpenClaw shims. The signup endpoint also now accepts `is_admin` but the CLI doesn't expose that flag. Without tooling, developers can't manage project admins through any of the three interfaces.
+
+## What Changes
+
+- **New MCP tools**: `promote_user(project_id, email)` and `demote_user(project_id, email)` — call the admin endpoints with service_key auth
+- **New CLI commands**: `run402 projects promote-user` and `run402 projects demote-user` — same endpoints, CLI output format
+- **New OpenClaw shims**: thin re-exports of the CLI commands
+- **CLI enhancement**: `--admin` flag on `run402 auth signup` — passes `is_admin: true` in the signup request body (requires service_key)
+- **MCP enhancement**: optional `is_admin` parameter on the existing signup flow (if an MCP signup tool exists; otherwise skip)
+- **sync.test.ts**: add both tools to the `SURFACE` array and remove them from `IGNORED_ENDPOINTS`
+
+## Capabilities
+
+### New Capabilities
+- `user-role-management`: Promote and demote project users to/from the `project_admin` role via MCP, CLI, and OpenClaw
+
+### Modified Capabilities
+<!-- No existing specs are changing at the requirement level -->
+
+## Impact
+
+- **MCP server** (`src/tools/`): two new tool files (`promote-user.ts`, `demote-user.ts`)
+- **CLI** (`cli/lib/projects.mjs`): two new subcommands (`promote-user`, `demote-user`)
+- **OpenClaw** (`openclaw/scripts/projects.mjs`): re-export the new CLI subcommands
+- **sync.test.ts**: update `SURFACE` array (add entries) and `IGNORED_ENDPOINTS` (remove the two endpoints)
+- **API endpoints used**: `POST /projects/v1/admin/:id/promote-user`, `POST /projects/v1/admin/:id/demote-user` — both require service_key auth
+- **No new dependencies** — uses existing `apiRequest`, `getProject`, `formatApiError` patterns

openspec/changes/archive/2026-03-30-add-promote-demote-user/specs/user-role-management/spec.md

@@ -0,0 +1,74 @@
+## ADDED Requirements
+
+### Requirement: MCP promote_user tool
+The system SHALL provide a `promote_user` MCP tool that sets a user's `is_admin` flag to `true` for a given project. The tool SHALL accept `project_id` (string) and `email` (string) parameters. It SHALL use `service_key` auth from the local keystore. It SHALL call `POST /projects/v1/admin/:id/promote-user` with `{ email }` in the request body. It SHALL return a success message including the email and project_id, or an error via `formatApiError`.
+
+#### Scenario: Successfully promote a user
+- **WHEN** `promote_user` is called with a valid `project_id` and `email` of an existing user
+- **THEN** the tool calls the promote-user endpoint with service_key auth and returns a success text response
+
+#### Scenario: Project not in keystore
+- **WHEN** `promote_user` is called with a `project_id` not present in the local keystore
+- **THEN** the tool returns `projectNotFound` error without making an API call
+
+#### Scenario: API returns error
+- **WHEN** the promote-user endpoint returns a non-OK response (e.g. 404 user not found)
+- **THEN** the tool returns the formatted error via `formatApiError`
+
+### Requirement: MCP demote_user tool
+The system SHALL provide a `demote_user` MCP tool that sets a user's `is_admin` flag to `false` for a given project. The tool SHALL accept `project_id` (string) and `email` (string) parameters. It SHALL use `service_key` auth from the local keystore. It SHALL call `POST /projects/v1/admin/:id/demote-user` with `{ email }` in the request body. It SHALL return a success message including the email and project_id, or an error via `formatApiError`.
+
+#### Scenario: Successfully demote a user
+- **WHEN** `demote_user` is called with a valid `project_id` and `email` of an existing admin user
+- **THEN** the tool calls the demote-user endpoint with service_key auth and returns a success text response
+
+#### Scenario: Project not in keystore
+- **WHEN** `demote_user` is called with a `project_id` not present in the local keystore
+- **THEN** the tool returns `projectNotFound` error without making an API call
+
+#### Scenario: API returns error
+- **WHEN** the demote-user endpoint returns a non-OK response
+- **THEN** the tool returns the formatted error via `formatApiError`
+
+### Requirement: CLI promote-user subcommand
+The system SHALL provide a `run402 projects promote-user <id> <email>` CLI subcommand. It SHALL look up the project via `findProject`, call the same API endpoint as the MCP tool, and output JSON to stdout. On error, it SHALL print JSON to stderr and exit with code 1.
+
+#### Scenario: CLI promote-user success
+- **WHEN** `run402 projects promote-user <id> <email>` is run with a valid project and email
+- **THEN** the command outputs the API response as JSON to stdout
+
+#### Scenario: CLI promote-user project not found
+- **WHEN** the project_id is not in the local keystore
+- **THEN** the command prints an error and exits with code 1
+
+### Requirement: CLI demote-user subcommand
+The system SHALL provide a `run402 projects demote-user <id> <email>` CLI subcommand. It SHALL look up the project via `findProject`, call the same API endpoint as the MCP tool, and output JSON to stdout. On error, it SHALL print JSON to stderr and exit with code 1.
+
+#### Scenario: CLI demote-user success
+- **WHEN** `run402 projects demote-user <id> <email>` is run with a valid project and email
+- **THEN** the command outputs the API response as JSON to stdout
+
+#### Scenario: CLI demote-user project not found
+- **WHEN** the project_id is not in the local keystore
+- **THEN** the command prints an error and exits with code 1
+
+### Requirement: OpenClaw commands via re-export
+The OpenClaw `projects.mjs` SHALL continue to re-export the CLI `projects.mjs` run function, which means the new `promote-user` and `demote-user` subcommands are automatically available with no additional OpenClaw changes.
+
+#### Scenario: OpenClaw promote-user available
+- **WHEN** OpenClaw dispatches `projects promote-user <id> <email>`
+- **THEN** the CLI's promote-user handler is invoked via the re-export
+
+### Requirement: sync.test.ts surface entries
+The `SURFACE` array in `sync.test.ts` SHALL include entries for `promote_user` and `demote_user` with their correct MCP tool names, CLI commands (`projects:promote-user`, `projects:demote-user`), OpenClaw commands, and API endpoints. The two endpoints SHALL be removed from `IGNORED_ENDPOINTS`.
+
+#### Scenario: Sync test passes with new tools
+- **WHEN** `npm run test:sync` is executed
+- **THEN** the test passes with the new promote_user and demote_user entries in SURFACE and removed from IGNORED_ENDPOINTS
+
+### Requirement: MCP tool registration
+Both `promote_user` and `demote_user` tools SHALL be registered in `src/index.ts` following the existing pattern (import schema + handler, register with `server.tool()`).
+
+#### Scenario: Tools appear in MCP tool list
+- **WHEN** the MCP server starts
+- **THEN** both `promote_user` and `demote_user` appear in the tool list with their Zod schemas

openspec/changes/archive/2026-03-30-add-promote-demote-user/tasks.md

@@ -0,0 +1,20 @@
+## 1. MCP Tools
+
+- [x] 1.1 Create `src/tools/promote-user.ts` — export `promoteUserSchema` and `handlePromoteUser` following the `set-secret.ts` pattern (service_key auth, `formatApiError`, `projectNotFound`)
+- [x] 1.2 Create `src/tools/demote-user.ts` — export `demoteUserSchema` and `handleDemoteUser` following the same pattern
+- [x] 1.3 Register both tools in `src/index.ts` — import schemas and handlers, add `server.tool()` calls
+
+## 2. CLI Commands
+
+- [x] 2.1 Add `promote-user` and `demote-user` subcommands to `cli/lib/projects.mjs` — add handler functions and switch cases in `run()`
+- [x] 2.2 Update the HELP text in `cli/lib/projects.mjs` to document the new subcommands
+
+## 3. Sync Test
+
+- [x] 3.1 Add `promote_user` and `demote_user` entries to the `SURFACE` array in `sync.test.ts`
+- [x] 3.2 Remove `POST /projects/v1/admin/:id/promote-user` and `POST /projects/v1/admin/:id/demote-user` from `IGNORED_ENDPOINTS`
+
+## 4. Tests & Verification
+
+- [x] 4.1 Create unit tests for the MCP tools (`src/tools/promote-user.test.ts`, `src/tools/demote-user.test.ts`) — test success, project not found, and API error cases
+- [x] 4.2 Run `npm test` to verify all tests pass (sync test, unit tests)

openspec/specs/user-role-management/spec.md

@@ -0,0 +1,72 @@
+### Requirement: MCP promote_user tool
+The system SHALL provide a `promote_user` MCP tool that sets a user's `is_admin` flag to `true` for a given project. The tool SHALL accept `project_id` (string) and `email` (string) parameters. It SHALL use `service_key` auth from the local keystore. It SHALL call `POST /projects/v1/admin/:id/promote-user` with `{ email }` in the request body. It SHALL return a success message including the email and project_id, or an error via `formatApiError`.
+
+#### Scenario: Successfully promote a user
+- **WHEN** `promote_user` is called with a valid `project_id` and `email` of an existing user
+- **THEN** the tool calls the promote-user endpoint with service_key auth and returns a success text response
+
+#### Scenario: Project not in keystore
+- **WHEN** `promote_user` is called with a `project_id` not present in the local keystore
+- **THEN** the tool returns `projectNotFound` error without making an API call
+
+#### Scenario: API returns error
+- **WHEN** the promote-user endpoint returns a non-OK response (e.g. 404 user not found)
+- **THEN** the tool returns the formatted error via `formatApiError`
+
+### Requirement: MCP demote_user tool
+The system SHALL provide a `demote_user` MCP tool that sets a user's `is_admin` flag to `false` for a given project. The tool SHALL accept `project_id` (string) and `email` (string) parameters. It SHALL use `service_key` auth from the local keystore. It SHALL call `POST /projects/v1/admin/:id/demote-user` with `{ email }` in the request body. It SHALL return a success message including the email and project_id, or an error via `formatApiError`.
+
+#### Scenario: Successfully demote a user
+- **WHEN** `demote_user` is called with a valid `project_id` and `email` of an existing admin user
+- **THEN** the tool calls the demote-user endpoint with service_key auth and returns a success text response
+
+#### Scenario: Project not in keystore
+- **WHEN** `demote_user` is called with a `project_id` not present in the local keystore
+- **THEN** the tool returns `projectNotFound` error without making an API call
+
+#### Scenario: API returns error
+- **WHEN** the demote-user endpoint returns a non-OK response
+- **THEN** the tool returns the formatted error via `formatApiError`
+
+### Requirement: CLI promote-user subcommand
+The system SHALL provide a `run402 projects promote-user <id> <email>` CLI subcommand. It SHALL look up the project via `findProject`, call the same API endpoint as the MCP tool, and output JSON to stdout. On error, it SHALL print JSON to stderr and exit with code 1.
+
+#### Scenario: CLI promote-user success
+- **WHEN** `run402 projects promote-user <id> <email>` is run with a valid project and email
+- **THEN** the command outputs the API response as JSON to stdout
+
+#### Scenario: CLI promote-user project not found
+- **WHEN** the project_id is not in the local keystore
+- **THEN** the command prints an error and exits with code 1
+
+### Requirement: CLI demote-user subcommand
+The system SHALL provide a `run402 projects demote-user <id> <email>` CLI subcommand. It SHALL look up the project via `findProject`, call the same API endpoint as the MCP tool, and output JSON to stdout. On error, it SHALL print JSON to stderr and exit with code 1.
+
+#### Scenario: CLI demote-user success
+- **WHEN** `run402 projects demote-user <id> <email>` is run with a valid project and email
+- **THEN** the command outputs the API response as JSON to stdout
+
+#### Scenario: CLI demote-user project not found
+- **WHEN** the project_id is not in the local keystore
+- **THEN** the command prints an error and exits with code 1
+
+### Requirement: OpenClaw commands via re-export
+The OpenClaw `projects.mjs` SHALL continue to re-export the CLI `projects.mjs` run function, which means the new `promote-user` and `demote-user` subcommands are automatically available with no additional OpenClaw changes.
+
+#### Scenario: OpenClaw promote-user available
+- **WHEN** OpenClaw dispatches `projects promote-user <id> <email>`
+- **THEN** the CLI's promote-user handler is invoked via the re-export
+
+### Requirement: sync.test.ts surface entries
+The `SURFACE` array in `sync.test.ts` SHALL include entries for `promote_user` and `demote_user` with their correct MCP tool names, CLI commands (`projects:promote-user`, `projects:demote-user`), OpenClaw commands, and API endpoints. The two endpoints SHALL be removed from `IGNORED_ENDPOINTS`.
+
+#### Scenario: Sync test passes with new tools
+- **WHEN** `npm run test:sync` is executed
+- **THEN** the test passes with the new promote_user and demote_user entries in SURFACE and removed from IGNORED_ENDPOINTS
+
+### Requirement: MCP tool registration
+Both `promote_user` and `demote_user` tools SHALL be registered in `src/index.ts` following the existing pattern (import schema + handler, register with `server.tool()`).
+
+#### Scenario: Tools appear in MCP tool list
+- **WHEN** the MCP server starts
+- **THEN** both `promote_user` and `demote_user` appear in the tool list with their Zod schemas

src/index.ts

@@ -46,6 +46,10 @@ import { listSubdomainsSchema, handleListSubdomains } from "./tools/list-subdoma
 import { archiveProjectSchema, handleArchiveProject } from "./tools/archive-project.js";
 import { pinProjectSchema, handlePinProject } from "./tools/pin-project.js";
 
+// New tools — user role management
+import { promoteUserSchema, handlePromoteUser } from "./tools/promote-user.js";
+import { demoteUserSchema, handleDemoteUser } from "./tools/demote-user.js";
+
 // New tools — billing
 import { checkBalanceSchema, handleCheckBalance } from "./tools/check-balance.js";
 import { listProjectsSchema, handleListProjects } from "./tools/list-projects.js";
@@ -332,6 +336,20 @@ server.tool(
   async (args) => handlePinProject(args),
 );
 
+server.tool(
+  "promote_user",
+  "Promote a user to project_admin role by email. Admins can manage secrets from the browser. Requires service_key.",
+  promoteUserSchema,
+  async (args) => handlePromoteUser(args),
+);
+
+server.tool(
+  "demote_user",
+  "Demote a user from project_admin role by email. Reverts to default authenticated role. Requires service_key.",
+  demoteUserSchema,
+  async (args) => handleDemoteUser(args),
+);
+
 // ─── Billing & allowance tools ───────────────────────────────────────────────
 
 server.tool(