@moda-ai/cli 1.13.0 → 1.13.1

package/dist/cli-session.d.ts

@@ -0,0 +1,26 @@
+import { CliAuthError } from './errors.js';
+import { type AuthSessionOptions, type StoredAuth } from './auth-storage.js';
+/**
+ * Fire-and-forget sliding-expiry renewal, invoked on every authenticated
+ * request: a no-op unless the session is a moda_ct token inside the renewal
+ * window. Never awaited by callers, never throws, never holds the process
+ * open (unref'd socket); on success the stored expires_at is rewritten in
+ * place.
+ */
+export declare function scheduleRenewalIfNearExpiry(session: StoredAuth, authOptions: AuthSessionOptions): void;
+/** The CliAuthError thrown whenever a stored moda_ct session has expired. */
+export declare function cliSessionExpiredError(): CliAuthError;
+/**
+ * Classify a 401 for a moda_ct session. Returns the CliAuthError to throw,
+ * or null when the renew probe says the token is actually alive (the caller
+ * then surfaces the original response unchanged).
+ */
+export declare function classifyModaCtUnauthorized(session: StoredAuth, authOptions: AuthSessionOptions): Promise<CliAuthError | null>;
+/**
+ * Best-effort server-side revocation of a stored moda_ct session token,
+ * called by `moda auth logout` before local deletion. No-op for legacy
+ * auth0-kind sessions; all failures are swallowed (the local deletion is
+ * the contract).
+ */
+export declare function revokeCliSessionToken(options?: AuthSessionOptions): Promise<void>;
+//# sourceMappingURL=cli-session.d.ts.map

package/dist/cli-session.js

@@ -0,0 +1,169 @@
+// src/cli-session.ts — moda_ct CLI session token lifecycle: renewal
+// (sliding expiry), revocation, and 401 classification against the
+// /api/cli/auth/* endpoints.
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { resolveModaBaseUrl } from './config.js';
+import { CliAuthError } from './errors.js';
+import { isModaCtSession, loadAuthSession, persistAuthSession, } from './auth-storage.js';
+// Background sliding-expiry renewal fires when a moda_ct session has less
+// than this long left.
+const RENEW_WINDOW_SECONDS = 7 * 86_400;
+const RENEW_TIMEOUT_MS = 10_000;
+// Synchronous renew probe used to classify a 401, and best-effort revoke on
+// logout: both must never stall a command, so they get a tight budget.
+const RENEW_PROBE_TIMEOUT_MS = 2_000;
+const REVOKE_TIMEOUT_MS = 2_000;
+/**
+ * POST an Authorization-bearer request to a CLI session lifecycle endpoint
+ * (/api/cli/auth/renew or /api/cli/auth/revoke) over raw node http/https.
+ * Not fetch: the background renewal must never delay process exit, and only
+ * a raw socket can be unref'd. Rejects on network failure or timeout.
+ */
+function postCliSessionEndpoint(path, token, timeoutMs, opts = {}) {
+    return new Promise((resolve, reject) => {
+        let url;
+        try {
+            // Resolve the origin from the same profile/env context the session was
+            // loaded with: a `--profile staging` session's renew/revoke must hit the
+            // staging backend that minted it, not the active/default profile's.
+            url = new URL(`${resolveModaBaseUrl(opts.authOptions)}${path}`);
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        const requestFn = url.protocol === 'https:' ? httpsRequest : httpRequest;
+        const req = requestFn(url, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}` },
+            timeout: timeoutMs,
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                resolve({
+                    status: res.statusCode ?? 0,
+                    body: Buffer.concat(chunks).toString('utf8'),
+                });
+            });
+            res.on('error', reject);
+        });
+        if (opts.unrefSocket) {
+            req.on('socket', (socket) => {
+                socket.unref();
+            });
+        }
+        req.on('timeout', () => {
+            req.destroy(new Error(`CLI session request timed out after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+/**
+ * Parse a renew response body and rewrite the stored session's expiry in
+ * place, preserving the profile scoping the session was loaded with.
+ * Best-effort: an unreadable or incomplete body is simply ignored.
+ */
+function persistRenewedExpiry(session, body, authOptions) {
+    try {
+        const parsed = JSON.parse(body);
+        const expiresAtMs = typeof parsed.expires_at === 'string' ? Date.parse(parsed.expires_at) : NaN;
+        if (!Number.isFinite(expiresAtMs))
+            return;
+        persistAuthSession({ ...session, expires_at: Math.floor(expiresAtMs / 1000) }, authOptions);
+    }
+    catch {
+        // Best-effort persistence only.
+    }
+}
+// Stampede guard: at most one background renewal in flight per process.
+let renewInFlight = false;
+/**
+ * Fire-and-forget sliding-expiry renewal, invoked on every authenticated
+ * request: a no-op unless the session is a moda_ct token inside the renewal
+ * window. Never awaited by callers, never throws, never holds the process
+ * open (unref'd socket); on success the stored expires_at is rewritten in
+ * place.
+ */
+export function scheduleRenewalIfNearExpiry(session, authOptions) {
+    if (!isModaCtSession(session))
+        return;
+    if (session.expires_at - Date.now() / 1000 >= RENEW_WINDOW_SECONDS)
+        return;
+    if (renewInFlight)
+        return;
+    renewInFlight = true;
+    void (async () => {
+        try {
+            const result = await postCliSessionEndpoint('/api/cli/auth/renew', session.access_token, RENEW_TIMEOUT_MS, { unrefSocket: true, authOptions });
+            if (result.status !== 200)
+                return;
+            persistRenewedExpiry(session, result.body, authOptions);
+        }
+        catch {
+            // Silent by design: renewal is opportunistic, the command result must
+            // not depend on it.
+        }
+        finally {
+            renewInFlight = false;
+        }
+    })();
+}
+/** The CliAuthError thrown whenever a stored moda_ct session has expired. */
+export function cliSessionExpiredError() {
+    return new CliAuthError('The stored CLI session token has expired. Run "moda auth login" to sign in again.', { reason: 'token_expired', login_command: ['moda', 'auth', 'login'] });
+}
+/**
+ * Classify a 401 for a moda_ct session. Returns the CliAuthError to throw,
+ * or null when the renew probe says the token is actually alive (the caller
+ * then surfaces the original response unchanged).
+ */
+export async function classifyModaCtUnauthorized(session, authOptions) {
+    const loginCommand = ['moda', 'auth', 'login'];
+    if (Date.now() / 1000 > session.expires_at) {
+        return cliSessionExpiredError();
+    }
+    let probe;
+    try {
+        probe = await postCliSessionEndpoint('/api/cli/auth/renew', session.access_token, RENEW_PROBE_TIMEOUT_MS, { authOptions });
+    }
+    catch {
+        return new CliAuthError('The Moda API rejected the stored CLI session token, and the renewal check could not reach the server. ' +
+            'The token has not expired, so this is likely transient: retry the command instead of logging in again.', { reason: 'renew_failed', login_command: loginCommand });
+    }
+    if (probe.status === 401) {
+        return new CliAuthError('The stored CLI session token has been revoked. Run "moda auth login" to sign in again.', { reason: 'token_revoked', login_command: loginCommand });
+    }
+    if (probe.status === 200) {
+        // The token is demonstrably alive (the probe just slid its expiry) but
+        // the original request still 401'd; persist the fresh expiry and let the
+        // caller see the original response.
+        persistRenewedExpiry(session, probe.body, authOptions);
+        return null;
+    }
+    // Any other renew status (e.g. a 5xx) is indistinguishable from a
+    // transient server problem: same retry guidance as a network failure.
+    return new CliAuthError('The Moda API rejected the stored CLI session token, and the renewal check failed ' +
+        `(HTTP ${probe.status}). The token has not expired, so this is likely transient: ` +
+        'retry the command instead of logging in again.', { reason: 'renew_failed', login_command: loginCommand });
+}
+/**
+ * Best-effort server-side revocation of a stored moda_ct session token,
+ * called by `moda auth logout` before local deletion. No-op for legacy
+ * auth0-kind sessions; all failures are swallowed (the local deletion is
+ * the contract).
+ */
+export async function revokeCliSessionToken(options = {}) {
+    const session = loadAuthSession({ ...options, includeExpired: true });
+    if (!session || !isModaCtSession(session))
+        return;
+    try {
+        await postCliSessionEndpoint('/api/cli/auth/revoke', session.access_token, REVOKE_TIMEOUT_MS, { authOptions: options });
+    }
+    catch {
+        // Best-effort: logout proceeds with local deletion regardless.
+    }
+}
+//# sourceMappingURL=cli-session.js.map

package/dist/init/index.js

@@ -44,8 +44,13 @@ export async function runInit(flags, options = {}) {
     emit('welcome', 'Onboarding this project as a Moda agent harness.', 'completed');
     phases.push({ id: 'welcome', title: 'Welcome', status: 'completed' });
     // Step 2: Authentication
+    // Every auth touchpoint below (cached-token check, browser login, tenant
+    // setup) must share the same --profile context, or `moda init --profile X`
+    // logs in / stores under the default profile while the rest of init reads
+    // from X — the session then looks unauthenticated or uses the wrong key.
+    const profile = stringFlag(flags.profile);
     log(renderInitStep(2, 7, 'Authentication'));
-    let token = loadToken();
+    let token = loadToken({ profile });
     if (!token) {
         if (json || agent) {
             throw new CliAuthError('Browser authentication is required before non-interactive init can continue.', {
@@ -66,7 +71,7 @@ export async function runInit(flags, options = {}) {
         }
         log(renderInitNote(`Opening browser to ${action === 'signup' ? 'sign up' : 'log in'}...`, 'warning'));
         emit('auth', `Opening browser to ${action}.`);
-        token = await login(action);
+        token = await login(action, { profile });
         log(renderInitNote('Authentication successful'));
     }
     else {
@@ -87,7 +92,7 @@ export async function runInit(flags, options = {}) {
         nonInteractive: json || agent,
         silent: !human,
         resumeCommand: ['moda', 'init', ...resumeFlagsForInit(flags)],
-        profile: stringFlag(flags.profile),
+        profile,
     });
     log(renderInitNote(`Active workspace: ${tenantName}`));
     emit('workspace', `Active workspace: ${tenantName}`, 'completed');

package/dist/init/tenant.js

@@ -1,6 +1,6 @@
 // src/init/tenant.ts — Tenant selection and API key provisioning
 import { select } from '@inquirer/prompts';
-import { authFetch } from '../auth.js';
+import { authFetch, getCachedLoginContext } from '../auth.js';
 import { loadCliConfig, resolveIngestUrl, resolveModaBaseUrl, saveCliConfig, } from '../config.js';
 import { resolveApiKeyFromActiveProfile, resolveTenantIdFromActiveProfile, } from '../profiles.js';
 import { CliAccessError, CliInputError, CliInputRequiredError } from '../errors.js';
@@ -99,13 +99,24 @@ export async function selectTenantAndCreateKey(options = {}) {
         profile: options.profile,
         env: options.env,
     };
-    // 1. Fetch CLI context
-    const contextRes = await authFetch('/api/cli/context', {}, authOptions);
-    if (!contextRes.ok) {
-        const body = await contextRes.text();
-        throw new Error(`Failed to fetch context (${contextRes.status}): ${body}`);
+    // 1. Fetch CLI context. A PKCE login that just ran in this process already
+    // returned the user + tenants in the exchange response; reuse it and skip
+    // one /api/cli/context round-trip. The cache is profile-keyed (a login for
+    // a different profile returns null here), and the fetch stays as the
+    // fallback for cached-token runs (no login happened) and legacy logins.
+    let ctx;
+    const cachedContext = getCachedLoginContext(authOptions);
+    if (cachedContext) {
+        ctx = cachedContext;
+    }
+    else {
+        const contextRes = await authFetch('/api/cli/context', {}, authOptions);
+        if (!contextRes.ok) {
+            const body = await contextRes.text();
+            throw new Error(`Failed to fetch context (${contextRes.status}): ${body}`);
+        }
+        ctx = (await contextRes.json());
     }
-    const ctx = (await contextRes.json());
     log(`  Authenticated as ${ctx.user.email}`);
     // 2. Select tenant
     if (ctx.tenants.length === 0) {

package/dist/profile-commands.js

@@ -1,4 +1,4 @@
-import { authFetch, clearAuthSession, isAuthSessionValid, loadAuthSession, login } from './auth.js';
+import { authFetch, clearAuthSession, isAuthSessionValid, loadAuthSession, login, revokeCliSessionToken, } from './auth.js';
 import { EXIT_AUTH_REQUIRED, EXIT_OK } from './output.js';
 import { KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS, createLocalKeyDescriptor, loadLocalKeyDescriptors, upsertLocalKeyDescriptor, writeLocalApiKeySecret, } from './keys.js';
 import { DEFAULT_INGEST_URL, PROD_BASE_URL, ensureSecretFilePermissions, getActiveProfile, getModaPaths, loadProfileConfig, resolveApiKeyFromActiveProfile, resolveSecretReference, secretFilePathFromRef, setActiveProfile, upsertProfile, } from './profiles.js';
@@ -72,6 +72,10 @@ export async function runAuthCommand(context) {
             return { exitCode: 0 };
         }
         case 'logout': {
+            // moda_ct session tokens are server-side revocable: best-effort revoke
+            // (bounded, catch-all inside) before the local deletion. Legacy
+            // auth0-kind sessions have nothing to revoke.
+            await revokeCliSessionToken({ profile: context.profile, env: context.env });
             clearAuthSession({ profile: context.profile, env: context.env });
             context.output.writeData({
                 status: 'logged_out',
@@ -119,6 +123,11 @@ export async function runAuthCommand(context) {
                     ? new Date(session.expires_at * 1000).toISOString()
                     : null,
             };
+            // `user` is emitted only when the stored session carries an email —
+            // the PKCE exchange path persists user_email; legacy sessions lack it.
+            if (session?.user_email) {
+                data.user = { email: session.user_email };
+            }
             if (boolFlag(context, 'online')) {
                 let online = { reachable: false };
                 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-07-06T09:53:55.227Z",
-  "cli_version": "1.13.0",
+  "bundled_at": "2026-07-06T10:28:52.049Z",
+  "cli_version": "1.13.1",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -78,6 +78,53 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+### Auth session inspection and token composition
+
+```bash
+moda auth login                  # browser PKCE sign-in; stores a moda_ct_ session token
+moda auth logout                 # revoke the session server-side, then delete it locally
+moda auth status                 # local session state; exit 0 logged in, exit 4 logged out
+moda auth status --online        # additionally probe GET /api/cli/context
+moda auth token                  # print the raw bearer token + newline, nothing else
+curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/context
+```
+
+- `moda auth login` opens the browser consent flow at `{MODA_BASE_URL}/auth/cli`
+  with a localhost callback (ports 8432-8435, first free). Approving in the
+  browser hands the CLI a one-time code that it exchanges for a `moda_ct_...`
+  session token (sliding 30-day expiry, renewed automatically in the
+  background while you keep using the CLI). If the browser cannot reach the
+  machine, paste the callback URL or the code shown on the consent page into
+  the terminal.
+- `moda auth logout` revokes the stored `moda_ct_` session server-side
+  (best-effort) and deletes the local credential; legacy sessions are just
+  deleted locally.
+- `moda auth status` reports
+  `{ "loggedIn": <bool>, "profile": <string|null>, "expiresAt": <ISO|null> }`
+  plus `"user": { "email": <string> }` when the stored session carries an
+  email (PKCE `moda_ct_` sessions do; legacy sessions omit it), and exits `4`
+  when logged out. That exit is an **expected state signal, not
+  an error**: the payload is clean data (no error block, no stderr noise), and
+  no browser is ever opened. With `--online` the payload adds
+  `{ "online": { "reachable": <bool>, "ok": <bool>, "tenantCount": <n> } }`:
+  `reachable: true` means any HTTP response arrived (even a 401/500), `ok`
+  reflects HTTP success, and `tenantCount` is present only when the response
+  was ok and carried a tenants array. A network failure or probe timeout
+  (5 s) yields `reachable: false`; the exit code always follows local session
+  validity only, never the probe.
+- `moda auth token` writes exactly the bare token plus a trailing newline to
+  stdout in **every** output mode — including piped/json/agent, because
+  command substitution is a pipe — so `$(moda auth token)` composes safely
+  with no envelope to strip. When logged out it prints a stderr message and
+  exits `4`; with an explicit `--json` flag it instead prints
+  `{"error":"not_authenticated"}` to stdout (still exit `4`).
+- `moda auth token` prints whichever credential kind is stored. Newer logins
+  store a `moda_ct_...` CLI session token, which authenticates **`/api/cli/*`
+  endpoints only** — it is not accepted by the Data API (`/api/v1/data/*`
+  wants a `moda_sk_...` API key) or other dashboard endpoints. Legacy
+  sessions print the Auth0 bearer token as before.
+- Both respect `--profile=NAME` and `MODA_PROFILE`.
+
 ## Agent protocol
 
 Run `moda manifest --json` first when integrating with the CLI. It returns the
@@ -117,10 +164,73 @@ Branch on the exit code; it is stable and cheaper than parsing the payload:
 | `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
 | `1` | error — bad input, API/network failure, or unexpected failure | Read `errors[]`; retry only when the code is retryable. |
 | `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
-| `4` | auth required | Run `auth.login_command`, then re-run `auth.resume_command` if present. |
-| `5` | input required | Pick a choice, append its `resume_flags`, and re-run. |
+| `4` | auth required — credentials are missing or expired | Run the `login_command` from the `auth` payload (`moda auth login`), then re-run `resume_command`. |
+| `5` | input required — a choice is needed that the non-interactive run could not answer | Pick a choice from the `input_request` payload and re-invoke the same command with that choice's `resume_flags` appended. |
 | `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
 
+Exit codes `4` and `5` are recoverable-by-caller failures: the envelope's
+`errors[]` entry carries the exact commands/flags to recover with, as argv
+arrays (execute element-wise; join with spaces only for display).
+
+#### `auth_required` payload (exit `4`)
+
+The envelope's `errors[]` entry carries the recovery data on its `auth` field
+(in `--agent --stream` mode the same error arrives as an NDJSON event with
+`"event": "auth_required"`):
+
+```json
+{
+  "code": "auth_required",
+  "message": "Browser authentication is required before non-interactive init can continue.",
+  "suggested_commands": ["moda auth login", "moda init --yes"],
+  "blocking": true,
+  "auth": {
+    "reason": "no_stored_credentials",
+    "login_command": ["moda", "auth", "login"],
+    "resume_command": ["moda", "init", "--yes"]
+  }
+}
+```
+
+`reason` is one of:
+
+- `no_stored_credentials` — no session stored. Run `login_command`, then
+  `resume_command` (when present).
+- `token_expired` — the stored session expired. Run `login_command`, then
+  `resume_command`.
+- `token_revoked` — the stored `moda_ct_` CLI session token was revoked
+  server-side (e.g. from the dashboard). Run `login_command`, then
+  `resume_command`.
+- `renew_failed` — the API rejected an **unexpired** `moda_ct_` token but the
+  renewal check could not reach the server, so this is likely transient:
+  **retry the command; do not re-login.**
+
+#### `needs_input` payload (exit `5`)
+
+The envelope's `errors[]` entry carries the recovery data on its
+`input_request` field (in `--agent --stream` mode the event type is
+`"needs_input"`):
+
+```json
+{
+  "code": "needs_input",
+  "message": "An organization must be selected to continue.",
+  "blocking": true,
+  "input_request": {
+    "id": "init_tenant_selection",
+    "question": "Select organization",
+    "kind": "select",
+    "choices": [
+      { "value": "tnt_a", "label": "Acme (owner)", "resume_flags": ["--tenant-id", "tnt_a"] },
+      { "value": "tnt_b", "label": "Beta (viewer)", "resume_flags": ["--tenant-id", "tnt_b"] }
+    ]
+  }
+}
+```
+
+Re-invoke the original command with the chosen `resume_flags` appended (here:
+`moda init --tenant-id tnt_a`).
+
 ### The `moda.agent.v1` envelope
 
 Fields an agent should read:
@@ -584,6 +694,10 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | Command | Purpose |
 |---|---|
 | `moda init` | Browser auth + provision API key + install agent rules |
+| `moda auth login` | Browser PKCE sign-in; stores a revocable `moda_ct_` session token |
+| `moda auth logout` | Revoke the CLI session server-side, then delete it locally |
+| `moda auth status` | Local auth session state (exit `4` = logged out — expected, not an error) |
+| `moda auth token` | Print the raw bearer token for `$(moda auth token)` composition |
 | `moda search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
 | `moda overview` | Dashboard KPIs, top clusters, recent activity |
 | `moda ask "<question>"` | Natural-language production/harness answer with evidence (exit `3` = degraded local fallback) |