@itpay/cli 2.0.40 → 2.1.1

package/dist/src/sell/mcp.js

@@ -0,0 +1,49 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { SELL_GUIDE, SELL_OPERATIONS, sellRequest } from './contract.js';
+import { LOCAL_ACTIONS, localAction } from './local.js';
+import { newBackendClient, loadConfig } from '../state/config.js';
+import { syncProject } from './sync.js';
+import { preview } from './preview.js';
+export async function serveSellMCP(directory) {
+    const server = new McpServer({ name: 'itpay-sell-local', version: SELL_GUIDE.version }, { instructions: 'Use itpay_seller_guide first. Local tests call Provider APIs and may incur cost; disclose side effects and obtain user approval. Never pass secret values in tool arguments. This server uses its configured project directory.' });
+    server.tool('itpay_seller_guide', 'Read the publishing guide and constraints', {}, async () => ({ content: [{ type: 'text', text: JSON.stringify({ ...SELL_GUIDE, operations: SELL_OPERATIONS }) }] }));
+    for (const action of LOCAL_ACTIONS) {
+        server.tool('itpay_seller_local_' + action.replaceAll(' ', '_').replaceAll('-', '_'), `Local ${action}. Paths are user-provided files; never scan for credentials. Confirm only after explicit user approval.`, { merchant_id: z.string().optional(), environment: z.string().optional(), service_id: z.string().optional(), url: z.string().url().optional(), file: z.string().optional(), name: z.string().optional(), provider_key: z.string().optional(), profile: z.string().optional(), version: z.string().optional(), run: z.string().optional(), confirmed: z.boolean().default(false) }, async (args) => {
+            try {
+                const result = await localAction(action, directory, { ...args, merchantId: args.merchant_id, providerKey: args.provider_key, serviceId: args.service_id, confirm: args.confirmed });
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Local action failed' }] };
+            }
+        });
+    }
+    server.tool('itpay_seller_sync', 'Upload or download the configured project after explicit user confirmation. Never pass credential values.', { action: z.enum(['push', 'pull']), merchant_id: z.string(), draft_id: z.string().optional(), bindings_file: z.string().optional(), confirmed: z.boolean().default(false) }, async (args) => {
+        try {
+            const result = await syncProject(args.action, directory, { merchantId: args.merchant_id, draftId: args.draft_id, bindings: args.bindings_file, confirm: args.confirmed });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Sync failed' }] };
+        }
+    });
+    let display;
+    server.tool('itpay_seller_preview', 'Open the existing Builder for this local workflow; user can then confirm through the local workflow tool.', {}, async () => { display ??= await preview(directory); return { content: [{ type: 'text', text: JSON.stringify({ url: display.url }) }] }; });
+    for (const operation of SELL_OPERATIONS) {
+        server.tool('itpay_seller_platform_' + operation.command.replaceAll(' ', '_').replaceAll('-', '_'), `${operation.description}. Input contract: ${JSON.stringify(operation.fields)}. Optional fields: ${JSON.stringify(operation.optional ?? [])}.`, { merchant_id: z.string().optional(), draft_id: z.string().optional(), library_api_id: z.string().optional(), intake_id: z.string().optional(), version_id: z.string().optional(), run_id: z.string().optional(), submission_id: z.string().optional(), input: z.record(z.unknown()).default({}), confirmed: z.boolean().default(false) }, async (args) => {
+            try {
+                if (operation.confirmation && !args.confirmed)
+                    throw new Error('Explicit user confirmation required');
+                const result = await newBackendClient(loadConfig()).sellRequest(sellRequest(operation, args, args.input));
+                return { content: [{ type: 'text', text: JSON.stringify(result ?? {}) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Platform action failed' }] };
+            }
+        });
+    }
+    process.stdin.on('end', () => display?.close());
+    await server.connect(new StdioServerTransport());
+}

package/dist/src/sell/preview.js

@@ -0,0 +1,70 @@
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve, extname } from 'node:path';
+import { project } from './local.js';
+export async function preview(directory) {
+    const packaged = fileURLToPath(new URL('../../../assets/sell-preview/', import.meta.url));
+    const assets = existsSync(packaged) ? packaged : fileURLToPath(new URL('../../assets/sell-preview/', import.meta.url));
+    if (!existsSync(resolve(assets, 'index.html')))
+        throw new Error('CLI preview assets are missing; install the complete CLI package');
+    const token = randomBytes(24).toString('hex');
+    const server = createServer((req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.method !== 'GET' || !req.url?.startsWith('/' + token + '/')) {
+            res.writeHead(404).end();
+            return;
+        }
+        try {
+            const path = req.url.slice(token.length + 2).split('?')[0] ?? '';
+            if (path === 'document') {
+                const p = project(directory);
+                const versions = JSON.parse(readFileSync(resolve(p.state, 'versions.json'), 'utf8'));
+                const version = versions.versions.find((v) => v.version_id === versions.selected);
+                res.setHeader('Content-Type', 'application/json');
+                const actualHash = 'sha256:' + createHash('sha256').update(p.yaml).digest('hex');
+                let run;
+                const marker = resolve(p.state, 'last-run.json');
+                if (existsSync(marker)) {
+                    const id = JSON.parse(readFileSync(marker, 'utf8')).run_id;
+                    if (typeof id === 'string' && /^[A-Za-z0-9_-]+$/.test(id) && existsSync(resolve(p.state, 'runs', id, 'meta.json'))) {
+                        const dir = resolve(p.state, 'runs', id), meta = JSON.parse(readFileSync(resolve(dir, 'meta.json'), 'utf8'));
+                        const traces = existsSync(resolve(dir, 'nodes.json')) ? JSON.parse(readFileSync(resolve(dir, 'nodes.json'), 'utf8')) : [];
+                        const report = existsSync(resolve(dir, 'report.json')) ? JSON.parse(readFileSync(resolve(dir, 'report.json'), 'utf8')).report : undefined;
+                        const configHash = 'sha256:' + createHash('sha256').update(JSON.stringify(p.config)).digest('hex');
+                        const stale = meta.hash !== actualHash || meta.config_hash !== configHash;
+                        const fixtures = p.config.fixtures ?? [];
+                        run = { status: stale ? 'stale' : report?.status ?? 'running', issues: report?.issues ?? [], validation: { fixture_runs: fixtures.map((f) => ({ ...f, nodes: traces.filter((t) => t.record_type === 'node' && t.fixture_id === f.fixture_id) })), api_recognitions: [], side_effect_operations: [] } };
+                    }
+                }
+                res.end(JSON.stringify({ document: p.yaml, version: version?.hash === actualHash ? version.name : 'Unsaved', hash: actualHash, pricing: p.config.pricing, run }));
+                return;
+            }
+            const file = resolve(assets, path || 'index.html');
+            if (!file.startsWith(resolve(assets) + '/')) {
+                res.writeHead(404).end();
+                return;
+            }
+            const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
+            res.setHeader('Content-Type', types[extname(file)] ?? 'application/octet-stream');
+            res.end(readFileSync(file));
+        }
+        catch {
+            res.writeHead(404).end();
+        }
+    });
+    return new Promise((done, fail) => {
+        server.on('error', fail);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                fail(new Error('Preview address unavailable'));
+                return;
+            }
+            done({ url: `http://127.0.0.1:${address.port}/${token}/`, close: () => server.close() });
+        });
+    });
+}

package/dist/src/sell/sync.js

@@ -0,0 +1,145 @@
+import { HttpError } from "../client/http.js";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { newBackendClient, loadConfig } from '../state/config.js';
+import { companion, project, localDependencies } from './local.js';
+const encode = encodeURIComponent;
+const hash = (value) => 'sha256:' + createHash('sha256').update(value).digest('hex');
+function read(path) { return JSON.parse(readFileSync(path, 'utf8')); }
+function save(path, value) { writeFileSync(path, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); }
+function platformWorkflow(draft) {
+    const document = draft.arazzo?.arazzo_document;
+    if (typeof document !== 'string' || !document.trim())
+        throw new Error('Platform response is missing the workflow document');
+    return document;
+}
+export async function syncProject(action, directory, options) {
+    const p = project(directory), cloudPath = join(p.state, 'cloud.json');
+    let cloud = existsSync(cloudPath) ? read(cloudPath) : {};
+    const merchant = options.merchantId ?? cloud.merchant_id ?? p.config.merchant_id;
+    if (!merchant)
+        throw new Error('--merchant-id is required');
+    if (cloud.merchant_id && cloud.merchant_id !== merchant)
+        throw new Error('Project is bound to a different merchant');
+    const api = newBackendClient(loadConfig()), org = '/v1/seller/organizations/' + encode(merchant);
+    const call = async (method, path, body) => await api.sellRequest({ method, path, ...(body !== undefined ? { body } : {}) });
+    if (action === 'pull') {
+        const draftID = options.draftId ?? cloud.draft_id;
+        if (!draftID)
+            throw new Error('--draft-id is required');
+        if (!options.confirm)
+            throw new Error('Pull replaces local workflow/settings; inspect changes and confirm first');
+        const bundle = await call('GET', `${org}/service-drafts/${encode(draftID)}/bundle`);
+        const backup = join(p.state, 'backups', String(Date.now()));
+        mkdirSync(backup, { recursive: true, mode: 0o700 });
+        writeFileSync(join(backup, 'workflow.yaml'), p.yaml);
+        save(join(backup, 'service.json'), p.config);
+        const draft = bundle.draft;
+        writeFileSync(join(p.root, 'workflow.yaml'), platformWorkflow(draft));
+        save(join(p.root, 'service.json'), { ...p.config, service_id: draft.service_id, public_name: draft.public_name, pricing: draft.pricing, policy: draft.policy, fixtures: bundle.fixtures.fixtures });
+        save(join(p.state, 'platform-dependencies.json'), bundle.dependencies);
+        cloud = { merchant_id: merchant, draft_id: draftID, revision: draft.semantic_revision, hash: draft.semantic_hash };
+        save(cloudPath, cloud);
+        return { cloud, backup, next: 'Save a new local version. Platform credentials were not downloaded.' };
+    }
+    const versions = read(join(p.state, 'versions.json'));
+    const version = versions.versions.find((v) => v.version_id === versions.selected);
+    const confirmation = existsSync(join(p.state, 'confirmation.json')) ? read(join(p.state, 'confirmation.json')) : {};
+    if (!version || version.hash !== hash(p.yaml) || version.config_hash !== hash(JSON.stringify(p.config)) || confirmation.version_id !== version.version_id || confirmation.hash !== version.hash || confirmation.config_hash !== version.config_hash)
+        throw new Error('Save and confirm the exact current version before uploading');
+    const validation = (await companion({ action: 'validate', dependencies: localDependencies(p.state), document: p.yaml, pricing: p.config.pricing, policy: p.config.policy })).find(event => event.type === 'validation')?.value;
+    if (!validation?.result?.valid)
+        throw new Error('Workflow does not pass validation');
+    if (!options.confirm)
+        return { local_version: version, cloud, pricing: p.config.pricing, instruction: 'Review the service package and platform API calls, then confirm upload. Platform verification is a separate explicit action.' };
+    if (!cloud.draft_id) {
+        const drafts = await call('GET', `${org}/service-drafts`);
+        const existing = drafts.drafts?.find((d) => d.service_id === p.config.service_id);
+        if (existing)
+            throw new Error('Service ID already exists. Pull that draft explicitly before updating it.');
+        const draft = await call('POST', `${org}/service-drafts`, { service_id: p.config.service_id, public_name: p.config.public_name });
+        cloud = { merchant_id: merchant, draft_id: draft.draft_id, revision: draft.semantic_revision, operation_bindings: {} };
+        save(cloudPath, cloud);
+    }
+    const base = `${org}/service-drafts/${encode(cloud.draft_id)}`;
+    let current = await call('GET', base + '/workflow');
+    if (current.semantic_revision !== cloud.revision)
+        throw new Error('Remote draft changed; pull and review before retrying');
+    if (cloud.local_version_id === version.version_id && cloud.hash === current.semantic_hash && cloud.version_id) {
+        const saved = await call('GET', base + '/workflow/versions');
+        if (saved.versions.some((item) => item.version_id === cloud.version_id)) {
+            const fixtureState = await call('GET', base + '/fixtures');
+            if (fixtureState.revision !== cloud.fixture_revision)
+                throw new Error('Remote test inputs changed; pull and review before retrying');
+            return { cloud, already_uploaded: true, next: 'Read the platform Guide and verify the saved version' };
+        }
+    }
+    const sources = join(p.state, 'sources');
+    cloud.operation_bindings ??= {};
+    if (existsSync(sources))
+        for (const file of readdirSync(sources)) {
+            const source = read(join(sources, file));
+            const imported = await call('POST', `${org}/api-intakes`, { provider_key: source.provider_key, document: source.original, media_type: 'application/yaml' });
+            for (const local of source.operations) {
+                const remote = imported.operations.find((operation) => operation.operation_key === local.operation_key && operation.method === local.method && operation.path === local.path);
+                if (!remote)
+                    throw new Error('Platform import differs from the local API contract');
+                if (remote.operation_hash !== local.operation_hash)
+                    throw new Error('Platform API contract changed; download and review the imported contract');
+                cloud.operation_bindings[local.provider_operation_version_id] = remote.provider_operation_version_id;
+            }
+            save(cloudPath, cloud);
+        }
+    const credentials = options.bindings ? read(resolve(options.bindings)) : {};
+    const document = validation.document;
+    for (const workflow of document.workflows)
+        for (const step of workflow.steps) {
+            const meta = step['x-itpay-operation'];
+            if (meta?.type === 'api_call') {
+                meta.providerOperationVersionId = cloud.operation_bindings[meta.providerOperationVersionId] ?? meta.providerOperationVersionId;
+                if (credentials[meta.credentialProfileId])
+                    meta.credentialProfileId = credentials[meta.credentialProfileId];
+            }
+        }
+    // Each durable boundary is recorded. On an ambiguous write, pull explicitly;
+    // never retry a guessed revision or overwrite another editor's changes.
+    current = await call('PUT', base + '/workflow', { expected_revision: cloud.revision, public_name: p.config.public_name, arazzo: document });
+    cloud.revision = current.semantic_revision;
+    save(cloudPath, cloud);
+    current = await call('PUT', base + '/pricing', { expected_revision: cloud.revision, pricing: p.config.pricing, policy: p.config.policy });
+    cloud.revision = current.semantic_revision;
+    save(cloudPath, cloud);
+    let fixtures;
+    try {
+        fixtures = await call('GET', base + '/fixtures');
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404)
+            fixtures = { revision: 0 };
+        else
+            throw error;
+    }
+    const savedFixtures = await call('PUT', base + '/fixtures', { expected_revision: fixtures.revision, fixtures: p.config.fixtures });
+    const existingVersions = await call('GET', base + '/workflow/versions');
+    const saved = existingVersions.versions.find((item) => item.name === version.name && item.arazzo_document === platformWorkflow(current)) ?? await call('POST', base + '/workflow/versions', { name: version.name, source: 'current', expected_revision: cloud.revision, arazzo_document: platformWorkflow(current) });
+    cloud.version_id = saved.version_id;
+    cloud.fixture_revision = savedFixtures.revision;
+    cloud.local_version_id = version.version_id;
+    cloud.hash = current.semantic_hash;
+    save(cloudPath, cloud);
+    await call('POST', base + '/workflow/validate', {});
+    return { cloud, platform_verified: false, next: { command: 'itpay sell verify', input: { workflow_version_id: cloud.version_id, expected_semantic_revision: cloud.revision, expected_fixture_revision: cloud.fixture_revision } }, instruction: 'Review and confirm platform verification before any real API calls. Local test success is not platform evidence.' };
+}
+export function registerSync(sell) {
+    for (const action of ['push', 'pull'])
+        sell.command(action).option('--project <directory>', 'Project directory', '.').option('--merchant-id <id>').option('--draft-id <id>').option('--bindings <file>', 'Local profile ID to platform credential profile ID map').option('--confirm').option('--json').action(async (options) => {
+            try {
+                process.stdout.write(JSON.stringify({ status: 'ok', result: await syncProject(action, options.project, options) }, null, 2) + '\n');
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stdout.write(JSON.stringify({ status: 'error', message: error instanceof Error ? error.message : 'Sync failed' }) + '\n');
+            }
+        });
+}

package/dist/src/state/account_auth.js

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
+    return resolve(env.HOME || homedir(), '.itpay-v3', `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
+}
+function read(baseURL, env = process.env, purpose = "seller") {
+    const path = sellerAuthPath(baseURL, env, purpose);
+    if (!existsSync(path))
+        return;
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state.baseURL !== baseURL)
+        throw new Error('Seller session backend mismatch');
+    return state;
+}
+function save(state, env = process.env, purpose = "seller") {
+    const path = sellerAuthPath(state.baseURL, env, purpose);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export function sellerSessionToken(baseURL, env = process.env) {
+    const state = read(baseURL, env);
+    return state?.expiresAt && Date.parse(state.expiresAt) > Date.now() ? state.sessionToken : undefined;
+}
+export function sellerAuth(action, baseURL, env = process.env, fetcher = fetch) {
+    return accountAuth(action, baseURL, env, fetcher);
+}
+export function agentAuth(action, baseURL, backend, env = process.env, fetcher = fetch) {
+    return accountAuth(action, baseURL, env, fetcher, backend);
+}
+async function accountAuth(action, baseURL, env, fetcher, backend) {
+    const purpose = backend ? 'agent-login' : 'seller';
+    const command = backend ? 'itpay auth status' : 'itpay sell auth status';
+    if (backend) {
+        const current = await backend.agentAccountStatus();
+        if (current.status === 'authenticated')
+            return current;
+    }
+    async function request(path, init = {}) {
+        const response = await fetcher(baseURL + path, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
+        if (!response.ok)
+            throw new Error(`ItPay authorization failed (${response.status}); retry login if expired`);
+        return response;
+    }
+    if (action === 'login') {
+        const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ provider: 'alipay', return_to: backend ? '/' : '/seller' }) });
+        const result = await response.json();
+        const url = new URL(result.start_url, baseURL);
+        if (url.origin !== new URL(baseURL).origin)
+            throw new Error('Unexpected authorization origin');
+        const startToken = url.searchParams.get('start_token');
+        if (!startToken || !result.poll_token || !result.dashboard_auth_session_id)
+            throw new Error('Incomplete authorization response');
+        save({ baseURL, sessionID: result.dashboard_auth_session_id, pollToken: result.poll_token, startToken }, env, purpose);
+        return { status: 'authorization_required', authorization_url: url.href, instruction: `Complete ItPay login in the browser, then run ${command}.` };
+    }
+    const state = read(baseURL, env, purpose);
+    if (action === 'logout') {
+        const token = sellerSessionToken(baseURL, env);
+        if (token)
+            await request('/v1/me/logout', { method: 'POST', headers: { Authorization: `Bearer ${token}` } });
+        rmSync(sellerAuthPath(baseURL, env), { force: true });
+        return { status: 'logged_out' };
+    }
+    if (!backend && sellerSessionToken(baseURL, env))
+        return { status: 'authenticated', base_url: baseURL, expires_at: state?.expiresAt };
+    if (!state?.sessionID || !state.pollToken || !state.startToken)
+        return { status: 'login_required' };
+    const path = `/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}`;
+    const progress = await (await request(`${path}?poll_token=${encodeURIComponent(state.pollToken)}`)).json();
+    if (progress.status !== 'completed')
+        return { status: progress.status, instruction: 'Finish login and email verification in the browser.' };
+    if (backend) {
+        const result = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
+        if (result.status !== 'authenticated')
+            throw new Error('Agent binding did not complete');
+        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+        return result;
+    }
+    const claimed = await request(`${path}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
+    const token = /(?:^|[, ]+)itpay_buyer_session=([^;]+)/.exec(claimed.headers.get('set-cookie') ?? '')?.[1];
+    const session = await claimed.json();
+    if (!token || !session.expires_at || !(Date.parse(session.expires_at) > Date.now()))
+        throw new Error('Incomplete Seller session');
+    save({ baseURL, sessionToken: token, expiresAt: session.expires_at }, env);
+    return { status: 'authenticated', base_url: baseURL, expires_at: session.expires_at };
+}

package/dist/src/state/config.js

@@ -1,7 +1,9 @@
-// CLI configuration loader. Production defaults to app.itpay.ai; the only
-// allowed override is the official sandbox Backend. Checkout
+import { sellerSessionToken } from "./account_auth.js";
+// CLI configuration loader. Production defaults to app.itpay.ai; supported public overrides
+// are the official sandbox and dev Backends. Checkout
 // display-token persistence belongs to the cart session file, protected with
 // owner-only permissions. Provider secrets are explicitly out of scope here.
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { mkdirSync } from "node:fs";
 import { resolve } from "node:path";
@@ -11,9 +13,10 @@ import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
+export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.0.40";
-export const API_CONTRACT_REVISION = "sha256:6445dc76e23c5b9f0d19cfbfd2a552c0dd96dd0a169f793fe0f6a1c93f3ea1a1";
+export const CLI_VERSION = "2.1.1";
+export const API_CONTRACT_REVISION = "sha256:b8593e4d73782a3ddeb5d070df1db572e422dd0aa08083372bc8971b5412b643";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
@@ -27,7 +30,7 @@ export function cliDistribution(env = process.env) {
 export class BackendOverrideError extends Error {
     code = "backend_override_forbidden";
     constructor() {
-        super(`ITPAY_BACKEND_URL only supports ${DEFAULT_BASE_URL} or ${SANDBOX_BASE_URL}`);
+        super(`ITPAY_BACKEND_URL only supports ${DEFAULT_BASE_URL}, ${SANDBOX_BASE_URL}, or ${DEV_BASE_URL}`);
         this.name = "BackendOverrideError";
     }
 }
@@ -37,21 +40,29 @@ export function resolveBackendURL(env = process.env) {
         return DEFAULT_BASE_URL;
     if (requested === SANDBOX_BASE_URL || requested === `${SANDBOX_BASE_URL}/`)
         return SANDBOX_BASE_URL;
+    if (requested === DEV_BASE_URL || requested === `${DEV_BASE_URL}/`)
+        return DEV_BASE_URL;
+    if (env.ITPAY_CLI_DEV === "1" && /^http:\/\/(localhost|127\.0\.0\.1):\d+\/?$/.test(requested))
+        return requested.replace(/\/$/, "");
     throw new BackendOverrideError();
 }
 export function qualifyBackendCommand(command, env = process.env) {
     const requested = env.ITPAY_BACKEND_URL?.trim();
-    if (requested !== SANDBOX_BASE_URL && requested !== `${SANDBOX_BASE_URL}/`)
+    if (!requested)
         return command;
-    if (!command.startsWith("itpay ") || command.startsWith(`ITPAY_BACKEND_URL=${SANDBOX_BASE_URL} `))
+    const target = resolveBackendURL(env);
+    if (target === DEFAULT_BASE_URL)
         return command;
-    return `ITPAY_BACKEND_URL=${SANDBOX_BASE_URL} ${command}`;
+    if (!command.startsWith("itpay ") || command.startsWith(`ITPAY_BACKEND_URL=${target} `))
+        return command;
+    return `ITPAY_BACKEND_URL=${target} ${command}`;
 }
 function stateFilename(filename, baseURL) {
-    if (baseURL !== SANDBOX_BASE_URL)
+    if (baseURL === DEFAULT_BASE_URL)
         return filename;
+    const suffix = baseURL === SANDBOX_BASE_URL ? "sandbox" : baseURL === DEV_BASE_URL ? "dev" : `local-${createHash("sha256").update(baseURL).digest("hex").slice(0, 16)}`;
     const dot = filename.lastIndexOf(".");
-    return dot < 0 ? `${filename}.sandbox` : `${filename.slice(0, dot)}.sandbox${filename.slice(dot)}`;
+    return dot < 0 ? `${filename}.${suffix}` : `${filename.slice(0, dot)}.${suffix}${filename.slice(dot)}`;
 }
 function stateDir(env) {
     return resolve(env.HOME || homedir(), CART_SESSION_DEFAULT_DIR);
@@ -74,7 +85,7 @@ export function loadConfig(env = process.env) {
     const ideImageDirOverride = env.ITPAY_IDE_IMAGE_DIR_OVERRIDE;
     return {
         baseURL,
-        environment: baseURL === SANDBOX_BASE_URL ? "development" : "production",
+        environment: baseURL === DEFAULT_BASE_URL ? "production" : "development",
         ...(agentType ? { agentType } : {}),
         checkoutCurrency,
         idempotencyKey,
@@ -104,7 +115,15 @@ export function newBackendClient(config) {
             "X-ItPay-CLI-Version": CLI_VERSION,
             "X-ItPay-Contract-Revision": API_CONTRACT_REVISION,
         },
-        requestAuthorizer: (input) => authority.authorizationHeaders(input),
+        requestAuthorizer: (input) => {
+            if (/^\/v1\/(seller\/organizations(?:\/|\?|$)|library\/)/.test(input.path)) {
+                const token = config.bearerToken ?? sellerSessionToken(config.baseURL);
+                if (!token)
+                    throw new Error("Seller login required; run itpay sell auth login");
+                return Promise.resolve({ Authorization: `Bearer ${token}` });
+            }
+            return authority.authorizationHeaders(input);
+        },
         recoverAuthorization: () => authority.recoverAuthorization(),
     });
     return new BackendClient(http);

package/dist/src/state/device_authority.js

@@ -2,7 +2,7 @@ import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, ran
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-const PROTECTED_PATHS = ["/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault"];
+const PROTECTED_PATHS = ["/v1/agent-device-account-bindings", "/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault"];
 export class DeviceAuthority {
     baseURL;
     backendKey;

package/docs/cli-reference/commands/auth.md

@@ -0,0 +1,9 @@
+# Account login
+
+Use `itpay auth login --json` to enroll the current Agent and open the official ItPay Web login. After the user finishes login and email verification, run `itpay auth status --json` to bind this enrolled Agent to the account. Keep declaring the actual `--agent-type` on both commands.
+
+For dev, keep `ITPAY_BACKEND_URL=https://dev.itpay.ai` on every command. Login state and device registration are isolated from production.
+
+Railway exact and smart query services each allow two anonymous queries after enrollment. After login, queries remain free within the published per-minute limits. On `login_required`, finish login and start a new query. On `rate_limited`, wait until the next minute; do not clear device state or retry in a loop.
+
+The Agent receives no general account bearer token. This binding reuses the existing stable device-account ownership mechanism; switching account owners is not supported. Seller authoring continues to use `itpay sell auth` separately.