spaps 0.8.2 → 0.9.1

package/src/cli-dispatcher.js

@@ -60,6 +60,35 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
       .option('--json', 'Output in JSON format');
   }
 
+  function addAccessDecisionOptions(command) {
+    return command
+      .option('--actor-type <type>', 'Actor type', 'user')
+      .option('--actor-ref <ref>', 'Stable actor reference')
+      .option('--user-id <id>', 'User UUID')
+      .option('--email <email>', 'Actor email address')
+      .option('--agent-id <id>', 'Agent UUID')
+      .option('--authenticated <bool>', 'Actor authenticated state')
+      .requiredOption('--action <action>', 'Action to check')
+      .requiredOption('--resource-type <type>', 'Resource type')
+      .requiredOption('--resource-ref <ref>', 'Stable resource reference')
+      .option('--resource-id <id>', 'Resource UUID')
+      .option('--resource-key <key>', 'Resource key')
+      .option('--entitlement-key <key>', 'Required entitlement key')
+      .option('--entitlement-resource-type <type>', 'Entitlement resource type')
+      .option('--entitlement-resource-id <id>', 'Entitlement resource UUID')
+      .option('--policy-name <name>', 'Policy name to evaluate')
+      .option('--policy-context <json>', 'Policy context JSON')
+      .option('--usage-feature-key <key>', 'Usage-control feature key')
+      .option('--usage-dimensions <json>', 'Usage dimensions JSON')
+      .option('--x402-resource-key <key>', 'x402 resource key')
+      .option('--approval-id <id>', 'Approval UUID')
+      .option('--approval-required', 'Require an approval before action execution', false)
+      .option('--authority-scope <scope>', 'Authority scope', 'application')
+      .option('--context <json>', 'Decision context JSON')
+      .option('--idempotency-key <key>', 'Decision idempotency key')
+      .option('--correlation-id <id>', 'Correlation id');
+  }
+
   // spaps home
   const cmdHome = program
     .command('home')
@@ -256,10 +285,18 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .command('doctor')
     .description('Diagnose local environment and config')
     .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('--server-url <url>', 'Full server URL (overrides --port and SPAPS_API_URL)')
+    .option('--origin <origin>', 'Browser origin to send with publishable-key auth diagnostics')
     .option('-s, --stripe <mode>', 'Stripe mode: mock|real')
     .option('--json', 'Output in JSON format')
     .action(
-      makeAction('doctor', (opts, _cmd, isJson) => ({ port: Number(opts.port), stripe: opts.stripe || null, json: isJson }))
+      makeAction('doctor', (opts, _cmd, isJson) => ({
+        port: Number(opts.port),
+        serverUrl: opts.serverUrl || null,
+        origin: opts.origin || null,
+        stripe: opts.stripe || null,
+        json: isJson,
+      }))
     );
   allowDryRun(cmdDoctor);
 
@@ -330,6 +367,77 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     );
   allowDryRun(cmdToken);
 
+  // spaps auth <subcommand>
+  const cmdAuth = program
+    .command('auth')
+    .description('Auth discovery and local diagnostic commands')
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+  if (!dryRun) {
+    cmdAuth.action(() => {
+      cmdAuth.outputHelp();
+    });
+  }
+  allowDryRun(cmdAuth);
+
+  function addAuthSubcommand(name, description, addOptions, shape) {
+    const command = cmdAuth.command(name).description(description);
+    addRemoteCommandOptions(command)
+      .option('--origin <origin>', 'Browser Origin header for publishable-key checks');
+    if (typeof addOptions === 'function') addOptions(command);
+    command.action(
+      makeAction('auth', (opts, _cmd, isJson) => ({
+        subcommand: name,
+        port: Number(opts.port) || DEFAULT_PORT,
+        serverUrl: opts.serverUrl || null,
+        origin: opts.origin || null,
+        ...shape(opts),
+        json: isJson,
+      }))
+    );
+    allowDryRun(command);
+    return command;
+  }
+
+  addAuthSubcommand(
+    'methods',
+    'Print the auth method matrix from GET /api/auth/methods',
+    null,
+    () => ({})
+  );
+
+  addAuthSubcommand(
+    'mfa-test',
+    'Exercise local TOTP MFA enrollment, activation, login challenge, verification, and cleanup',
+    (command) =>
+      command
+        .option('--email <email>', 'Local test user email (or SPAPS_TEST_EMAIL)')
+        .option('--password <password>', 'Local test user password (or SPAPS_TEST_PASSWORD)')
+        .option('--allow-remote', 'Allow running against a non-local server URL', false),
+    (opts) => ({
+      email: opts.email || null,
+      password: opts.password || null,
+      allowRemote: Boolean(opts.allowRemote),
+    })
+  );
+
+  addAuthSubcommand(
+    'sms-test',
+    'Request or verify an SMS OTP against local console SMS',
+    (command) =>
+      command
+        .option('--phone-number <phone>', 'E.164 phone number (or SPAPS_TEST_PHONE_NUMBER)')
+        .option('--challenge-id <id>', 'Existing SMS challenge id to verify')
+        .option('--code <code>', 'SMS code from local server logs')
+        .option('--allow-remote', 'Allow running against a non-local server URL', false),
+    (opts) => ({
+      phoneNumber: opts.phoneNumber || null,
+      challengeId: opts.challengeId || null,
+      code: opts.code || null,
+      allowRemote: Boolean(opts.allowRemote),
+    })
+  );
+
   // spaps dayrate <subcommand>
   const cmdDayrate = program
     .command('dayrate <subcommand>')
@@ -646,6 +754,242 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     );
   allowDryRun(cmdIssueReports);
 
+  // spaps access check
+  const cmdAccess = program
+    .command('access')
+    .description('Access decision commands')
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+  if (!dryRun) {
+    cmdAccess.action(() => {
+      cmdAccess.outputHelp();
+    });
+  }
+  allowDryRun(cmdAccess);
+
+  const cmdAccessCheck = addAccessDecisionOptions(cmdAccess.command('check').description('Check whether an actor can perform an action'));
+  addRemoteCommandOptions(cmdAccessCheck).action(
+    makeAction('access', (opts, _cmd, isJson) => ({
+      subcommand: 'check',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      actorType: opts.actorType || 'user',
+      actorRef: opts.actorRef || null,
+      userId: opts.userId || null,
+      email: opts.email || null,
+      agentId: opts.agentId || null,
+      authenticated: opts.authenticated === undefined ? null : opts.authenticated,
+      action: opts.action || null,
+      resourceType: opts.resourceType || null,
+      resourceRef: opts.resourceRef || null,
+      resourceId: opts.resourceId || null,
+      resourceKey: opts.resourceKey || null,
+      entitlementKey: opts.entitlementKey || null,
+      entitlementResourceType: opts.entitlementResourceType || null,
+      entitlementResourceId: opts.entitlementResourceId || null,
+      policyName: opts.policyName || null,
+      policyContext: opts.policyContext || null,
+      usageFeatureKey: opts.usageFeatureKey || null,
+      usageDimensions: opts.usageDimensions || null,
+      x402ResourceKey: opts.x402ResourceKey || null,
+      approvalId: opts.approvalId || null,
+      approvalRequired: Boolean(opts.approvalRequired),
+      authorityScope: opts.authorityScope || 'application',
+      context: opts.context || null,
+      idempotencyKey: opts.idempotencyKey || null,
+      correlationId: opts.correlationId || null,
+      json: isJson,
+    }))
+  );
+  allowDryRun(cmdAccessCheck);
+
+  // spaps journey run
+  const cmdJourney = program
+    .command('journey')
+    .description('Prepare agent-safe next actions for an application journey')
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+  if (!dryRun) {
+    cmdJourney.action(() => {
+      cmdJourney.outputHelp();
+    });
+  }
+  allowDryRun(cmdJourney);
+
+  const cmdJourneyRun = addAccessDecisionOptions(cmdJourney.command('run').description('Run the access-to-next-action preparation flow'));
+  addRemoteCommandOptions(
+    cmdJourneyRun
+      .option('--include-command-templates', 'Include command templates for operator-gated actions', false)
+      .option('--operator-gated', 'Request server-authorized operator-gated templates', false)
+      .option('--operator-labels <csv>', 'Comma-separated operator labels')
+      .option('--environment <environment>', 'Execution environment', 'production')
+  ).action(
+    makeAction('journey', (opts, _cmd, isJson) => ({
+      subcommand: 'run',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      actorType: opts.actorType || 'user',
+      actorRef: opts.actorRef || null,
+      userId: opts.userId || null,
+      email: opts.email || null,
+      agentId: opts.agentId || null,
+      authenticated: opts.authenticated === undefined ? null : opts.authenticated,
+      action: opts.action || null,
+      resourceType: opts.resourceType || null,
+      resourceRef: opts.resourceRef || null,
+      resourceId: opts.resourceId || null,
+      resourceKey: opts.resourceKey || null,
+      entitlementKey: opts.entitlementKey || null,
+      entitlementResourceType: opts.entitlementResourceType || null,
+      entitlementResourceId: opts.entitlementResourceId || null,
+      policyName: opts.policyName || null,
+      policyContext: opts.policyContext || null,
+      usageFeatureKey: opts.usageFeatureKey || null,
+      usageDimensions: opts.usageDimensions || null,
+      x402ResourceKey: opts.x402ResourceKey || null,
+      approvalId: opts.approvalId || null,
+      approvalRequired: Boolean(opts.approvalRequired),
+      authorityScope: opts.authorityScope || 'application',
+      context: opts.context || null,
+      idempotencyKey: opts.idempotencyKey || null,
+      correlationId: opts.correlationId || null,
+      includeCommandTemplates: Boolean(opts.includeCommandTemplates),
+      operatorGated: Boolean(opts.operatorGated),
+      operatorLabels: opts.operatorLabels || null,
+      environment: opts.environment || 'production',
+      json: isJson,
+    }))
+  );
+  allowDryRun(cmdJourneyRun);
+
+  // spaps graph <nodes|paths|impact>
+  const cmdGraph = program
+    .command('graph')
+    .description('Inspect the materialized SPAPS capability graph')
+    .showHelpAfterError()
+    .showSuggestionAfterError();
+  if (!dryRun) {
+    cmdGraph.action(() => {
+      cmdGraph.outputHelp();
+    });
+  }
+  allowDryRun(cmdGraph);
+
+  addRemoteCommandOptions(
+    cmdGraph.command('nodes')
+      .description('List capability graph nodes')
+      .option('--application-id <id>', 'Explicit application id for super-admin reads')
+      .option('--node-type <type>', 'Filter by node type')
+      .option('--status <status>', 'Filter by row status', 'active')
+      .option('-q, --query <query>', 'Case-insensitive label search')
+      .option('--cursor <cursor>', 'Pagination cursor')
+      .option('--limit <n>', 'Pagination limit')
+  ).action(
+    makeAction('graph', (opts, _cmd, isJson) => ({
+      subcommand: 'nodes',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      applicationId: opts.applicationId || null,
+      nodeType: opts.nodeType || null,
+      status: opts.status || 'active',
+      query: opts.query || null,
+      cursor: opts.cursor || null,
+      limit: opts.limit ? Number(opts.limit) : null,
+      json: isJson,
+    }))
+  );
+
+  addRemoteCommandOptions(
+    cmdGraph.command('paths')
+      .description('Find bounded paths between two graph nodes')
+      .requiredOption('--from <node_key>', 'Starting node key')
+      .requiredOption('--to <node_key>', 'Target node key')
+      .option('--application-id <id>', 'Explicit application id for super-admin reads')
+      .option('--max-depth <n>', 'Maximum path depth')
+      .option('--limit <n>', 'Path limit')
+      .option('--include-stale', 'Include stale graph rows', false)
+  ).action(
+    makeAction('graph', (opts, _cmd, isJson) => ({
+      subcommand: 'paths',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      applicationId: opts.applicationId || null,
+      fromNodeKey: opts.from || null,
+      toNodeKey: opts.to || null,
+      maxDepth: opts.maxDepth ? Number(opts.maxDepth) : null,
+      limit: opts.limit ? Number(opts.limit) : null,
+      includeStale: Boolean(opts.includeStale),
+      json: isJson,
+    }))
+  );
+
+  addRemoteCommandOptions(
+    cmdGraph.command('impact')
+      .description('Traverse outward from one graph node')
+      .requiredOption('--node-key <node_key>', 'Starting node key')
+      .option('--application-id <id>', 'Explicit application id for super-admin reads')
+      .option('--max-depth <n>', 'Maximum traversal depth')
+      .option('--limit <n>', 'Result limit')
+      .option('--include-stale', 'Include stale graph rows', false)
+  ).action(
+    makeAction('graph', (opts, _cmd, isJson) => ({
+      subcommand: 'impact',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      applicationId: opts.applicationId || null,
+      nodeKey: opts.nodeKey || null,
+      maxDepth: opts.maxDepth ? Number(opts.maxDepth) : null,
+      limit: opts.limit ? Number(opts.limit) : null,
+      includeStale: Boolean(opts.includeStale),
+      json: isJson,
+    }))
+  );
+
+  addRemoteCommandOptions(
+    cmdGraph.command('refresh')
+      .description('Refresh the capability graph projection')
+      .option('--application-id <id>', 'Explicit application id for super-admin refresh')
+      .option('--correlation-id <id>', 'Correlation id for audit and projection diagnostics')
+  ).action(
+    makeAction('graph', (opts, _cmd, isJson) => ({
+      subcommand: 'refresh',
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      applicationId: opts.applicationId || null,
+      correlationId: opts.correlationId || null,
+      json: isJson,
+    }))
+  );
+
+  // spaps explain <decision-id>
+  const cmdExplain = addRemoteCommandOptions(
+    program
+      .command('explain <decision-id>')
+      .description('Explain one persisted access decision trace')
+  ).action(
+    makeAction('explain', (opts, cmd, isJson) => ({
+      decisionId: cmd.args[0],
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      json: isJson,
+    }))
+  );
+  allowDryRun(cmdExplain);
+
+  // spaps contract
+  const cmdContract = addRemoteCommandOptions(
+    program
+      .command('contract')
+      .description('Fetch the capability graph client contract')
+  ).action(
+    makeAction('contract', (opts, _cmd, isJson) => ({
+      port: Number(opts.port) || DEFAULT_PORT,
+      serverUrl: opts.serverUrl || null,
+      json: isJson,
+    }))
+  );
+  allowDryRun(cmdContract);
+
   return { program, getIntents: () => intents };
 }
 

package/src/doctor.js

@@ -7,6 +7,11 @@ const chalk = require('chalk');
 const { getServerStatus } = require('./ai-helper');
 const { DEFAULT_PORT } = require('./config');
 const { listDomains } = require('./domains');
+const {
+  buildAuthDoctorChecks,
+  fetchAuthMethods,
+  resolveDiagnosticOrigin,
+} = require('./auth/surface');
 
 function checkNodeVersion() {
   const version = process.versions.node || '0.0.0';
@@ -20,9 +25,9 @@ function checkNodeVersion() {
   };
 }
 
-async function checkPort(port) {
+async function checkPort(port, serverUrl = null) {
   // If server is running, we consider port check OK
-  const status = await getServerStatus(port);
+  const status = await getServerStatus({ port, serverUrl });
   if (status.running) {
     return {
       check: 'port',
@@ -31,6 +36,14 @@ async function checkPort(port) {
       fix: null
     };
   }
+  if (serverUrl) {
+    return {
+      check: 'port',
+      success: false,
+      details: { port, running: false, url: status.url, error: status.error || null },
+      fix: `Check SPAPS_API_URL or --server-url (${status.url})`,
+    };
+  }
   // Otherwise ensure port is free to bind
   const free = await new Promise((resolve) => {
     const tester = net.createServer()
@@ -224,22 +237,99 @@ async function checkDomainMounts(port) {
   return Promise.all(listDomains().map((d) => probeDomain(port, d)));
 }
 
+async function checkAuthSurface({
+  port = DEFAULT_PORT,
+  serverUrl = null,
+  origin = null,
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  const runtime = await getServerStatus({ port, serverUrl });
+  if (!runtime.running) {
+    return [
+      {
+        check: 'auth_methods',
+        success: false,
+        details: { running: false, url: runtime.url, error: runtime.error || null },
+        fix: `Start the SPAPS server or pass --server-url to a reachable server before checking /api/auth/methods.`,
+      },
+    ];
+  }
+
+  const resolvedOrigin = resolveDiagnosticOrigin({ origin });
+  try {
+    const discovery = await fetchAuthMethods({
+      port,
+      serverUrl: runtime.url,
+      origin: resolvedOrigin,
+      cwd,
+      env,
+    });
+    const checks = await buildAuthDoctorChecks({
+      methods: discovery.methods,
+      runtime,
+      origin: resolvedOrigin,
+    });
+    const matrix = checks.find((check) => check.check === 'auth_methods');
+    if (matrix) {
+      matrix.details = {
+        ...matrix.details,
+        server_url: discovery.serverUrl,
+        origin: resolvedOrigin,
+        api_key_source: discovery.apiKeySource,
+      };
+    }
+    return checks;
+  } catch (err) {
+    const status = err.status || null;
+    return [
+      {
+        check: 'auth_methods',
+        success: false,
+        details: {
+          server_url: runtime.url,
+          origin: resolvedOrigin,
+          status,
+          code: err.code || 'AUTH_METHODS_FAILED',
+          error: err.message || String(err),
+        },
+        fix:
+          status === 401 || status === 403
+            ? 'Set SPAPS_API_KEY and SPAPS_ORIGIN (or pass --origin) for the application whose auth methods you are diagnosing.'
+            : 'Ensure GET /api/auth/methods is mounted and reachable on the configured SPAPS server.',
+      },
+    ];
+  }
+}
+
 function formatHuman(results) {
   const ok = results.every(r => r.success);
   console.log(chalk.yellow('\n🍠 SPAPS Doctor\n'));
   results.forEach(r => {
     const icon = r.success ? chalk.green('✔') : chalk.red('✖');
     console.log(`${icon} ${r.check} ${chalk.gray(JSON.stringify(r.details))}`);
+    if (r.check === 'auth_methods' && Array.isArray(r.details?.methods)) {
+      r.details.methods.forEach((method) => {
+        const state = method.enabled ? chalk.green('enabled') : chalk.gray('disabled');
+        console.log(`   ${method.method}: ${state}`);
+      });
+    }
     if (!r.success && r.fix) console.log(chalk.cyan(`   fix: ${r.fix}`));
   });
   console.log();
   console.log(ok ? chalk.green('All checks passed!') : chalk.red('Some checks failed. See fixes above.'));
 }
 
-async function runDoctor({ port = DEFAULT_PORT, stripe = null, json = false } = {}) {
+async function runDoctor({
+  port = DEFAULT_PORT,
+  serverUrl = null,
+  stripe = null,
+  json = false,
+  origin = null,
+} = {}) {
   const results = [];
   results.push(checkNodeVersion());
-  results.push(await checkPort(port));
+  results.push(await checkPort(port, serverUrl));
   // Warn if using 3000 which often collides with Next.js
   if (port === 3000) {
     results.push({
@@ -260,6 +350,8 @@ async function runDoctor({ port = DEFAULT_PORT, stripe = null, json = false } =
   results.push(await checkWebhook(port));
   const domainResults = await checkDomainMounts(port);
   results.push(...domainResults);
+  const authResults = await checkAuthSurface({ port, serverUrl, origin });
+  results.push(...authResults);
 
   const ok = results.every(r => r.success);
   const payload = { success: ok, results, next_steps: ok ? [] : ['Apply suggested fixes and re-run: npx spaps doctor --json'] };
@@ -271,4 +363,4 @@ async function runDoctor({ port = DEFAULT_PORT, stripe = null, json = false } =
   return payload;
 }
 
-module.exports = { runDoctor, checkDomainMounts };
+module.exports = { runDoctor, checkDomainMounts, checkAuthSurface };

package/src/domain-cli.js

@@ -29,6 +29,7 @@ async function callEndpoint({ options = {}, method = 'GET', path, body = null, q
     return {
       status: res.status,
       data: res.data,
+      raw: res.raw,
       ok: res.status >= 200 && res.status < 300,
     };
   } catch (err) {