@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.1 → 0.2.0

package/lib/types/endpoint-auth.js

@@ -0,0 +1,297 @@
+/**
+ * Endpoint-key authentication — the claude-code harness's ONLY auth mode.
+ * There is no OAuth anywhere in this package: a delegation round reaches its
+ * endpoint with `ANTHROPIC_BASE_URL` plus `ANTHROPIC_API_KEY` (x-api-key) or
+ * `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer), exactly the environment a
+ * shell would export for a proxy relay, and `claude -p` needs nothing else
+ * (verified against claude 2.1.296: a fresh scoped home with only these
+ * variables runs a round and scaffolds `.claude.json` itself — no onboarding
+ * or key-approval gate in headless mode).
+ *
+ * Two layers, merged per field, file over config:
+ *
+ * - `<scopedHome>/endpoint-auth.json` (mode 0600) — the per-scope credential.
+ *   Its name deliberately matches the eval contract hash's credential denylist
+ *   (`auth`), so the key material never enters an evaluation's condition
+ *   fingerprint; the file's mtime serves as the credential stamp, which makes
+ *   "edit the file" the recovery gesture for a `rejected` grade.
+ * - The plugin config's `baseUrl` / `apiKey` / `authToken` — the deployment
+ *   default every scope without a file shares. Read PER ROUND from the
+ *   apply-time snapshot, so a profile edit applies to the next round (and a
+ *   host restart clears the in-memory `rejected` mark).
+ *
+ * The env layer this module emits rides the family's existing plumbing:
+ * `delegationEnv` on the host, and `containerExecSpawn`'s name-only `-e`
+ * forwarding into a container (the value travels in the docker client's
+ * environment, never on an argv). A containerized round therefore
+ * authenticates with the same credential as the host — nothing is authorized
+ * inside the unit, which is the point.
+ * @module @khorsheed/dsh-local-agent-claude-code/endpoint-auth
+ */
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The scoped-home credential file's name. Chosen to match the eval contract
+ * hash's credential-shaped denylist (`/token|key|credential|secret|password|auth|\.env/i`),
+ * so the file is excluded from condition fingerprints by name.
+ */
+export const ENDPOINT_AUTH_FILE = 'endpoint-auth.json';
+/** Trim and normalize one credential field; blank reads as absent. */
+function field(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Whether a resolved endpoint carries a usable credential. */
+export function hasEndpointCredential(auth) {
+    return auth !== undefined && (field(auth.apiKey) !== undefined || field(auth.authToken) !== undefined);
+}
+/**
+ * Read the scope's endpoint-auth.json. Absent or unreadable yields undefined
+ * (the caller falls back to the plugin config); malformed JSON or a non-object
+ * payload also yields undefined — a torn file must not fail a status read.
+ * Non-string fields are dropped, never carried through.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the file's endpoint credential, or undefined.
+ */
+export async function readEndpointAuthFile(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, ENDPOINT_AUTH_FILE), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const baseUrl = field(parsed['baseUrl']);
+        const apiKey = field(parsed['apiKey']);
+        const authToken = field(parsed['authToken']);
+        return {
+            ...baseUrl === undefined ? {} : { baseUrl },
+            ...apiKey === undefined ? {} : { apiKey },
+            ...authToken === undefined ? {} : { authToken },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one scope's effective endpoint credential: the scope's
+ * endpoint-auth.json merged FIELD BY FIELD over the plugin config's
+ * `baseUrl` / `apiKey` / `authToken` (a file that names only a key rotates
+ * the key while keeping the deployment's relay URL). The result may carry no
+ * credential at all — {@link hasEndpointCredential} is the judgment, kept
+ * separate so the caller can still route/log the resolved baseUrl.
+ * @param homeDir - the scope's scoped home.
+ * @param config - the plugin config's deployment-level endpoint triple.
+ * @returns the merged endpoint auth.
+ */
+export async function resolveEndpointAuth(homeDir, config) {
+    const file = await readEndpointAuthFile(homeDir);
+    const configBaseUrl = field(config.baseUrl);
+    const configApiKey = field(config.apiKey);
+    const configAuthToken = field(config.authToken);
+    return {
+        ...configBaseUrl === undefined ? {} : { baseUrl: configBaseUrl },
+        ...configApiKey === undefined ? {} : { apiKey: configApiKey },
+        ...configAuthToken === undefined ? {} : { authToken: configAuthToken },
+        ...file,
+    };
+}
+/**
+ * The spawn-env layer for a resolved endpoint: one entry per defined field,
+ * nothing else. Undefined yields an empty layer — the spread then adds no
+ * keys at all, byte-identical to the pre-endpoint env.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the explicit env entries for the delegation spawn.
+ */
+export function endpointAuthEnv(auth) {
+    if (auth === undefined)
+        return {};
+    const baseUrl = field(auth.baseUrl);
+    const apiKey = field(auth.apiKey);
+    const authToken = field(auth.authToken);
+    return {
+        ...baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: baseUrl },
+        ...apiKey === undefined ? {} : { ANTHROPIC_API_KEY: apiKey },
+        ...authToken === undefined ? {} : { ANTHROPIC_AUTH_TOKEN: authToken },
+    };
+}
+/**
+ * The credential marker's modification stamp (epoch ms): the endpoint file's
+ * mtime, or undefined when the scope has no file (a config-sourced credential
+ * has no marker — rotating it pairs with the profile edit and instance
+ * restart that clear the in-memory grade marks). A fresh file write is a
+ * fresh stamp, which is how an edited-in key recovers a `rejected` grade.
+ * @param homeDir - the scope's scoped home.
+ * @returns the stamp, or undefined.
+ */
+export async function endpointAuthStamp(homeDir) {
+    try {
+        return (await stat(join(homeDir, ENDPOINT_AUTH_FILE))).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the scope carries its own endpoint file at all. */
+export async function endpointAuthFileExists(homeDir) {
+    return (await endpointAuthStamp(homeDir)) !== undefined;
+}
+/**
+ * Write the scope's endpoint-auth.json (mode 0600, mkdir -p first), the
+ * per-scope provisioning path an evaluation's `conditions provision` (or a
+ * person) uses to give one scope its own credential. Whole-file write: the
+ * payload is exactly what {@link readEndpointAuthFile} parses back.
+ * @param homeDir - the scope's scoped home.
+ * @param auth - the endpoint credential to persist.
+ */
+export async function writeEndpointAuth(homeDir, auth) {
+    await mkdir(homeDir, { recursive: true });
+    const baseUrl = field(auth.baseUrl);
+    const apiKey = field(auth.apiKey);
+    const authToken = field(auth.authToken);
+    const payload = {
+        ...baseUrl === undefined ? {} : { baseUrl },
+        ...apiKey === undefined ? {} : { apiKey },
+        ...authToken === undefined ? {} : { authToken },
+    };
+    await writeFile(join(homeDir, ENDPOINT_AUTH_FILE), JSON.stringify(payload, undefined, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * Clear the scope's OWN endpoint credential (the endpoint-auth.json file).
+ * A deployment-level credential from the plugin config is untouched — the
+ * core's logout reply then names the profile row as the place to edit.
+ * @param homeDir - the scope's scoped home.
+ */
+export async function clearEndpointAuth(homeDir) {
+    await rm(join(homeDir, ENDPOINT_AUTH_FILE), { force: true });
+}
+/** The official endpoint used when no baseUrl is configured anywhere. */
+export const OFFICIAL_BASE_URL = 'https://api.anthropic.com';
+/** How many served model ids the check reply lists before truncating. */
+const CHECK_MODEL_LIST_LIMIT = 8;
+/** Bound on the error-body excerpt a failed check reports. */
+const CHECK_ERROR_BODY_LIMIT = 200;
+/** The effort levels one served-model entry advertises, oldest-first. */
+function servedEfforts(effort) {
+    if (typeof effort !== 'object' || effort === null)
+        return undefined;
+    const levels = ['low', 'medium', 'high', 'xhigh', 'max']
+        .filter(level => effort[level]?.supported === true);
+    return levels.length === 0 ? undefined : levels;
+}
+/**
+ * The effort block's home in a served-model entry. Anthropic's current
+ * /v1/models shape nests it under `capabilities.effort` (verified against the
+ * openproxy relay 2026-10-22: `capabilities.effort.<level>.supported`); the
+ * flat top-level `effort` the parser was written against still wins when
+ * present, so either shape answers.
+ */
+function servedEffortsOf(record) {
+    const direct = servedEfforts(record['effort']);
+    if (direct !== undefined)
+        return direct;
+    const capabilities = record['capabilities'];
+    if (typeof capabilities !== 'object' || capabilities === null)
+        return undefined;
+    return servedEfforts(capabilities['effort']);
+}
+/**
+ * `GET <baseUrl>/v1/models` with the resolved credential's auth header(s) —
+ * the token-free endpoint probe shared by the `/claude-code check` verdict
+ * and the model catalog. Anthropic's own API serves this route with
+ * `x-api-key`; relays (openproxy verified) proxy it and answer the same
+ * shape. Never throws: every failure mode folds into the result.
+ * @param endpoint - the resolved endpoint auth (caller checks the credential).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param signal - abort for the whole probe (timeout bundled by the caller).
+ * @returns the folded result.
+ */
+export async function fetchEndpointModels(endpoint, fetchImpl, signal) {
+    const headers = { 'anthropic-version': '2023-06-01' };
+    if (endpoint.apiKey !== undefined)
+        headers['x-api-key'] = endpoint.apiKey;
+    if (endpoint.authToken !== undefined)
+        headers['authorization'] = `Bearer ${endpoint.authToken}`;
+    const fetcher = fetchImpl ?? globalThis.fetch;
+    const url = `${endpoint.baseUrl.replace(/\/+$/, '')}/v1/models`;
+    let response;
+    try {
+        response = await fetcher(url, { headers, signal: signal ?? AbortSignal.timeout(8_000) });
+    }
+    catch (error) {
+        return { kind: 'unreachable', message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!response.ok) {
+        return { kind: 'http', status: response.status, body: (await response.text().catch(() => '')).slice(0, CHECK_ERROR_BODY_LIMIT) };
+    }
+    let data;
+    try {
+        data = JSON.parse(await response.text()).data;
+    }
+    catch {
+        return { kind: 'malformed' };
+    }
+    if (!Array.isArray(data))
+        return { kind: 'malformed' };
+    const models = [];
+    for (const entry of data) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        if (typeof record.id !== 'string' || record.id === '')
+            continue;
+        const efforts = servedEffortsOf(record);
+        models.push({
+            id: record.id,
+            ...typeof record.display_name === 'string' && record.display_name !== '' ? { displayName: record.display_name } : {},
+            ...efforts === undefined ? {} : { efforts },
+        });
+    }
+    return { kind: 'models', models };
+}
+/**
+ * Probe the resolved endpoint with a cheap, token-free round-trip: `GET
+ * <baseUrl>/v1/models` with the resolved credential's auth header(s). A 200
+ * proves both reachability and credential validity — the exact evidence a
+ * "verify" button needs — and the served model list rides the reply so the
+ * user sees what the endpoint offers (any id can be typed into the model
+ * field by hand). One transport-level retry rides along: a local proxy
+ * restart (a Surge/clash reload) stalls the first attempt into the timeout
+ * and answers the retry immediately. Never throws: every failure mode folds
+ * into the reply text, since the reply IS the diagnostic.
+ * @param endpoint - the resolved endpoint auth (scope file over settings).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param timeoutMs - one attempt's deadline (two attempts at most).
+ * @returns the human-readable verdict for the `/claude-code check` reply.
+ */
+export async function checkClaudeEndpoint(endpoint, fetchImpl, timeoutMs = 20_000) {
+    if (!hasEndpointCredential(endpoint)) {
+        return 'No endpoint credential configured — fill API Key or Auth Token on the settings card (or the profile row) first.';
+    }
+    const baseUrl = (endpoint.baseUrl ?? OFFICIAL_BASE_URL).replace(/\/+$/, '');
+    let result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    if (result.kind === 'unreachable') {
+        result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    }
+    if (result.kind === 'unreachable')
+        return `Endpoint unreachable (${baseUrl}): ${result.message}`;
+    if (result.kind === 'http') {
+        return `Endpoint answered HTTP ${String(result.status)} (${baseUrl})${result.body === '' ? '' : `: ${result.body}`}`;
+    }
+    if (result.kind === 'malformed') {
+        return `Endpoint reachable (${baseUrl}) but the model list did not parse — the credential worked, the reply was not /v1/models-shaped.`;
+    }
+    if (result.models.length === 0)
+        return `Endpoint reachable (${baseUrl}); it serves no models.`;
+    const ids = result.models.map(model => model.id);
+    const listed = ids.slice(0, CHECK_MODEL_LIST_LIMIT).join(', ');
+    const more = ids.length > CHECK_MODEL_LIST_LIMIT ? `, … +${String(ids.length - CHECK_MODEL_LIST_LIMIT)} more` : '';
+    return `Endpoint reachable (${baseUrl}): ${String(ids.length)} model(s) served — ${listed}${more}`;
+}

package/lib/types/index.d.ts

@@ -1,13 +1,13 @@
 /**
  * Claude Code harness instantiation of the local-agent family. Registers the
  * `claude-code` harness into the core registry: scoped home under the shared
- * homes root (`CLAUDE_CONFIG_DIR`), login as a manual handoff (claude ≥2.1
- * prints no OAuth URL off a TTY, so `/login` replies with the exact terminal
- * command and the registry watches for the credential), and project-file
- * session records. Delegation mounts through the `claude-local` provider
- * (one-shot `claude -p --output-format json` under the scoped home); the
- * bundle patch's `tool-subagent-claude-code-local` row puts the tool on the
- * profile root, so every agent preset can delegate.
+ * homes root (`CLAUDE_CONFIG_DIR`), endpoint-key authentication (the scope's
+ * `endpoint-auth.json` over the plugin config's `baseUrl`/`apiKey`/
+ * `authToken` triple — no OAuth, no browser flow, nothing to authorize inside
+ * a container), and project-file session records. Delegation mounts through
+ * the `claude-local` provider (one-shot `claude -p` under the scoped home);
+ * the bundle patch's `tool-subagent-claude-code-local` row puts the tool on
+ * the profile root, so every agent preset can delegate.
  *
  * @module @khorsheed/dsh-local-agent-claude-code
  */
@@ -17,7 +17,7 @@ import z from '@deepseek-ai/schemastery';
 export declare const name = "local-agent-claude-code";
 /** Services required before the harness can register. */
 export declare const inject: string[];
-/** Plugin config: the permission mode fresh delegations default to, plus the live driver. */
+/** Plugin config: the permission mode fresh delegations default to, the endpoint credential, plus the live driver. */
 export interface Config {
     /**
      * `claude -p` permission handling; `skip` passes
@@ -36,17 +36,33 @@ export interface Config {
      */
     model?: string;
     /**
-     * `ANTHROPIC_BASE_URL` for the child CLI; absent inherits the host
-     * process environment (a user-level proxy like `https://proxy.example.com/anthropic`
-     * is typically exported there). Set when delegations must route through a
-     * different endpoint than the login flow used.
+     * The deployment-level endpoint: `ANTHROPIC_BASE_URL` for every delegation
+     * (e.g. a relay like `https://openproxy.to/claude`, or absent for the
+     * official API). A scope's own `endpoint-auth.json` overrides it field by
+     * field — the settings card's credential form edits THAT file (never the
+     * profile). See endpoint-auth.ts for the whole auth model — there is no
+     * OAuth path in this package.
      */
     baseUrl?: string;
     /**
-     * HTTP proxy for the child CLI's own traffic (model calls AND OAuth
-     * refresh), provisioned into the scoped `settings.json` env block. Needed
-     * when the host process environment carries no proxy (a supervisor-spawned
-     * instance does not inherit the user's shell exports).
+     * The deployment-level credential, sent as `ANTHROPIC_API_KEY` (the
+     * `x-api-key` header). Keep it in the LOCAL profile row only — never commit
+     * it (the repo hygiene gate blocks credential-shaped strings, but the
+     * profile is not the repo's business).
+     */
+    apiKey?: string;
+    /**
+     * The deployment-level credential, sent as `ANTHROPIC_AUTH_TOKEN` (the
+     * `Authorization: Bearer` header) — some relays expect Bearer instead of
+     * `x-api-key`. When both keys are set the CLI's own precedence applies.
+     */
+    authToken?: string;
+    /**
+     * HTTP proxy for the child CLI's own traffic, provisioned into the scoped
+     * `settings.json` env block. Needed when the host process environment
+     * carries no proxy (a supervisor-spawned instance does not inherit the
+     * user's shell exports). Distinct from {@link baseUrl}: this is a local
+     * traffic forwarder, not the model endpoint.
      */
     proxyUrl?: string;
     /**