@arrhq/crate-cli 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @arrhq/crate-cli
 
-Crate MCP をCLIで操作するための公開向けクライアントです。
+Crate をCLIで操作するための公開向けクライアントです。
 
 ## Install
 
@@ -10,14 +10,31 @@ npm i -g @arrhq/crate-cli
 
 ## Configure
 
-以下のいずれかで接続情報を設定します。
+推奨（一般ユーザー）:
 
-- `CRATE_MCP_URL` / `CRATE_MCP_INGEST_TOKEN`
-- `~/.codex/config.toml` の `mcp_servers` 設定
+```bash
+crate auth login --crate-url https://crateio.com
+crate auth status
+```
+
+認証トークン保存:
+
+- macOS: Keychain（`security` コマンド）を優先
+- 上記が使えない環境: `~/.config/crate-cli/auth.json`（`0600`）へフォールバック
+
+CI/ヘッドレス向け（補助導線）:
+
+```bash
+export CRATE_URL="https://crateio.com"
+export CRATE_TOKEN="<crate_mt_...>"
+export CRATE_PROJECT_ID="<project_uuid>" # optional
+```
 
 ## Usage
 
 ```bash
+crate auth login
+crate auth status
 crate tool list
 crate tool call --name list_project_tasks --args-json '{"status":"open","limit":20}'
 crate tasks list --status in_progress --limit 50
@@ -26,9 +43,3 @@ crate tasks update --task-id <task_uuid> --status in_progress
 crate checkpoint status --client-event-id <checkpoint_uuid>
 crate tasks close --task-id <task_uuid> --client-event-id <checkpoint_uuid>
 ```
-
-## Release flow
-
-1. CLIの変更PRで `.changeset/*.md` を追加する（`pnpm changeset`）。
-2. `main` へのマージ後、GitHub Actions `Crate CLI Release` が Release PR を作成する。
-3. Release PR をマージすると npm publish が実行される（Trusted Publisher/OIDC 前提）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrhq/crate-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Crate MCP CLI for fine-grained task/checkpoint/tool operations",
   "type": "module",
   "license": "MIT",
@@ -12,11 +12,11 @@
     "src",
     "README.md"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "crate": "node ./bin/crate.mjs",
     "test": "node --test ../../scripts/__tests__/crate-cli.test.mjs"
-  },
-  "engines": {
-    "node": ">=20"
   }
-}
+}

package/src/cli.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 import { execFile } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -11,6 +12,15 @@ import { promisify } from "node:util";
 const DEFAULT_TIMEOUT_MS = 20_000;
 const DEFAULT_MAX_WAIT_SECONDS = 180;
 const DEFAULT_POLL_INTERVAL_SECONDS = 3;
+const DEFAULT_CRATE_URL = "https://crateio.com";
+const DEFAULT_OAUTH_CLIENT_ID = "crate-cli-public";
+const DEFAULT_OAUTH_SCOPES = "snapshot:write tasks:write tasks:read";
+const DEFAULT_AUTH_CALLBACK_TIMEOUT_SECONDS = 180;
+const AUTH_STORE_PATH = join(homedir(), ".config", "crate-cli", "auth.json");
+const AUTH_STORE_VERSION = 2;
+const AUTH_KEYCHAIN_SERVICE = "arrhq.crate-cli";
+const AUTH_KEYCHAIN_ACCOUNT_PREFIX = "oauth-session:";
+const AUTH_CALLBACK_PATH = "/oauth/callback";
 
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -27,6 +37,9 @@ const HELP_TEXT = `Usage:
   crate <command> [options]
 
 Commands:
+  auth login
+  auth status
+  auth logout
   tool list
   tool call
   tasks list
@@ -36,6 +49,8 @@ Commands:
   checkpoint status
 
 Examples:
+  crate auth login
+  crate auth status
   crate tool list
   crate tool call --name list_project_tasks --args-json '{"status":"open","limit":20}'
   crate tasks list --status in_progress --limit 50
@@ -45,29 +60,53 @@ Examples:
   crate checkpoint status --client-event-id <checkpoint_uuid>
 
 Global options:
-  --mcp-url <url>              MCP endpoint URL
-  --mcp-ingest-token <token>   MCP token (x-crate-ingest-token)
-  --server-name <name>         mcp server key in ~/.codex/config.toml
+  --crate-url <url>            Crate URL (e.g. https://crateio.com)
+  --token <token>              Crate API token
+  --project-id <uuid>          Default project_id for endpoint resolution
+  --server-name <name>         mcp server key in ~/.codex/config.toml (optional)
+  --mcp-url <url>              Legacy: MCP endpoint URL
+  --mcp-ingest-token <token>   Legacy: MCP token (x-crate-ingest-token)
   --timeout-ms <ms>            RPC timeout (default: 20000)
   --json                       JSON output
   --help                       Show help`;
 
 const COMMAND_HELP = {
+  "auth login": `Usage: crate auth login [options]
+Options:
+  --crate-url <url>            default: https://crateio.com
+  --project-id <uuid>          optional project hint
+  --scope "<scopes>"           default: "snapshot:write tasks:write tasks:read"
+  --client-id <id>             default: crate-cli-public
+  --callback-timeout-seconds <n> default: 180
+  --no-browser                 print URL without launching browser
+  --json`,
+  "auth status": `Usage: crate auth status [options]
+Options:
+  --json`,
+  "auth logout": `Usage: crate auth logout [options]
+Options:
+  --json`,
   "tool list": `Usage: crate tool list [options]
 Options:
+  --crate-url <url>
+  --token <token>
+  --project-id <uuid>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "tool call": `Usage: crate tool call --name <tool> [options]
 Options:
-  --name <tool_name>           MCP tool name (required)
+  --name <tool_name>           Crate tool name (required)
   --args-json <json>           Tool arguments as JSON object (default: {})
   --args-file <path>           Path to JSON file for tool arguments
+  --crate-url <url>
+  --token <token>
+  --project-id <uuid>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "tasks list": `Usage: crate tasks list [options]
@@ -75,9 +114,11 @@ Options:
   --project-id <uuid>
   --status <open|in_progress|close|canceled>
   --limit <n>
+  --crate-url <url>
+  --token <token>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "tasks create": `Usage: crate tasks create --title <text> [options]
@@ -93,9 +134,11 @@ Options:
   --context-label <label>
   --actor-context <text>
   --source-context <text>
+  --crate-url <url>
+  --token <token>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "tasks update": `Usage: crate tasks update --task-id <uuid> [options]
@@ -113,9 +156,11 @@ Options:
   --context-label <label>      required fallback when status=close and client_event_id omitted
   --actor-context <text>
   --source-context <text>
+  --crate-url <url>
+  --token <token>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "tasks close": `Usage: crate tasks close --task-id <uuid> [options]
@@ -130,9 +175,11 @@ Options:
   --github-repo-full-name <owner/repo>
   --max-wait-seconds <n>       default: 180
   --poll-interval-seconds <n>  default: 3
+  --crate-url <url>
+  --token <token>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
   "checkpoint status": `Usage: crate checkpoint status [options]
@@ -141,9 +188,11 @@ Options:
   --session-id <id>            Required when client_event_id omitted
   --context-label <label>      Required when client_event_id omitted
   --project-id <uuid>
+  --crate-url <url>
+  --token <token>
+  --server-name <name>
   --mcp-url <url>
   --mcp-ingest-token <token>
-  --server-name <name>
   --timeout-ms <ms>
   --json`,
 };
@@ -289,7 +338,540 @@ const parseFlags = (argv, schema, defaults = {}) => {
   return { options, seenFlags };
 };
 
+const parseAuthStore = (raw) => {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    const current = parsed.current;
+    if (!current || typeof current !== "object") return null;
+    return {
+      current: {
+        crate_url: toTrimmed(current.crate_url),
+        project_id: toTrimmed(current.project_id),
+        client_id: toTrimmed(current.client_id),
+        token_endpoint: toTrimmed(current.token_endpoint),
+        authorization_endpoint: toTrimmed(current.authorization_endpoint),
+        access_token: toTrimmed(current.access_token),
+        refresh_token: toTrimmed(current.refresh_token),
+        token_type: toTrimmed(current.token_type),
+        scope: toTrimmed(current.scope),
+        expires_at: toTrimmed(current.expires_at),
+        created_at: toTrimmed(current.created_at),
+        updated_at: toTrimmed(current.updated_at),
+        credential_key: toTrimmed(current.credential_key),
+        storage: toTrimmed(current.storage),
+        access_token: toTrimmed(current.access_token),
+        refresh_token: toTrimmed(current.refresh_token),
+      },
+    };
+  } catch {
+    return null;
+  }
+};
+
+const buildAuthCredentialKey = (session) => {
+  const crateUrl = normalizeCrateUrl(session?.crate_url);
+  const origin = toOriginFromUrl(crateUrl || session?.crate_url || "");
+  const projectId = toTrimmed(session?.project_id) || "-";
+  const clientId = toTrimmed(session?.client_id) || DEFAULT_OAUTH_CLIENT_ID;
+  if (!origin) return "";
+  return `${origin}|${projectId}|${clientId}`;
+};
+
+const buildAuthKeychainAccount = (credentialKey) => {
+  const normalized = toTrimmed(credentialKey);
+  if (!normalized) return "";
+  const digest = createHash("sha256").update(normalized).digest("hex");
+  return `${AUTH_KEYCHAIN_ACCOUNT_PREFIX}${digest}`;
+};
+
+const parseKeychainSecret = (raw) => {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    const accessToken = toTrimmed(parsed.access_token);
+    const refreshToken = toTrimmed(parsed.refresh_token);
+    if (!accessToken) return null;
+    return {
+      access_token: accessToken,
+      refresh_token: refreshToken,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const isDarwinKeychainAvailable = async () => {
+  if (process.platform !== "darwin") return false;
+  try {
+    await execFileAsync("security", ["help"], { timeout: 5_000, maxBuffer: 64 * 1024 });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const readDarwinKeychainSecret = async (account) => {
+  if (!account) return null;
+  try {
+    const { stdout } = await execFileAsync(
+      "security",
+      ["find-generic-password", "-s", AUTH_KEYCHAIN_SERVICE, "-a", account, "-w"],
+      { timeout: 10_000, maxBuffer: 128 * 1024 },
+    );
+    return parseKeychainSecret(stdout);
+  } catch {
+    return null;
+  }
+};
+
+const writeDarwinKeychainSecret = async (account, secretText) => {
+  if (!account || !secretText) return false;
+  try {
+    await execFileAsync(
+      "security",
+      [
+        "add-generic-password",
+        "-U",
+        "-s",
+        AUTH_KEYCHAIN_SERVICE,
+        "-a",
+        account,
+        "-w",
+        secretText,
+      ],
+      { timeout: 10_000, maxBuffer: 64 * 1024 },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const deleteDarwinKeychainSecret = async (account) => {
+  if (!account) return;
+  try {
+    await execFileAsync(
+      "security",
+      ["delete-generic-password", "-s", AUTH_KEYCHAIN_SERVICE, "-a", account],
+      { timeout: 10_000, maxBuffer: 64 * 1024 },
+    );
+  } catch {
+    // Ignore missing keychain entry errors.
+  }
+};
+
+const readAuthStore = async () => {
+  try {
+    const raw = await readFile(AUTH_STORE_PATH, "utf8");
+    const parsed = parseAuthStore(raw);
+    if (!parsed?.current) return null;
+
+    const current = parsed.current;
+    const credentialKey = current.credential_key || buildAuthCredentialKey(current);
+    const account = buildAuthKeychainAccount(credentialKey);
+    const keychainEnabled = await isDarwinKeychainAvailable();
+
+    let tokens = null;
+    if (keychainEnabled) {
+      tokens = await readDarwinKeychainSecret(account);
+    }
+
+    // Backward-compatibility for previously file-stored secrets.
+    const legacyAccessToken = toTrimmed(current.access_token);
+    const legacyRefreshToken = toTrimmed(current.refresh_token);
+    if (!tokens && legacyAccessToken) {
+      tokens = {
+        access_token: legacyAccessToken,
+        refresh_token: legacyRefreshToken,
+      };
+
+      if (keychainEnabled) {
+        const migrated = await writeDarwinKeychainSecret(
+          account,
+          JSON.stringify(tokens),
+        );
+        if (migrated) {
+          await writeAuthStore({
+            current: {
+              ...current,
+              credential_key: credentialKey,
+              access_token: tokens.access_token,
+              refresh_token: tokens.refresh_token,
+            },
+          });
+        }
+      }
+    }
+
+    return {
+      current: {
+        crate_url: current.crate_url,
+        project_id: current.project_id,
+        client_id: current.client_id,
+        token_endpoint: current.token_endpoint,
+        authorization_endpoint: current.authorization_endpoint,
+        token_type: current.token_type,
+        scope: current.scope,
+        expires_at: current.expires_at,
+        created_at: current.created_at,
+        updated_at: current.updated_at,
+        credential_key: credentialKey,
+        storage: keychainEnabled ? "keychain" : "file",
+        access_token: tokens?.access_token ?? "",
+        refresh_token: tokens?.refresh_token ?? "",
+      },
+    };
+  } catch {
+    return null;
+  }
+};
+
+const writeAuthStore = async (store) => {
+  const current = store?.current;
+  if (!current || typeof current !== "object") {
+    throw new Error("Invalid auth store payload.");
+  }
+
+  const accessToken = toTrimmed(current.access_token);
+  const refreshToken = toTrimmed(current.refresh_token);
+  const credentialKey = current.credential_key || buildAuthCredentialKey(current);
+  const account = buildAuthKeychainAccount(credentialKey);
+  const keychainEnabled = await isDarwinKeychainAvailable();
+
+  let storage = "file";
+  if (keychainEnabled && accessToken) {
+    const saved = await writeDarwinKeychainSecret(
+      account,
+      JSON.stringify({
+        access_token: accessToken,
+        refresh_token: refreshToken,
+      }),
+    );
+    if (saved) {
+      storage = "keychain";
+    }
+  }
+
+  const dir = join(homedir(), ".config", "crate-cli");
+  await mkdir(dir, { recursive: true });
+
+  const sanitized = {
+    version: AUTH_STORE_VERSION,
+    current: {
+      crate_url: toTrimmed(current.crate_url),
+      project_id: toTrimmed(current.project_id),
+      client_id: toTrimmed(current.client_id),
+      token_endpoint: toTrimmed(current.token_endpoint),
+      authorization_endpoint: toTrimmed(current.authorization_endpoint),
+      token_type: toTrimmed(current.token_type),
+      scope: toTrimmed(current.scope),
+      expires_at: toTrimmed(current.expires_at),
+      created_at: toTrimmed(current.created_at),
+      updated_at: toTrimmed(current.updated_at),
+      credential_key: credentialKey,
+      storage,
+    },
+  };
+
+  if (storage !== "keychain") {
+    sanitized.current.access_token = accessToken;
+    sanitized.current.refresh_token = refreshToken;
+  }
+
+  const body = `${JSON.stringify(sanitized, null, 2)}\n`;
+  await writeFile(AUTH_STORE_PATH, body, { mode: 0o600 });
+  return { storage };
+};
+
+const clearAuthStore = async () => {
+  try {
+    const raw = await readFile(AUTH_STORE_PATH, "utf8");
+    const parsed = parseAuthStore(raw);
+    const current = parsed?.current;
+    if (current) {
+      const credentialKey = current.credential_key || buildAuthCredentialKey(current);
+      const account = buildAuthKeychainAccount(credentialKey);
+      if (await isDarwinKeychainAvailable()) {
+        await deleteDarwinKeychainSecret(account);
+      }
+    }
+  } catch {
+    // Ignore parse/read errors and continue clearing local file.
+  }
+  try {
+    await unlink(AUTH_STORE_PATH);
+  } catch {
+    // Ignore missing file errors.
+  }
+};
+
+const normalizeCrateUrl = (value) => {
+  const raw = toTrimmed(value);
+  if (!raw) return "";
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return "";
+  }
+  parsed.hash = "";
+  const path = (parsed.pathname || "/").replace(/\/+$/g, "") || "/";
+  parsed.pathname = path;
+  return parsed.toString();
+};
+
+const toOriginFromUrl = (value) => {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return "";
+  }
+};
+
+const toIsoTimestampFromExpiresIn = (value) => {
+  const seconds = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(seconds) || seconds <= 0) return "";
+  return new Date(Date.now() + seconds * 1000).toISOString();
+};
+
+const isExpiredOrNearExpiry = (iso, leewaySeconds = 60) => {
+  const ts = Date.parse(toTrimmed(iso));
+  if (Number.isNaN(ts)) return true;
+  return ts - Date.now() <= leewaySeconds * 1000;
+};
+
+const generatePkceCodeVerifier = () => randomBytes(64).toString("base64url");
+
+const createPkceS256Challenge = (verifier) =>
+  createHash("sha256").update(verifier).digest("base64url");
+
+const createAuthStateToken = () => randomBytes(24).toString("base64url");
+
+const buildAuthorizationEndpoint = (crateUrl, projectId) => {
+  const endpoint = new URL("/oauth/authorize", crateUrl);
+  if (projectId) endpoint.searchParams.set("project_id", projectId);
+  return endpoint.toString();
+};
+
+const buildTokenEndpoint = (crateUrl) => new URL("/api/oauth/token", crateUrl).toString();
+
+const fetchJson = async (url, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+      },
+      signal: controller.signal,
+    });
+    const payload = await response.json().catch(() => null);
+    return { ok: response.ok, status: response.status, payload };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const postForm = async (url, body, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams(body).toString(),
+      signal: controller.signal,
+    });
+    const payload = await response.json().catch(() => null);
+    return { ok: response.ok, status: response.status, payload };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const resolveOAuthEndpoints = async (crateUrl, projectId, timeoutMs) => {
+  const metadataUrl = new URL("/.well-known/oauth-authorization-server", crateUrl);
+  if (projectId) metadataUrl.searchParams.set("project_id", projectId);
+
+  const fallback = {
+    authorization_endpoint: buildAuthorizationEndpoint(crateUrl, projectId),
+    token_endpoint: buildTokenEndpoint(crateUrl),
+  };
+
+  const metadata = await fetchJson(metadataUrl.toString(), timeoutMs);
+  if (!metadata.ok || !metadata.payload || typeof metadata.payload !== "object") {
+    return fallback;
+  }
+
+  const authorizationEndpoint = toTrimmed(metadata.payload.authorization_endpoint);
+  const tokenEndpoint = toTrimmed(metadata.payload.token_endpoint);
+  return {
+    authorization_endpoint: authorizationEndpoint || fallback.authorization_endpoint,
+    token_endpoint: tokenEndpoint || fallback.token_endpoint,
+  };
+};
+
+const openExternalBrowser = async (targetUrl) => {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    await execFileAsync("open", [targetUrl], { timeout: 10_000, maxBuffer: 64 * 1024 });
+    return;
+  }
+  if (platform === "win32") {
+    await execFileAsync("cmd", ["/c", "start", "", targetUrl], {
+      timeout: 10_000,
+      maxBuffer: 64 * 1024,
+    });
+    return;
+  }
+  await execFileAsync("xdg-open", [targetUrl], { timeout: 10_000, maxBuffer: 64 * 1024 });
+};
+
+const startLoopbackCallbackServer = async ({
+  callbackPath,
+  timeoutSeconds,
+}) => {
+  const normalizedPath = callbackPath.startsWith("/") ? callbackPath : `/${callbackPath}`;
+
+  let resolved = false;
+  let resolveResult;
+  let rejectResult;
+  const resultPromise = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const server = createServer((request, response) => {
+    let requestUrl;
+    try {
+      requestUrl = new URL(request.url || "/", `http://${request.headers.host || "127.0.0.1"}`);
+    } catch {
+      response.statusCode = 400;
+      response.end("Invalid callback URL");
+      return;
+    }
+
+    if (requestUrl.pathname !== normalizedPath) {
+      response.statusCode = 404;
+      response.end("Not found");
+      return;
+    }
+
+    const code = toTrimmed(requestUrl.searchParams.get("code"));
+    const state = toTrimmed(requestUrl.searchParams.get("state"));
+    const error = toTrimmed(requestUrl.searchParams.get("error"));
+    const errorDescription = toTrimmed(requestUrl.searchParams.get("error_description"));
+
+    response.statusCode = 200;
+    response.setHeader("Content-Type", "text/html; charset=utf-8");
+    response.end(
+      "<!doctype html><html><body><h1>Crate CLI</h1><p>認証が完了しました。このタブを閉じてください。</p></body></html>",
+    );
+
+    if (resolved) return;
+    resolved = true;
+    resolveResult({ code, state, error, error_description: errorDescription });
+  });
+
+  const timeoutMs = timeoutSeconds * 1000;
+  const timeout = setTimeout(() => {
+    if (resolved) return;
+    resolved = true;
+    rejectResult(new Error("OAuth callback timed out. Please run `crate auth login` again."));
+    server.close();
+  }, timeoutMs);
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    clearTimeout(timeout);
+    server.close();
+    throw new Error("Failed to bind local callback server.");
+  }
+
+  const redirectUri = new URL(`http://127.0.0.1:${address.port}${normalizedPath}`).toString();
+
+  const close = async () =>
+    new Promise((resolve) => {
+      clearTimeout(timeout);
+      server.close(() => resolve());
+    });
+
+  return {
+    redirectUri,
+    waitForCallback: () => resultPromise,
+    close,
+  };
+};
+
+const buildMcpResourceUrl = (crateUrl, projectId) => {
+  const url = new URL("/api/mcp", crateUrl);
+  if (projectId) url.searchParams.set("project_id", projectId);
+  return url.toString();
+};
+
+const normalizeAuthSession = (store) => {
+  if (!store?.current) return null;
+  const current = store.current;
+  if (!current.crate_url || !current.access_token) return null;
+  return current;
+};
+
+const refreshOAuthSession = async (session, timeoutMs) => {
+  if (!session.refresh_token || !session.token_endpoint || !session.client_id) {
+    return null;
+  }
+
+  const response = await postForm(
+    session.token_endpoint,
+    {
+      grant_type: "refresh_token",
+      refresh_token: session.refresh_token,
+      client_id: session.client_id,
+    },
+    timeoutMs,
+  );
+  if (!response.ok || !response.payload || typeof response.payload !== "object") {
+    return null;
+  }
+
+  const accessToken = toTrimmed(response.payload.access_token);
+  const refreshToken = toTrimmed(response.payload.refresh_token) || session.refresh_token;
+  const expiresAt = toIsoTimestampFromExpiresIn(response.payload.expires_in);
+  if (!accessToken || !refreshToken || !expiresAt) {
+    return null;
+  }
+
+  const now = new Date().toISOString();
+  return {
+    ...session,
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    token_type: toTrimmed(response.payload.token_type) || session.token_type,
+    scope: toTrimmed(response.payload.scope) || session.scope,
+    expires_at: expiresAt,
+    updated_at: now,
+  };
+};
+
 const getCommonDefaults = () => ({
+  crateUrl: process.env.CRATE_URL?.trim() ?? "",
+  apiToken: process.env.CRATE_TOKEN?.trim() ?? "",
+  projectId: process.env.CRATE_PROJECT_ID?.trim() ?? "",
   mcpUrl: process.env.CRATE_MCP_URL?.trim() ?? "",
   mcpIngestToken: process.env.CRATE_MCP_INGEST_TOKEN?.trim() ?? "",
   serverName: process.env.CRATE_MCP_SERVER_NAME?.trim() ?? "",
@@ -307,6 +889,10 @@ const getWriteDefaults = () => ({
 });
 
 const COMMON_SCHEMA = {
+  "--crate-url": { key: "crateUrl", type: "string" },
+  "--api-url": { key: "crateUrl", type: "string" },
+  "--token": { key: "apiToken", type: "string" },
+  "--project-id": { key: "projectId", type: "string" },
   "--mcp-url": { key: "mcpUrl", type: "string" },
   "--mcp-ingest-token": { key: "mcpIngestToken", type: "string" },
   "--server-name": { key: "serverName", type: "string" },
@@ -328,6 +914,9 @@ const WRITE_SCHEMA = {
 };
 
 const normalizeCommonOptions = (options) => {
+  options.crateUrl = toTrimmed(options.crateUrl);
+  options.apiToken = toTrimmed(options.apiToken);
+  options.projectId = toTrimmed(options.projectId);
   options.mcpUrl = toTrimmed(options.mcpUrl);
   options.mcpIngestToken = toTrimmed(options.mcpIngestToken);
   options.serverName = toTrimmed(options.serverName);
@@ -470,6 +1059,33 @@ const parseGithubRepoFromRemoteUrl = (remoteUrl) => {
   return normalizeGithubRepoFullName(raw);
 };
 
+const buildMcpUrlFromCrateUrl = (crateUrl, projectId = "") => {
+  const normalizedBaseUrl = toTrimmed(crateUrl);
+  if (!normalizedBaseUrl) return "";
+
+  let parsed;
+  try {
+    parsed = new URL(normalizedBaseUrl);
+  } catch {
+    throw new Error("--crate-url must be a valid URL.");
+  }
+
+  const pathname = (parsed.pathname || "/").replace(/\/+$/g, "") || "/";
+  if (!pathname.endsWith("/api/mcp")) {
+    const prefix = pathname === "/" ? "" : pathname;
+    parsed.pathname = `${prefix}/api/mcp`;
+  } else {
+    parsed.pathname = pathname;
+  }
+
+  const normalizedProjectId = toTrimmed(projectId);
+  if (normalizedProjectId && !parsed.searchParams.get("project_id")) {
+    parsed.searchParams.set("project_id", normalizedProjectId);
+  }
+
+  return parsed.toString();
+};
+
 const inferGithubRepoFromGitRemote = async () => {
   try {
     const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], {
@@ -483,18 +1099,28 @@ const inferGithubRepoFromGitRemote = async () => {
 };
 
 const resolveMcpConnection = async (options) => {
-  if (options.mcpUrl && options.mcpIngestToken) {
+  const hasCrateInput = Boolean(options.crateUrl || options.apiToken);
+  const hasLegacyInput = Boolean(options.mcpUrl || options.mcpIngestToken);
+  const hasCrateComplete = Boolean(options.crateUrl && options.apiToken);
+  const hasLegacyComplete = Boolean(options.mcpUrl && options.mcpIngestToken);
+  if (hasCrateComplete && hasLegacyComplete) {
+    throw new Error(
+      "Do not provide both --crate-url/--token and --mcp-url/--mcp-ingest-token.",
+    );
+  }
+
+  if (hasCrateComplete) {
     return {
-      mcpUrl: options.mcpUrl,
-      mcpIngestToken: options.mcpIngestToken,
+      mcpUrl: buildMcpUrlFromCrateUrl(options.crateUrl, options.projectId),
+      mcpIngestToken: options.apiToken,
     };
   }
 
-  if (options.mcpUrl && !options.mcpIngestToken) {
-    throw new Error("MCP token is missing. Provide --mcp-ingest-token.");
-  }
-  if (!options.mcpUrl && options.mcpIngestToken) {
-    throw new Error("MCP URL is missing. Provide --mcp-url.");
+  if (hasLegacyComplete) {
+    return {
+      mcpUrl: options.mcpUrl,
+      mcpIngestToken: options.mcpIngestToken,
+    };
   }
 
   const servers = await readCodexServerConfigs();
@@ -522,8 +1148,44 @@ const resolveMcpConnection = async (options) => {
     };
   }
 
+  const authStore = await readAuthStore();
+  let authSession = normalizeAuthSession(authStore);
+  if (authSession && isExpiredOrNearExpiry(authSession.expires_at)) {
+    const refreshed = await refreshOAuthSession(authSession, options.timeoutMs);
+    if (refreshed) {
+      authSession = refreshed;
+      await writeAuthStore({ current: refreshed });
+    }
+  }
+  if (authSession) {
+    const effectiveCrateUrl = normalizeCrateUrl(options.crateUrl) || authSession.crate_url;
+    const effectiveProjectId = toTrimmed(options.projectId) || authSession.project_id || "";
+    const effectiveToken = options.apiToken || authSession.access_token;
+    if (effectiveCrateUrl && effectiveToken) {
+      return {
+        mcpUrl: buildMcpUrlFromCrateUrl(effectiveCrateUrl, effectiveProjectId),
+        mcpIngestToken: effectiveToken,
+      };
+    }
+  }
+
+  if (options.crateUrl && !options.apiToken) {
+    throw new Error("Crate API token is missing. Provide --token or run `crate auth login`.");
+  }
+  if (!options.crateUrl && options.apiToken) {
+    throw new Error("Crate URL is missing. Provide --crate-url.");
+  }
+  if (options.mcpUrl && !options.mcpIngestToken) {
+    throw new Error("MCP token is missing. Provide --mcp-ingest-token.");
+  }
+  if (!options.mcpUrl && options.mcpIngestToken) {
+    throw new Error("MCP URL is missing. Provide --mcp-url.");
+  }
+
   throw new Error(
-    "Unable to resolve MCP server automatically. Provide --server-name, or --mcp-url and --mcp-ingest-token.",
+    hasCrateInput || hasLegacyInput
+      ? "Unable to resolve connection with current options."
+      : "Unable to resolve connection automatically. Run `crate auth login`, or provide --crate-url and --token, --server-name, or --mcp-url and --mcp-ingest-token.",
   );
 };
 
@@ -846,6 +1508,9 @@ const parseCommand = (argv) => {
 
   const compound = `${first} ${second}`;
   const knownCompound = new Set([
+    "auth login",
+    "auth status",
+    "auth logout",
     "tool list",
     "tool call",
     "tasks list",
@@ -1002,7 +1667,6 @@ const handleTasksList = async (argv, runtime) => {
 
   const { options } = parseFlags(argv, schema, {
     ...getCommonDefaults(),
-    projectId: "",
     status: "",
     limit: 50,
   });
@@ -1054,7 +1718,6 @@ const handleTasksCreate = async (argv, runtime) => {
     description: "",
     actorContext: "agent",
     sourceContext: "crate-cli",
-    projectId: "",
     githubRepoFullName: process.env.CRATE_GITHUB_REPO_FULL_NAME?.trim() ?? "",
   });
 
@@ -1129,7 +1792,6 @@ const handleTasksUpdate = async (argv, runtime) => {
     status: "",
     actorContext: "agent",
     sourceContext: "crate-cli",
-    projectId: "",
     githubRepoFullName: process.env.CRATE_GITHUB_REPO_FULL_NAME?.trim() ?? "",
   });
 
@@ -1210,7 +1872,6 @@ const handleCheckpointStatus = async (argv, runtime) => {
 
   const { options, seenFlags } = parseFlags(argv, schema, {
     ...getCommonDefaults(),
-    projectId: "",
     clientEventId: process.env.CRATE_EVENT_CLIENT_EVENT_ID?.trim() ?? "",
     sessionId: process.env.CODEX_THREAD_ID?.trim() ?? "",
     contextLabel: process.env.CRATE_EVENT_CONTEXT_LABEL?.trim() ?? "",
@@ -1395,8 +2056,256 @@ const handleTasksClose = async (argv, runtime) => {
   return 0;
 };
 
+const parseAuthLoginOptions = (argv) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    "--scope": { key: "scope", type: "string" },
+    "--client-id": { key: "clientId", type: "string" },
+    "--callback-timeout-seconds": { key: "callbackTimeoutSeconds", type: "integer" },
+    "--no-browser": { key: "noBrowser", type: "boolean" },
+  };
+
+  const { options } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    scope: DEFAULT_OAUTH_SCOPES,
+    clientId: DEFAULT_OAUTH_CLIENT_ID,
+    callbackTimeoutSeconds: DEFAULT_AUTH_CALLBACK_TIMEOUT_SECONDS,
+    noBrowser: false,
+  });
+  normalizeCommonOptions(options);
+  options.scope = toTrimmed(options.scope);
+  options.clientId = toTrimmed(options.clientId);
+  options.crateUrl = normalizeCrateUrl(options.crateUrl || DEFAULT_CRATE_URL);
+  options.projectId = toTrimmed(options.projectId);
+  options.callbackTimeoutSeconds = parsePositiveInteger(
+    options.callbackTimeoutSeconds,
+    "--callback-timeout-seconds",
+  );
+  if (!options.crateUrl) {
+    throw new Error("--crate-url must be a valid URL.");
+  }
+  if (!options.clientId) {
+    throw new Error("--client-id is required.");
+  }
+  return options;
+};
+
+const handleAuthLogin = async (argv) => {
+  const options = parseAuthLoginOptions(argv);
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["auth login"]}\n`);
+    return 0;
+  }
+
+  const endpoints = await resolveOAuthEndpoints(
+    options.crateUrl,
+    options.projectId,
+    options.timeoutMs,
+  );
+  const callback = await startLoopbackCallbackServer({
+    callbackPath: AUTH_CALLBACK_PATH,
+    timeoutSeconds: options.callbackTimeoutSeconds,
+  });
+
+  const state = createAuthStateToken();
+  const codeVerifier = generatePkceCodeVerifier();
+  const codeChallenge = createPkceS256Challenge(codeVerifier);
+  const resourceUrl = buildMcpResourceUrl(options.crateUrl, options.projectId);
+  const authorizeUrl = new URL(endpoints.authorization_endpoint);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", options.clientId);
+  authorizeUrl.searchParams.set("redirect_uri", callback.redirectUri);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", codeChallenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("resource", resourceUrl);
+  authorizeUrl.searchParams.set("mcp_url", resourceUrl);
+  if (options.projectId) {
+    authorizeUrl.searchParams.set("project_id", options.projectId);
+  }
+  if (options.scope) {
+    authorizeUrl.searchParams.set("scope", options.scope);
+  }
+
+  let browserOpened = false;
+  if (!options.noBrowser) {
+    try {
+      await openExternalBrowser(authorizeUrl.toString());
+      browserOpened = true;
+    } catch {
+      browserOpened = false;
+    }
+  }
+
+  if (!options.outputJson) {
+    process.stdout.write(`OAuth authorize URL:\n${authorizeUrl.toString()}\n`);
+    if (browserOpened) {
+      process.stdout.write("ブラウザを開きました。認証完了を待機します。\n");
+    } else {
+      process.stdout.write("上記URLをブラウザで開いて認証してください。\n");
+    }
+  }
+
+  let callbackResult;
+  try {
+    callbackResult = await callback.waitForCallback();
+  } finally {
+    await callback.close();
+  }
+
+  if (callbackResult.error) {
+    const description = toTrimmed(callbackResult.error_description);
+    throw new Error(
+      description
+        ? `OAuth authorization failed: ${callbackResult.error} (${description})`
+        : `OAuth authorization failed: ${callbackResult.error}`,
+    );
+  }
+  if (!callbackResult.code) {
+    throw new Error("OAuth authorization code was not returned.");
+  }
+  if (callbackResult.state !== state) {
+    throw new Error("OAuth state mismatch. Please retry `crate auth login`.");
+  }
+
+  const tokenResponse = await postForm(
+    endpoints.token_endpoint,
+    {
+      grant_type: "authorization_code",
+      code: callbackResult.code,
+      client_id: options.clientId,
+      redirect_uri: callback.redirectUri,
+      code_verifier: codeVerifier,
+    },
+    options.timeoutMs,
+  );
+  if (!tokenResponse.ok || !tokenResponse.payload || typeof tokenResponse.payload !== "object") {
+    const error = toTrimmed(tokenResponse.payload?.error) || `status=${tokenResponse.status}`;
+    const desc = toTrimmed(tokenResponse.payload?.error_description);
+    throw new Error(desc ? `OAuth token exchange failed: ${error} (${desc})` : `OAuth token exchange failed: ${error}`);
+  }
+
+  const accessToken = toTrimmed(tokenResponse.payload.access_token);
+  const refreshToken = toTrimmed(tokenResponse.payload.refresh_token);
+  const tokenType = toTrimmed(tokenResponse.payload.token_type) || "Bearer";
+  const scope = toTrimmed(tokenResponse.payload.scope) || options.scope;
+  const expiresAt = toIsoTimestampFromExpiresIn(tokenResponse.payload.expires_in);
+
+  if (!accessToken || !refreshToken || !expiresAt) {
+    throw new Error("OAuth token response is missing required fields.");
+  }
+
+  const now = new Date().toISOString();
+  const store = {
+    current: {
+      crate_url: options.crateUrl,
+      project_id: options.projectId,
+      client_id: options.clientId,
+      token_endpoint: endpoints.token_endpoint,
+      authorization_endpoint: endpoints.authorization_endpoint,
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      token_type: tokenType,
+      scope,
+      expires_at: expiresAt,
+      created_at: now,
+      updated_at: now,
+    },
+  };
+  await writeAuthStore(store);
+
+  outputMaybeJson(
+    options,
+    {
+      status: "authenticated",
+      crate_url: options.crateUrl,
+      project_id: options.projectId || null,
+      expires_at: expiresAt,
+      scope,
+      browser_opened: browserOpened,
+    },
+    (payload) => {
+      const lines = ["authentication succeeded"];
+      lines.push(`- crate_url: ${payload.crate_url}`);
+      lines.push(`- project_id: ${payload.project_id ?? "(auto)"}`);
+      lines.push(`- expires_at: ${payload.expires_at}`);
+      lines.push(`- scope: ${payload.scope}`);
+      return `${lines.join("\n")}\n`;
+    },
+  );
+  return 0;
+};
+
+const handleAuthStatus = async (argv) => {
+  const { options } = parseFlags(argv, COMMON_SCHEMA, getCommonDefaults());
+  normalizeCommonOptions(options);
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["auth status"]}\n`);
+    return 0;
+  }
+
+  const store = await readAuthStore();
+  let session = normalizeAuthSession(store);
+  if (session && isExpiredOrNearExpiry(session.expires_at)) {
+    const refreshed = await refreshOAuthSession(session, options.timeoutMs);
+    if (refreshed) {
+      session = refreshed;
+      await writeAuthStore({ current: refreshed });
+    }
+  }
+
+  if (!session) {
+    outputMaybeJson(
+      options,
+      { authenticated: false },
+      () => "not authenticated. run `crate auth login`.\n",
+    );
+    return 0;
+  }
+
+  outputMaybeJson(
+    options,
+    {
+      authenticated: true,
+      crate_url: session.crate_url,
+      project_id: session.project_id || null,
+      scope: session.scope,
+      expires_at: session.expires_at,
+      token_type: session.token_type,
+    },
+    (payload) => {
+      const lines = ["authenticated"];
+      lines.push(`- crate_url: ${payload.crate_url}`);
+      lines.push(`- project_id: ${payload.project_id ?? "(auto)"}`);
+      lines.push(`- expires_at: ${payload.expires_at}`);
+      lines.push(`- scope: ${payload.scope || "(default)"}`);
+      return `${lines.join("\n")}\n`;
+    },
+  );
+  return 0;
+};
+
+const handleAuthLogout = async (argv) => {
+  const { options } = parseFlags(argv, COMMON_SCHEMA, getCommonDefaults());
+  normalizeCommonOptions(options);
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["auth logout"]}\n`);
+    return 0;
+  }
+
+  await clearAuthStore();
+  outputMaybeJson(options, { status: "logged_out" }, () => "logged out.\n");
+  return 0;
+};
+
 const runWithCommand = async (command, args, runtime) => {
   switch (command) {
+    case "auth login":
+      return handleAuthLogin(args, runtime);
+    case "auth status":
+      return handleAuthStatus(args, runtime);
+    case "auth logout":
+      return handleAuthLogout(args, runtime);
     case "tool list":
       return handleToolList(args, runtime);
     case "tool call":
@@ -1441,6 +2350,7 @@ export const runCrateCli = async (argv = process.argv.slice(2), runtime = {}) =>
 };
 
 export const __testables = {
+  buildMcpUrlFromCrateUrl,
   classifyTaskCloseError,
   normalizeContextLabel,
   normalizeClientEventId,