@coswic/aipay 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @coswic/aipay
 
+## 0.5.0 — 2026-09-08
+
+- Add `apps callbacks list/add/remove` with the developer’s own management authorization and linked-project defaults.
+- Preserve other registered callbacks, make no-op changes idempotent, and refuse to remove the final callback.
+- Require server ETag support for mutations; concurrent edits and uncertain outcomes require readback instead of blind retries.
+- Guide agents through developer CLI login and callback management; local `init` remains distinct from server registration.
+- Allow HTTPS application callbacks in `init` and `doctor`; `test --callback` can use a separately registered loopback callback without changing project settings.
+- Bound developer API requests to 30 seconds and allow conditional mutations to disable automatic retries after a 401.
+
 ## 0.4.0 — 2026-09-08
 
 - Simplify setup instructions around standard OAuth and HTTPS connectivity.

package/README.md

@@ -4,7 +4,8 @@ The command-line companion to [`@coswic/aipay-sdk`](https://www.npmjs.com/packag
 Made for developers and for the coding agents they hand the Console prompt to.
 
 ```bash
-npx @coswic/aipay init --app <client_id> --auth <authorization server> --api <api base>
+npx @coswic/aipay@latest login --api <api base>
+npx @coswic/aipay@latest init --app <client_id> --auth <authorization server> --api <api base>
 npx @coswic/aipay test
 ```
 
@@ -12,6 +13,11 @@ npx @coswic/aipay test
 
 | Command | What it does |
 |---|---|
+| `aipay login` / `whoami` / `logout` | Sign in as the developer to manage your Apps; on a remote machine use `login --device`. This is separate from an end user authorizing AI spending in your App. |
+| `aipay apps list` / `apps create --name <name>` | List or create Apps using your developer authorization. |
+| `aipay apps callbacks list --app <client_id>` | Read the registered callback URLs. In a linked project, `--app` can be omitted; `--dir` selects the project. |
+| `aipay apps callbacks add --app <client_id> --callback <url>` | Add a registered callback while preserving the others. Adding an existing URL makes no write. |
+| `aipay apps callbacks remove --app <client_id> --callback <url>` | Remove one callback; removing an absent URL makes no write. The final callback cannot be removed. |
 | `aipay init` | Links the project to your app: writes `.aipay/project.json` (commit it), `.env.local` (public values only, git-ignored), a start/callback route for your framework (Next.js, Express, Fastify, Hono, plain Node) or a browser helper for a Vite SPA (`--framework` overrides detection), `aipay-agent.md` (the developer docs, fetched once, for your agent to read offline) and installs the SDK. Never overwrites a file it did not write this run. `--dry-run` shows the plan. |
 | `aipay test` | The proof: a real sign-in through the AI-Pay authorization server, received by the CLI on a loopback callback, then one chat completion on that user's behalf. Prints the receipt (`request_id`, amount charged). The Console's verify step turns green from the server side. The authorization server ignores the port for `127.0.0.1` redirect URIs (RFC 8252), so the CLI binds any free port and your dev server can keep running; `--port <n>` forces one. `--no-open` prints the URL instead of opening a browser; `--model <id>` picks the model. |
 | `aipay doctor` | Checks Node, the link, `.env.local`, the SDK install, and that the authorization server and API are reachable. `--offline` skips the network. |
@@ -22,6 +28,41 @@ Every command accepts `--json` (one JSON document on stdout) and `--dir <path>`.
 
 Exit codes: `0` ok · `1` a problem you can fix locally · `2` usage · `3` network/auth.
 
+## Registering a deployed callback
+
+```bash
+npx @coswic/aipay@latest whoami
+# If signed out, or signed into another API environment:
+npx @coswic/aipay@latest login --api https://api.example
+npx @coswic/aipay@latest apps callbacks list --app <client_id>
+npx @coswic/aipay@latest apps callbacks add --app <client_id> --callback https://yourapp.example/auth/aipay/callback
+```
+
+`init` and `doctor` accept HTTPS application callbacks as well as HTTP loopback callbacks.
+For a project configured with HTTPS, verify the hosted app in the browser or use
+`aipay test --callback <registered-http-loopback-url-without-query>` without changing its configuration.
+
+`init --callback` configures the project locally; it does not register the URL with the
+server. Register the deployed callback with `apps callbacks add`, then use that same URL
+in the app configuration. Keep the local callback for development. Callback commands
+always use the API and authorization server associated with your developer login.
+When `--app` is omitted, the linked project's `api_base` and `auth_origin` must match that
+login; a mismatch blocks the command before any request, so sign in to the correct environment
+first. An explicit `--app` uses the current login environment without consulting the project.
+Human and JSON output include `api_base` and `auth_origin` for verification; check `whoami`
+when switching environments.
+
+Changes use the server's callback ETag in `If-Match`. If the server does not support this
+precondition, the CLI refuses to change callbacks and asks for a server update. A concurrent
+edit returns a conflict: list again before deciding whether to repeat your change. There
+is no automatic write retry. After a timeout or an uncertain provider result, the CLI reads
+back the list; readback can confirm the requested state, otherwise the outcome remains
+unconfirmed. JSON output distinguishes success, no-op, conflict, and unknown outcome.
+
+The platform's verification callback stays system-managed and is excluded from the editable
+list. No client secret, owner cookie, or admin credential is needed: approve the normal CLI
+developer login in your browser.
+
 ## Signing in from a remote machine
 
 `aipay login` opens a browser on this machine (loopback PKCE). On an SSH box, a container or

package/dist/agent-guide.js

@@ -1,6 +1,10 @@
 export const AGENT_GUIDE_FILE = 'aipay-agent.md';
 export function agentGuide(input) {
     const p = input.project;
+    const callback = new URL(p.callback);
+    const verification = callback.protocol === 'https:' || callback.search
+        ? 'Sign in through the running app and make one chat completion whose response carries a receipt (`aipay.request_id`). Alternatively, use `aipay test --callback <registered-http-loopback-url>` with an already registered HTTP loopback URL without a query; leave the project callback unchanged.'
+        : '`aipay test` completes: a real sign-in through the AI-Pay authorization server and one chat completion whose response carries a receipt (`aipay.request_id`).';
     const files = input.scaffolded.length
         ? input.scaffolded.map((f) => `- \`${f}\``).join('\n')
         : '- (none — the project had them already)';
@@ -16,7 +20,7 @@ export function agentGuide(input) {
 | client_id | \`${p.app.client_id}\` (public client, PKCE S256, no secret) |
 | Authorization server | ${p.auth_origin} |
 | API base | ${p.api_base} |
-| Registered callback | \`${p.callback}\` (for 127.0.0.1 the port is not compared, so any local port works) |
+| Configured callback (register with CLI before use) | \`${p.callback}\` (for 127.0.0.1 the port is not compared, so any local port works) |
 | Local config | \`.aipay/project.json\` (commit it), \`.env.local\` (do not commit) |
 
 Files scaffolded by the CLI (edit freely; the CLI never overwrites existing files):
@@ -26,14 +30,15 @@ ${files}
 
 1. \`aipay doctor\` reports no problems.
 2. The app's dev server serves the start route and the callback route above.
-3. \`aipay test\` completes: a real sign-in through the AI-Pay authorization server and
-   one chat completion whose response carries a receipt (\`aipay.request_id\`).
+3. ${verification}
 4. Typecheck/build pass. Do not commit automatically and do not deploy.
 
 ## Rules for agents
 
 - Read the docs below before changing the integration; they are the source of truth.
 - Use standard OAuth sign-in and app authorization.
+- Manage App settings with the developer’s own CLI authorization: check \`aipay whoami\`, then run \`aipay login --api ${p.api_base}\` if needed (add \`--device\` on a remote machine). Ask the user to approve the CLI login; never substitute another App’s token.
+- Use \`aipay apps callbacks list|add|remove --app ${p.app.client_id}\` to manage registered URLs. \`init --callback\` only writes local configuration; it does not register a URL. Preserve existing callbacks; on a conflict or unknown outcome, read the current list before acting again.
 - Keep OAuth tokens out of code, config files, and version control.
 - Never request \`offline_access\` unless the product needs background renewal.
 - Key user accounts on \`sub\` from the userinfo endpoint, never on email.

package/dist/callback-url.d.ts

@@ -0,0 +1,3 @@
+export declare function hasUnsafeCallbackText(value: string): boolean;
+/** Application callbacks may use HTTPS; CLI test receivers remain HTTP loopback. */
+export declare function parseAppCallback(callback: string): URL;

package/dist/callback-url.js

@@ -0,0 +1,14 @@
+export function hasUnsafeCallbackText(value) {
+    return (/[\s*]/.test(value) ||
+        [...value].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127));
+}
+/** Application callbacks may use HTTPS; CLI test receivers remain HTTP loopback. */
+export function parseAppCallback(callback) {
+    if (!/^https?:\/\//.test(callback) || hasUnsafeCallbackText(callback))
+        throw new Error('callback must be an exact URL without whitespace, control characters or wildcards');
+    const url = new URL(callback);
+    const loopback = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname);
+    if ((!loopback && url.protocol !== 'https:') || url.username || url.password || url.hash)
+        throw new Error('callback must be HTTPS or HTTP on 127.0.0.1/localhost, without credentials or a fragment');
+    return url;
+}

package/dist/commands/app-callbacks.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export declare function runCallbacks(args: ParsedArgs, out: Reporter, env: NodeJS.ProcessEnv): Promise<number>;

package/dist/commands/app-callbacks.js

@@ -0,0 +1,304 @@
+/** Owner-managed callback changes use one conditional PUT and readback, never a blind retry. */
+import { resolve } from 'node:path';
+import { flagString } from '../args.js';
+import { createAuthStore } from '../auth-store.js';
+import { hasUnsafeCallbackText } from '../callback-url.js';
+import { openDeveloperApi } from '../developer-api.js';
+import { CliError, EXIT } from '../output.js';
+import { readProject } from '../project.js';
+class CallbackError extends CliError {
+    publicError;
+    constructor(publicError, exitCode = EXIT.remote) {
+        super(publicError.code, publicError.message, exitCode);
+        this.publicError = publicError;
+    }
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function remoteError(status, body) {
+    const outer = record(body);
+    const nested = record(outer.error);
+    const error = Object.keys(nested).length ? nested : outer;
+    const details = record(error.details);
+    const safe = {};
+    for (const key of ['outcome', 'retryable', 'readback_required', 'current_redirect_uris_etag'])
+        if (typeof details[key] === 'string' || typeof details[key] === 'boolean')
+            safe[key] = details[key];
+    if (Array.isArray(details.current_redirect_uris) &&
+        details.current_redirect_uris.every((u) => typeof u === 'string'))
+        safe.current_redirect_uris = details.current_redirect_uris;
+    const code = typeof error.code === 'string'
+        ? error.code
+        : typeof outer.error === 'string'
+            ? outer.error
+            : 'remote';
+    return {
+        code,
+        status,
+        message: status === 401
+            ? 'The developer authorization was rejected. Run aipay login before trying again.'
+            : status === 409 || status === 412
+                ? 'The callback list changed or another update is in progress. Run aipay apps callbacks list before making another change; this update was not retried.'
+                : `Callback management request failed (HTTP ${status}).`,
+        ...(typeof error.request_id === 'string' ? { request_id: error.request_id } : {}),
+        ...(typeof details.outcome === 'string' ? { outcome: details.outcome } : {}),
+        ...(Object.keys(safe).length ? { details: safe } : {}),
+    };
+}
+function thrownError(error) {
+    return error instanceof CallbackError
+        ? error.publicError
+        : error instanceof CliError
+            ? { code: error.code, message: error.message }
+            : { code: 'network_error', message: 'Could not confirm the callback request with AI-Pay.' };
+}
+/** Preserve exact URI strings: OAuth callback matching is not URL normalization. */
+function validateCallback(value) {
+    try {
+        const url = new URL(value);
+        if (!/^https?:\/\//.test(value) ||
+            hasUnsafeCallbackText(value) ||
+            url.username ||
+            url.password ||
+            url.hash ||
+            (url.protocol !== 'https:' &&
+                !(url.protocol === 'http:' &&
+                    (url.hostname === '127.0.0.1' || url.hostname === 'localhost'))))
+            throw new Error();
+    }
+    catch {
+        throw new CliError('usage', '--callback must be an exact HTTPS URL or HTTP localhost/127.0.0.1 URL, without credentials, whitespace, control characters, a fragment or wildcard.', EXIT.usage);
+    }
+}
+function inputOf(args) {
+    const action = args.positionals[1];
+    if (!['list', 'add', 'remove'].includes(action ?? '') || args.positionals.length !== 2)
+        throw new CliError('usage', 'usage: aipay apps callbacks list|add|remove --app <id> [--callback <url>] [--dir <path>]', EXIT.usage);
+    for (const name of Object.keys(args.flags))
+        if (!['app', 'callback', 'dir', 'json', 'help'].includes(name))
+            throw new CliError('usage', `unknown callbacks flag --${name}`, EXIT.usage);
+    for (const name of ['app', 'callback', 'dir'])
+        if (name in args.flags && !flagString(args.flags, name))
+            throw new CliError('usage', `--${name} requires a value`, EXIT.usage);
+    const callback = flagString(args.flags, 'callback');
+    if (action === 'list' ? callback !== null : callback === null)
+        throw new CliError('usage', action === 'list' ? 'callbacks list does not accept --callback' : 'missing --callback <url>', EXIT.usage);
+    if (callback !== null)
+        validateCallback(callback);
+    let appId = flagString(args.flags, 'app');
+    let projectEnvironment;
+    if (!appId) {
+        try {
+            const project = readProject(resolve(flagString(args.flags, 'dir') ?? '.'));
+            appId = project?.app.client_id ?? null;
+            if (project)
+                projectEnvironment = { api_base: project.api_base, auth_origin: project.auth_origin };
+        }
+        catch {
+            throw new CliError('invalid_project', 'Cannot read a valid .aipay/project.json; pass --app <id> explicitly.', EXIT.usage);
+        }
+    }
+    if (!appId || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(appId))
+        throw new CliError('usage', 'Provide --app <app/client UUID> or a linked project with --dir <path>.', EXIT.usage);
+    return {
+        action: action,
+        appId,
+        callback,
+        ...(projectEnvironment ? { projectEnvironment } : {}),
+    };
+}
+/** Compare endpoints without changing either the credential destination or project files. */
+function checkEnvironment(project, auth) {
+    if (!project)
+        return;
+    const normalized = (value) => {
+        try {
+            const url = new URL(value);
+            if (!['https:', 'http:'].includes(url.protocol) ||
+                url.username ||
+                url.password ||
+                url.search ||
+                url.hash)
+                return null;
+            return url.href.replace(/\/$/, '');
+        }
+        catch {
+            return null;
+        }
+    };
+    for (const key of ['api_base', 'auth_origin']) {
+        const expected = normalized(project[key]);
+        if (!expected || expected !== normalized(auth[key]))
+            throw new CallbackError({
+                code: 'environment_mismatch',
+                message: 'The linked project belongs to a different AI-Pay environment. Sign in to the correct environment first; use --app explicitly only to manage an app in the current login environment.',
+                outcome: 'not_attempted',
+            }, EXIT.problem);
+    }
+}
+async function readCallbacks(api, path, appId) {
+    const response = await api.request('GET', `${path}/oauth-client`);
+    if (response.status !== 200)
+        throw new CallbackError(remoteError(response.status, response.body));
+    const body = record(response.body);
+    if (!Array.isArray(body.redirect_uris) ||
+        !body.redirect_uris.every((u) => typeof u === 'string') ||
+        (body.app_id !== undefined && body.app_id !== appId) ||
+        (body.client_id !== undefined && body.client_id !== appId))
+        throw new CallbackError({
+            code: 'invalid_response',
+            message: 'AI-Pay returned an invalid callback list.',
+        });
+    const system = typeof body.test_callback_uri === 'string' ? body.test_callback_uri : undefined;
+    return {
+        redirect_uris: body.redirect_uris.filter((u) => u !== system),
+        ...(typeof body.redirect_uris_etag === 'string'
+            ? { redirect_uris_etag: body.redirect_uris_etag }
+            : {}),
+        ...(system !== undefined ? { test_callback_uri: system } : {}),
+    };
+}
+function sameUris(left, right) {
+    const expected = new Set(left);
+    const actual = new Set(right);
+    return expected.size === actual.size && [...expected].every((uri) => actual.has(uri));
+}
+async function execute(api, input) {
+    const path = `/v1/developer/apps/${encodeURIComponent(input.appId)}`;
+    const before = await readCallbacks(api, path, input.appId);
+    const base = { app_id: input.appId, action: input.action };
+    if (input.action === 'list')
+        return { ok: true, ...base, ...before };
+    if (!before.redirect_uris_etag ||
+        !/^"redirect-uris-[0-9a-f]{64}"$/.test(before.redirect_uris_etag))
+        throw new CallbackError({
+            code: 'conditional_update_unavailable',
+            message: 'This AI-Pay service does not provide a supported callback version. Update the service before changing callbacks; callbacks list remains available.',
+            outcome: 'not_attempted',
+        }, EXIT.problem);
+    if (input.callback === before.test_callback_uri)
+        throw new CallbackError({
+            code: 'system_callback',
+            message: 'This callback is managed by AI-Pay and cannot be added or removed.',
+            outcome: 'not_attempted',
+        }, EXIT.problem);
+    const present = before.redirect_uris.includes(input.callback);
+    if ((input.action === 'add' && present) || (input.action === 'remove' && !present))
+        return { ok: true, ...base, ...before, changed: false, outcome: 'unchanged' };
+    const desired = input.action === 'add'
+        ? [...before.redirect_uris, input.callback]
+        : before.redirect_uris.filter((uri) => uri !== input.callback);
+    if (!desired.length)
+        throw new CallbackError({
+            code: 'last_callback',
+            message: 'Keep at least one developer callback; the system callback does not count.',
+            outcome: 'not_attempted',
+        }, EXIT.problem);
+    let writeError;
+    try {
+        const response = await api.request('PUT', `${path}/redirect-uris`, {
+            body: { redirect_uris: desired },
+            headers: { 'if-match': before.redirect_uris_etag },
+            retryUnauthorized: false,
+        });
+        if (response.status < 200 || response.status >= 300) {
+            const error = remoteError(response.status, response.body);
+            if (response.status < 500)
+                throw new CallbackError({
+                    ...error,
+                    outcome: response.status === 412 || response.status === 409 ? 'conflict' : 'rejected',
+                });
+            writeError = error;
+        }
+    }
+    catch (error) {
+        if (error instanceof CallbackError)
+            throw error;
+        const detail = thrownError(error);
+        if (['unauthorized', 'expired', 'not_logged_in'].includes(detail.code))
+            throw new CallbackError({ ...detail, outcome: 'rejected' });
+        writeError = detail;
+    }
+    let observed;
+    try {
+        observed = await readCallbacks(api, path, input.appId);
+    }
+    catch (error) {
+        throw new CallbackError({
+            code: 'callback_update_unknown',
+            message: 'The callback update could not be verified. Run callbacks list before making another change; no update was retried.',
+            outcome: 'unknown',
+            ...(typeof writeError?.request_id === 'string' ? { request_id: writeError.request_id } : {}),
+            ...(writeError ? { write_error: writeError } : {}),
+            readback_error: thrownError(error),
+        });
+    }
+    if (!sameUris(desired, observed.redirect_uris))
+        throw new CallbackError({
+            code: 'callback_update_unconfirmed',
+            message: 'The current callback list does not match the requested list. Review callbacks list before making another change; no update was retried.',
+            outcome: 'unknown',
+            ...(typeof writeError?.request_id === 'string' ? { request_id: writeError.request_id } : {}),
+            ...(writeError ? { write_error: writeError } : {}),
+            current_redirect_uris: observed.redirect_uris,
+            expected_redirect_uris: desired,
+        });
+    return {
+        ok: true,
+        ...base,
+        ...observed,
+        changed: true,
+        outcome: 'confirmed',
+        verified: true,
+        ...(writeError ? { reconciled: true, write_error: writeError } : {}),
+    };
+}
+export async function runCallbacks(args, out, env) {
+    // Reject malformed invocations before loading credentials or contacting AI-Pay.
+    const input = inputOf(args);
+    let environment;
+    try {
+        const store = createAuthStore(env);
+        const stored = store.load();
+        if (stored) {
+            environment = { api_base: stored.api_base, auth_origin: stored.auth_origin };
+            // Check before openDeveloperApi can renew an expired token.
+            checkEnvironment(input.projectEnvironment, environment);
+        }
+        const api = await openDeveloperApi(store);
+        environment = { api_base: api.auth.api_base, auth_origin: api.auth.auth_origin };
+        // A concurrent CLI login may have replaced the stored environment between reads.
+        checkEnvironment(input.projectEnvironment, environment);
+        const result = await execute(api, input);
+        out.line('ok', input.action === 'list'
+            ? 'Registered developer callbacks'
+            : result.changed
+                ? 'Requested callback list verified.'
+                : 'Callback list already matches; no update needed.');
+        for (const uri of result.redirect_uris)
+            out.line('info', uri);
+        out.kv('api_base', environment.api_base);
+        out.kv('auth_origin', environment.auth_origin);
+        out.result({ ...result, ...environment });
+        return EXIT.ok;
+    }
+    catch (error) {
+        const detail = thrownError(error);
+        out.line('bad', detail.message);
+        if (environment) {
+            out.kv('api_base', environment.api_base);
+            out.kv('auth_origin', environment.auth_origin);
+        }
+        out.result({
+            ok: false,
+            app_id: input.appId,
+            action: input.action,
+            ...environment,
+            error: detail,
+        });
+        return error instanceof CliError ? error.exitCode : EXIT.remote;
+    }
+}

package/dist/commands/apps.js

@@ -10,6 +10,7 @@ import { flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
 import { errorMessage, openDeveloperApi } from '../developer-api.js';
 import { CliError, EXIT } from '../output.js';
+import { runCallbacks } from './app-callbacks.js';
 import { DEFAULT_CALLBACK } from './init.js';
 export async function createApp(api, input) {
     const key = input.key ?? `aipay-cli-${randomUUID()}`;
@@ -23,6 +24,14 @@ export async function createApp(api, input) {
 }
 export async function runApps(args, out, env = process.env) {
     const sub = args.positionals[0] ?? 'list';
+    if (sub === 'callbacks')
+        return runCallbacks(args, out, env);
+    if (sub !== 'list' && sub !== 'create')
+        throw new CliError('usage', `unknown apps subcommand "${sub}" (list | create | callbacks)`, EXIT.usage);
+    if (args.positionals.length > 1)
+        throw new CliError('usage', 'unexpected apps positional argument', EXIT.usage);
+    if (sub === 'create' && !flagString(args.flags, 'name'))
+        throw new CliError('usage', 'missing --name <app name>', EXIT.usage);
     const store = createAuthStore(env);
     const api = await openDeveloperApi(store);
     if (sub === 'list') {

package/dist/commands/doctor.js

@@ -6,8 +6,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { flagBool, flagString } from '../args.js';
+import { parseAppCallback } from '../callback-url.js';
 import { detectProject } from '../detect.js';
-import { parseCallback } from '../loopback.js';
 import { EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, readProject } from '../project.js';
 import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
@@ -54,11 +54,11 @@ export async function collectChecks(dir, opts, deps) {
         text: `linked to ${project.app.name ?? project.app.client_id} (.aipay/project.json)`,
     });
     try {
-        const t = parseCallback(project.callback);
+        const t = parseAppCallback(project.callback);
         checks.push({
             id: 'callback',
             level: 'ok',
-            text: `callback ${project.callback} (loopback, port ${t.port})`,
+            text: `callback ${project.callback} (${t.protocol === 'https:' ? 'HTTPS' : `loopback, port ${t.port || 80}`})`,
         });
     }
     catch (e) {

package/dist/commands/init.js

@@ -12,9 +12,9 @@ import { dirname, join, resolve } from 'node:path';
 import { AGENT_GUIDE_FILE, agentGuide } from '../agent-guide.js';
 import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
+import { parseAppCallback } from '../callback-url.js';
 import { detectProject, installCommand } from '../detect.js';
 import { openDeveloperApi } from '../developer-api.js';
-import { parseCallback } from '../loopback.js';
 import { CliError, EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, FRAMEWORKS, isFramework, mergeEnvFile, mergeGitignore, readProject, VITE_ENV_KEYS, writeProject, } from '../project.js';
 import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
@@ -57,7 +57,7 @@ export async function runInit(args, out, deps = {}) {
         throw new CliError('usage', `--app must be the app's client_id (a UUID), got "${clientId}"`, EXIT.usage);
     const authOrigin = originOf(flagString(args.flags, 'auth') ?? existing?.auth_origin ?? login?.auth_origin ?? null, '--auth');
     const apiBase = originOf(flagString(args.flags, 'api') ?? existing?.api_base ?? login?.api_base ?? null, '--api');
-    const target = parseCallback(callback); // throws on non-loopback
+    const target = parseAppCallback(callback);
     const dryRun = flagBool(args.flags, 'dry-run');
     const install = flagBool(args.flags, 'install', true);
     const name = flagString(args.flags, 'name') ?? createdName ?? existing?.app.name ?? null;
@@ -143,7 +143,7 @@ export async function runInit(args, out, deps = {}) {
             framework: det.framework,
             typescript: det.typescript,
             srcDir: det.srcDir,
-            callbackPath: target.path,
+            callbackPath: target.pathname,
         })) {
             const abs = join(dir, f.path);
             if (existsSync(abs))
@@ -216,7 +216,9 @@ export async function runInit(args, out, deps = {}) {
         }, out, env);
     out.blank();
     out.line('ok', dryRun ? 'dry run — nothing written' : `linked to app ${name ?? clientId}`);
-    out.line('info', 'next: run `aipay test` — it receives the callback on a free loopback port, so your dev server can keep running');
+    out.line('info', target.protocol === 'https:' || target.search
+        ? 'next: verify sign-in in the running app, or use `aipay test --callback <registered-http-loopback-url>` (without a query) to verify with a local receiver; project settings stay unchanged'
+        : 'next: run `aipay test` — it receives the callback on a free loopback port, so your dev server can keep running');
     out.result({
         ok: installExit === null || installExit === 0,
         dry_run: dryRun,

package/dist/commands/test.js

@@ -21,7 +21,16 @@ export async function runTest(args, out, deps = {}) {
         throw new CliError('not_linked', 'this directory is not linked to an app — run `aipay init --app <client_id> ...` first', EXIT.problem);
     const timeoutS = Number(flagString(args.flags, 'timeout') ?? '300');
     const fetchImpl = fetch;
-    const target = parseCallback(project.callback);
+    if ('callback' in args.flags && !flagString(args.flags, 'callback'))
+        throw new CliError('usage', '--callback requires a registered HTTP loopback URL', EXIT.usage);
+    const callback = flagString(args.flags, 'callback') ?? project.callback;
+    let target;
+    try {
+        target = parseCallback(callback);
+    }
+    catch {
+        throw new CliError('loopback_required', 'CLI test needs a registered HTTP loopback callback without query, fragment or credentials. Verify the hosted app in your browser, or pass --callback <registered-loopback-url>; the project configuration is preserved.', EXIT.usage);
+    }
     // 127.0.0.1: the authorization server ignores the port for loopback redirect URIs
     // (RFC 8252 §7.3), so the CLI takes any free port and your dev server can keep running.
     // localhost / explicit --port: bind exactly that port.
@@ -35,9 +44,9 @@ export async function runTest(args, out, deps = {}) {
     const redirectUri = redirectUriFor(target, loop.port);
     const cfg = { hydraPublicUrl: project.auth_origin, clientId: project.app.client_id, redirectUri };
     const { url, state, codeVerifier } = await createConnectUrl(cfg);
-    const note = redirectUri === project.callback
+    const note = redirectUri === callback
         ? ''
-        : ` (registered: ${project.callback}; the port is not compared for 127.0.0.1)`;
+        : ` (registered: ${callback}; the port is not compared for 127.0.0.1)`;
     out.line('info', `listening on ${redirectUri}${note}`);
     out.line('info', `sign in here (opens in your browser):\n\n  ${url}\n`);
     deps.onAuthorizeUrl?.(url);

package/dist/developer-api.d.ts

@@ -8,6 +8,7 @@ export interface DeveloperApi {
     request<T = Record<string, unknown>>(method: string, path: string, opts?: {
         body?: unknown;
         headers?: Record<string, string>;
+        retryUnauthorized?: boolean;
     }): Promise<ApiResult<T>>;
 }
 export declare function openDeveloperApi(store: AuthStore): Promise<DeveloperApi>;

package/dist/developer-api.js

@@ -18,6 +18,7 @@ export async function openDeveloperApi(store) {
         async request(method, path, opts = {}) {
             const call = async (a) => f(new URL(path, a.api_base), {
                 method,
+                signal: AbortSignal.timeout(30_000),
                 headers: {
                     authorization: `Bearer ${a.access_token}`,
                     ...(opts.body !== undefined ? { 'content-type': 'application/json' } : {}),
@@ -26,14 +27,14 @@ export async function openDeveloperApi(store) {
                 ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
             });
             let res = await call(api.auth);
-            if (res.status === 401 && api.auth.refresh_token) {
+            if (res.status === 401 && api.auth.refresh_token && opts.retryUnauthorized !== false) {
                 api.auth = await refresh(store, api.auth, f);
                 res = await call(api.auth);
             }
             const text = await res.text();
             if (isEmpty404(res.status, text))
                 throw new CliError('empty_404', EMPTY_404_HINT, EXIT.remote);
-            if (res.status === 401)
+            if (res.status === 401 && opts.retryUnauthorized !== false)
                 throw new CliError('unauthorized', 'the API rejected the developer token — run `aipay login` again', EXIT.remote);
             let body = null;
             try {

package/dist/loopback.js

@@ -5,6 +5,7 @@
  * disk; the token exchange happens in the caller's memory.
  */
 import { createServer } from 'node:http';
+import { hasUnsafeCallbackText } from './callback-url.js';
 /**
  * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
  * is ignored, so the CLI may receive the callback on any free port while the app keeps
@@ -20,6 +21,8 @@ export function redirectUriFor(target, port) {
 }
 export function parseCallback(callback) {
     const u = new URL(callback);
+    if (hasUnsafeCallbackText(callback) || u.username || u.password || u.search || u.hash)
+        throw new Error('CLI loopback callbacks cannot contain credentials, query, fragment, whitespace or wildcards');
     if (u.protocol !== 'http:')
         throw new Error(`callback must be http:// on a loopback host (got ${callback})`);
     const host = u.hostname;

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\napps    list your apps / create one (Idempotency-Key: a retried create never makes a second app)\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
+export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]\n  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\napps    list/create your apps; callbacks list/add/remove manages registered redirects\n        callback changes preserve other URLs and reject concurrent edits\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
 export declare function main(argv: string[], io?: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;

package/dist/main.js

@@ -16,18 +16,21 @@ Usage
   aipay whoami [--json] · aipay logout [--json]
   aipay apps list [--json]
   aipay apps create --name <name> [--callback <url>] [--json]
+  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]
+  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]
   aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]
              [--framework next|express|fastify|hono|vite|node]  override detection
              [--dir <path>] [--dry-run] [--no-install] [--json]
   aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it
-  aipay test [--model <id>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]
+  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]
   aipay doctor [--offline] [--dir <path>] [--json]
   aipay status [--dir <path>] [--json]
   aipay unlink [--dry-run] [--dir <path>] [--json]
 
 login   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the
         OS keychain or a 0600 file — never into the project
-apps    list your apps / create one (Idempotency-Key: a retried create never makes a second app)
+apps    list/create your apps; callbacks list/add/remove manages registered redirects
+        callback changes preserve other URLs and reject concurrent edits
 init    link this project to an app: .aipay/project.json, .env.local, .gitignore,
         a callback route for your framework, aipay-agent.md, and the SDK install
         (--auth/--api are optional once you are signed in; --create makes the app first)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.4.0",
-  "description": "AI-Pay CLI — init (link an app + scaffold the integration), doctor, test (real sign-in + first receipt), status, unlink. For developers and their coding agents.",
+  "version": "0.5.0",
+  "description": "AI-Pay CLI — developer sign-in, App and callback management, project integration, diagnostics, and real sign-in + AI receipt verification.",
   "license": "MIT",
   "type": "module",
   "bin": {