@coswic/aipay 0.1.0 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ npx @coswic/aipay test
 
 | Command | What it does |
 |---|---|
-| `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), `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 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. |
 | `aipay status` | What this directory is linked to. |
@@ -22,6 +22,21 @@ 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.
 
+## Signing in from a remote machine
+
+`aipay login` opens a browser on this machine (loopback PKCE). On an SSH box, a container or
+CI there is no browser, so use the device flow (RFC 8628):
+
+```
+aipay login --device --api https://api.example
+```
+
+The CLI prints a URL and a short code. Open the URL in a browser on any device (your laptop,
+your phone), enter the code, sign in and confirm — the CLI is polling and finishes on its
+own. Nothing is written to the project; tokens go to the keychain or the 0600 file exactly
+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
@@ -45,6 +60,13 @@ src/aipay-routes.ts   # framework wiring (or app/auth/aipay/*/route.ts for Next.
 
 Access and refresh tokens obtained by `aipay test` live in memory only.
 
+Your own developer tokens (`aipay login`) never touch the project either. They go to the
+macOS Keychain (`security`), the Linux keyring (`secret-tool`), or on Windows a file
+encrypted with DPAPI for your user account (`%APPDATA%\aipay\credentials.dpapi`, via
+Windows PowerShell) — and only when none of those exist, a `credentials.json` readable by
+you alone (mode 0600), with a warning at login. `AIPAY_TOKEN_STORE=file` forces the plain
+file; `AIPAY_CONFIG_DIR` moves the directory.
+
 ## Development
 
 ```bash

package/dist/auth-store.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Where the developer's management tokens live between commands.
+ *
+ * Order of preference (decision D5, 2026-09-04): the OS keychain when a CLI for it exists
+ * (macOS `security`, Linux `secret-tool`), on Windows a DPAPI-protected file (Windows
+ * PowerShell's ConvertFrom-SecureString — encrypted for this Windows user, no plaintext on
+ * disk), else a 0600 file under the user's config dir with a one-line warning at login.
+ * Tokens are never written into the project directory. `AIPAY_TOKEN_STORE=file` forces the
+ * plain file everywhere (escape hatch when a keychain misbehaves).
+ */
+import { type SpawnSyncOptions, type SpawnSyncReturns } from 'node:child_process';
 export interface StoredAuth {
     api_base: string;
     auth_origin: string;
@@ -11,7 +22,8 @@ export interface StoredAuth {
     sub: string;
 }
 export interface AuthStore {
-    kind: 'keychain' | 'file';
+    /** keychain = OS secret service; dpapi = Windows user-scoped encryption; file = plain 0600 file */
+    kind: 'keychain' | 'dpapi' | 'file';
     load(): StoredAuth | null;
     save(auth: StoredAuth): void;
     clear(): void;
@@ -20,4 +32,16 @@ export interface AuthStore {
 }
 export declare function configDir(env?: NodeJS.ProcessEnv): string;
 export declare function createAuthStore(env?: NodeJS.ProcessEnv): AuthStore;
+/** Minimal spawn shape the DPAPI store needs (injectable so the round-trip is unit-testable off Windows). */
+export type Exec = (cmd: string, args: string[], opts: SpawnSyncOptions & {
+    encoding: 'utf8';
+}) => Pick<SpawnSyncReturns<string>, 'status' | 'stdout'>;
+/**
+ * Windows: DPAPI (user scope) via PowerShell — the same primitive the OS uses for saved
+ * credentials. The file holds only the encrypted blob; another Windows account (or a copy
+ * of the file on another machine) cannot decrypt it. The token JSON is base64-encoded
+ * before protection so no PowerShell console encoding can mangle it. A plain
+ * `credentials.json` left by CLI 0.1.0 is still read, and replaced on the next save.
+ */
+export declare function dpapiStore(dir: string, exec?: Exec): AuthStore;
 export declare function fileStore(dir: string): AuthStore;

package/dist/auth-store.js

@@ -2,8 +2,11 @@
  * Where the developer's management tokens live between commands.
  *
  * Order of preference (decision D5, 2026-09-04): the OS keychain when a CLI for it exists
- * (macOS `security`, Linux `secret-tool`), else a 0600 file under the user's config dir
- * with a one-line warning at login. Tokens are never written into the project directory.
+ * (macOS `security`, Linux `secret-tool`), on Windows a DPAPI-protected file (Windows
+ * PowerShell's ConvertFrom-SecureString — encrypted for this Windows user, no plaintext on
+ * disk), else a 0600 file under the user's config dir with a one-line warning at login.
+ * Tokens are never written into the project directory. `AIPAY_TOKEN_STORE=file` forces the
+ * plain file everywhere (escape hatch when a keychain misbehaves).
  */
 import { spawnSync } from 'node:child_process';
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -28,9 +31,69 @@ export function createAuthStore(env = process.env) {
             return macKeychain();
         if (process.platform === 'linux' && has('secret-tool'))
             return secretTool();
+        if (process.platform === 'win32' && has('powershell'))
+            return dpapiStore(configDir(env));
     }
     return fileStore(configDir(env));
 }
+/** Windows PowerShell 5.1 ships with every Windows; `-NoProfile -NonInteractive` keeps it quiet and fast. */
+const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'];
+/** stdin → DPAPI blob (hex). The secret travels over stdin only — never in argv (visible in Task Manager/ETW). */
+const PS_PROTECT = '$in=[Console]::In.ReadToEnd().Trim(); $s=ConvertTo-SecureString -String $in -AsPlainText -Force; ConvertFrom-SecureString -SecureString $s';
+/** DPAPI blob (hex) on stdin → plaintext on stdout. */
+const PS_UNPROTECT = '$in=[Console]::In.ReadToEnd().Trim(); $s=ConvertTo-SecureString -String $in; [System.Net.NetworkCredential]::new("", $s).Password';
+/**
+ * Windows: DPAPI (user scope) via PowerShell — the same primitive the OS uses for saved
+ * credentials. The file holds only the encrypted blob; another Windows account (or a copy
+ * of the file on another machine) cannot decrypt it. The token JSON is base64-encoded
+ * before protection so no PowerShell console encoding can mangle it. A plain
+ * `credentials.json` left by CLI 0.1.0 is still read, and replaced on the next save.
+ */
+export function dpapiStore(dir, exec = spawnSync) {
+    const file = join(dir, 'credentials.dpapi');
+    const legacy = fileStore(dir);
+    const run = (script, input) => {
+        const r = exec('powershell', [...PS_ARGS, script], {
+            input,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            windowsHide: true,
+        });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        const out = r.stdout.trim();
+        return out ? out : null;
+    };
+    return {
+        kind: 'dpapi',
+        where: `${file} (encrypted for this Windows user with DPAPI)`,
+        load() {
+            if (!existsSync(file))
+                return legacy.load();
+            const plain = run(PS_UNPROTECT, readFileSync(file, 'utf8'));
+            if (!plain)
+                return null;
+            try {
+                return parse(Buffer.from(plain, 'base64').toString('utf8'));
+            }
+            catch {
+                return null;
+            }
+        },
+        save(auth) {
+            const blob = run(PS_PROTECT, Buffer.from(JSON.stringify(auth), 'utf8').toString('base64'));
+            if (!blob)
+                throw new Error('could not protect the tokens with Windows DPAPI (PowerShell failed)');
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(file, `${blob}\n`);
+            legacy.clear(); // a 0.1.0 plaintext file must not outlive the encrypted one
+        },
+        clear() {
+            rmSync(file, { force: true });
+            legacy.clear();
+        },
+    };
+}
 function macKeychain() {
     const account = 'developer';
     return {

package/dist/commands/init.js

@@ -18,7 +18,7 @@ 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, mergeEnvFile, mergeGitignore, readProject, writeProject, } from '../project.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 { reportSetupEvent } from '../setup-events.js';
 import { scaffoldFiles } from '../templates.js';
@@ -66,10 +66,18 @@ export async function runInit(args, out, deps = {}) {
     const remote = deps.remote ?? createRemote(env);
     const now = (deps.now ?? (() => new Date()))();
     const det = detectProject(dir);
+    // --framework: detection can be wrong (monorepos, unusual layouts) — the developer/agent may
+    // name the target; the value must be one we have templates for.
+    const forced = flagString(args.flags, 'framework');
+    if (forced !== undefined && forced !== null) {
+        if (!isFramework(forced))
+            throw new CliError('usage', `--framework must be one of ${FRAMEWORKS.join(', ')} (got "${forced}")`, EXIT.usage);
+        det.framework = forced;
+    }
     out.line('info', `project: ${dir}`);
     out.kv('package.json', det.hasPackageJson ? 'found' : 'none (plain directory)');
     out.kv('manager', det.packageManager ?? '—');
-    out.kv('framework', det.framework ?? '—');
+    out.kv('framework', `${det.framework ?? '—'}${forced ? ' (from --framework)' : ''}`);
     out.kv('language', det.typescript ? 'TypeScript' : 'JavaScript');
     out.kv('callback', callback);
     const plan = [];
@@ -96,6 +104,15 @@ export async function runInit(args, out, deps = {}) {
         [ENV_KEYS.authOrigin]: authOrigin,
         [ENV_KEYS.apiBase]: apiBase,
         [ENV_KEYS.callback]: callback,
+        // Vite exposes only VITE_-prefixed values to the browser: same four public values, aliased.
+        ...(det.framework === 'vite'
+            ? {
+                [VITE_ENV_KEYS.clientId]: clientId,
+                [VITE_ENV_KEYS.authOrigin]: authOrigin,
+                [VITE_ENV_KEYS.apiBase]: apiBase,
+                [VITE_ENV_KEYS.callback]: callback,
+            }
+            : {}),
     });
     if (envMerged.changed.length) {
         plan.push({

package/dist/commands/login.d.ts

@@ -6,11 +6,20 @@ export interface CliConfig {
     scopes: string[];
     redirect_path: string;
     audience: string;
+    /** A2: the server allows the device grant for the CLI (older APIs omit it = false). */
+    device_authorization: boolean;
 }
 export interface LoginDeps {
     env?: NodeJS.ProcessEnv;
     open?: (url: string) => boolean;
     onAuthorizeUrl?: (url: string) => void;
+    /** A2: called with the verification URL and the user code (tests / drivers). */
+    onDeviceCode?: (info: {
+        url: string;
+        userCode: string;
+    }) => void;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare function fetchCliConfig(apiBase: string, env: NodeJS.ProcessEnv): Promise<CliConfig>;
 /** Resolve the API base: flag → env → linked project → error. */

package/dist/commands/login.js

@@ -1,16 +1,20 @@
 /**
- * `aipay login [--api <base>] [--no-open] [--timeout <s>] [--json]`
+ * `aipay login [--api <base>] [--device] [--no-open] [--timeout <s>] [--json]`
  *
- * Developer sign-in for the CLI itself (consultant §10.2, auth model A / A1): the CLI is
- * a first-party public client. It asks the API for its client config, runs loopback PKCE
- * against the authorization server with audience aipay-developer-api and the management
- * scope, then keeps the tokens in the OS keychain (or a 0600 file). No app secrets exist.
+ * Developer sign-in for the CLI itself (consultant §10.2, auth model A): the CLI is a
+ * first-party public client. It asks the API for its client config, then either
+ *   A1 — runs loopback PKCE against the authorization server (a browser on this machine), or
+ *   A2 — `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
+ *        CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
+ * Both use audience aipay-developer-api and the management scope, and keep the tokens in
+ * the OS keychain (or a 0600 file). No app secrets exist.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { exchangeCode, getUserInfo } from '@coswic/aipay-sdk';
 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 { CliError, EXIT } from '../output.js';
@@ -43,6 +47,7 @@ export async function fetchCliConfig(apiBase, env) {
         scopes: cfg.scopes.filter((s) => typeof s === 'string'),
         redirect_path: typeof cfg.redirect_path === 'string' ? cfg.redirect_path : '/cli/callback',
         audience: typeof cfg.audience === 'string' ? cfg.audience : 'aipay-developer-api',
+        device_authorization: cfg.device_authorization === true,
     };
 }
 /** Resolve the API base: flag → env → linked project → error. */
@@ -88,16 +93,20 @@ export async function runLogin(args, out, deps = {}) {
     const apiBase = resolveApiBase(args, env, dir);
     const cfg = await fetchCliConfig(apiBase, env);
     const timeoutS = Number(flagString(args.flags, 'timeout') ?? '300');
+    const fetchImpl = deps.fetchImpl ?? gatedFetch(env);
+    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 });
     const redirectUri = `http://127.0.0.1:${loop.port}${cfg.redirect_path}`;
     const { url, state, codeVerifier } = managementAuthorizeUrl(cfg, redirectUri);
     out.line('info', `signing in to ${apiBase} as a developer — approve "AI-Pay CLI" in your browser:\n\n  ${url}\n`);
+    if (cfg.device_authorization)
+        out.line('info', 'no browser on this machine? run `aipay login --device` instead');
     if (out.json)
         out.debug(`authorize_url ${url}`);
     deps.onAuthorizeUrl?.(url);
     if (flagBool(args.flags, 'open', true))
         (deps.open ?? openBrowser)(url);
-    const fetchImpl = gatedFetch(env);
     try {
         const cb = await loop.waitForCallback;
         const u = new URL(cb.url);
@@ -110,40 +119,71 @@ export async function runLogin(args, out, deps = {}) {
         if (!code)
             throw new CliError('remote', 'callback without a code', EXIT.remote);
         const tokens = await exchangeCode({ hydraPublicUrl: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
-        const user = await getUserInfo({ hydraPublicUrl: cfg.auth_origin }, tokens.accessToken, {
-            fetchImpl,
-        });
-        const store = createAuthStore(env);
-        const auth = {
-            api_base: apiBase,
-            auth_origin: cfg.auth_origin,
-            client_id: cfg.client_id,
-            access_token: tokens.accessToken,
-            refresh_token: tokens.refreshToken,
-            expires_at: Date.now() + tokens.expiresInSeconds * 1000,
+        return finishLogin({
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresInSeconds: tokens.expiresInSeconds,
             scope: tokens.scope,
-            email: user.email ?? null,
-            sub: user.sub,
-        };
-        store.save(auth);
-        out.line('ok', `signed in as ${auth.email ?? auth.sub}`);
-        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,
-            email: auth.email,
-            sub: auth.sub,
-            scope: auth.scope,
-            store: store.kind,
-            expires_at: auth.expires_at,
-        });
-        return EXIT.ok;
+        }, cfg, apiBase, fetchImpl, env, out);
     }
     finally {
         await loop.close();
     }
 }
+/** A2 (RFC 8628): print URL + code, poll until approved on another device. */
+async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
+    if (!cfg.device_authorization)
+        throw new CliError('device_unsupported', `${apiBase} does not offer device sign-in yet — run \`aipay login\` on a machine with a browser`, EXIT.remote);
+    const client = {
+        authOrigin: cfg.auth_origin,
+        clientId: cfg.client_id,
+        scopes: cfg.scopes,
+        audience: cfg.audience,
+    };
+    const auth = await requestDeviceCode(client, fetchImpl);
+    const url = auth.verificationUriComplete ?? auth.verificationUri;
+    out.line('info', `signing in to ${apiBase} as a developer — on any device with a browser, open:\n\n  ${url}\n\n  and enter the code:  ${auth.userCode}\n`);
+    out.line('info', `waiting for approval (the code expires in ${Math.round(auth.expiresInSeconds / 60)} min)…`);
+    if (out.json) {
+        out.debug(`device_url ${url}`);
+        out.debug(`user_code ${auth.userCode}`);
+    }
+    deps.onDeviceCode?.({ url, userCode: auth.userCode });
+    const tokens = await pollDeviceToken(client, { ...auth, expiresInSeconds: Math.min(auth.expiresInSeconds, timeoutS) }, { fetchImpl, ...(deps.sleep ? { sleep: deps.sleep } : {}) });
+    return finishLogin(tokens, cfg, apiBase, fetchImpl, env, out);
+}
+/** Shared tail of both flows: identity → keychain/file → summary. */
+async function finishLogin(tokens, cfg, apiBase, fetchImpl, env, out) {
+    const user = await getUserInfo({ hydraPublicUrl: cfg.auth_origin }, tokens.accessToken, {
+        fetchImpl,
+    });
+    const store = createAuthStore(env);
+    const auth = {
+        api_base: apiBase,
+        auth_origin: cfg.auth_origin,
+        client_id: cfg.client_id,
+        access_token: tokens.accessToken,
+        refresh_token: tokens.refreshToken,
+        expires_at: Date.now() + tokens.expiresInSeconds * 1000,
+        scope: tokens.scope,
+        email: user.email ?? null,
+        sub: user.sub,
+    };
+    store.save(auth);
+    out.line('ok', `signed in as ${auth.email ?? auth.sub}`);
+    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,
+        email: auth.email,
+        sub: auth.sub,
+        scope: auth.scope,
+        store: store.kind,
+        expires_at: auth.expires_at,
+    });
+    return EXIT.ok;
+}

package/dist/commands/test.js

@@ -114,6 +114,7 @@ export async function runTest(args, out, deps = {}) {
             if (e instanceof InsufficientBalanceError) {
                 result.completion = { error: 'insufficient_balance' };
                 out.line('warn', 'signed in fine, but this account has no balance for a completion — top up in the Console and rerun');
+                await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: 'insufficient_balance' }, out, env);
                 out.result(result);
                 return EXIT.problem;
             }
@@ -128,6 +129,8 @@ export async function runTest(args, out, deps = {}) {
         if (e instanceof CliError) {
             result.error = { code: e.code, message: e.message };
             out.line('bad', e.message);
+            // 顧問 §13.2：失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
+            await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: e.code }, out, env);
             out.result(result);
             return e.exitCode;
         }

package/dist/commands/unlink.js

@@ -7,7 +7,7 @@ import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { flagBool, flagString } from '../args.js';
 import { EXIT } from '../output.js';
-import { ENV_FILE, ENV_KEYS, PROJECT_DIR, projectPath, readProject } from '../project.js';
+import { ENV_FILE, ENV_KEYS, PROJECT_DIR, projectPath, readProject, VITE_ENV_KEYS, } from '../project.js';
 export function runUnlink(args, out) {
     const dir = resolve(flagString(args.flags, 'dir') ?? '.');
     const dryRun = flagBool(args.flags, 'dry-run');
@@ -22,7 +22,10 @@ export function runUnlink(args, out) {
     let envChanged = false;
     if (existsSync(envPath)) {
         const before = readFileSync(envPath, 'utf8');
-        const after = stripEnvKeys(before, Object.values(ENV_KEYS));
+        const after = stripEnvKeys(before, [
+            ...Object.values(ENV_KEYS),
+            ...Object.values(VITE_ENV_KEYS),
+        ]);
         envChanged = after !== before;
         if (envChanged && !dryRun)
             writeFileSync(envPath, after);

package/dist/detect.js

@@ -34,6 +34,10 @@ export function detectFramework(pkg) {
         return 'fastify';
     if ('express' in deps)
         return 'express';
+    // Browser SPA (React/Vue/Svelte on Vite): PKCE runs in the browser; no server route to write.
+    // A project with both a server framework and Vite is treated as the server (routes win above).
+    if ('vite' in deps)
+        return 'vite';
     return 'node';
 }
 export function detectProject(dir) {

package/dist/device.d.ts

@@ -0,0 +1,38 @@
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** Same URL with the user code embedded (RFC 8628 §3.3.1) when the server offers one. */
+    verificationUriComplete: string | null;
+    expiresInSeconds: number;
+    /** Minimum seconds between polls (server-suggested; slow_down adds 5s). */
+    intervalSeconds: number;
+}
+export interface DeviceTokens {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresInSeconds: number;
+    scope: string;
+}
+export interface DeviceClientConfig {
+    authOrigin: string;
+    clientId: string;
+    scopes: string[];
+    audience: string;
+}
+/** POST /oauth2/device/auth — public client, so only client_id/scope/audience are sent. */
+export declare function requestDeviceCode(cfg: DeviceClientConfig, fetchImpl?: typeof fetch): Promise<DeviceAuthorization>;
+export interface PollOptions {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Called before each wait (progress dots for humans). */
+    onWait?: (secondsLeft: number) => void;
+}
+/**
+ * Poll POST /oauth2/token with the device grant until the developer approves, denies, or the
+ * code expires. `authorization_pending` → wait `interval`; `slow_down` → interval += 5s
+ * (RFC 8628 §3.5); anything else is final.
+ */
+export declare function pollDeviceToken(cfg: DeviceClientConfig, auth: DeviceAuthorization, opts?: PollOptions): Promise<DeviceTokens>;

package/dist/device.js

@@ -0,0 +1,122 @@
+/**
+ * RFC 8628 device authorization for `aipay login --device` (consultant §10.2, auth model A2):
+ * for machines without a browser (SSH boxes, containers, CI). The CLI asks the
+ * authorization server for a device code + a short user code, prints the verification
+ * URL and the code, then polls the token endpoint until the developer approves it in
+ * a browser on any device. No loopback listener, no ports.
+ */
+import { CliError, EXIT } from './output.js';
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** POST /oauth2/device/auth — public client, so only client_id/scope/audience are sent. */
+export async function requestDeviceCode(cfg, fetchImpl = fetch) {
+    const form = new URLSearchParams({
+        client_id: cfg.clientId,
+        scope: cfg.scopes.join(' '),
+        audience: cfg.audience,
+    });
+    let res;
+    try {
+        res = await fetchImpl(new URL('/oauth2/device/auth', cfg.authOrigin), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+    }
+    catch (e) {
+        throw new CliError('network', `cannot reach ${cfg.authOrigin}: ${e.message}`, EXIT.remote);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        const err = parseOAuthError(text);
+        if (err?.error === 'invalid_grant' || err?.error === 'unauthorized_client')
+            throw new CliError('device_unsupported', 'this AI-Pay does not allow device sign-in for the CLI yet — use `aipay login` on a machine with a browser', EXIT.remote);
+        throw new CliError('remote', `device authorization failed: HTTP ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+    }
+    const j = JSON.parse(text);
+    if (typeof j.device_code !== 'string' ||
+        typeof j.user_code !== 'string' ||
+        typeof j.verification_uri !== 'string')
+        throw new CliError('remote', 'unexpected device authorization response', EXIT.remote);
+    return {
+        deviceCode: j.device_code,
+        userCode: j.user_code,
+        verificationUri: j.verification_uri,
+        verificationUriComplete: typeof j.verification_uri_complete === 'string' ? j.verification_uri_complete : null,
+        expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 600,
+        intervalSeconds: typeof j.interval === 'number' && j.interval > 0 ? j.interval : 5,
+    };
+}
+/**
+ * Poll POST /oauth2/token with the device grant until the developer approves, denies, or the
+ * code expires. `authorization_pending` → wait `interval`; `slow_down` → interval += 5s
+ * (RFC 8628 §3.5); anything else is final.
+ */
+export async function pollDeviceToken(cfg, auth, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + auth.expiresInSeconds * 1000;
+    let interval = auth.intervalSeconds;
+    for (;;) {
+        if (now() >= deadline)
+            throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+        opts.onWait?.(Math.max(0, Math.round((deadline - now()) / 1000)));
+        await sleep(interval * 1000);
+        const form = new URLSearchParams({
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: auth.deviceCode,
+            client_id: cfg.clientId,
+        });
+        let res;
+        try {
+            res = await fetchImpl(new URL('/oauth2/token', cfg.authOrigin), {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: form.toString(),
+            });
+        }
+        catch {
+            continue; // transient network blip: keep polling until the deadline
+        }
+        const text = await res.text();
+        if (res.ok) {
+            const j = JSON.parse(text);
+            if (typeof j.access_token !== 'string')
+                throw new CliError('remote', 'token response missing access_token', EXIT.remote);
+            return {
+                accessToken: j.access_token,
+                refreshToken: typeof j.refresh_token === 'string' ? j.refresh_token : null,
+                expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 0,
+                scope: typeof j.scope === 'string' ? j.scope : cfg.scopes.join(' '),
+            };
+        }
+        const err = parseOAuthError(text);
+        switch (err?.error) {
+            case 'authorization_pending':
+                continue;
+            case 'slow_down':
+                interval += 5;
+                continue;
+            case 'expired_token':
+                throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+            case 'access_denied':
+                throw new CliError('denied', 'sign-in was denied in the browser', EXIT.remote);
+            default:
+                throw new CliError('remote', `token endpoint returned ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+        }
+    }
+}
+function parseOAuthError(text) {
+    try {
+        const j = JSON.parse(text);
+        return {
+            ...(typeof j.error === 'string' ? { error: j.error } : {}),
+            ...(typeof j.error_description === 'string'
+                ? { error_description: j.error_description }
+                : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

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>] [--no-open] [--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             [--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 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 function main(argv: string[], io?: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;

package/dist/main.js

@@ -12,11 +12,12 @@ import { cliVersion } from './version.js';
 export const HELP = `aipay — AI-Pay CLI
 
 Usage
-  aipay login [--api <base>] [--no-open] [--json]      developer sign-in for the CLI itself
+  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself
   aipay whoami [--json] · aipay logout [--json]
   aipay apps list [--json]
   aipay apps create --name <name> [--callback <url>] [--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]

package/dist/project.d.ts

@@ -19,7 +19,10 @@ export interface ProjectConfig {
     };
     linked_at: string;
 }
-export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'node';
+export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'vite' | 'node';
+/** Accepted by `--framework`; detection picks server frameworks first, then Vite, then plain Node. */
+export declare const FRAMEWORKS: readonly Framework[];
+export declare function isFramework(v: unknown): v is Framework;
 export declare const PROJECT_DIR = ".aipay";
 export declare const PROJECT_FILE = "project.json";
 export declare const ENV_FILE = ".env.local";
@@ -34,6 +37,14 @@ export declare const ENV_KEYS: {
     readonly apiBase: 'AIPAY_API_BASE';
     readonly callback: 'AIPAY_CALLBACK_URL';
 };
+/** Vite only exposes VITE_-prefixed values to browser code, so a Vite project gets the same four
+ * public values twice: the plain names (for any server-side tooling) and these aliases. */
+export declare const VITE_ENV_KEYS: {
+    readonly clientId: 'VITE_AIPAY_CLIENT_ID';
+    readonly authOrigin: 'VITE_AIPAY_AUTH_ORIGIN';
+    readonly apiBase: 'VITE_AIPAY_API_BASE';
+    readonly callback: 'VITE_AIPAY_CALLBACK_URL';
+};
 /**
  * Merge our keys into `.env.local` without touching anything else in it: existing lines
  * for our keys are replaced in place, missing ones appended under a marker comment.

package/dist/project.js

@@ -9,6 +9,18 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+/** Accepted by `--framework`; detection picks server frameworks first, then Vite, then plain Node. */
+export const FRAMEWORKS = [
+    'next',
+    'express',
+    'fastify',
+    'hono',
+    'vite',
+    'node',
+];
+export function isFramework(v) {
+    return typeof v === 'string' && FRAMEWORKS.includes(v);
+}
 export const PROJECT_DIR = '.aipay';
 export const PROJECT_FILE = 'project.json';
 export const ENV_FILE = '.env.local';
@@ -50,6 +62,14 @@ export const ENV_KEYS = {
     apiBase: 'AIPAY_API_BASE',
     callback: 'AIPAY_CALLBACK_URL',
 };
+/** Vite only exposes VITE_-prefixed values to browser code, so a Vite project gets the same four
+ * public values twice: the plain names (for any server-side tooling) and these aliases. */
+export const VITE_ENV_KEYS = {
+    clientId: 'VITE_AIPAY_CLIENT_ID',
+    authOrigin: 'VITE_AIPAY_AUTH_ORIGIN',
+    apiBase: 'VITE_AIPAY_API_BASE',
+    callback: 'VITE_AIPAY_CALLBACK_URL',
+};
 /**
  * Merge our keys into `.env.local` without touching anything else in it: existing lines
  * for our keys are replaced in place, missing ones appended under a marker comment.

package/dist/templates.js

@@ -39,6 +39,13 @@ export function scaffoldFiles(input) {
                     content: honoRoutes(input, startPath),
                 },
             ];
+        case 'vite':
+            // Browser SPA: no server, so the helper module itself runs in the page (PKCE public
+            // client; tokens live in sessionStorage for the tab) and a boot file handles the callback.
+            return [
+                { path: `${prefix(input.srcDir)}aipay.${ext}`, content: browserModule(input) },
+                { path: `${prefix(input.srcDir)}aipay-boot.${ext}`, content: viteBoot(input) },
+            ];
         default:
             return [
                 core,
@@ -224,3 +231,103 @@ export async function handleAIPay(req${ts ? ': IncomingMessage' : ''}, res${ts ?
 }
 `;
 }
+/**
+ * Vite/browser variant of the helper module. Same three steps as the server module, but the
+ * pending flow and the tokens live in sessionStorage (tab-scoped, gone when the tab closes) and
+ * the config comes from `import.meta.env.VITE_AIPAY_*` — Vite only exposes VITE_-prefixed values.
+ */
+function browserModule(input) {
+    const ts = input.typescript;
+    const t = (typed, plain) => (ts ? typed : plain);
+    return `${ts ? '/// <reference types="vite/client" />\n' : ''}// Browser (Vite) build of the AI-Pay helper. Reads the VITE_AIPAY_* values \`aipay init\`
+// wrote to .env.local (Vite exposes only VITE_-prefixed values to the page). No secret
+// exists: the app is a public PKCE client and the token endpoint accepts browser calls.
+import {
+  AIPayClient,
+  createConnectUrl,
+  getUserInfo,
+  handleCallback,${t('\n  type TokenSet,', '')}
+} from '@coswic/aipay-sdk'
+
+const cfg = {
+  hydraPublicUrl: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  clientId: import.meta.env.VITE_AIPAY_CLIENT_ID${t(' as string', '')},
+  redirectUri: import.meta.env.VITE_AIPAY_CALLBACK_URL${t(' as string', '')},
+}
+const apiBase = import.meta.env.VITE_AIPAY_API_BASE${t(' as string', '')}
+/** Path part of the registered callback — the page that must call completeSignInIfCallback(). */
+export const CALLBACK_PATH = ${JSON.stringify(input.callbackPath)}
+
+const PENDING_KEY = 'aipay:pending' // { state, codeVerifier } while the user is at AI-Pay
+const TOKENS_KEY = 'aipay:tokens' // TokenSet for this tab (sessionStorage: cleared when the tab closes)
+
+/** Step 1 — send the user to AI-Pay. The PKCE verifier is kept under the state for the callback. */
+export async function beginSignIn()${t(': Promise<void>', '')} {
+  const { url, state, codeVerifier } = await createConnectUrl(cfg)
+  sessionStorage.setItem(PENDING_KEY, JSON.stringify({ state, codeVerifier }))
+  location.assign(url)
+}
+
+/**
+ * Step 2 — call once at startup. On the callback page it exchanges the code (state + PKCE are
+ * verified by the SDK), stores the tokens for this tab and cleans the URL; elsewhere it is a no-op.
+ */
+export async function completeSignInIfCallback()${t(': Promise<{ sub: string; email: string | null } | null>', '')} {
+  if (location.pathname !== CALLBACK_PATH) return null
+  const raw = sessionStorage.getItem(PENDING_KEY)
+  sessionStorage.removeItem(PENDING_KEY)
+  const saved = raw ? ${t('(JSON.parse(raw) as { state: string; codeVerifier: string })', 'JSON.parse(raw)')} : null
+  const tokens = await handleCallback(cfg, location.href, saved)
+  sessionStorage.setItem(TOKENS_KEY, JSON.stringify(tokens))
+  history.replaceState(null, '', '/')
+  const user = await getUserInfo(cfg, tokens.accessToken)
+  // user.sub is the stable per-app id of this user — key your accounts on it, not on email.
+  return { sub: user.sub, email: user.email ?? null }
+}
+
+export function currentTokens()${t(': TokenSet | null', '')} {
+  const raw = sessionStorage.getItem(TOKENS_KEY)
+  return raw ? ${t('(JSON.parse(raw) as TokenSet)', 'JSON.parse(raw)')} : null
+}
+
+export function signOut()${t(': void', '')} {
+  sessionStorage.removeItem(TOKENS_KEY)
+}
+
+/** Step 3 — call a model on the user's behalf; the response carries the billing receipt. */
+export async function firstCompletion(model${t(': string', '')}) {
+  const tokens = currentTokens()
+  if (!tokens) throw new Error('not signed in')
+  const client = new AIPayClient({ baseUrl: apiBase, accessToken: tokens.accessToken })
+  const res = await client.chat.completions.create({
+    model,
+    messages: [{ role: 'user', content: 'Say hello in five words.' }],
+    max_tokens: 32,
+  })
+  return { text: res.choices[0]?.message.content ?? '', receipt: res.aipay }
+}
+`;
+}
+/** Startup wiring for a Vite app: handle the callback page, expose the two actions to your UI. */
+function viteBoot(input) {
+    const ts = input.typescript;
+    const from = ts ? './aipay' : './aipay.js';
+    return `// Call bootAIPay() once when your app starts (top of main.${ts ? 'ts' : 'js'} / before rendering).
+// It completes the sign-in when the page is the AI-Pay callback (${input.callbackPath}) and
+// otherwise does nothing. Vite's dev server serves index.html for that path (SPA fallback),
+// so no route configuration is needed; with a client-side router, keep the path unrouted.
+import { beginSignIn, completeSignInIfCallback, currentTokens, firstCompletion } from '${from}'
+
+export async function bootAIPay() {
+  const justSignedIn = await completeSignInIfCallback()
+  const signedIn = justSignedIn !== null || currentTokens() !== null
+  return {
+    signedIn,
+    /** Wire this to your "Sign in with AI-Pay" button. */
+    beginSignIn,
+    /** After sign-in: one model call; the receipt (cost, request id) is on the result. */
+    firstCompletion,
+  }
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.1.0",
+  "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.",
   "license": "MIT",
   "type": "module",