@oar-sh/oar 0.9.6 → 0.9.7

package/shared/claude-cloud/base-url.mjs

@@ -0,0 +1,47 @@
+// Where the cloud client sends its calls.
+//
+// Always the Anthropic API, with one exception for tests: the environment
+// variable below may point the client at a fake API on the same machine. The
+// client sends the Claude login as a bearer token to whatever its base URL
+// is, so an environment variable must never be able to name another host: a
+// value that is not a plain http(s) URL of the loopback interface is ignored
+// and the default stays. The relay's client and the cloud worker's both ask
+// here, so the rule lives in this one function.
+
+import { CLAUDE_CLOUD_BASE_URL } from './api-client.mjs';
+
+export const CLAUDE_CLOUD_BASE_URL_ENV = 'OAR_CLAUDE_CLOUD_API_BASE_URL';
+
+// Exactly these, as the URL parser writes them (it lower-cases the name and
+// puts the IPv6 address in brackets). No "anything in 127/8", no trailing dot,
+// no name that merely starts or ends like one of them.
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', '[::1]', 'localhost']);
+
+/**
+ * The origin of a loopback http(s) URL (`http://127.0.0.1:4010`), or null for
+ * anything else: another host, another scheme, a URL with a user or a
+ * password in it, or text that is no URL at all. A path, query or fragment is
+ * dropped: the client's routes start at the root.
+ */
+export function loopbackBaseUrlOrNull(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) return null;
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.username || url.password) return null;
+  if (!LOOPBACK_HOSTNAMES.has(url.hostname)) return null;
+  return url.origin;
+}
+
+/**
+ * The base URL for `createClaudeCloudClient`: the loopback URL named by
+ * `OAR_CLAUDE_CLOUD_API_BASE_URL`, else the Anthropic API.
+ */
+export function resolveClaudeCloudBaseUrl(env = process.env) {
+  return loopbackBaseUrlOrNull(env?.[CLAUDE_CLOUD_BASE_URL_ENV]) || CLAUDE_CLOUD_BASE_URL;
+}

package/shared/claude-cloud/credentials.mjs

@@ -0,0 +1,221 @@
+// The Claude login a cloud session runs on.
+//
+// Claude Cloud sessions are created with the claude.ai login the Claude CLI
+// keeps in `<CLAUDE_CONFIG_DIR | ~/.claude>/.credentials.json`. This module is
+// the only place that reads it. It hands out the access token, says what it
+// found (never the token itself), and takes the token back out of any text
+// that is about to leave the process.
+//
+// What it never does: use the refresh token. A refresh from here would rotate
+// the login under the CLI and log it out. When the token has run out the file
+// is read again (the CLI rewrites it while it works), then the caller's
+// `nudge` may run the CLI once so that it refreshes its own login, and after
+// that the answer is `login_expired`.
+//
+// Nothing here logs, and no error it throws carries the token.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CLAUDE_CLOUD_ERROR_CODES = Object.freeze([
+  'login_missing',
+  'login_expired',
+  'github_not_connected',
+  'repo_access_denied',
+  'environment_missing',
+  'not_found',
+  'rate_limited',
+  'bad_request',
+  'transient',
+]);
+
+const DEFAULT_ERROR_MESSAGES = Object.freeze({
+  login_missing: 'No Claude login was found on this machine. Log in with the Claude CLI first.',
+  login_expired: 'The Claude login has expired or was rejected. Log in to Claude again.',
+  github_not_connected: 'GitHub is not connected to this Claude account.',
+  repo_access_denied: 'The Claude GitHub app has no access to this repository.',
+  environment_missing: 'The Claude Cloud environment was not found.',
+  not_found: 'Claude Cloud did not find the session or resource.',
+  rate_limited: 'Claude Cloud is rate limiting this account. Try again later.',
+  bad_request: 'Claude Cloud refused the request.',
+  transient: 'Claude Cloud is not answering right now.',
+});
+
+/** The plain sentence for an error code; the fallback of every ClaudeCloudError. */
+export function claudeCloudErrorMessage(code) {
+  return DEFAULT_ERROR_MESSAGES[code] || DEFAULT_ERROR_MESSAGES.transient;
+}
+
+/**
+ * Every failure of the cloud client and of the credentials: `code` (one of
+ * CLAUDE_CLOUD_ERROR_CODES), `status` (the HTTP status, or null when no answer
+ * was involved) and `detail` (what the API said, already redacted, or null).
+ *
+ * `new ClaudeCloudError(code, message?, { status, detail })`; also accepted:
+ * `(message, { code, … })` and `({ code, message, … })`.
+ */
+export class ClaudeCloudError extends Error {
+  constructor(code, message, options) {
+    let fields;
+    if (code && typeof code === 'object') fields = code;
+    else if (message && typeof message === 'object') {
+      fields = message.code ? { ...message, message: code } : { ...message, code };
+    } else fields = { ...(options || {}), code, message };
+    const errorCode = String(fields.code || 'transient');
+    super(String(fields.message || '') || claudeCloudErrorMessage(errorCode));
+    this.name = 'ClaudeCloudError';
+    this.code = errorCode;
+    this.status = Number.isFinite(fields.status) ? fields.status : null;
+    this.detail = fields.detail ? String(fields.detail) : null;
+  }
+}
+
+export const CLAUDE_CLOUD_TOKEN_ENV = 'CLAUDE_CODE_OAUTH_TOKEN';
+/** The cached token is trusted until this long before it runs out. */
+export const CLAUDE_CLOUD_TOKEN_MARGIN_MS = 60_000;
+/** The CLI is asked to refresh its login at most this often. */
+export const CLAUDE_CLOUD_NUDGE_INTERVAL_MS = 5 * 60_000;
+
+const REDACTED = '[redacted]';
+/** Tokens handed out earlier stay redactable after the file moved on. */
+const MAX_REMEMBERED_TOKENS = 16;
+
+/** Where the CLI keeps its login: `CLAUDE_CONFIG_DIR`, else `.claude` in the home directory. */
+export function resolveClaudeCredentialsPath({ env = process.env, homedir = os.homedir, pathImpl = path } = {}) {
+  const configDir = String(env?.CLAUDE_CONFIG_DIR || '').trim();
+  if (configDir) return pathImpl.join(configDir, '.credentials.json');
+  const home = String((typeof homedir === 'function' ? homedir() : homedir) || '').trim();
+  return pathImpl.join(home, '.claude', '.credentials.json');
+}
+
+function textOrNull(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  return text || null;
+}
+
+function isoOrNull(ms) {
+  if (ms === null) return null;
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+/**
+ * `nudge`: an async function that makes the Claude CLI refresh its own login
+ * (the caller decides which command). Called at most once per five minutes,
+ * and only when the login in the file is about to run out or has.
+ */
+export function createClaudeCloudCredentials({
+  env = process.env,
+  homedir = os.homedir,
+  fsImpl = fs,
+  now = Date.now,
+  nudge = null,
+  pathImpl = path,
+} = {}) {
+  let cached = null;
+  let loading = null;
+  let lastNudgeAt = null;
+  const remembered = [];
+
+  function remember(token) {
+    if (!token || remembered.includes(token)) return;
+    remembered.push(token);
+    if (remembered.length > MAX_REMEMBERED_TOKENS) remembered.shift();
+  }
+
+  function readEnvToken() {
+    const token = textOrNull(env?.[CLAUDE_CLOUD_TOKEN_ENV]);
+    if (token) remember(token);
+    return token;
+  }
+
+  /** The login in the file, or null when there is no file, no JSON or no token in it. */
+  function readFileLogin() {
+    let oauth = null;
+    try {
+      const filePath = resolveClaudeCredentialsPath({ env, homedir, pathImpl });
+      oauth = JSON.parse(fsImpl.readFileSync(filePath, 'utf8'))?.claudeAiOauth;
+    } catch {
+      return null;
+    }
+    const accessToken = textOrNull(oauth?.accessToken);
+    if (!accessToken) return null;
+    remember(accessToken);
+    const expiresAt = Number(oauth.expiresAt);
+    return {
+      accessToken,
+      expiresAt: Number.isFinite(expiresAt) && expiresAt > 0 ? expiresAt : null,
+      subscriptionType: textOrNull(oauth.subscriptionType),
+      rateLimitTier: textOrNull(oauth.rateLimitTier),
+    };
+  }
+
+  // A login without an expiry time is taken as it is and read again each time.
+  const isExpired = (login) => login.expiresAt !== null && now() >= login.expiresAt;
+  const isFresh = (login) => login.expiresAt !== null && now() < login.expiresAt - CLAUDE_CLOUD_TOKEN_MARGIN_MS;
+  const needsRefresh = (login) => login.expiresAt !== null && !isFresh(login);
+
+  async function loadFromFile() {
+    let login = readFileLogin();
+    if (login && needsRefresh(login) && typeof nudge === 'function'
+      && (lastNudgeAt === null || now() - lastNudgeAt >= CLAUDE_CLOUD_NUDGE_INTERVAL_MS)) {
+      lastNudgeAt = now();
+      // A nudge that fails changes nothing: the file decides.
+      try { await nudge(); } catch {}
+      login = readFileLogin();
+    }
+    cached = null;
+    if (!login) throw new ClaudeCloudError('login_missing');
+    if (isExpired(login)) throw new ClaudeCloudError('login_expired');
+    // Inside the last minute the token still works, so it is handed out, but
+    // `isFresh` keeps it from being served from the cache.
+    cached = login;
+    return login.accessToken;
+  }
+
+  /**
+   * The bearer token. `forceReload` skips the cache (the API refused the
+   * cached token: the CLI may have replaced it early). Throws ClaudeCloudError
+   * `login_missing` or `login_expired`.
+   */
+  async function getAccessToken({ forceReload = false } = {}) {
+    const envToken = readEnvToken();
+    if (envToken) return envToken;
+    if (!forceReload && cached && isFresh(cached)) return cached.accessToken;
+    // One read (and one nudge) for everybody who asks while it runs.
+    if (!loading) loading = loadFromFile().finally(() => { loading = null; });
+    return loading;
+  }
+
+  /** What there is to say about the login without saying the token. Never throws. */
+  function describe() {
+    const none = { source: 'none', hasToken: false, expiresAt: null, subscriptionType: null, rateLimitTier: null, expired: false };
+    if (readEnvToken()) return { ...none, source: 'env', hasToken: true };
+    const login = readFileLogin();
+    if (!login) return none;
+    return {
+      source: 'file',
+      hasToken: true,
+      expiresAt: isoOrNull(login.expiresAt),
+      subscriptionType: login.subscriptionType,
+      rateLimitTier: login.rateLimitTier,
+      expired: isExpired(login),
+    };
+  }
+
+  /**
+   * The text without any token this module has handed out or seen, and
+   * without anything that has the shape of a bearer header or a Claude token.
+   */
+  function redact(text) {
+    let out = String(text ?? '');
+    readEnvToken();
+    for (const token of remembered) out = out.split(token).join(REDACTED);
+    return out
+      .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`)
+      .replace(/\bsk-ant-[A-Za-z0-9_-]{8,}/g, REDACTED);
+  }
+
+  return { getAccessToken, describe, redact };
+}

package/shared/claude-cloud/repo-url.mjs

@@ -0,0 +1,111 @@
+// Repository, branch and model strings for Claude Cloud sessions.
+//
+// A cloud session clones a GitHub repository by its https URL and, when one is
+// named, checks out a branch. Both arrive as free text (the New Chat fields,
+// an `origin` remote read from a folder), so everything is brought to one form
+// here before it is stored or sent: the server validates with these, the
+// browser shows what they return, the client sends it.
+//
+// Pure functions, no I/O.
+
+const GITHUB_HOSTS = new Set(['github.com', 'www.github.com']);
+// GitHub's own rules: an account name is letters, digits and single hyphens
+// (never leading), at most 39 characters; a repository name is letters,
+// digits, `.`, `_` and `-`, at most 100.
+const OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
+const MAX_BRANCH_LENGTH = 255;
+
+function ownerAndRepoFromPath(pathText) {
+  const parts = String(pathText || '').split('/').filter(Boolean);
+  // Exactly owner/repo: a pasted page URL (…/tree/main, /orgs/<name>/…) would
+  // otherwise be read as some other repository.
+  if (parts.length !== 2) return null;
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/i, '');
+  if (!OWNER_PATTERN.test(owner) || owner.endsWith('-')) return null;
+  if (!REPO_PATTERN.test(repo) || repo === '.' || repo === '..') return null;
+  return { owner, repo };
+}
+
+/**
+ * The canonical https form of a GitHub repository reference, or null when the
+ * text is not one. Accepts `https://github.com/owner/repo` (with `.git`, a
+ * trailing slash, or credentials in front of the host, which are dropped),
+ * `git@github.com:owner/repo.git`, `ssh://git@github.com/owner/repo`,
+ * `git://…` and the scheme-less `github.com/owner/repo`.
+ */
+export function normalizeGitHubRepoUrl(input) {
+  const text = String(input ?? '').trim();
+  if (!text || /\s/.test(text)) return null;
+
+  let host = '';
+  let pathText = '';
+  // scp-like: [user@]host:owner/repo(.git). A scheme is followed by `//`, so
+  // `https://…` and `ssh://…` never match here.
+  const scp = text.match(/^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9.-]+):(?!\/\/)(.+)$/);
+  if (scp) {
+    host = scp[1];
+    pathText = scp[2];
+  } else {
+    const withScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(text) ? text : `https://${text}`;
+    let url;
+    try {
+      url = new URL(withScheme);
+    } catch {
+      return null;
+    }
+    if (!['https:', 'http:', 'ssh:', 'git:', 'git+ssh:'].includes(url.protocol)) return null;
+    host = url.hostname;
+    pathText = url.pathname;
+  }
+
+  if (!GITHUB_HOSTS.has(host.toLowerCase())) return null;
+  const parsed = ownerAndRepoFromPath(pathText);
+  if (!parsed) return null;
+  const slug = `${parsed.owner}/${parsed.repo}`;
+  return { repoUrl: `https://github.com/${slug}`, owner: parsed.owner, repo: parsed.repo, slug };
+}
+
+/**
+ * Whether git would accept the text as a branch name (the rules of
+ * `git check-ref-format --branch`). Nothing is trimmed: a name with a space
+ * around it is not a branch name.
+ */
+export function isValidBranchName(value) {
+  if (typeof value !== 'string') return false;
+  if (!value || value.length > MAX_BRANCH_LENGTH) return false;
+  if (value === '@' || value.startsWith('-')) return false;
+  // Control characters, space, and the characters git reserves for revisions.
+  if (/[\u0000- \u007f~^:?*[\\]/.test(value)) return false;
+  if (value.includes('..') || value.includes('@{') || value.includes('//')) return false;
+  if (value.startsWith('/') || value.endsWith('/') || value.endsWith('.')) return false;
+  return value.split('/').every((part) => !part.startsWith('.') && !part.endsWith('.lock'));
+}
+
+/**
+ * A model id without its tier suffix: "claude-opus-5[1m]" → "claude-opus-5".
+ * The cloud takes plain ids only.
+ */
+export function stripModelTierSuffix(model) {
+  return String(model ?? '').trim().replace(/\s*\[[^\]]*\]$/, '').trim();
+}
+
+function encodeRefForUrl(ref) {
+  return ref.split('/').map((part) => encodeURIComponent(part)).join('/');
+}
+
+/**
+ * Where GitHub shows what a pushed branch changed: the compare page against
+ * `base`, the compare page against the default branch when no base is known,
+ * and the branch itself when it is the base (a compare of a branch with itself
+ * is empty). Null when the slug or the branch is not usable.
+ */
+export function compareUrl(slug, base, branch) {
+  const repo = normalizeGitHubRepoUrl(`https://github.com/${String(slug ?? '').trim()}`);
+  if (!repo || !isValidBranchName(branch)) return null;
+  const head = encodeRefForUrl(branch);
+  if (base === branch) return `${repo.repoUrl}/tree/${head}`;
+  if (!isValidBranchName(base)) return `${repo.repoUrl}/compare/${head}`;
+  return `${repo.repoUrl}/compare/${encodeRefForUrl(base)}...${head}`;
+}

package/shared/provider-routing.mjs

@@ -11,7 +11,9 @@
  */
 export const LEGACY_RELAY_PROVIDER_TYPES = Object.freeze(['github', 'openai']);
 
-export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok']);
+// `claude-cloud` is its own provider, never an alias of `claude`: its worker
+// drives a session in Anthropic's cloud and spawns no CLI.
+export const SESSION_WORKER_PROVIDER_TYPES = Object.freeze(['claude', 'cursor', 'grok', 'claude-cloud']);
 
 export function isLegacyRelayProviderType(value) {
   const normalized = String(value || '').trim().toLowerCase();
@@ -23,7 +25,7 @@ export function isSessionWorkerProviderType(value) {
   return SESSION_WORKER_PROVIDER_TYPES.includes(String(value || '').trim().toLowerCase());
 }
 
-/** `'claude', 'cursor', 'grok'` — for interpolation into SQL NOT IN (...) lists. */
+/** `'claude', 'cursor', 'grok', 'claude-cloud'` — for interpolation into SQL NOT IN (...) lists. */
 export function sessionWorkerProviderSqlList() {
   return SESSION_WORKER_PROVIDER_TYPES.map((provider) => `'${provider}'`).join(', ');
 }