@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
183 lines (170 loc) • 8.98 kB
text/typescript
/**
* The hub-state contract shared by `GET|HEAD /v1/hub-state` and every connected client.
*
* Why it exists (#4236): an agent working on a connected client machine read that machine's
* own `~/.opencodex/config.json` and `ocx status`, saw `xai ✗ not logged in`, no grok provider
* and five delegable models, and concluded the hub could not serve grok — while the hub had
* xAI logged in and was serving grok all along. A client's local credential store is empty BY
* DESIGN, so reporting it as the truth is not a cosmetic defect: it makes the client lie about
* the only machine that has the facts.
*
* What may cross this boundary is deliberately narrow. The client holds a per-client DATA key
* and no management credential, so this is a least-privilege data-plane read in the `/v1/catalog`
* (#809) tradition rather than a widened `/api/*` boundary. The payload is BOOLEANS and model
* ids: `hasCredential` is the same `!!p.apiKey` projection `GET /api/providers` already ships,
* and `loggedIn` is `oauthLoginSummary`'s boolean with the email and account id dropped
* entirely. No keys, no tokens, no quotas, no usage, no account identity — and nothing of that
* shape may be added later, because this surface is reachable with a data key.
*
* The delta over `/v1/catalog`, stated exactly, because "only two booleans" was wrong and a
* wrong boundary claim is worse than none. Provider names already leak through `/v1/catalog`
* slugs and `/v1/models` ids, but only for providers those routes list. What this route adds is:
* `hasCredential`, `loggedIn`, `authMode`, the featured roster — and the NAME and adapter of an
* ENABLED provider that the catalog omits for want of a usable credential. That last one is the
* point of the route (a client has to be able to say "the hub has xai configured and has no key
* for it" rather than "the hub cannot serve grok"), and it is the whole widening.
*
* A provider the operator marked `disabled` is NOT exported — see `src/server/hub-state.ts`.
* Naming it would tell a data-key holder about a provider no other data-plane route mentions,
* and a client has no use for it: it is not routable, so "absent" is the truthful report.
*/
export const HUB_STATE_SCHEMA_VERSION = 1;
/** Hard caps, so the serialized body is bounded by construction rather than by hope. */
export const MAX_HUB_STATE_PROVIDERS = 200;
export const MAX_HUB_STATE_SUBAGENT_MODELS = 32;
export const MAX_HUB_STATE_OAUTH_PROVIDERS = 200;
export const MAX_HUB_STATE_STRING_CHARS = 200;
/** Response/transfer ceiling. The caps above keep a realistic body two orders below this. */
export const MAX_HUB_STATE_BYTES = 64 * 1024;
/**
* Mirrors `OcxProviderConfig.authMode` (src/types/provider.ts); default `"key"`.
*
* It is shape, not secret: it says HOW a provider authenticates, which is what lets a client
* explain `hasCredential: false` on an `oauth` provider without claiming nothing is configured.
*/
export const HUB_STATE_AUTH_MODES = ["key", "forward", "oauth", "local"] as const;
export type HubStateAuthMode = (typeof HUB_STATE_AUTH_MODES)[number] | null;
export interface HubStateProvider {
name: string;
adapter: string;
authMode: HubStateAuthMode;
/** Presence only — the same `!!p.apiKey` projection `GET /api/providers` ships. */
hasCredential: boolean;
/**
* Always `false` from a hub of this version, which does not export a disabled provider at all.
* The field stays in the contract because an OLDER hub does send `true`, and a client reading
* one must still be able to label the row rather than present it as routable.
*/
disabled: boolean;
}
export interface HubStateOAuthEntry {
provider: string;
/** `oauthLoginSummary().loggedIn`. The email and account id are dropped, not masked. */
loggedIn: boolean;
}
export interface HubStateDTO {
schemaVersion: typeof HUB_STATE_SCHEMA_VERSION;
/** Always "hub": the route 404s on any other role, so a client can trust what it reads. */
runtimeRole: "hub";
hubVersion: string;
/** `hub.dataPublicOrigin` when the operator set one; null rather than a guess. */
origin: string | null;
providers: HubStateProvider[];
oauth: HubStateOAuthEntry[];
/** The hub's effective featured subagent roster — what a client should delegate to. */
subagentModels: string[];
/**
* At least one row was dropped to fit a cap above, so the arrays are a prefix rather than the
* whole truth. Silent truncation is what this flag exists to prevent: a client that lists 200
* of 240 providers and says nothing has told the reader the other 40 do not exist, which is
* the same class of confident-and-wrong report #4236 is about.
*/
truncated: boolean;
claudeCode: { enabled: boolean };
}
function boundedString(value: unknown, max = MAX_HUB_STATE_STRING_CHARS): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
if (!trimmed || trimmed.length > max || /[\x00-\x1f\x7f]/.test(trimmed)) return null;
return trimmed;
}
/**
* Validate a hub-state body received over the wire.
*
* Returns null instead of throwing so both the live fetch and the on-disk cache can reject a
* malformed document the same way, and so a client NEVER degrades to its own local login state
* on a shape it does not recognize — degrading quietly is the defect being fixed.
*
* Unknown keys are dropped rather than refused: a newer hub must be readable by an older
* client, and the fields this projection reads are all required.
*/
export function parseHubStateBody(value: unknown): HubStateDTO | null {
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
const raw = value as Record<string, unknown>;
if (raw.schemaVersion !== HUB_STATE_SCHEMA_VERSION) return null;
if (raw.runtimeRole !== "hub") return null;
const hubVersion = boundedString(raw.hubVersion, 64);
if (!hubVersion) return null;
const origin = raw.origin === null || raw.origin === undefined ? null : boundedString(raw.origin, 512);
if (raw.origin !== null && raw.origin !== undefined && origin === null) return null;
if (!Array.isArray(raw.providers) || raw.providers.length > MAX_HUB_STATE_PROVIDERS) return null;
if (!Array.isArray(raw.oauth) || raw.oauth.length > MAX_HUB_STATE_OAUTH_PROVIDERS) return null;
if (!Array.isArray(raw.subagentModels) || raw.subagentModels.length > MAX_HUB_STATE_SUBAGENT_MODELS) return null;
const claudeCode = raw.claudeCode;
if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) return null;
const enabled = (claudeCode as Record<string, unknown>).enabled;
if (typeof enabled !== "boolean") return null;
// Absent means false: a hub that predates the flag truncated nothing this client can detect,
// and refusing its document would turn a new honesty field into a compatibility break. A
// present non-boolean is still refused, like every other field here.
if (raw.truncated !== undefined && typeof raw.truncated !== "boolean") return null;
const truncated = raw.truncated === true;
const providers: HubStateProvider[] = [];
for (const row of raw.providers) {
if (!row || typeof row !== "object" || Array.isArray(row)) return null;
const entry = row as Record<string, unknown>;
const name = boundedString(entry.name);
const adapter = boundedString(entry.adapter);
if (!name || !adapter) return null;
if (typeof entry.hasCredential !== "boolean" || typeof entry.disabled !== "boolean") return null;
const authMode = entry.authMode;
const normalizedAuthMode = typeof authMode === "string" && (HUB_STATE_AUTH_MODES as readonly string[]).includes(authMode)
? authMode as NonNullable<HubStateAuthMode>
: null;
// An unrecognized authMode is refused rather than nulled: nulling it would let a newer hub's
// new mode read as "unset", which is a different claim about the provider.
if (authMode !== null && authMode !== undefined && normalizedAuthMode === null) return null;
providers.push({
name,
adapter,
authMode: normalizedAuthMode,
hasCredential: entry.hasCredential,
disabled: entry.disabled,
});
}
const oauth: HubStateOAuthEntry[] = [];
for (const row of raw.oauth) {
if (!row || typeof row !== "object" || Array.isArray(row)) return null;
const entry = row as Record<string, unknown>;
const provider = boundedString(entry.provider);
if (!provider || typeof entry.loggedIn !== "boolean") return null;
oauth.push({ provider, loggedIn: entry.loggedIn });
}
const subagentModels: string[] = [];
for (const row of raw.subagentModels) {
const model = boundedString(row);
if (!model) return null;
subagentModels.push(model);
}
return {
schemaVersion: HUB_STATE_SCHEMA_VERSION,
runtimeRole: "hub",
hubVersion,
origin,
providers,
oauth,
subagentModels,
truncated,
claudeCode: { enabled },
};
}