spaps 0.9.0 → 0.9.1

package/README.md

@@ -26,6 +26,7 @@ Run SPAPS locally, inspect the current auth mode, then either use local mode dir
 | "I want a working local app, not a fake contract" | Self-service provisioning when `SELF_SERVICE_PASSWORD` is available |
 | "If provisioning fails, tell me exactly why" | Explicit `scaffold_only` fallback and warnings |
 | "I want persistent local personas, roles, and entitlements in this repo" | `spaps fixtures ...` and a repo-local `.spaps/` kernel |
+| "Can an agent tell me why this action is blocked?" | `spaps access check`, `journey run`, `graph`, `explain`, and `contract` |
 
 ## No Backend Yet? Start Here
 
@@ -59,6 +60,12 @@ This package targets `Node.js >=22`.
 
 The default is `auto`: use repo assets when they exist, otherwise fall back to the bundled runtime. The bundled runtime defaults to `SPAPS_LOCAL_MODE=true`, so RBAC fixtures and test personas work out of the box.
 
+`SPAPS_LOCAL_MODE` is the SPAPS app's canonical local auth/persona switch.
+`DEVELOPMENT_ENVIRONMENT=local` is only for base quickstart services that wire
+`LocalAuthMiddleware`. The CLI reads runtime truth from `/health/local-mode`;
+servers also expose the resolved value in `/health/ready` and the
+`X-SPAPS-Mode` response header.
+
 ## Local Data Sources
 
 `spaps local` separates runtime selection from base data selection:
@@ -120,14 +127,66 @@ npm install spaps
 | `spaps create <name>` | Scaffold a SPAPS starter project directory and try local provisioning | `--template`, `--dir`, `--port`, `--force`, `--json` |
 | `spaps fixtures <subcommand>` | Manage repo-local `.spaps` auth fixtures | `--dir`, `--port`, `--base-url`, `--persona`, `--seed`, `--sync-server`, `--format`, `--force`, `--json` |
 | `spaps docs` | Browse or search bundled docs | `--interactive`, `--search`, `--json` |
-| `spaps tools` | Emit the AI tool spec (covers auth, stripe, dayrate, email, webhooks, policies, billing, issue-reporting) | `--port`, `--format`, `--json` |
-| `spaps doctor` | Diagnose local environment problems and probe that every domain router is mounted | `--port`, `--stripe`, `--json` |
+| `spaps tools` | Emit the AI tool spec (covers auth-method discovery, auth, stripe, dayrate, email, webhooks, policies, billing, issue-reporting) | `--port`, `--format`, `--json` |
+| `spaps doctor` | Diagnose local environment, domain mounts, and auth-provider configuration | `--port`, `--server-url`, `--origin`, `--stripe`, `--json` |
+| `spaps auth methods` | Print the active app's auth-method matrix from `/api/auth/methods` | `--server-url`, `--port`, `--origin`, `--json` |
+| `spaps auth mfa-test` | Exercise local TOTP MFA enroll, activate, login challenge, verify, and cleanup | `--email`, `--password`, `--server-url`, `--origin`, `--allow-remote`, `--json` |
+| `spaps auth sms-test` | Request or verify a local console SMS OTP challenge | `--phone-number`, `--challenge-id`, `--code`, `--server-url`, `--origin`, `--allow-remote`, `--json` |
 | `spaps dayrate config` | Fetch the active dayrate admin config (requires admin JWT) | `--server-url`, `--port`, `--json` |
 | `spaps billing status\|attach\|verify` | Inspect, bind, and verify the current app's billing-account resolution (admin/operator) | `--billing-account-id`, `--server-url`, `--port`, `--json` |
 | `spaps email <verb>` | Thin email control-plane commands over the existing SPAPS email API | `--server-url`, `--port`, `--json`; run `spaps email --help` for verb-specific flags |
 | `spaps policy list\|create\|delete` | List, create, or delete authorization policies (admin) | `--name`, `--effect`, `--conditions`, `--id`, `--is-active`, `--limit`, `--json` |
 | `spaps webhook list\|register` | List registered webhooks or register a new outbound webhook | `--url`, `--events`, `--json` |
 | `spaps issue-reports list-mine` | List issue reports created by the authenticated caller | `--status`, `--limit`, `--offset`, `--json` |
+| `spaps access check` | Compose an access decision and return reasons, facts, next actions, and sources | `--actor-ref`, `--action`, `--resource-type`, `--resource-ref`, `--entitlement-key`, `--policy-name`, `--usage-feature-key`, `--json` |
+| `spaps journey run` | Prepare the next safe action for an agent and request command templates when the server recognizes trusted operator context | access flags plus `--include-command-templates`, `--operator-gated`, `--operator-labels`, `--environment`, `--json` |
+| `spaps graph nodes\|paths\|impact\|refresh` | Inspect or refresh the materialized capability graph for the current app | `--application-id`, `--node-type`, `--query`, `--from`, `--to`, `--node-key`, `--max-depth`, `--include-stale`, `--correlation-id`, `--json` |
+| `spaps explain <decision-id>` | Fetch a persisted decision trace with graph references | `--server-url`, `--port`, `--json` |
+| `spaps contract` | Fetch the capability graph client contract | `--server-url`, `--port`, `--json` |
+
+`spaps contract --json` includes graph vocabulary fields for agents:
+`graph_node_types`, `graph_edge_types`, `graph_source_domains`, and
+`source_domain_notes`.
+
+### Agent Decision Commands
+
+The capability commands use a stable JSON envelope when `--json` is present:
+
+```json
+{
+  "schema_version": "spaps.cli.capability.v1",
+  "command": "access.check",
+  "success": true,
+  "status": 200,
+  "data": {},
+  "diagnostics": [],
+  "remediations": [],
+  "sources": []
+}
+```
+
+`access check` exits `0` for a valid denied decision. Agents should inspect
+`data.allowed`, `data.outcome`, and `remediations` instead of treating denial
+as a shell failure.
+
+Failed API responses preserve server diagnostics: `diagnostics[].code`,
+`diagnostics[].status`, `diagnostics[].details`, top-level `request_id`, and
+top-level `remediations` are carried through when the server returns them.
+
+`--operator-gated` and `--operator-labels` are compatibility/descriptive inputs.
+They do not grant operator authority. Mutation command templates require a
+server-recognized non-publishable key plus an authenticated admin/operator user
+context; publishable callers cannot self-attest the gate.
+
+Exit codes used by the capability commands:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Command completed; the decision may still be `allowed: false` |
+| `2` | Local input or setup error |
+| `10` | Authenticated API request failed |
+| `20` | `spaps contract` failed |
+| `30` | `spaps journey run` failed |
 
 ### Email Commands
 
@@ -186,6 +245,13 @@ spaps policy list --json
 spaps policy create --name allow_admin --effect allow --conditions '{"role":"admin"}' --json
 spaps webhook register --url https://example.com/hook --events user.created,user.deleted --json
 spaps issue-reports list-mine --status open --json
+spaps access check --actor-ref user_123 --action checkout.create --resource-type product --resource-ref dayrate --entitlement-key bookme_paid --json
+spaps journey run --action admin.delete_user --resource-type user --resource-ref user_123 --include-command-templates --json
+spaps graph refresh --correlation-id local-refresh --json
+spaps graph nodes --node-type x402_resource --query dayrate --json
+spaps graph paths --from actor:user_123 --to x402_resource:dayrate --json
+spaps explain 11111111-1111-4111-8111-111111111111 --json
+spaps contract --json
 ```
 
 ## CLI Auth
@@ -196,6 +262,12 @@ spaps issue-reports list-mine --status open --json
 - authenticated follow-up calls at `/api/auth/*`
 - standard SPAPS response envelopes
 
+For users with activated TOTP MFA, `spaps connect` keeps polling the device
+token endpoint while the browser approval page completes the second factor. The
+approval page handles `mfa_required` from `/api/cli/device/verify` by retrying
+that endpoint with `challenge_id`, `challenge`, and either `totp_code` or
+`recovery_code`; the CLI does not need an MFA flag.
+
 The CLI no longer assumes a built-in `spaps-cli` application slug. Resolve the client id in this order:
 
 - `--client-id <app-slug>`
@@ -221,6 +293,21 @@ SPAPS_CLI_CLIENT_ID=my-app npx spaps login
 VITE_SPAPS_API_KEY=spaps_pub_demo npx spaps whoami --json
 ```
 
+Auth diagnostics:
+
+```bash
+npx spaps doctor --server-url http://localhost:3301 --origin http://localhost:3000 --json
+npx spaps auth methods --origin http://localhost:3000 --json
+SPAPS_TEST_EMAIL=user@example.com SPAPS_TEST_PASSWORD=correct-horse npx spaps auth mfa-test --json
+npx spaps auth sms-test --phone-number +15555550100 --json
+npx spaps auth sms-test --phone-number +15555550100 --challenge-id <id> --code <code> --json
+```
+
+`mfa-test` and `sms-test` refuse non-local server URLs unless `--allow-remote`
+is set. The SMS command cannot read OTP digits from the server because SPAPS
+does not return them in API responses; with the console provider, read the code
+from local server logs and rerun with `--challenge-id` and `--code`.
+
 Still reserved and not finished:
 
 - `spaps types`

package/client.js

@@ -68,6 +68,10 @@ try {
         headers: { Authorization: `Bearer ${this.accessToken}` }
       });
     }
+
+    async getAuthMethods() {
+      return this.client.get('/api/auth/methods');
+    }
     
     async createCheckoutSession(priceId, successUrl, cancelUrl) {
       return this.client.post('/api/stripe/checkout-sessions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {

package/src/ai-tool-spec.js

@@ -75,6 +75,87 @@ function buildAuthSection(runtime) {
   };
 }
 
+const CORE_TOOL_ROUTES = [
+  { name: 'login', method: 'POST', path: '/api/auth/login', requestBody: true },
+  { name: 'register', method: 'POST', path: '/api/auth/register', requestBody: true },
+  { name: 'auth_methods', method: 'GET', path: '/api/auth/methods' },
+  { name: 'get_current_user', method: 'GET', path: '/api/auth/user' },
+  { name: 'create_checkout_session', method: 'POST', path: '/api/stripe/checkout-sessions', requestBody: true },
+  { name: 'list_products', method: 'GET', path: '/api/stripe/products' },
+  { name: 'request_magic_link', method: 'POST', path: '/api/auth/magic-link', requestBody: true },
+  { name: 'get_wallet_nonce', method: 'POST', path: '/api/auth/nonce', requestBody: true },
+  { name: 'wallet_sign_in', method: 'POST', path: '/api/auth/wallet-sign-in', requestBody: true },
+  { name: 'verify_magic_link', method: 'POST', path: '/api/auth/verify-magic-link', requestBody: true },
+  { name: 'oidc_nonce', method: 'POST', path: '/api/auth/oidc/nonce', requestBody: true },
+  { name: 'oidc_sign_in', method: 'POST', path: '/api/auth/oidc/sign-in', requestBody: true },
+  { name: 'sms_request', method: 'POST', path: '/api/auth/sms/request', requestBody: true },
+  { name: 'sms_verify', method: 'POST', path: '/api/auth/sms/verify', requestBody: true },
+  { name: 'webauthn_assertion_options', method: 'POST', path: '/api/auth/webauthn/assertion/options', requestBody: true },
+  { name: 'webauthn_assertion_verify', method: 'POST', path: '/api/auth/webauthn/assertion/verify', requestBody: true },
+  { name: 'webauthn_register_options', method: 'POST', path: '/api/auth/webauthn/register/options', requestBody: true },
+  { name: 'webauthn_register_verify', method: 'POST', path: '/api/auth/webauthn/register/verify', requestBody: true },
+  { name: 'mfa_verify', method: 'POST', path: '/api/auth/mfa/verify', requestBody: true },
+  { name: 'mfa_totp_enroll', method: 'POST', path: '/api/auth/mfa/totp/enroll', requestBody: true },
+  { name: 'mfa_totp_activate', method: 'POST', path: '/api/auth/mfa/totp/activate', requestBody: true },
+  { name: 'mfa_totp_disable', method: 'POST', path: '/api/auth/mfa/totp/disable', requestBody: true },
+];
+
+const CLI_AUTH_TOOLS = [
+  {
+    name: 'spaps_auth_methods',
+    description: 'Run `spaps auth methods` to print the configured auth method matrix for an application.',
+    command: 'spaps auth methods',
+    cli: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        server_url: { type: 'string', description: 'SPAPS server URL; maps to --server-url' },
+        origin: { type: 'string', description: 'Browser origin to send with publishable-key checks; maps to --origin' },
+        json: { type: 'boolean', default: true },
+      },
+    },
+  },
+  {
+    name: 'spaps_auth_mfa_test',
+    description: 'Run `spaps auth mfa-test` against a local SPAPS stack to exercise TOTP enrollment, activation, MFA challenge verification, and cleanup.',
+    command: 'spaps auth mfa-test',
+    cli: true,
+    local_only_by_default: true,
+    parameters: {
+      type: 'object',
+      required: ['email', 'password'],
+      properties: {
+        email: { type: 'string', description: 'Local test user email; maps to --email' },
+        password: { type: 'string', description: 'Local test user password; maps to --password' },
+        server_url: { type: 'string', description: 'SPAPS server URL; maps to --server-url' },
+        origin: { type: 'string', description: 'Browser origin to send with publishable-key checks; maps to --origin' },
+        allow_remote: { type: 'boolean', default: false, description: 'Maps to --allow-remote' },
+        json: { type: 'boolean', default: true },
+      },
+    },
+  },
+  {
+    name: 'spaps_auth_sms_test',
+    description: 'Run `spaps auth sms-test` against local console SMS to request a challenge, then verify it with a code read from local server logs.',
+    command: 'spaps auth sms-test',
+    cli: true,
+    local_only_by_default: true,
+    parameters: {
+      type: 'object',
+      required: ['phone_number'],
+      properties: {
+        phone_number: { type: 'string', description: 'E.164 phone number; maps to --phone-number' },
+        challenge_id: { type: 'string', description: 'Existing SMS challenge id; maps to --challenge-id' },
+        code: { type: 'string', description: 'SMS code from local server logs; maps to --code' },
+        server_url: { type: 'string', description: 'SPAPS server URL; maps to --server-url' },
+        origin: { type: 'string', description: 'Browser origin to send with publishable-key checks; maps to --origin' },
+        allow_remote: { type: 'boolean', default: false, description: 'Maps to --allow-remote' },
+        json: { type: 'boolean', default: true },
+      },
+    },
+  },
+];
+
 async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', include_non_agent = false } = {}) {
   const baseUrl = `http://localhost:${port}`;
   const runtime = await getServerRuntime({ port });
@@ -118,6 +199,16 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', inc
           }
         }
       },
+      {
+        name: 'auth_methods',
+        description: 'Discover the public auth methods configured for this application before rendering sign-in UI.',
+        method: 'GET',
+        path: '/api/auth/methods',
+        parameters: {
+          type: 'object',
+          properties: {}
+        }
+      },
       {
         name: 'get_current_user',
         description: 'Get the currently authenticated user. Uses the bearer token from a previous login.',
@@ -187,6 +278,185 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', inc
             chain_type: { type: 'string', enum: ['solana', 'ethereum', 'bitcoin', 'base'] }
           }
         }
+      },
+      {
+        name: 'wallet_sign_in',
+        description: 'Exchange a signed wallet nonce for SPAPS tokens or an mfa_required challenge.',
+        method: 'POST',
+        path: '/api/auth/wallet-sign-in',
+        parameters: {
+          type: 'object',
+          required: ['wallet_address', 'signature', 'message'],
+          properties: {
+            wallet_address: { type: 'string' },
+            signature: { type: 'string' },
+            message: { type: 'string' },
+            chain_type: { type: 'string', enum: ['solana', 'ethereum', 'bitcoin', 'base'] },
+            username: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'verify_magic_link',
+        description: 'Exchange a magic-link token for SPAPS tokens or an mfa_required challenge.',
+        method: 'POST',
+        path: '/api/auth/verify-magic-link',
+        parameters: {
+          type: 'object',
+          required: ['token'],
+          properties: {
+            token: { type: 'string' },
+            type: { type: 'string', default: 'magiclink' },
+            state: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'oidc_nonce',
+        description: 'Create a nonce challenge before exchanging an OIDC provider ID token.',
+        method: 'POST',
+        path: '/api/auth/oidc/nonce',
+        parameters: { type: 'object', properties: {} }
+      },
+      {
+        name: 'oidc_sign_in',
+        description: 'Exchange an OIDC ID token and challenge_id for SPAPS tokens or an mfa_required challenge.',
+        method: 'POST',
+        path: '/api/auth/oidc/sign-in',
+        parameters: {
+          type: 'object',
+          required: ['provider', 'id_token', 'challenge_id'],
+          properties: {
+            provider: { type: 'string' },
+            id_token: { type: 'string' },
+            challenge_id: { type: 'string' },
+            username: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'sms_request',
+        description: 'Request an enumeration-safe SMS OTP challenge.',
+        method: 'POST',
+        path: '/api/auth/sms/request',
+        parameters: {
+          type: 'object',
+          required: ['phone_number'],
+          properties: {
+            phone_number: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'sms_verify',
+        description: 'Verify an SMS OTP challenge for SPAPS tokens or an mfa_required challenge.',
+        method: 'POST',
+        path: '/api/auth/sms/verify',
+        parameters: {
+          type: 'object',
+          required: ['phone_number', 'code', 'challenge_id'],
+          properties: {
+            phone_number: { type: 'string' },
+            code: { type: 'string' },
+            challenge_id: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'webauthn_assertion_options',
+        description: 'Request WebAuthn assertion options before navigator.credentials.get().',
+        method: 'POST',
+        path: '/api/auth/webauthn/assertion/options',
+        parameters: {
+          type: 'object',
+          properties: {
+            email: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'webauthn_assertion_verify',
+        description: 'Verify a browser WebAuthn assertion for SPAPS tokens or an mfa_required challenge.',
+        method: 'POST',
+        path: '/api/auth/webauthn/assertion/verify',
+        parameters: {
+          type: 'object',
+          required: ['challenge_id', 'credential'],
+          properties: {
+            challenge_id: { type: 'string' },
+            credential: { type: 'object' }
+          }
+        }
+      },
+      {
+        name: 'webauthn_register_options',
+        description: 'Request WebAuthn passkey registration options for an authenticated user.',
+        method: 'POST',
+        path: '/api/auth/webauthn/register/options',
+        parameters: { type: 'object', properties: {} }
+      },
+      {
+        name: 'webauthn_register_verify',
+        description: 'Verify browser WebAuthn registration output for an authenticated user.',
+        method: 'POST',
+        path: '/api/auth/webauthn/register/verify',
+        parameters: {
+          type: 'object',
+          required: ['challenge_id', 'credential'],
+          properties: {
+            challenge_id: { type: 'string' },
+            credential: { type: 'object' }
+          }
+        }
+      },
+      {
+        name: 'mfa_verify',
+        description: 'Complete an mfa_required challenge with a TOTP code or recovery code.',
+        method: 'POST',
+        path: '/api/auth/mfa/verify',
+        parameters: {
+          type: 'object',
+          required: ['challenge_id', 'challenge'],
+          properties: {
+            challenge_id: { type: 'string' },
+            challenge: { type: 'string' },
+            code: { type: 'string' },
+            recovery_code: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'mfa_totp_enroll',
+        description: 'Enroll TOTP MFA for an authenticated user.',
+        method: 'POST',
+        path: '/api/auth/mfa/totp/enroll',
+        parameters: { type: 'object', properties: {} }
+      },
+      {
+        name: 'mfa_totp_activate',
+        description: 'Activate pending TOTP MFA enrollment with a current code.',
+        method: 'POST',
+        path: '/api/auth/mfa/totp/activate',
+        parameters: {
+          type: 'object',
+          required: ['code'],
+          properties: {
+            code: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'mfa_totp_disable',
+        description: 'Disable TOTP MFA for an authenticated user with a current code.',
+        method: 'POST',
+        path: '/api/auth/mfa/totp/disable',
+        parameters: {
+          type: 'object',
+          required: ['code'],
+          properties: {
+            code: { type: 'string' }
+          }
+        }
       }
     ]
   };
@@ -194,6 +464,7 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', inc
   // Merge domain registry tools (dayrate, email, webhooks, policies, issue_reporting).
   // Admin routes carry admin_required:true; non-agent routes (e.g. mailgun inbound)
   // are excluded unless include_non_agent is set.
+  spec.tools.push(...CLI_AUTH_TOOLS.map((tool) => ({ ...tool })));
   const domainTools = buildDomainTools({ includeNonAgent: include_non_agent });
   for (const dt of domainTools) {
     spec.tools.push(dt);
@@ -242,15 +513,15 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', inc
         if (t && ep) {
           t.method = ep.method;
           t.path = ep.path;
+          if (ep.auth !== undefined) t.auth = ep.auth;
+          if (ep.rate_tier !== undefined) t.rate_tier = ep.rate_tier;
+          if (ep.publishable_scope !== undefined) t.publishable_scope = ep.publishable_scope;
+          if (ep.entitlement_key !== undefined) t.entitlement_key = ep.entitlement_key;
         }
       };
-      patchTool('login', 'POST', '/api/auth/login');
-      patchTool('register', 'POST', '/api/auth/register');
-      patchTool('get_current_user', 'GET', '/api/auth/user');
-      patchTool('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
-      patchTool('list_products', 'GET', '/api/stripe/products');
-      patchTool('request_magic_link', 'POST', '/api/auth/magic-link');
-      patchTool('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      for (const route of CORE_TOOL_ROUTES) {
+        patchTool(route.name, route.method, route.path);
+      }
     }
   } catch {
     // Best-effort alignment only
@@ -302,18 +573,10 @@ async function buildOpenAIToolSpec({ port = DEFAULT_PORT, version = '0.0.0', inc
           if (Object.keys(examples).length) t.examples = examples;
         }
       };
-      setBodySchema('login', 'POST', '/api/auth/login');
-      setBodySchema('register', 'POST', '/api/auth/register');
-      setBodySchema('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
-      setBodySchema('request_magic_link', 'POST', '/api/auth/magic-link');
-      setBodySchema('get_wallet_nonce', 'POST', '/api/auth/nonce');
-      setResponses('login', 'POST', '/api/auth/login');
-      setResponses('register', 'POST', '/api/auth/register');
-      setResponses('get_current_user', 'GET', '/api/auth/user');
-      setResponses('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
-      setResponses('list_products', 'GET', '/api/stripe/products');
-      setResponses('request_magic_link', 'POST', '/api/auth/magic-link');
-      setResponses('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      for (const route of CORE_TOOL_ROUTES) {
+        if (route.requestBody) setBodySchema(route.name, route.method, route.path);
+        setResponses(route.name, route.method, route.path);
+      }
       // Enrich every domain-registry tool opportunistically. Skips silently
       // if the operation isn\u2019t in the OpenAPI doc.
       for (const t of spec.tools) {

package/src/auth/handlers.js

@@ -21,6 +21,11 @@ const {
 const { isHeadless, tryOpenBrowser } = require('./env');
 const { authFetch, resolveServerUrl, refreshAccessToken } = require('./client');
 const { resolveLoginClientId } = require('./client-id');
+const {
+  fetchAuthMethods,
+  runMfaTest,
+  runSmsTest,
+} = require('./surface');
 
 function emitJsonError(command, err, extra = {}) {
   console.log(
@@ -454,7 +459,111 @@ async function tokenHandler({ options }) {
   process.stdout.write(creds.access_token + '\n');
 }
 
+function renderMethods(methods) {
+  console.log();
+  console.log(chalk.bold('Auth methods'));
+  for (const method of methods) {
+    const status = method.enabled ? chalk.green('enabled') : chalk.gray('disabled');
+    const config = method.config && Object.keys(method.config).length
+      ? ` ${chalk.gray(JSON.stringify(method.config))}`
+      : '';
+    console.log(`  ${method.method}: ${status}${config}`);
+  }
+  console.log();
+}
+
+function renderProbeResult(result) {
+  console.log();
+  console.log(chalk.green(`✓ ${result.command} completed`));
+  if (Array.isArray(result.steps)) {
+    for (const step of result.steps) {
+      const mark = step.success ? chalk.green('✓') : chalk.yellow('!');
+      console.log(`  ${mark} ${step.name}`);
+    }
+  }
+  if (result.verification_required) {
+    console.log(chalk.yellow('  verification required'));
+    console.log(chalk.gray(`  challenge_id: ${result.challenge_id}`));
+    console.log(chalk.gray(`  next: ${result.next_step}`));
+  }
+  console.log();
+}
+
+async function authHandler({ options }) {
+  const isJson = Boolean(options.json);
+  const serverUrl = resolveServerUrl(options);
+  const command = `auth.${options.subcommand || 'unknown'}`;
+
+  try {
+    if (options.subcommand === 'methods') {
+      const result = await fetchAuthMethods({
+        serverUrl,
+        origin: options.origin || null,
+      });
+      const payload = {
+        success: true,
+        command: 'auth.methods',
+        server_url: serverUrl,
+        origin: result.origin,
+        api_key_source: result.apiKeySource,
+        methods: result.methods,
+      };
+      if (isJson) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        renderMethods(result.methods);
+      }
+      return;
+    }
+
+    if (options.subcommand === 'mfa-test') {
+      const result = await runMfaTest({
+        serverUrl,
+        origin: options.origin || null,
+        email: options.email || process.env.SPAPS_TEST_EMAIL || null,
+        password: options.password || process.env.SPAPS_TEST_PASSWORD || null,
+        allowRemote: Boolean(options.allowRemote),
+      });
+      if (isJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        renderProbeResult(result);
+      }
+      return;
+    }
+
+    if (options.subcommand === 'sms-test') {
+      const result = await runSmsTest({
+        serverUrl,
+        origin: options.origin || null,
+        phoneNumber: options.phoneNumber || process.env.SPAPS_TEST_PHONE_NUMBER || null,
+        challengeId: options.challengeId || null,
+        code: options.code || null,
+        allowRemote: Boolean(options.allowRemote),
+      });
+      if (isJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        renderProbeResult(result);
+      }
+      return;
+    }
+
+    const err = new Error('Unknown auth subcommand. Use `spaps auth --help`.');
+    err.code = 'UNKNOWN_AUTH_SUBCOMMAND';
+    throw err;
+  } catch (err) {
+    if (isJson) {
+      emitJsonError(command, err, { server_url: serverUrl });
+    } else {
+      console.error(chalk.red(`\n❌ ${err.message || String(err)}`));
+    }
+    process.exit(err.code === 'MISSING_ARGUMENT' || err.code === 'REMOTE_REFUSED' ? 2 : 1);
+  }
+}
+
 module.exports = {
+  authHandler,
   loginHandler,
   logoutHandler,
   whoamiHandler,