@moda-ai/cli 1.13.0 → 1.13.2

package/dist/init/tenant.js

@@ -1,8 +1,12 @@
 // src/init/tenant.ts — Tenant selection and API key provisioning
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
 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 { getModaDir, resolveApiKeyFromActiveProfile, resolveTenantIdFromActiveProfile, writeSecretJsonFile, } from '../profiles.js';
 import { CliAccessError, CliInputError, CliInputRequiredError } from '../errors.js';
 // Mirrors the backend's checkAdminAccess: only the viewer role is denied.
 const ADMIN_ACCESS_MESSAGE = 'You need admin or owner access to create API keys.';
@@ -12,6 +16,118 @@ const SIGNED_KEY_VERSION = 'v1';
 // Bound the pre-bootstrap liveness probe tightly: a slow or unreachable
 // endpoint must never block init — we just mint a fresh key instead.
 const VALIDATE_TIMEOUT_MS = 3_000;
+/**
+ * Post-bootstrap validate-retry schedule (WP-2.3): key provisioning spans
+ * Postgres + Cloudflare KV, so a freshly minted key can lag a moment before
+ * it validates. Retry the liveness probe at these delays (3 attempts after
+ * the initial call, ~3.5s of retry sleeps plus up to VALIDATE_TIMEOUT_MS per
+ * probe against a hanging endpoint) before warning and moving on.
+ */
+const POST_BOOTSTRAP_VALIDATE_DELAYS_MS = [
+    500, 1_000, 2_000,
+];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// The backend truncates the bootstrap label to 60 printable chars; clip the
+// hostname client-side too so what we send is what lands on the key name.
+const MAX_LABEL_LENGTH = 60;
+// Backend contract for the Idempotency-Key header (UUIDs match this too).
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * State file backing bootstrap idempotency across process restarts:
+ * ~/.moda/pending-bootstrap.json maps tenant id -> the Idempotency-Key of an
+ * in-flight (or failed) bootstrap POST. Written BEFORE the POST and cleared
+ * on success, so a retry after a network failure reuses the same key and the
+ * backend replays the original response instead of minting another ApiKey.
+ *
+ * Deliberately global (~/.moda, like config.json) and shared across
+ * profiles: the server scopes keys to the authenticated user, so the worst
+ * case of cross-profile sharing is one extra key minted — not worth
+ * profile-scoping the file.
+ */
+function pendingBootstrapPath(options = {}) {
+    return join(getModaDir(options), 'pending-bootstrap.json');
+}
+function loadPendingBootstrapState(options = {}) {
+    try {
+        const path = pendingBootstrapPath(options);
+        if (!existsSync(path))
+            return {};
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        const state = {};
+        for (const [tenantId, entry] of Object.entries(parsed)) {
+            if (entry &&
+                typeof entry === 'object' &&
+                typeof entry.idempotency_key === 'string') {
+                state[tenantId] = entry;
+            }
+        }
+        return state;
+    }
+    catch {
+        // A corrupt state file must never block init; fresh keys are always safe.
+        return {};
+    }
+}
+/**
+ * Return the Idempotency-Key to use for this tenant's bootstrap POST,
+ * persisting it before the network call. A key left over from a previous
+ * failed attempt is reused so the retry replays instead of double-minting.
+ * File-system failures degrade to an in-memory key (init must never block).
+ */
+function reserveBootstrapIdempotencyKey(tenantId, options = {}) {
+    const state = loadPendingBootstrapState(options);
+    const existing = state[tenantId]?.idempotency_key;
+    if (existing && IDEMPOTENCY_KEY_PATTERN.test(existing)) {
+        return existing;
+    }
+    const key = randomUUID();
+    state[tenantId] = {
+        idempotency_key: key,
+        created_at: new Date().toISOString(),
+    };
+    try {
+        writeSecretJsonFile(pendingBootstrapPath(options), state);
+    }
+    catch {
+        // Best-effort persistence: without it a retry mints a fresh key, which
+        // is the pre-idempotency behavior, not a failure.
+    }
+    return key;
+}
+/** Clear the tenant's pending key after a successful bootstrap. */
+function clearBootstrapIdempotencyKey(tenantId, options = {}) {
+    try {
+        const state = loadPendingBootstrapState(options);
+        if (!(tenantId in state))
+            return;
+        delete state[tenantId];
+        const path = pendingBootstrapPath(options);
+        if (Object.keys(state).length === 0) {
+            rmSync(path, { force: true });
+        }
+        else {
+            writeSecretJsonFile(path, state);
+        }
+    }
+    catch {
+        // Leftover state is harmless: the key replays the stored response.
+    }
+}
+/** Label sent in the bootstrap body; the backend sanitizes it further. */
+function bootstrapLabel(custom) {
+    const clipped = custom?.trim().slice(0, MAX_LABEL_LENGTH);
+    if (clipped)
+        return clipped;
+    try {
+        return hostname().slice(0, MAX_LABEL_LENGTH) || 'moda init';
+    }
+    catch {
+        return 'moda init';
+    }
+}
 /**
  * Signed CLI keys embed their tenant: the format is
  * moda_sk_<base64url("v1:keyId:tenantId:timestamp:signature")> — see
@@ -87,6 +203,27 @@ function findStoredKeyForTenant(tenantId, options = {}) {
     }
     return undefined;
 }
+/**
+ * Post-bootstrap verification (WP-2.3): confirm a freshly minted key is live
+ * before declaring success, reusing the same Data API probe as dedup.
+ * Provisioning spans Postgres + Cloudflare KV (eventual consistency), so
+ * failures are retried at the POST_BOOTSTRAP_VALIDATE_DELAYS_MS schedule.
+ * Exhaustion is a stderr warning, never an init failure: init's final doctor
+ * step surfaces persistent problems, and blocking here past the retry
+ * schedule would punish every user for a transient propagation delay.
+ */
+async function verifyFreshKeyLive(key, probeOptions, overrides) {
+    const delays = overrides?.delaysMs ?? POST_BOOTSTRAP_VALIDATE_DELAYS_MS;
+    const sleep = overrides?.sleep ?? defaultSleep;
+    if (await isStoredKeyLive(key, probeOptions))
+        return;
+    for (const delayMs of delays) {
+        await sleep(delayMs);
+        if (await isStoredKeyLive(key, probeOptions))
+            return;
+    }
+    console.error('  Warning: API key created but not yet active; propagation can take a few seconds. moda doctor --online will confirm.');
+}
 export async function selectTenantAndCreateKey(options = {}) {
     const log = (message) => {
         if (!options.silent)
@@ -99,13 +236,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) {
@@ -161,11 +309,16 @@ export async function selectTenantAndCreateKey(options = {}) {
     // so re-running init does not accumulate one CLI key per run. A failed
     // decode, tenant mismatch, or probe failure falls through to minting.
     let result;
+    let reused = false;
     const storedKey = findStoredKeyForTenant(selected.id, authOptions);
     if (storedKey &&
         embeddedTenantId(storedKey) === selected.id &&
         (await isStoredKeyLive(storedKey, authOptions))) {
         log(`  Using existing CLI key for ${selected.name} (created earlier)`);
+        // A pending idempotency key left by an earlier failed bootstrap is moot
+        // once the stored key is reused; clear it so it does not linger.
+        clearBootstrapIdempotencyKey(selected.id, authOptions);
+        reused = true;
         result = {
             apiKey: storedKey,
             tenantId: selected.id,
@@ -173,40 +326,79 @@ export async function selectTenantAndCreateKey(options = {}) {
             tenantSlug: selected.slug,
         };
     }
-    // 4. Create API key via bootstrap endpoint
+    // 4. Create API key via bootstrap endpoint. The Idempotency-Key is
+    // persisted to ~/.moda/pending-bootstrap.json BEFORE the POST, so a retry
+    // after a network failure reuses the same key and the backend replays the
+    // original response instead of minting a second ApiKey.
     if (!result) {
+        const idempotencyKey = reserveBootstrapIdempotencyKey(selected.id, authOptions);
         const bootstrapRes = await authFetch('/api/cli/bootstrap', {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ tenantId: selected.id }),
+            headers: {
+                'Content-Type': 'application/json',
+                'Idempotency-Key': idempotencyKey,
+            },
+            body: JSON.stringify({
+                tenantId: selected.id,
+                label: bootstrapLabel(options.label),
+            }),
         }, authOptions);
         if (bootstrapRes.status === 403) {
             throw new CliAccessError(ADMIN_ACCESS_MESSAGE, { guidance: ADMIN_ACCESS_GUIDANCE });
         }
+        if (bootstrapRes.status === 409) {
+            const body = await bootstrapRes.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                // Fall through to the generic error below.
+            }
+            if (parsed?.error === 'cli_key_cap_reached') {
+                throw new CliAccessError(parsed.message ||
+                    'This organization has reached its CLI API key limit.', {
+                    // Command-agnostic: this path is shared by `moda init` and
+                    // `moda provision`.
+                    guidance: 'Revoke old CLI keys in the dashboard (Settings -> API Keys), then retry.',
+                });
+            }
+            throw new Error(`Failed to create API key (409): ${body}`);
+        }
         if (!bootstrapRes.ok) {
             const body = await bootstrapRes.text();
             throw new Error(`Failed to create API key (${bootstrapRes.status}): ${body}`);
         }
         result = (await bootstrapRes.json());
+        clearBootstrapIdempotencyKey(selected.id, authOptions);
+        // Fresh mints only: the reused-key path above already proved liveness
+        // via the dedup probe, so re-validating there would be a wasted call.
+        await verifyFreshKeyLive(result.apiKey, authOptions, options.validateRetry);
     }
     // Persist to ~/.moda/config.json (mode 0600) so the snapshot/session-end
     // hook can authenticate (api_key) and the local dev orchestrator can scope
     // ClickHouse (tenant_id) without the user exporting env vars into the shell
     // that launches Claude. Env still wins over the file at read time.
-    saveCliConfig({
-        api_key: result.apiKey,
-        tenant_id: result.tenantId,
-        ingest_url: resolveIngestUrl(authOptions),
-    }, authOptions);
-    // resolveTenantId() prefers MODA_TENANT_ID over the config file, so a stale
-    // env var silently shadows the selection we just saved. Warn unless the env
-    // var was itself the source of the selection.
-    const envTenantId = (options.env ?? process.env).MODA_TENANT_ID;
-    if (envTenantId && options.tenantIdSource !== 'env' && envTenantId !== result.tenantId) {
-        console.error(`  Warning: MODA_TENANT_ID is set to a different organization id and will shadow the saved selection (${result.tenantId}) for later commands. Unset it or set it to the selected organization id.`);
-    }
-    log('  API key + tenant saved to ~/.moda/config.json\n');
-    log('  (Set MODA_API_KEY / MODA_TENANT_ID to override for scripts/CI.)\n');
-    return result;
+    //
+    // Headless callers (persistConfig: false) skip this block entirely: they
+    // own their credential storage, and the env-shadow warning below only
+    // makes sense when a selection was actually saved.
+    if (options.persistConfig !== false) {
+        saveCliConfig({
+            api_key: result.apiKey,
+            tenant_id: result.tenantId,
+            ingest_url: resolveIngestUrl(authOptions),
+        }, authOptions);
+        // resolveTenantId() prefers MODA_TENANT_ID over the config file, so a stale
+        // env var silently shadows the selection we just saved. Warn unless the env
+        // var was itself the source of the selection.
+        const envTenantId = (options.env ?? process.env).MODA_TENANT_ID;
+        if (envTenantId && options.tenantIdSource !== 'env' && envTenantId !== result.tenantId) {
+            console.error(`  Warning: MODA_TENANT_ID is set to a different organization id and will shadow the saved selection (${result.tenantId}) for later commands. Unset it or set it to the selected organization id.`);
+        }
+        log('  API key + tenant saved to ~/.moda/config.json\n');
+        log('  (Set MODA_API_KEY / MODA_TENANT_ID to override for scripts/CI.)\n');
+    }
+    return { ...result, reused };
 }
 //# sourceMappingURL=tenant.js.map

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/dist/provision.d.ts

@@ -0,0 +1,28 @@
+import { type CommandContext } from './command-context.js';
+export interface ProvisionRunOptions {
+    /**
+     * Original invocation as an argv array (e.g. ['moda', 'provision',
+     * '--save']), threaded into recoverable failures so the caller knows
+     * exactly how to resume after logging in.
+     */
+    resumeCommand?: string[];
+}
+export interface ProvisionResult {
+    exitCode: number;
+    apiKey?: string;
+}
+/**
+ * The credentials document printed to stdout. Field names are a public
+ * contract (`moda provision | jq -r .apiKey`); do not rename.
+ */
+export interface ProvisionPayload {
+    apiKey: string;
+    tenantId: string;
+    tenantName: string;
+    tenantSlug: string;
+    ingestUrl: string;
+    baseUrl: string;
+    reused: boolean;
+}
+export declare function runProvision(context: CommandContext, options?: ProvisionRunOptions): Promise<ProvisionResult>;
+//# sourceMappingURL=provision.d.ts.map

package/dist/provision.js

@@ -0,0 +1,104 @@
+// src/provision.ts — moda provision: headless tenant + API key provisioning
+// for CI jobs and agents. Requires an existing CLI session (moda auth login
+// run previously); browserless signup is explicitly out of scope (decision
+// D3), so a missing session fails fast with CliAuthError instead of opening
+// a browser.
+import { loadAuthSession } from './auth.js';
+import { stringOption } from './command-context.js';
+import { resolveIngestUrl, resolveModaBaseUrl } from './config.js';
+import { CliAuthError } from './errors.js';
+import { selectTenantAndCreateKey } from './init/tenant.js';
+export async function runProvision(context, options = {}) {
+    const resumeCommand = options.resumeCommand ?? ['moda', 'provision'];
+    // Pre-coercion raw values (like init's tenantIdFlag/profileFlag): the
+    // dispatcher's flagsToArgs number-coerces numeric-looking values, which
+    // must never happen to tenant ids, profile names, or labels.
+    const profileFlag = stringOption(context.rawFlags.profile);
+    const authOptions = { profile: profileFlag, env: context.env };
+    // Provision never opens a browser (headless by contract), so the session
+    // check happens up front: no stored session is a recoverable exit-4
+    // failure with explicit instructions, not a login prompt.
+    const session = loadAuthSession(authOptions);
+    if (!session) {
+        const expiredSession = loadAuthSession({ ...authOptions, includeExpired: true });
+        throw new CliAuthError('moda provision requires an existing CLI session and never opens a browser. ' +
+            'Run "moda auth login" on a machine with a browser first, then re-run provision here ' +
+            '(or skip provisioning and set MODA_API_KEY directly).', {
+            reason: expiredSession ? 'token_expired' : 'no_stored_credentials',
+            login_command: ['moda', 'auth', 'login'],
+            resume_command: resumeCommand,
+        });
+    }
+    const flagTenantId = stringOption(context.rawFlags['tenant-id'] ?? context.rawFlags.tenant_id);
+    const envTenantId = stringOption(context.env.MODA_TENANT_ID);
+    const label = stringOption(context.rawFlags.label);
+    const save = context.flags.save === 'true';
+    // Reuses init's dedup + bootstrap machinery (stored-key liveness probe,
+    // Idempotency-Key persistence, label, cap/viewer errors). Multi-tenant
+    // accounts without --tenant-id/MODA_TENANT_ID throw CliInputRequiredError
+    // (exit 5) with per-tenant resume flags — even on a TTY, provision is
+    // headless by contract and never prompts.
+    let result;
+    try {
+        result = await selectTenantAndCreateKey({
+            tenantId: flagTenantId ?? envTenantId,
+            tenantIdSource: flagTenantId !== undefined ? 'flag' : envTenantId !== undefined ? 'env' : undefined,
+            // Unconditional (init derives this from flags/TTY): provision is
+            // headless by contract even on an interactive terminal.
+            nonInteractive: true,
+            // stdout must stay exactly one JSON credentials document; all provision
+            // prose goes to stderr, so suppress the tenant-selection prose entirely.
+            silent: true,
+            // Multi-tenant runs surface CliInputRequiredError (exit 5); echo this
+            // invocation's resume command so the caller knows how to continue.
+            resumeCommand,
+            label,
+            // Headless callers own their credential storage; --save opts into the
+            // init-style ~/.moda/config.json persistence.
+            persistConfig: save,
+            profile: profileFlag,
+            env: context.env,
+        });
+    }
+    catch (error) {
+        // A mid-flight 401 classified by authFetch (token_expired /
+        // token_revoked / renew_failed during the context or bootstrap call)
+        // throws a CliAuthError that carries only the login command. Re-throw
+        // with this invocation's resume command attached so the caller knows how
+        // to continue after recovering, matching the upfront session gate above.
+        if (error instanceof CliAuthError && !error.auth.resume_command) {
+            throw new CliAuthError(error.message, {
+                reason: error.auth.reason,
+                login_command: error.auth.login_command,
+                resume_command: resumeCommand,
+            });
+        }
+        throw error;
+    }
+    const payload = {
+        apiKey: result.apiKey,
+        tenantId: result.tenantId,
+        tenantName: result.tenantName,
+        tenantSlug: result.tenantSlug,
+        ingestUrl: resolveIngestUrl(authOptions),
+        baseUrl: resolveModaBaseUrl(authOptions),
+        reused: result.reused,
+    };
+    // Security note on stderr, never stdout: stdout carries a live credential
+    // and must stay exactly one parseable JSON document.
+    console.error('Output contains a live API key. Avoid piping to logs.');
+    if (save) {
+        console.error('Saved API key + tenant to ~/.moda/config.json (--save).');
+    }
+    // `moda provision` exists to be composed: `KEY=$(moda provision | jq -r
+    // .apiKey)`. Command substitution IS a pipe, so stdout is a non-TTY and
+    // the CLI would auto-select agent mode and wrap the payload in a
+    // moda.agent.v1 envelope, burying apiKey under `.data`. Like `moda auth
+    // token`, this command therefore deliberately bypasses the CliOutput
+    // envelope machinery in EVERY output mode (human/json/agent) and writes
+    // exactly one JSON document to stdout — nothing else. Human TTY runs get
+    // the same machine-parseable JSON: credentials output is the whole point.
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return { exitCode: 0, apiKey: result.apiKey };
+}
+//# sourceMappingURL=provision.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "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:32:52.250Z",
+  "cli_version": "1.13.2",
   "skills": [
     {
       "id": "integration-node-anthropic",