@coswic/aipay 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# @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.
+- Report empty 404 responses without inferring their cause.
+- Remove the retired `AIPAY_GATE_TOKEN` setting and automatic `X-AIPay-Gate` header injection. OAuth tokens, PKCE, device authorization, refresh and revocation retain their existing behavior.
+- **Programmatic compatibility:** remove the `GATE_ENV`, `gatedFetch`, `gateHeaders` and `looksGated` exports; use `isEmpty404` to identify an empty 404 response. Remove the gate-only environment arguments from `createRemote`, `fetchCliConfig`, `openDeveloperApi` and the doctor dependency interface. `Remote.fetchDocs`/`probe` results and init JSON use `empty404` instead of `gated`; the corresponding error code is `empty_404`.
+
+## 0.3.0
+
+- `aipay init --framework next|express|fastify|hono|vite|node` overrides framework detection.
+- Vite (browser SPA) projects: `init` writes a browser helper (`aipay.ts`, PKCE in the page,
+  tokens in sessionStorage) plus `aipay-boot.ts`, and `VITE_AIPAY_*` aliases in `.env.local`
+  (Vite exposes only VITE_-prefixed values). Server frameworks still win when both are present.
+- `aipay test` reports failures to the Console too (`cli.test` with `ok:false` and an error
+  code), so the verify step can show what went wrong.
+
+## 0.2.1
+
+Same content as 0.2.0. Version 0.2.0 on npm was published by mistake without `dist` (the
+tarball only had README and package.json); it is deprecated and `latest` points past it.
+Install 0.2.1 or later.
+
+## 0.2.0
+
+- `aipay login --device`: RFC 8628 device authorization for machines without a browser (SSH
+  boxes, containers, CI). Prints a URL and a short code; approve on any device; the CLI polls.
+  Requires an AI-Pay whose `/v1/cli/config` reports `device_authorization: true`.
+- Windows: developer tokens are now protected with DPAPI (Windows PowerShell
+  `ConvertFrom-SecureString`) in `%APPDATA%\aipay\credentials.dpapi` instead of a plaintext
+  `credentials.json`. An existing plaintext file is read once and replaced on the next login.
+  `AIPAY_TOKEN_STORE=file` keeps the old behaviour.
+- `aipay login` (browser flow) mentions `--device` when the server supports it.
+
+## 0.1.0
+
+- First release: `init`, `test`, `doctor`, `status`, `unlink`, `login`/`logout`/`whoami`,
+  `apps list`/`apps create`; loopback PKCE on any free port; tokens in the OS keychain or a
+  0600 file; setup progress reported to the Console.

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
@@ -37,16 +78,12 @@ own. Nothing is written to the project; tokens go to the keychain or the 0600 fi
 like the browser flow. With `--json`, the URL and code are echoed on stderr as
 `device_url …` / `user_code …` so an agent can show them to you.
 
-## Pilot gate
-
-During the closed pilot, non-public AI-Pay paths answer `404` with an empty body unless the
-request carries the gate token. Export it and the CLI sends it as `X-AIPay-Gate`:
-
-```bash
-export AIPAY_GATE_TOKEN=<token from the Console>
-```
+## Connection troubleshooting
 
-The CLI never writes the token to any file and never prints it.
+Check the configured API and authorization server URLs and network connectivity if a
+request fails. An empty `404` alone does not identify the cause; it does not establish
+whether a path is missing or why the server returned that response. Run `aipay doctor`
+to check the configured endpoints before retrying.
 
 ## What gets written
 

package/dist/agent-guide.d.ts

@@ -2,9 +2,9 @@
  * `aipay-agent.md`: the file a coding agent reads first. Header = the facts of THIS
  * project (app, endpoints, what was scaffolded, what "done" means); body = the AI-Pay
  * developer docs fetched from the API (`/docs.md?lang=en`), so the agent does not need
- * network access — or the gate token — to read them later.
+ * network access to read them later.
  *
- * Never contains tokens. If the docs are gated (404 with empty body) the file still gets
+ * Never contains tokens. If the docs cannot be fetched, the file still gets
  * written with the header and a pointer, and the CLI warns.
  */
 import type { ProjectConfig } from './project.js';

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,15 +30,16 @@ ${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.
-- The pilot gate token comes only from the \`AIPAY_GATE_TOKEN\` environment variable.
-  Never write it into code, config files, or version control.
+- 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.
 
@@ -53,8 +58,8 @@ ${input.docsMarkdown.trim()}
 # AI-Pay developer documentation
 
 The docs could not be fetched when this file was written (see the \`aipay init\` output).
-Read them at ${input.docsUrl} — during the pilot send the header \`X-AIPay-Gate\` with the
-value of \`AIPAY_GATE_TOKEN\`, or run \`aipay init\` again with the variable set.
+Check the endpoint URL and network connectivity, then read
+${input.docsUrl} or run \`aipay init\` again. An empty 404 alone does not identify the cause.
 `;
     return head + body;
 }

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,8 +24,16 @@ 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, env);
+    const api = await openDeveloperApi(store);
     if (sub === 'list') {
         const res = await api.request('GET', '/v1/developer/apps');
         if (res.status !== 200)

package/dist/commands/doctor.d.ts

@@ -8,10 +8,9 @@ export interface Check {
 }
 export interface DoctorDeps {
     remote?: Remote;
-    env?: NodeJS.ProcessEnv;
     nodeVersion?: string;
 }
 export declare function runDoctor(args: ParsedArgs, out: Reporter, deps?: DoctorDeps): Promise<number>;
 export declare function collectChecks(dir: string, opts: {
     offline: boolean;
-}, deps: DoctorDeps, env: NodeJS.ProcessEnv): Promise<Check[]>;
+}, deps: DoctorDeps): Promise<Check[]>;

package/dist/commands/doctor.js

@@ -6,16 +6,14 @@
 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 { GATE_ENV } from '../gate.js';
-import { parseCallback } from '../loopback.js';
 import { EXIT } from '../output.js';
 import { ENV_FILE, ENV_KEYS, readProject } from '../project.js';
-import { createRemote, docsUrl, GATE_HINT } from '../remote.js';
+import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
 export async function runDoctor(args, out, deps = {}) {
     const dir = resolve(flagString(args.flags, 'dir') ?? '.');
-    const env = deps.env ?? process.env;
-    const checks = await collectChecks(dir, { offline: flagBool(args.flags, 'offline') }, deps, env);
+    const checks = await collectChecks(dir, { offline: flagBool(args.flags, 'offline') }, deps);
     for (const c of checks)
         out.line(c.level, c.text);
     const problems = checks.filter((c) => c.level === 'bad');
@@ -24,7 +22,7 @@ export async function runDoctor(args, out, deps = {}) {
     out.result({ ok: problems.length === 0, dir, checks });
     return problems.length ? EXIT.problem : EXIT.ok;
 }
-export async function collectChecks(dir, opts, deps, env) {
+export async function collectChecks(dir, opts, deps) {
     const checks = [];
     const major = Number((deps.nodeVersion ?? process.versions.node).split('.')[0]);
     checks.push(major >= 20
@@ -56,11 +54,11 @@ export async function collectChecks(dir, opts, deps, env) {
         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) {
@@ -114,14 +112,8 @@ export async function collectChecks(dir, opts, deps, env) {
             if (!existsSync(join(dir, f)))
                 checks.push({ id: 'scaffold', level: 'warn', text: `scaffolded file removed: ${f}` });
     }
-    if (!env[GATE_ENV])
-        checks.push({
-            id: 'gate',
-            level: 'info',
-            text: `${GATE_ENV} not set (fine after the pilot; required during it)`,
-        });
     if (!opts.offline) {
-        const remote = deps.remote ?? createRemote(env);
+        const remote = deps.remote ?? createRemote();
         const oidc = await remote.probe(new URL('/.well-known/openid-configuration', project.auth_origin).toString());
         checks.push(oidc.ok
             ? {
@@ -137,8 +129,8 @@ export async function collectChecks(dir, opts, deps, env) {
         const api = await remote.probe(docsUrl(project.api_base, 'en'));
         if (api.ok)
             checks.push({ id: 'api', level: 'ok', text: `API reachable (${project.api_base})` });
-        else if (api.gated)
-            checks.push({ id: 'api', level: 'bad', text: `API ${project.api_base}: ${GATE_HINT}` });
+        else if (api.empty404)
+            checks.push({ id: 'api', level: 'bad', text: `API ${project.api_base}: ${EMPTY_404_HINT}` });
         else
             checks.push({
                 id: 'api',

package/dist/commands/init.js

@@ -4,8 +4,7 @@
  *
  * Links the project to an app and scaffolds the integration. Idempotent: rerunning
  * updates .aipay/project.json + .env.local and never overwrites files it did not write
- * this run. Nothing here needs an AI-Pay login (public client info only) — the gate
- * token, if any, is read from the environment for the docs fetch.
+ * this run. Linking an existing app uses public client info.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -13,13 +12,12 @@ 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 { GATE_ENV } from '../gate.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, GATE_HINT } from '../remote.js';
+import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
 import { reportSetupEvent } from '../setup-events.js';
 import { scaffoldFiles } from '../templates.js';
 import { cliVersion } from '../version.js';
@@ -43,7 +41,7 @@ export async function runInit(args, out, deps = {}) {
             throw new CliError('usage', 'pass either --app <client_id> or --create <name>, not both', EXIT.usage);
         if (!login)
             throw new CliError('not_logged_in', '--create needs a developer sign-in first: `aipay login --api <base>`', EXIT.problem);
-        const api = deps.developerApi ?? (await openDeveloperApi(createAuthStore(env), env));
+        const api = deps.developerApi ?? (await openDeveloperApi(createAuthStore(env)));
         const created = await createApp(api, {
             name: createName,
             callback,
@@ -59,11 +57,11 @@ 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;
-    const remote = deps.remote ?? createRemote(env);
+    const remote = deps.remote ?? createRemote();
     const now = (deps.now ?? (() => new Date()))();
     const det = detectProject(dir);
     // --framework: detection can be wrong (monorepos, unusual layouts) — the developer/agent may
@@ -145,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))
@@ -162,8 +160,8 @@ export async function runInit(args, out, deps = {}) {
     project.scaffold.files = Array.from(new Set([...project.scaffold.files, ...scaffolded]));
     // 5. docs → agent guide
     const docs = await remote.fetchDocs(apiBase, 'en');
-    if (docs.gated)
-        out.line('warn', GATE_HINT);
+    if (docs.empty404)
+        out.line('warn', EMPTY_404_HINT);
     else if (!docs.markdown)
         out.line('warn', `docs fetch failed (${docs.status}); guide written without the docs body`);
     const guidePath = join(dir, AGENT_GUIDE_FILE);
@@ -218,9 +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');
-    if (!env[GATE_ENV])
-        out.line('info', `pilot: if AI-Pay answers 404 with an empty body, export ${GATE_ENV} (Console → your app)`);
+    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,
@@ -229,7 +227,7 @@ export async function runInit(args, out, deps = {}) {
         detection: det,
         plan,
         install: installCmd ? { command: installCmd, exit: installExit } : null,
-        docs: { fetched: !!docs.markdown, gated: docs.gated, status: docs.status },
+        docs: { fetched: !!docs.markdown, empty404: docs.empty404, status: docs.status },
         reported,
     });
     return installExit === null || installExit === 0 ? EXIT.ok : EXIT.problem;

package/dist/commands/login.d.ts

@@ -21,7 +21,7 @@ export interface LoginDeps {
     fetchImpl?: typeof fetch;
     sleep?: (ms: number) => Promise<void>;
 }
-export declare function fetchCliConfig(apiBase: string, env: NodeJS.ProcessEnv): Promise<CliConfig>;
+export declare function fetchCliConfig(apiBase: string): Promise<CliConfig>;
 /** Resolve the API base: flag → env → linked project → error. */
 export declare function resolveApiBase(args: ParsedArgs, env: NodeJS.ProcessEnv, dir: string): string;
 /** Authorization URL for the management login. The SDK's createConnectUrl fixes the

package/dist/commands/login.js

@@ -15,23 +15,23 @@ import { flagBool, flagString } from '../args.js';
 import { createAuthStore } from '../auth-store.js';
 import { openBrowser } from '../browser.js';
 import { pollDeviceToken, requestDeviceCode } from '../device.js';
-import { GATE_ENV, gatedFetch, looksGated } from '../gate.js';
 import { startLoopback } from '../loopback.js';
+import { isEmpty404 } from '../network.js';
 import { CliError, EXIT } from '../output.js';
 import { readProject } from '../project.js';
-import { GATE_HINT } from '../remote.js';
-export async function fetchCliConfig(apiBase, env) {
-    const f = gatedFetch(env);
+import { EMPTY_404_HINT } from '../remote.js';
+export async function fetchCliConfig(apiBase) {
+    const f = fetch;
     let res;
     try {
         res = await f(new URL('/v1/cli/config', apiBase));
     }
     catch (e) {
-        throw new CliError('network', `cannot reach ${apiBase}: ${e.message}`, EXIT.remote);
+        throw new CliError('network', `cannot reach ${apiBase}: ${e.message}. Check the endpoint URL and network connectivity, then retry.`, EXIT.remote);
     }
     const text = await res.text();
-    if (looksGated(res.status, text))
-        throw new CliError('gated', GATE_HINT, EXIT.remote);
+    if (isEmpty404(res.status, text))
+        throw new CliError('empty_404', EMPTY_404_HINT, EXIT.remote);
     if (res.status === 404)
         throw new CliError('cli_disabled', `${apiBase} does not offer CLI sign-in (developer management is not enabled there)`, EXIT.remote);
     if (!res.ok)
@@ -91,9 +91,9 @@ export async function runLogin(args, out, deps = {}) {
     const env = deps.env ?? process.env;
     const dir = flagString(args.flags, 'dir') ?? '.';
     const apiBase = resolveApiBase(args, env, dir);
-    const cfg = await fetchCliConfig(apiBase, env);
+    const cfg = await fetchCliConfig(apiBase);
     const timeoutS = Number(flagString(args.flags, 'timeout') ?? '300');
-    const fetchImpl = deps.fetchImpl ?? gatedFetch(env);
+    const fetchImpl = deps.fetchImpl ?? fetch;
     if (flagBool(args.flags, 'device', false))
         return deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps);
     const loop = await startLoopback({ host: '127.0.0.1', port: 0, path: cfg.redirect_path }, { timeoutMs: timeoutS * 1000 });
@@ -174,8 +174,6 @@ async function finishLogin(tokens, cfg, apiBase, fetchImpl, env, out) {
     out.line('info', `tokens kept in ${store.where}${store.kind === 'file' ? ' — no keychain tool found; the file is readable only by you' : ''}`);
     if (!tokens.refreshToken)
         out.line('warn', 'no refresh token was granted; you will need to sign in again when this one expires');
-    if (!env[GATE_ENV])
-        out.line('info', `pilot: if the API answers 404 with an empty body later, export ${GATE_ENV}`);
     out.result({
         ok: true,
         api_base: apiBase,

package/dist/commands/session.js

@@ -1,6 +1,5 @@
 import { createAuthStore } from '../auth-store.js';
 import { openDeveloperApi } from '../developer-api.js';
-import { gatedFetch } from '../gate.js';
 import { CliError, EXIT } from '../output.js';
 export async function runWhoami(_args, out, env = process.env) {
     const store = createAuthStore(env);
@@ -10,7 +9,7 @@ export async function runWhoami(_args, out, env = process.env) {
         out.result({ signed_in: false });
         return EXIT.ok;
     }
-    const api = await openDeveloperApi(store, env); // refreshes if needed
+    const api = await openDeveloperApi(store); // refreshes if needed
     out.line('ok', `${api.auth.email ?? api.auth.sub} @ ${api.auth.api_base}`);
     out.kv('scope', api.auth.scope || '—');
     out.kv('expires', new Date(api.auth.expires_at).toISOString());
@@ -36,7 +35,7 @@ export async function runLogout(_args, out, env = process.env) {
     }
     // Best effort: revoke the refresh token (and with it the access token) at the authorization server.
     let revoked = false;
-    const f = gatedFetch(env);
+    const f = fetch;
     for (const token of [auth.refresh_token, auth.access_token]) {
         if (!token)
             continue;

package/dist/commands/test.js

@@ -9,11 +9,9 @@
 import { AIPayClient, AuthorizationError, ConnectError, createConnectUrl, getUserInfo, handleCallback, InsufficientBalanceError, } from '@coswic/aipay-sdk';
 import { flagBool, flagString } from '../args.js';
 import { openBrowser } from '../browser.js';
-import { GATE_ENV, gatedFetch, looksGated } from '../gate.js';
 import { parseCallback, portIsVariable, redirectUriFor, startLoopback } from '../loopback.js';
 import { CliError, EXIT } from '../output.js';
 import { readProject } from '../project.js';
-import { GATE_HINT } from '../remote.js';
 import { reportSetupEvent } from '../setup-events.js';
 export async function runTest(args, out, deps = {}) {
     const env = deps.env ?? process.env;
@@ -22,8 +20,17 @@ export async function runTest(args, out, deps = {}) {
     if (!project)
         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 = gatedFetch(env);
-    const target = parseCallback(project.callback);
+    const fetchImpl = fetch;
+    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.
@@ -37,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);
@@ -135,11 +142,10 @@ export async function runTest(args, out, deps = {}) {
             return e.exitCode;
         }
         const msg = e.message ?? String(e);
-        const gated = /404/.test(msg) && looksGated(404, '');
         result.error = { code: 'failed', message: msg };
-        out.line('bad', gated ? `${msg}\n${GATE_HINT}` : msg);
-        if (!env[GATE_ENV])
-            out.line('info', `pilot: if this was a 404 with an empty body, export ${GATE_ENV} and retry`);
+        out.line('bad', msg);
+        if (/\b404\b/.test(msg))
+            out.line('info', 'Check the endpoint URL and network connectivity before retrying.');
         out.result(result);
         return EXIT.remote;
     }

package/dist/developer-api.d.ts

@@ -8,7 +8,8 @@ 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, env?: NodeJS.ProcessEnv): Promise<DeveloperApi>;
+export declare function openDeveloperApi(store: AuthStore): Promise<DeveloperApi>;
 export declare function errorMessage(body: unknown, status: number): string;

package/dist/developer-api.js

@@ -1,17 +1,16 @@
 /**
  * Calls to the developer management API with the developer's own token (audience
- * aipay-developer-api). Refreshes once on 401 when a refresh token exists; the gate header
- * comes from the environment like everywhere else.
+ * aipay-developer-api). Refreshes once on 401 when a refresh token exists.
  */
 import { refreshAccessToken } from '@coswic/aipay-sdk';
-import { gatedFetch, looksGated } from './gate.js';
+import { isEmpty404 } from './network.js';
 import { CliError, EXIT } from './output.js';
-import { GATE_HINT } from './remote.js';
-export async function openDeveloperApi(store, env = process.env) {
+import { EMPTY_404_HINT } from './remote.js';
+export async function openDeveloperApi(store) {
     let auth = store.load();
     if (!auth)
         throw new CliError('not_logged_in', 'not signed in — run `aipay login` first', EXIT.problem);
-    const f = gatedFetch(env);
+    const f = fetch;
     if (auth.expires_at - 30_000 < Date.now())
         auth = await refresh(store, auth, f);
     const api = {
@@ -19,6 +18,7 @@ export async function openDeveloperApi(store, env = process.env) {
         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' } : {}),
@@ -27,14 +27,14 @@ export async function openDeveloperApi(store, env = process.env) {
                 ...(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 (looksGated(res.status, text))
-                throw new CliError('gated', GATE_HINT, EXIT.remote);
-            if (res.status === 401)
+            if (isEmpty404(res.status, text))
+                throw new CliError('empty_404', EMPTY_404_HINT, EXIT.remote);
+            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/index.d.ts

@@ -12,9 +12,9 @@ export { formatUusd, pickModel, runTest } from './commands/test.js';
 export { runUnlink, stripEnvKeys } from './commands/unlink.js';
 export { detectFramework, detectPackageManager, detectProject, installCommand } from './detect.js';
 export { openDeveloperApi } from './developer-api.js';
-export { GATE_ENV, gatedFetch, gateHeaders, looksGated } from './gate.js';
 export { parseCallback, startLoopback } from './loopback.js';
 export { main } from './main.js';
+export { isEmpty404 } from './network.js';
 export { CliError, createReporter, EXIT, type Reporter } from './output.js';
 export { ENV_KEYS, isProjectConfig, mergeEnvFile, mergeGitignore, type ProjectConfig, readProject, writeProject, } from './project.js';
 export { createRemote, docsUrl, type Remote } from './remote.js';

package/dist/index.js

@@ -12,9 +12,9 @@ export { formatUusd, pickModel, runTest } from './commands/test.js';
 export { runUnlink, stripEnvKeys } from './commands/unlink.js';
 export { detectFramework, detectPackageManager, detectProject, installCommand } from './detect.js';
 export { openDeveloperApi } from './developer-api.js';
-export { GATE_ENV, gatedFetch, gateHeaders, looksGated } from './gate.js';
 export { parseCallback, startLoopback } from './loopback.js';
 export { main } from './main.js';
+export { isEmpty404 } from './network.js';
 export { CliError, createReporter, EXIT } from './output.js';
 export { ENV_KEYS, isProjectConfig, mergeEnvFile, mergeGitignore, readProject, writeProject, } from './project.js';
 export { createRemote, docsUrl } from './remote.js';

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\nPilot gate: export AIPAY_GATE_TOKEN=<token from the Console>; never write it to files.\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)
@@ -37,7 +40,6 @@ status  what this directory is linked to
 unlink  forget the link (keeps your code)
 
 Exit codes: 0 ok · 1 problem you can fix · 2 usage · 3 network/auth
-Pilot gate: export AIPAY_GATE_TOKEN=<token from the Console>; never write it to files.
 `;
 export async function main(argv, io) {
     const args = parseArgs(argv);

package/dist/network.d.ts

@@ -0,0 +1,3 @@
+/** Describe the observed response without inferring its network or server-side cause. */
+export declare function isEmpty404(status: number, bodyText: string): boolean;
+export declare const EMPTY_404_HINT = "AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.";

package/dist/network.js

@@ -0,0 +1,5 @@
+/** Describe the observed response without inferring its network or server-side cause. */
+export function isEmpty404(status, bodyText) {
+    return status === 404 && bodyText.trim() === '';
+}
+export const EMPTY_404_HINT = 'AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.';

package/dist/project.js

@@ -1,8 +1,7 @@
 /**
  * Local artifacts (consultant report §6.5):
  *   .aipay/project.json  — committable: which app this project is linked to (no secrets)
- *   .env.local           — NOT committed: only public values today (client_id, URLs); the
- *                          gate token is read from the environment and never written
+ *   .env.local           — NOT committed: only public values (client_id, URLs)
  *   .gitignore           — gets `.env.local` and `.aipay/local/` appended once
  *
  * Tokens live only in memory for the duration of `aipay test`. Nothing here writes them.

package/dist/remote.d.ts

@@ -1,21 +1,21 @@
 /**
  * Everything that talks to AI-Pay over the network, in one place so the commands stay
- * readable and tests can stub it. Gate header via the environment (see gate.ts).
+ * readable and tests can stub it.
  */
-import { GATE_HINT } from './gate.js';
+import { EMPTY_404_HINT } from './network.js';
 export interface Remote {
     fetchDocs(apiBase: string, locale?: 'en' | 'zh-Hant'): Promise<{
         markdown: string | null;
-        gated: boolean;
+        empty404: boolean;
         status: number;
     }>;
     probe(url: string): Promise<{
         ok: boolean;
         status: number;
-        gated: boolean;
+        empty404: boolean;
         error?: string;
     }>;
 }
-export declare function createRemote(env?: NodeJS.ProcessEnv): Remote;
+export declare function createRemote(): Remote;
 export declare function docsUrl(apiBase: string, locale?: 'en' | 'zh-Hant'): string;
-export { GATE_HINT };
+export { EMPTY_404_HINT };

package/dist/remote.js

@@ -1,11 +1,11 @@
 /**
  * Everything that talks to AI-Pay over the network, in one place so the commands stay
- * readable and tests can stub it. Gate header via the environment (see gate.ts).
+ * readable and tests can stub it.
  */
-import { GATE_HINT, gatedFetch, looksGated } from './gate.js';
+import { EMPTY_404_HINT, isEmpty404 } from './network.js';
 import { CliError, EXIT } from './output.js';
-export function createRemote(env = process.env) {
-    const f = gatedFetch(env);
+export function createRemote() {
+    const f = fetch;
     return {
         async fetchDocs(apiBase, locale = 'en') {
             const url = docsUrl(apiBase, locale);
@@ -14,21 +14,21 @@ export function createRemote(env = process.env) {
                 res = await f(url, { headers: { accept: 'text/markdown, text/plain' } });
             }
             catch (e) {
-                throw new CliError('network', `cannot reach ${url}: ${e.message}`, EXIT.remote);
+                throw new CliError('network', `cannot reach ${url}: ${e.message}. Check the endpoint URL and network connectivity, then retry.`, EXIT.remote);
             }
             const text = await res.text();
             if (res.ok)
-                return { markdown: text, gated: false, status: res.status };
-            return { markdown: null, gated: looksGated(res.status, text), status: res.status };
+                return { markdown: text, empty404: false, status: res.status };
+            return { markdown: null, empty404: isEmpty404(res.status, text), status: res.status };
         },
         async probe(url) {
             try {
                 const res = await f(url, { method: 'GET', redirect: 'manual' });
                 const text = await res.text();
-                return { ok: res.ok, status: res.status, gated: looksGated(res.status, text) };
+                return { ok: res.ok, status: res.status, empty404: isEmpty404(res.status, text) };
             }
             catch (e) {
-                return { ok: false, status: 0, gated: false, error: e.message };
+                return { ok: false, status: 0, empty404: false, error: e.message };
             }
         },
     };
@@ -38,4 +38,4 @@ export function docsUrl(apiBase, locale = 'en') {
     u.searchParams.set('lang', locale);
     return u.toString();
 }
-export { GATE_HINT };
+export { EMPTY_404_HINT };

package/dist/setup-events.js

@@ -11,7 +11,7 @@ export async function reportSetupEvent(appId, kind, detail, out, env = process.e
     if (!store.load())
         return false; // not signed in with the CLI → the Console still sees server facts
     try {
-        const api = await openDeveloperApi(store, env);
+        const api = await openDeveloperApi(store);
         const res = await api.request('POST', `/v1/developer/apps/${encodeURIComponent(appId)}/setup-events`, {
             body: { kind, detail },
         });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.3.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": {
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -24,7 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@coswic/aipay-sdk": "^0.3.1"
+    "@coswic/aipay-sdk": "^0.3.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/dist/gate.d.ts

@@ -1,13 +0,0 @@
-/**
- * Pilot gate: during the closed pilot, non-public paths answer 404 with an empty body
- * unless the request carries `X-AIPay-Gate: <token>` (or the browser cookie set by
- * `/__gate/<token>`). The CLI only ever reads the token from the environment — it is
- * never written to any file and never printed.
- */
-export declare const GATE_ENV = "AIPAY_GATE_TOKEN";
-export declare function gateHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
-/** fetch wrapper that adds the gate header; passed to the SDK as `fetchImpl`. */
-export declare function gatedFetch(env?: NodeJS.ProcessEnv): typeof fetch;
-/** Explain a 404-with-empty-body in gate terms (the SDK/API otherwise say "not found"). */
-export declare function looksGated(status: number, bodyText: string): boolean;
-export declare const GATE_HINT = "AI-Pay answered 404 with an empty body \u2014 that is the pilot gate, not a missing route. Set AIPAY_GATE_TOKEN in your environment (the value is in the Console next to the app) and retry. Do not put it in code or version control.";

package/dist/gate.js

@@ -1,29 +0,0 @@
-/**
- * Pilot gate: during the closed pilot, non-public paths answer 404 with an empty body
- * unless the request carries `X-AIPay-Gate: <token>` (or the browser cookie set by
- * `/__gate/<token>`). The CLI only ever reads the token from the environment — it is
- * never written to any file and never printed.
- */
-export const GATE_ENV = 'AIPAY_GATE_TOKEN';
-export function gateHeaders(env = process.env) {
-    const token = env[GATE_ENV];
-    return token ? { 'X-AIPay-Gate': token } : {};
-}
-/** fetch wrapper that adds the gate header; passed to the SDK as `fetchImpl`. */
-export function gatedFetch(env = process.env) {
-    const extra = gateHeaders(env);
-    if (!Object.keys(extra).length)
-        return fetch;
-    return (input, init) => {
-        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
-        for (const [k, v] of Object.entries(extra))
-            if (!headers.has(k))
-                headers.set(k, v);
-        return fetch(input, { ...init, headers });
-    };
-}
-/** Explain a 404-with-empty-body in gate terms (the SDK/API otherwise say "not found"). */
-export function looksGated(status, bodyText) {
-    return status === 404 && bodyText.trim() === '';
-}
-export const GATE_HINT = `AI-Pay answered 404 with an empty body — that is the pilot gate, not a missing route. Set ${GATE_ENV} in your environment (the value is in the Console next to the app) and retry. Do not put it in code or version control.`;