@rynfar/meridian 1.41.0 → 1.42.0

package/README.md

@@ -239,6 +239,20 @@ meridian profile add work
 
 > **⚠ Important:** Claude's OAuth reuses your browser session. Before adding a second account, sign out of claude.ai and sign into the other account first.
 
+#### Headless / CI: register an OAuth token
+
+When a browser isn't available (containers, CI runners, remote shells), generate a long-lived OAuth token with `claude setup-token` and register it as a profile:
+
+```bash
+# Prompt for the token (input is hidden — paste the value from `claude setup-token`)
+meridian profile add ci --oauth-token
+
+# Or pass it inline
+meridian profile add ci --oauth-token sk-ant-oat01-...
+```
+
+OAuth-token profiles store the token in `profiles.json` and feed it to the SDK via `CLAUDE_CODE_OAUTH_TOKEN` — no Keychain entry, no browser handshake. To prevent the SDK's 401-recovery from silently falling back to the host's `~/.claude` credentials, OAuth-token profiles also pin `CLAUDE_CONFIG_DIR` to an isolated per-profile directory under `~/.config/meridian/profiles/<name>/`. That directory holds only SDK state (sessions, settings) — never `.credentials.json`, since the token is delivered through the env.
+
 ### Switching profiles
 
 ```bash
@@ -256,14 +270,15 @@ You can also switch profiles from the web UI at `http://127.0.0.1:3456/profiles`
 | Command | Description |
 |---------|-------------|
 | `meridian profile add <name>` | Add a profile and authenticate via browser |
+| `meridian profile add <name> --oauth-token [TOKEN]` | Add a headless profile from a `claude setup-token` value (prompts when `TOKEN` is omitted) |
 | `meridian profile list` | List profiles and auth status |
 | `meridian profile switch <name>` | Switch the active profile (requires running proxy) |
-| `meridian profile login <name>` | Re-authenticate an expired profile |
+| `meridian profile login <name>` | Re-authenticate an expired profile (browser-login profiles only) |
 | `meridian profile remove <name>` | Remove a profile and its credentials |
 
 ### How it works
 
-Each profile stores its credentials in an isolated `CLAUDE_CONFIG_DIR` under `~/.config/meridian/profiles/<name>/`. When a request arrives, Meridian resolves the profile in priority order:
+Each profile stores its credentials in an isolated `CLAUDE_CONFIG_DIR` under `~/.config/meridian/profiles/<name>/`. OAuth-token profiles use the same isolated directory layout — but the token itself lives in `~/.config/meridian/profiles.json` and is fed to the SDK via `CLAUDE_CODE_OAUTH_TOKEN`, so the per-profile dir holds only SDK state (sessions, settings) and never the credential. When a request arrives, Meridian resolves the profile in priority order:
 
 1. `x-meridian-profile` request header (per-request override)
 2. Active profile (set via `meridian profile switch` or the web UI)
@@ -276,11 +291,21 @@ Session state is scoped per profile — switching accounts won't cross-contamina
 For advanced setups (CI, Docker), profiles can also be provided via environment variable:
 
 ```bash
-export MERIDIAN_PROFILES='[{"id":"personal","claudeConfigDir":"/path/to/config1"},{"id":"work","claudeConfigDir":"/path/to/config2"}]'
+export MERIDIAN_PROFILES='[
+  {"id":"personal","claudeConfigDir":"/path/to/config1"},
+  {"id":"work","claudeConfigDir":"/path/to/config2"},
+  {"id":"ci","oauthToken":"sk-ant-oat01-..."}
+]'
 export MERIDIAN_DEFAULT_PROFILE=personal
 meridian
 ```
 
+Profile shapes:
+
+- `claudeConfigDir` — points at a `~/.claude`-style directory; uses Claude Max OAuth from that dir
+- `apiKey` (with optional `baseUrl`) — direct Anthropic API access; sets `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
+- `oauthToken` — long-lived token from `claude setup-token`; sets `CLAUDE_CODE_OAUTH_TOKEN`, no config dir needed
+
 When `MERIDIAN_PROFILES` is set, it takes precedence over disk-configured profiles. When unset, Meridian auto-discovers profiles from `~/.config/meridian/profiles.json` on each request.
 
 ## Agent Setup
@@ -710,9 +735,10 @@ export default {
 | `meridian` | Start the proxy server |
 | `meridian setup` | Configure the OpenCode plugin in `~/.config/opencode/opencode.json` |
 | `meridian profile add <name>` | Add a profile and authenticate via browser |
+| `meridian profile add <name> --oauth-token [TOKEN]` | Add a headless profile from a `claude setup-token` value (prompts when `TOKEN` is omitted) |
 | `meridian profile list` | List all profiles and their auth status |
 | `meridian profile switch <name>` | Switch the active profile (requires running proxy) |
-| `meridian profile login <name>` | Re-authenticate an expired profile |
+| `meridian profile login <name>` | Re-authenticate an expired profile (browser-login profiles only) |
 | `meridian profile remove <name>` | Remove a profile and its credentials |
 | `meridian refresh-token` | Manually refresh the Claude OAuth token (exits 0/1) |
 
@@ -767,6 +793,19 @@ docker run \
 
 Switch profiles at runtime via the `x-meridian-profile` header or `meridian profile switch` (see [Multi-Profile Support](#multi-profile-support)).
 
+### OAuth-token profiles in Docker (no volume mount)
+
+If you'd rather not mount a credential directory, generate a long-lived OAuth token on the host with `claude setup-token` and pass it as a profile. There's nothing to mount — the token alone is the credential:
+
+```bash
+docker run \
+  -e 'MERIDIAN_PROFILES=[{"id":"ci","oauthToken":"sk-ant-oat01-..."}]' \
+  -e MERIDIAN_DEFAULT_PROFILE=ci \
+  -p 3456:3456 meridian
+```
+
+This is the recommended path for CI runners, ephemeral containers, and cross-host deployments where browser-based login isn't reachable. Treat the token like any other secret — inject it via your platform's secret store rather than committing it to your image or compose file.
+
 ## Testing
 
 ```bash

package/dist/{cli-0eky480v.js → cli-7k1fcprd.js}

@@ -85,6 +85,9 @@ function configDirToKeychainService(claudeConfigDir) {
 function configDirToCredentialsFile(claudeConfigDir) {
   return join(resolve(claudeConfigDir), ".credentials.json");
 }
+function serializeCredentials(credentials) {
+  return JSON.stringify(credentials);
+}
 function parseKeychainValue(raw) {
   const trimmed = raw.trim();
   try {
@@ -113,7 +116,7 @@ function buildMacosStore(serviceName) {
       }
     },
     async write(credentials) {
-      const json = JSON.stringify(credentials, null, 2);
+      const json = serializeCredentials(credentials);
       const wasHex = keychainWasHexByService.get(serviceName) ?? false;
       const value = wasHex ? Buffer.from(json).toString("hex") : json;
       try {
@@ -142,7 +145,7 @@ function buildFileStore(filePath) {
     async write(credentials) {
       try {
         mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, JSON.stringify(credentials, null, 2), "utf-8");
+        writeFileSync(filePath, serializeCredentials(credentials), "utf-8");
         return true;
       } catch (err) {
         claudeLog("token_refresh.file_write_failed", { path: filePath, error: String(err) });
@@ -226,8 +229,71 @@ async function doRefresh(store) {
   claudeLog("token_refresh.success", { expiresAt });
   return true;
 }
+async function ensureFreshToken(store, bufferMs = 5 * 60 * 1000) {
+  const s = store ?? createPlatformCredentialStore();
+  const credentials = await s.read();
+  const expiresAt = credentials?.claudeAiOauth?.expiresAt;
+  if (!expiresAt)
+    return false;
+  if (expiresAt - Date.now() > bufferMs)
+    return true;
+  return refreshOAuthToken(s);
+}
+var scheduledRefreshTimer = null;
+var scheduledRefreshActive = false;
+var scheduledRefreshGeneration = 0;
+function startBackgroundRefresh(store, bufferMs = 5 * 60 * 1000, failureRetryMs = 5 * 60 * 1000) {
+  if (scheduledRefreshActive)
+    return;
+  scheduledRefreshActive = true;
+  const gen = ++scheduledRefreshGeneration;
+  scheduleNext(store ?? createPlatformCredentialStore(), bufferMs, failureRetryMs, gen);
+}
+function stopBackgroundRefresh() {
+  scheduledRefreshActive = false;
+  scheduledRefreshGeneration++;
+  if (scheduledRefreshTimer)
+    clearTimeout(scheduledRefreshTimer);
+  scheduledRefreshTimer = null;
+}
+async function scheduleNext(store, bufferMs, failureRetryMs, gen) {
+  if (!scheduledRefreshActive || gen !== scheduledRefreshGeneration)
+    return;
+  const credentials = await store.read().catch(() => null);
+  if (!scheduledRefreshActive || gen !== scheduledRefreshGeneration)
+    return;
+  const expiresAt = credentials?.claudeAiOauth?.expiresAt;
+  if (!expiresAt) {
+    armTimer(failureRetryMs, store, bufferMs, failureRetryMs, gen);
+    return;
+  }
+  const dueIn = expiresAt - Date.now() - bufferMs;
+  if (dueIn <= 0) {
+    const ok = await refreshOAuthToken(store);
+    if (!scheduledRefreshActive || gen !== scheduledRefreshGeneration)
+      return;
+    claudeLog("token_refresh.scheduled", { ok, immediate: true });
+    console.error(`[token_refresh] scheduled refresh (immediate) ok=${ok}`);
+    armTimer(ok ? 0 : failureRetryMs, store, bufferMs, failureRetryMs, gen);
+    return;
+  }
+  armTimer(dueIn, store, bufferMs, failureRetryMs, gen);
+}
+function armTimer(delayMs, store, bufferMs, failureRetryMs, gen) {
+  scheduledRefreshTimer = setTimeout(async () => {
+    if (!scheduledRefreshActive || gen !== scheduledRefreshGeneration)
+      return;
+    scheduleNext(store, bufferMs, failureRetryMs, gen);
+  }, delayMs);
+  if (scheduledRefreshTimer && scheduledRefreshTimer.unref) {
+    scheduledRefreshTimer.unref();
+  }
+}
+function isBackgroundRefreshActive() {
+  return scheduledRefreshActive;
+}
 function resetInflightRefresh() {
   inflightRefresh = null;
 }
 
-export { withClaudeLogContext, claudeLog, configDirToKeychainService, configDirToCredentialsFile, createPlatformCredentialStore, credentialsFilePathForProfile, refreshOAuthToken, resetInflightRefresh };
+export { withClaudeLogContext, claudeLog, configDirToKeychainService, configDirToCredentialsFile, serializeCredentials, createPlatformCredentialStore, credentialsFilePathForProfile, refreshOAuthToken, ensureFreshToken, startBackgroundRefresh, stopBackgroundRefresh, isBackgroundRefreshActive, resetInflightRefresh };

package/dist/{cli-vdp9s10c.js → cli-cx463q74.js}

@@ -86,6 +86,14 @@ function resolveProfile(profiles, defaultProfile, requestedId) {
   return buildResolvedProfile(profile);
 }
 function buildResolvedProfile(profile) {
+  if (profile.oauthToken || profile.type === "oauth-token") {
+    const env2 = {};
+    if (profile.oauthToken) {
+      env2.CLAUDE_CODE_OAUTH_TOKEN = profile.oauthToken;
+      env2.CLAUDE_CONFIG_DIR = join(homedir(), ".config", "meridian", "profiles", profile.id);
+    }
+    return { id: profile.id, type: "oauth-token", env: env2 };
+  }
   const type = profile.type ?? "claude-max";
   if (type === "api") {
     const env2 = {};