@infimind/video-mcp-cli 1.0.11 → 1.0.13

package/README.md

@@ -78,6 +78,7 @@ After saving the configuration, restart Claude Desktop for the changes to take e
 Get information about the authenticated user.
 
 **Example usage in Claude:**
+
 ```
 Get my user information for the video generator
 ```
@@ -86,28 +87,32 @@ Get my user information for the video generator
 
 Create a video generation task.
 
-Supported engines:
+Supported models (pass `model`; `route` is a deprecated legacy alias):
+
+- `WA`: 极睿WA专业版 (default; available to non-VIP users)
+- `SD`: 极睿SD专业版 (VIP only)
+- `SD25`: 极睿SD2.5专业版 (VIP only)
+- `HA`: 极睿HA专业版 (VIP only)
+- `H3`: 极睿H3专业版 (VIP only)
 
-- `S2`: 极睿Sa专业版
-- `S5`: 极睿Sd专业版 (VIP only)
-- `S6`: 极睿Ha专业版 (VIP only)
+`SA` (Sora 2 / route `S2`/`S10`) is retired. Requests that still send it are rejected with `MODEL_RETIRED`; use `WA` instead.
 
 Parameter applicability:
 
-| Parameter | S2 极睿Sa专业版 | S5 极睿Sd专业版 | S6 极睿Ha专业版 |
-| --- | --- | --- | --- |
-| `sourceImage` | Optional single image | Not supported | Standard mode single image |
-| `sourceImages` | Not supported | allinone / firstlast images | reference / edit reference images |
-| `sourceVideos` | Not supported | allinone reference videos | edit input videos |
-| `sourceAudios` | Not supported | allinone reference audio | Not supported |
-| `sourceVideoDurationSeconds` | Not supported | dryRun estimate for videos | dryRun estimate for edit video |
-| `sourceAudioDurationSeconds` | Not supported | dryRun estimate for audio | Not supported |
-| `taskMode` | Not needed | `allinone` / `firstlast` | `standard` / `reference` / `edit` |
-| `resolution` | Not supported | `720p` / `1080p` | `720p` / `1080p` |
-| `ratio` | Not supported | Not supported | reference or text-to-video standard mode |
-| `generateAudio` | Not supported | Optional | Not supported |
-| `webSearchEnabled` | Not supported | Optional | Not supported |
-| `dryRun` | Optional preflight | Optional preflight | Optional preflight |
+| Parameter                    | WA 极睿WA专业版                    | SD 极睿SD专业版             | HA 极睿HA专业版                          |
+| ---------------------------- | ---------------------------------- | --------------------------- | ---------------------------------------- |
+| `sourceImage`                | Not supported                      | Not supported               | Standard mode single image               |
+| `sourceImages`               | allinone / firstlast / edit images | allinone / firstlast images | reference / edit reference images        |
+| `sourceVideos`               | allinone / edit reference videos   | allinone reference videos   | edit input videos                        |
+| `sourceAudios`               | allinone / edit reference audio    | allinone reference audio    | Not supported                            |
+| `sourceVideoDurationSeconds` | dryRun estimate for videos         | dryRun estimate for videos  | dryRun estimate for edit video           |
+| `sourceAudioDurationSeconds` | dryRun estimate for audio          | dryRun estimate for audio   | Not supported                            |
+| `taskMode`                   | `allinone` / `firstlast` / `edit`  | `allinone` / `firstlast`    | `standard` / `reference` / `edit`        |
+| `resolution`                 | `480p` / `720p` / `1080p`          | `720p` / `1080p`            | `720p` / `1080p`                         |
+| `ratio`                      | `adaptive` / `16:9` / `9:16` / ... | Not supported               | reference or text-to-video standard mode |
+| `generateAudio`              | Optional                           | Optional                    | Not supported                            |
+| `webSearchEnabled`           | Not supported                      | Optional                    | Not supported                            |
+| `dryRun`                     | Optional preflight                 | Optional preflight          | Optional preflight                       |
 
 Local file paths and public URLs are both supported.
 
@@ -117,10 +122,12 @@ Media limits:
 
 - Local video files: MP4/MOV, up to 50MB each, 2-15 seconds.
 - Local audio files: MP3/WAV, up to 15MB each, 2-15 seconds.
-- S5 allinone: up to 9 images, 3 videos, and 3 audio files.
-- S5 firstlast: up to 2 images; the first frame is required.
-- S6 reference: up to 9 images.
-- S6 edit: up to 1 video and 5 images.
+- WA: up to 10 images, 5 videos, and 5 audio files; fixed 5/10/15/20/25/30-second output (Edit uses smart duration only).
+- SD allinone: up to 9 images, 3 videos, and 3 audio files.
+- SD firstlast: up to 2 images; the first frame is required.
+- SD25 allinone/edit: up to 30 images, 10 videos, and 10 audio files.
+- HA reference: up to 9 images.
+- HA edit: up to 1 video and 5 images.
 
 URL safety rules:
 
@@ -146,17 +153,20 @@ Use `dryRun: true` to validate parameters, VIP access, media rules, and estimate
 }
 ```
 
-#### 极睿Sa专业版 - 标准生成
+#### 极睿WA专业版 - 全能参考（默认模型）
 
-S2 uses `sourceImage`, `seconds`, and `size`; do not pass `taskMode` or `resolution`.
+WA is the default model when `model` is omitted. Do not pass `sourceImage` or `webSearchEnabled`.
 
 ```json
 {
   "prompt": "一个高质感的产品展示视频，柔和布光，镜头缓慢推进",
-  "route": "S2",
-  "sourceImage": "/path/to/product.jpg",
-  "seconds": 10,
+  "model": "WA",
+  "taskMode": "allinone",
+  "sourceImages": ["/path/to/product.jpg"],
+  "seconds": 5,
   "size": "720x1280",
+  "ratio": "9:16",
+  "resolution": "720p",
   "language": "zh-CN",
   "count": 1,
   "dryRun": true
@@ -264,6 +274,49 @@ Image-to-video:
 
 After dry run succeeds and the estimated credits look correct, remove `dryRun` or set it to `false` to create the real task. After creating a task, use `get_video_status` with the returned `taskId` to query progress and video links.
 
+### `create_motion_video_remake_task` / `get_motion_video_remake_status`
+
+Create and poll a motion video remake task using a character image and an MP4 motion reference. Local files and public URLs are supported.
+
+```json
+{
+  "sourceImage": "/path/to/person.jpg",
+  "referenceVideo": "/path/to/motion.mp4",
+  "mode": "move",
+  "quality": "std",
+  "count": 1,
+  "referenceVideoDurationSeconds": 12,
+  "dryRun": true
+}
+```
+
+For `dryRun`, `referenceVideoDurationSeconds` is an optional estimate hint. If it is omitted, media validation still runs but credit fields are returned as `null`; the hint is never treated as detected media metadata. During formal creation, the backend ignores the hint, uploads the MP4 to OSS, reads the authoritative duration and dimensions through OSS `video/info`, and bills from the unrounded duration. Images are limited to 5 MB; MP4 references are limited to 100 MB and 30 seconds. After preflight succeeds, set `dryRun` to `false`, then poll the returned `taskId` with `get_motion_video_remake_status`.
+
+### `create_ecommerce_storyboard_task` / `get_ecommerce_storyboard_status`
+
+Create and poll an ecommerce storyboard with a complete story, per-scene descriptions, video prompts, and sketch images.
+
+```json
+{
+  "productName": "Smart Watch",
+  "productDescription": "Lightweight watch with long battery life and fitness tracking",
+  "targetAudience": "Young professionals",
+  "videoStyle": "Energetic product demo",
+  "productImage": "/path/to/product.png",
+  "targetDuration": 60,
+  "language": "en",
+  "orientation": "vertical",
+  "dryRun": true
+}
+```
+
+Storyboard preflight estimates a fixed cost of 2 credits. Set `dryRun` to `false` to create the task, then call `get_ecommerce_storyboard_status`. Storyboard scenes are not automatically submitted as final video tasks; pass a selected scene prompt and image to `create_video_task` when needed.
+
+### Backend deployment requirements for 1.1.0
+
+- Apply `drizzle/migrations/0070_add_creative_billing_state.sql` after `0069_add_output_upscale_attempt.sql` and before deploying the application and motion poller. The additive columns default historical creative rows to already charged.
+- Verify that the configured OSS bucket supports `video/info` and that the application identity can read media metadata before enabling the new tools. The application can be rolled back without dropping the additive columns.
+
 ## Development
 
 ```bash
@@ -303,7 +356,9 @@ Set `SORA_API_URL=http://localhost:3000/api` when testing against a local app se
   "mcpServers": {
     "sora-video-generator-local": {
       "command": "node",
-      "args": ["/absolute/path/to/sora_video_generator/mcp-server/dist/index.js"],
+      "args": [
+        "/absolute/path/to/sora_video_generator/mcp-server/dist/index.js"
+      ],
       "env": {
         "SORA_MCP_TOKEN": "YOUR_TOKEN",
         "SORA_API_URL": "http://localhost:3000/api"

package/dist/auth/credentialWriter.js

@@ -0,0 +1,85 @@
+/**
+ * Atomic credential file writer.
+ *
+ * Writes to a temp file in the same directory, then renames over the
+ * target. Sets directory mode 0700 and file mode 0600 after the rename.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, openSync, closeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsDir, credentialsFilePath } from "./paths.js";
+function assertPermissions() {
+    const dir = credentialsDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        const st = statSync(dir);
+        if (process.platform !== "win32") {
+            const mode = st.mode & 0o777;
+            if (mode & 0o077) {
+                throw new Error(`credentials directory is world/group accessible (mode=${mode.toString(8)})`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            err.message.startsWith("credentials directory")) {
+            throw err;
+        }
+    }
+}
+export function writeCredentials(payload) {
+    assertPermissions();
+    const target = credentialsFilePath();
+    const tmp = join(dirname(target), `.${Date.now()}.${process.pid}.tmp`);
+    const json = JSON.stringify(payload, null, 2);
+    const fd = openSync(tmp, "wx", 0o600);
+    try {
+        writeFileSync(fd, json, { encoding: "utf8" });
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, target);
+    try {
+        chmodSync(target, 0o600);
+    }
+    catch {
+        // best-effort
+    }
+    return target;
+}
+export function readCredentials() {
+    const target = credentialsFilePath();
+    if (!existsSync(target))
+        return null;
+    try {
+        const st = statSync(target);
+        if (process.platform !== "win32") {
+            const mode = st.mode & 0o777;
+            if (mode & 0o077) {
+                throw new Error(`credentials file is world/group accessible (mode=${mode.toString(8)})`);
+            }
+        }
+        const text = readFileSync(target, "utf8");
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+}
+export function deleteCredentials() {
+    const target = credentialsFilePath();
+    if (!existsSync(target))
+        return false;
+    unlinkSync(target);
+    return true;
+}

package/dist/auth/exchange.js

@@ -0,0 +1,67 @@
+/**
+ * Token exchange helpers. The CLI never logs the raw token, code, or
+ * verifier; pass them through the redacting writers in `redact.ts`.
+ */
+const DEFAULT_API_URL = "https://aigc-next.iclip.cn/api";
+export async function exchangeAuthorizationCode(input) {
+    const url = new URL("/api/oauth/workbuddy/token", input.apiBaseUrl).toString();
+    const body = {
+        grant_type: "authorization_code",
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        code_verifier: input.codeVerifier,
+        installation_id: input.installationId,
+        client_id: "infimind-video-workbuddy-cli",
+    };
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        return { ok: false, reason: "network_error" };
+    }
+    if (!resp.ok) {
+        return { ok: false, reason: `http_${resp.status}` };
+    }
+    let json;
+    try {
+        json = (await resp.json());
+    }
+    catch {
+        return { ok: false, reason: "invalid_response" };
+    }
+    if (!json.access_token || !json.token_type) {
+        return { ok: false, reason: "invalid_response" };
+    }
+    return { ok: true, token: json };
+}
+export async function revokeWorkbuddyToken(input) {
+    const url = new URL("/api/oauth/workbuddy/revoke", input.apiBaseUrl).toString();
+    try {
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify({
+                token: input.accessToken,
+                installation_id: input.installationId,
+            }),
+        });
+        return { ok: resp.ok, status: resp.status };
+    }
+    catch (err) {
+        return { ok: false, status: 0, reason: "network_error" };
+    }
+}
+export function defaultApiUrl() {
+    return process.env.SORA_API_URL || DEFAULT_API_URL;
+}

package/dist/auth/installationId.js

@@ -0,0 +1,36 @@
+/**
+ * Stable per-installation identifier. Generated once and persisted under
+ *   ~/.workbuddy/connectors/infimind-video/auth/installation_id
+ * so the same machine always produces the same id. We do not transmit the
+ * hostname to the server; only the hash of this id is sent.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, } from "node:fs";
+import { dirname } from "node:path";
+import { installationIdFilePath } from "./paths.js";
+const INSTALLATION_ID_LENGTH = 32; // 32 bytes base64url = 43 chars
+export function readOrCreateInstallationId() {
+    const path = installationIdFilePath();
+    if (existsSync(path)) {
+        try {
+            const value = readFileSync(path, "utf8").trim();
+            if (/^[A-Za-z0-9_-]{16,128}$/.test(value)) {
+                return value;
+            }
+        }
+        catch {
+            // fall through to regeneration
+        }
+    }
+    const generated = randomBytes(INSTALLATION_ID_LENGTH).toString("base64url");
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, generated, { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(dirname(path), 0o700);
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // best-effort; CI / Windows may not support chmod
+    }
+    return generated;
+}

package/dist/auth/login.js

@@ -0,0 +1,77 @@
+/**
+ * `sora-mcp auth login` implementation.
+ *
+ * Sequence:
+ *   1. Read or generate the installationId (persisted on disk).
+ *   2. Bind 127.0.0.1 to a random port and prepare state + PKCE challenge.
+ *   3. Print the HTTPS authorization URL within 10 s of invocation.
+ *   4. Wait for the loopback callback or 5-minute timeout.
+ *   5. Exchange the code with PKCE verifier + installation id.
+ *   6. Persist the credential atomically.
+ */
+import { bindLoopback } from "./loopback.js";
+import { readOrCreateInstallationId } from "./installationId.js";
+import { exchangeAuthorizationCode, defaultApiUrl } from "./exchange.js";
+import { writeCredentials } from "./credentialWriter.js";
+const TIMEOUT_MS = 5 * 60 * 1000;
+const PRINT_URL_DEADLINE_MS = 10_000;
+const CLI_VERSION = "1.0.13";
+function detectPlatform() {
+    return process.platform;
+}
+export async function runLogin() {
+    const installationId = readOrCreateInstallationId();
+    const apiBaseUrl = defaultApiUrl();
+    const platform = detectPlatform();
+    const binding = await bindLoopback();
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: "infimind-video-workbuddy-cli",
+        redirect_uri: binding.url,
+        state: binding.state,
+        code_challenge: binding.codeChallenge,
+        code_challenge_method: "S256",
+        installation_id: installationId,
+        platform,
+        cli_version: CLI_VERSION,
+    });
+    const authUrl = `${apiBaseUrl.replace(/\/+$/, "")}/oauth/workbuddy/authorize?${params.toString()}`;
+    // Print URL within 10s.
+    const printTimer = setTimeout(() => {
+        process.stdout.write(`\n[workbuddy-auth] login URL not printed within 10s; binding kept\n`);
+    }, PRINT_URL_DEADLINE_MS);
+    process.stdout.write(`\n[workbuddy-auth] open this URL in your browser:\n${authUrl}\n`);
+    clearTimeout(printTimer);
+    let callback;
+    try {
+        callback = await binding.awaitCallback(TIMEOUT_MS);
+    }
+    catch (err) {
+        await binding.close();
+        return { ok: false, reason: err.message || "callback_failed" };
+    }
+    await binding.close();
+    const exchanged = await exchangeAuthorizationCode({
+        apiBaseUrl,
+        redirectUri: binding.url,
+        code: callback.code,
+        codeVerifier: binding.codeVerifier,
+        installationId,
+        platform,
+        cliVersion: CLI_VERSION,
+    });
+    if (!exchanged.ok || !exchanged.token) {
+        return { ok: false, reason: exchanged.reason ?? "exchange_failed" };
+    }
+    const issuedAt = new Date().toISOString();
+    writeCredentials({
+        installationId,
+        accessToken: exchanged.token.access_token,
+        tokenType: "Bearer",
+        scope: exchanged.token.scope,
+        issuedAt,
+        platform,
+        cliVersion: CLI_VERSION,
+    });
+    return { ok: true, authUrl };
+}

package/dist/auth/logout.js

@@ -0,0 +1,34 @@
+/**
+ * `sora-mcp auth logout` implementation.
+ *
+ * Order:
+ *   1. Read the credential file.
+ *   2. Call /api/oauth/workbuddy/revoke.
+ *   3. Only delete the local file if the revoke succeeded.
+ *   4. If the network is unreachable, keep the local file and exit non-zero
+ *      so the user can retry revocation.
+ */
+import { readCredentials, deleteCredentials } from "./credentialWriter.js";
+import { revokeWorkbuddyToken, defaultApiUrl } from "./exchange.js";
+export async function runLogout() {
+    const creds = readCredentials();
+    if (!creds) {
+        return { ok: true, revoked: false, localDeleted: false };
+    }
+    const apiBaseUrl = defaultApiUrl();
+    const result = await revokeWorkbuddyToken({
+        apiBaseUrl,
+        accessToken: creds.accessToken,
+        installationId: creds.installationId,
+    });
+    if (!result.ok) {
+        return {
+            ok: false,
+            reason: result.reason ?? `http_${result.status}`,
+            revoked: false,
+            localDeleted: false,
+        };
+    }
+    const localDeleted = deleteCredentials();
+    return { ok: true, revoked: true, localDeleted };
+}

package/dist/auth/loopback.js

@@ -0,0 +1,155 @@
+/**
+ * Loopback HTTP listener that captures the WorkBuddy OAuth callback.
+ *
+ * Per RFC 8252 §7.3 the CLI binds 127.0.0.1 to a random port, registers
+ * `/oauth/callback` and waits for a single GET with `?code=...&state=...`.
+ * Anything else is rejected with 400.
+ */
+import { createServer, } from "node:http";
+import { createHash } from "node:crypto";
+import { generateCodeVerifier, s256Challenge } from "./pkce.js";
+async function pickRandomPort(hostname) {
+    return await new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.on("error", reject);
+        probe.listen(0, hostname, () => {
+            const addr = probe.address();
+            if (addr && typeof addr === "object") {
+                const port = addr.port;
+                probe.close(() => resolve(port));
+            }
+            else {
+                probe.close(() => reject(new Error("no_port")));
+            }
+        });
+    });
+}
+function htmlResponse(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.setHeader("Cache-Control", "no-store");
+    res.end(body);
+}
+const SUCCESS_PAGE = `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <title>WorkBuddy 授权完成</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", sans-serif; background: #0f1115; color: #f1f1f1; margin: 0; padding: 48px; }
+    .card { max-width: 480px; margin: 0 auto; background: #1a1d23; border: 1px solid #2a2d33; border-radius: 12px; padding: 32px; text-align: center; }
+    h1 { font-size: 20px; margin: 0 0 16px; }
+    p { color: #b8b8b8; font-size: 14px; line-height: 1.6; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>WorkBuddy 授权完成</h1>
+    <p>您已成功将极睿视频账户连接到 WorkBuddy。</p>
+    <p>请返回 WorkBuddy 继续；可以关闭此页面。</p>
+  </div>
+</body>
+</html>`;
+const ERROR_PAGE = (msg) => `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <title>WorkBuddy 授权失败</title>
+</head>
+<body style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; padding: 48px;">
+  <h1>WorkBuddy 授权失败</h1>
+  <p>${msg}</p>
+  <p>请返回 WorkBuddy 重试。</p>
+</body>
+</html>`;
+export async function bindLoopback(opts = {}) {
+    const hostname = opts.hostname ?? "127.0.0.1";
+    const port = opts.preferredPort ?? (await pickRandomPort(hostname));
+    const stateBytes = createHash("sha256")
+        .update(`${Date.now()}.${Math.random()}`)
+        .digest();
+    const state = stateBytes.toString("base64url").slice(0, 32);
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = s256Challenge(codeVerifier);
+    let resolveCb = null;
+    let rejectCb = null;
+    let settled = false;
+    const callbackPromise = new Promise((resolve, reject) => {
+        resolveCb = resolve;
+        rejectCb = reject;
+    });
+    const handle = (req, res) => {
+        if (settled) {
+            htmlResponse(res, 410, ERROR_PAGE("回调已过期"));
+            return;
+        }
+        const url = req.url ?? "/";
+        if (!url.startsWith("/oauth/callback")) {
+            htmlResponse(res, 404, ERROR_PAGE("Not Found"));
+            return;
+        }
+        if (req.method !== "GET") {
+            htmlResponse(res, 405, ERROR_PAGE("Method Not Allowed"));
+            return;
+        }
+        const parsed = new URL(url, `http://${hostname}:${port}`);
+        const code = parsed.searchParams.get("code");
+        const stateParam = parsed.searchParams.get("state");
+        const error = parsed.searchParams.get("error");
+        if (error) {
+            settled = true;
+            htmlResponse(res, 400, ERROR_PAGE(`授权服务器返回 ${error}`));
+            rejectCb?.(new Error(`oauth_error:${error}`));
+            return;
+        }
+        if (!code || !stateParam) {
+            htmlResponse(res, 400, ERROR_PAGE("缺少 code 或 state"));
+            return;
+        }
+        if (stateParam !== state) {
+            settled = true;
+            htmlResponse(res, 400, ERROR_PAGE("state 不匹配"));
+            rejectCb?.(new Error("state_mismatch"));
+            return;
+        }
+        settled = true;
+        htmlResponse(res, 200, SUCCESS_PAGE);
+        resolveCb?.({ code, state: stateParam });
+    };
+    const server = createServer(handle);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, hostname, () => resolve());
+    });
+    const boundPort = server.address()?.port ?? port;
+    const close = () => new Promise(resolve => {
+        server.close(() => resolve());
+    });
+    const awaitCallback = (timeoutMs) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                reject(new Error("loopback_timeout"));
+            }
+        }, timeoutMs);
+        callbackPromise
+            .then(v => {
+            clearTimeout(timer);
+            resolve(v);
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+    return {
+        port: boundPort,
+        url: `http://${hostname}:${boundPort}/oauth/callback`,
+        state,
+        codeVerifier,
+        codeChallenge,
+        close,
+        awaitCallback,
+    };
+}

package/dist/auth/paths.js

@@ -0,0 +1,30 @@
+/**
+ * Filesystem layout for WorkBuddy-managed credentials.
+ *
+ * Per plan §4: the CLI persists the credential file at
+ *   ~/.workbuddy/connectors/infimind-video/auth/credentials.json
+ * with directory mode 0700 and file mode 0600.
+ *
+ * `~` is resolved to $HOME (or to a process.env override WORKBUDDY_HOME for
+ * testing). Tests can monkey-patch the resolver by setting WORKBUDDY_HOME.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export const WORKBUDDY_HOME_ENV = "WORKBUDDY_HOME";
+export const CONNECTOR_ID = "infimind-video";
+export const CREDENTIAL_FILENAME = "credentials.json";
+export function workbuddyHome() {
+    const env = process.env[WORKBUDDY_HOME_ENV];
+    if (env && env.length > 0)
+        return resolve(env);
+    return join(homedir(), ".workbuddy");
+}
+export function credentialsDir() {
+    return join(workbuddyHome(), "connectors", CONNECTOR_ID, "auth");
+}
+export function credentialsFilePath() {
+    return join(credentialsDir(), CREDENTIAL_FILENAME);
+}
+export function installationIdFilePath() {
+    return join(credentialsDir(), "installation_id");
+}

package/dist/auth/pkce.js

@@ -0,0 +1,11 @@
+/**
+ * PKCE S256 helpers (CLI side). Mirrors the server's checks exactly so the
+ * verifier we generate always produces a challenge the server accepts.
+ */
+import { createHash, randomBytes } from "node:crypto";
+export function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+export function s256Challenge(verifier) {
+    return createHash("sha256").update(verifier, "utf8").digest("base64url");
+}