@quantiya/codevibe-core 2.0.1 → 2.0.2

package/dist/credential-broker/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The vendor providers Rung 1 brokers. Claude + Codex (Anthropic +
+ * OpenAI) only — Gemini stays out of the substrate (§6 Q4, agy is
+ * reduced-trust).
+ */
+export type VendorProvider = "anthropic" | "openai";
+/** A route the broker serves. */
+export type BrokerRouteMethod = "POST" | "GET";
+/**
+ * The locked broker route table (§3.2). Declared as data-shape types so
+ * the W1 gateway and any conformance test agree on the surface without
+ * a contract reopen.
+ */
+export interface BrokerRoute {
+    method: BrokerRouteMethod;
+    path: "/v1/messages" | "/v1/responses" | "/healthz";
+    /** Whether the route requires a valid agent→broker token. */
+    auth: "broker_token" | "none";
+}
+/**
+ * The broker's locked route table — exactly three routes (§3.2). Any
+ * other method+path → 403.
+ */
+export declare const BROKER_ROUTES: readonly BrokerRoute[];
+/**
+ * The broker's HTTP status taxonomy (§3.2 + §3.2 upstream-auth note).
+ * Declared as a typed enum so the W1 gateway and reviewers share one
+ * source of truth for the fail-closed status mapping.
+ */
+export type BrokerStatus = 200 | 400 | 401 | 403 | 502 | 503;
+/**
+ * An inbound request to the broker. `method`/`path` are **raw HTTP
+ * strings**, deliberately NOT narrowed to `BROKER_ROUTES` (Codex W0 R1):
+ * the §3.2 contract is "everything else → 403", so the type MUST be able
+ * to represent a *disallowed* route for the W1 gateway's `handle()` to be
+ * conformance-testable (send `/v1/admin` / `DELETE` → assert 403). Only
+ * the three `(method, path)` pairs in `BROKER_ROUTES` are forwarded; every
+ * other request fails closed at 403.
+ */
+export interface BrokerRequest {
+    method: string;
+    path: string;
+    /** Opaque short-lived agent→broker token (§3.3); absent for `/healthz`. */
+    brokerToken?: string;
+    /** Model-bound JSON body (the only carried-through surface, §3.4). */
+    body?: unknown;
+    /**
+     * Agent-supplied headers (lowercased keys), if the transport surfaced
+     * any. The §3.4 canonical constructor DROPS all of them except an
+     * exact-allowlist beta token; carried on the wire type so `handle()`'s
+     * canonicalization is conformance-testable (assert the agent's
+     * `authorization` / `x-api-key` / unknown headers do not reach upstream).
+     */
+    agentHeaders?: Readonly<Record<string, string>>;
+    /** Agent-supplied query params, if any. ALL are dropped (§3.4). */
+    agentQuery?: Readonly<Record<string, string>>;
+    /** Agent-declared content type, if surfaced. Non-JSON → 400 (§3.4). */
+    agentContentType?: string;
+}
+/** Response from a broker model-gateway route. */
+export interface BrokerResponse {
+    status: BrokerStatus;
+    /** Upstream model-bound JSON body on 200; an error envelope otherwise. */
+    body?: unknown;
+}
+/**
+ * The lifecycle surface of the per-session local broker daemon (§3.2).
+ * The LE starts one broker per session on `127.0.0.1:<ephemeral>` and
+ * tears it down at session end. Signatures only in W0.
+ */
+export interface ModelGatewayBroker {
+    /** Start listening on an ephemeral loopback port; resolve the bound addr. */
+    start(): Promise<{
+        hostBrokerAddr: string;
+    }>;
+    /** Liveness — the LE waits for this before launching the agent. */
+    healthz(): Promise<boolean>;
+    /** Handle one model-gateway request (the §3.2 route surface). */
+    handle(req: BrokerRequest): Promise<BrokerResponse>;
+    /** Tear down; zeroize the in-process upstream credential (§3.3). */
+    stop(): Promise<void>;
+}
+/**
+ * The provider-scoped vendor-key storage API (§3.3) — [NEW], owner W1.
+ * Reuses the existing keychain backend (OS keyring + file fallback).
+ * Signatures only in W0; the implementation (keychain accounts
+ * `vendor-key-<provider>`) lands in W1.
+ */
+export interface VendorKeyStore {
+    /**
+     * Read the user's vendor key for `provider` from the keychain. Returns
+     * `null` when no key is present — the broker then fails closed (503),
+     * NEVER a silent fallback to an ambient `ANTHROPIC_API_KEY` /
+     * `OPENAI_API_KEY` (that would re-introduce the I1 ambient-cred path).
+     */
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    /** Persist the user's vendor key for `provider` (one-time setup step). */
+    setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+}
+/**
+ * The agent→broker token (§3.3): per-session, broker-minted, opaque,
+ * short-lived. Authenticates the agent to the LOCAL broker only — it is
+ * NOT a vendor credential.
+ */
+export interface BrokerToken {
+    /** Opaque token value emitted to the agent's apiKeyHelper / `[auth]` hook. */
+    readonly value: string;
+    /** Epoch-ms expiry; the helper refreshes on expiry / on a broker 401. */
+    readonly expiresAtMs: number;
+}
+/**
+ * The result of a broker→vendor upstream call. The broker maps upstream
+ * status to the agent-facing `BrokerStatus` (§3.2): an upstream 401/403
+ * (bad/expired vendor key) → 502 (NOT a pass-through), every other status
+ * carries through.
+ */
+export interface UpstreamResponse {
+    /** Raw upstream HTTP status. */
+    status: number;
+    /** Parsed JSON body (model-bound). */
+    body?: unknown;
+}
+/**
+ * The broker→vendor upstream HTTP client (§3.3/§3.4). INJECTED so W1 tests
+ * use a stub (no real network). The real fetch-backed client lands when
+ * the broker is wired into the LE; W1 only depends on this interface.
+ */
+export interface UpstreamClient {
+    /**
+     * POST the canonical request upstream. `headers` already includes the
+     * synthesized vendor/version headers AND the injected upstream
+     * credential (the caller adds the credential header). Resolves with the
+     * upstream status + body; rejects only on a transport/network error
+     * (which the broker maps to its forward-error path).
+     */
+    post(args: {
+        url: string;
+        headers: Readonly<Record<string, string>>;
+        body: unknown;
+    }): Promise<UpstreamResponse>;
+}

package/dist/credential-broker/upstream-client.d.ts

@@ -0,0 +1,20 @@
+import type { UpstreamClient, UpstreamResponse } from "./types";
+/**
+ * The production fetch-backed {@link UpstreamClient}. Constructed once per
+ * broker session by the LE and injected into `LocalModelGatewayBroker`
+ * (replacing the W1 stub).
+ */
+export declare class FetchUpstreamClient implements UpstreamClient {
+    private readonly opts;
+    constructor(opts?: {
+        /** Injectable for tests (default: global `fetch`). */
+        fetchFn?: typeof fetch;
+        /** Per-request timeout (ms). */
+        timeoutMs?: number;
+    });
+    post(args: {
+        url: string;
+        headers: Readonly<Record<string, string>>;
+        body: unknown;
+    }): Promise<UpstreamResponse>;
+}

package/dist/credential-broker/vendor-key-store.d.ts

@@ -0,0 +1,54 @@
+import type { VendorKeyStore, VendorProvider } from "./types";
+/**
+ * Keychain-backed implementation of {@link VendorKeyStore} (§3.3). Reads
+ * the same keychain service the rest of CodeVibe uses (`getConfig()
+ * .keychain.serviceName`) so vendor keys live alongside the existing
+ * device identity + OAuth tokens under one auditable backend.
+ *
+ * r5 HIGH-1 / r6 HIGH-2 (Codex): unlike the OAuth-token storage, the vendor
+ * key is KEYCHAIN-ONLY at rest for BOTH read and write — `setVendorKey`
+ * (write) and `getVendorKey` (read) BOTH require the real OS keychain and
+ * FAIL CLOSED rather than touch the plaintext file backend (see the two
+ * methods + file header). The agent can never REACH the key at runtime on any
+ * substrate (A1 never mounts `~/.codevibe`; A5 denies it in the Seatbelt
+ * profile).
+ */
+export declare class KeychainVendorKeyStore implements VendorKeyStore {
+    private get serviceName();
+    /**
+     * Read the user's vendor key from the keychain. Returns `null` when no
+     * key is present (the broker fails closed — 503). Backend errors
+     * (keyring unavailable, corrupted store) propagate to the caller, same
+     * as `KeychainManager.getTokens` — a hard config failure the user must
+     * see, NOT a silent "no key" that would mask a broken keychain.
+     *
+     * NO ambient-env fallback (I1): a missing key is `null`, full stop.
+     *
+     * r6 HIGH-2 (Codex): KEYCHAIN-ONLY on the READ side too. We require the real
+     * OS keychain (`getActiveBackendKind() === 'keytar'`) BEFORE reading. On the
+     * FILE backend we FAIL CLOSED by returning `null` (the broker then fails
+     * closed — 503) and DO NOT read `~/.codevibe/<service>.json` — so a legacy /
+     * manually-placed PLAINTEXT vendor key is never sourced from the file store.
+     * On a file-backend (headless Linux) box the user supplies the vendor key
+     * per-session into broker memory (the documented open item — see file header).
+     * SCOPED to the vendor key — the shared backend's OAuth-token file fallback
+     * (#29) is untouched (we only call the read-only `getActiveBackendKind`).
+     */
+    getVendorKey(provider: VendorProvider): Promise<string | null>;
+    /**
+     * Persist the user's vendor key (one-time setup step). The plaintext
+     * value is never logged.
+     *
+     * r5 HIGH-1 (Codex): FAIL CLOSED if only the FILE backend is available —
+     * the broker refuses to write a PLAINTEXT vendor key to
+     * `~/.codevibe/<service>.json`. We prefer the REAL OS keychain; if it is
+     * unavailable (the file backend is active), we throw rather than silently
+     * persisting the key in plaintext (which would break the keychain-only
+     * at-rest invariant). This is SCOPED to the vendor key — the shared
+     * backend's OAuth-token file fallback (#29) is untouched. r6 HIGH-2: the READ
+     * side (`getVendorKey`) is now gated the SAME way (returns `null` on the file
+     * backend, no plaintext read); on a fail-closed box the user supplies the key
+     * per-session into broker memory.
+     */
+    setVendorKey(provider: VendorProvider, key: string): Promise<void>;
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { CryptoService, cryptoService, CryptoError, ENCRYPTION_VERSION } from '.
 export { AppSyncClient, AppSyncGraphQLError, DownloadUrlResponse } from './appsync';
 export { queries, mutations, subscriptions } from './appsync';
 export { AuthService, authService } from './auth';
+export { bindOAuthServer, PRIMARY_PORT, PORT_RANGE_SIZE } from './auth';
 export { runAuthCli } from './auth';
 export { fireAuthCompletedBeacon, fireAuthFailedBeacon, markErrorBeaconed, errorWasBeaconed, getErrorReason, } from './auth';
 export type { AuthFailureReason, AuthStage } from './auth';
@@ -11,14 +12,18 @@ export type { Config, Environment } from './config';
 export { Logger, logger, createLogger } from './logger';
 export { parseInteractivePrompt, normalizeSnapshot, } from './prompt-parser';
 export type { ParsedInteractivePrompt, PromptKind, InteractivePromptOption, } from './prompt-parser';
-export { resumeOrCreateSession, prepareSessionEncryption, rekeySessionForNewDevices, startDeviceKeyWatcher, registerDeviceEncryptionKey, } from './session';
+export { resumeOrCreateSession, prepareSessionEncryption, rekeySessionForNewDevices, startDeviceKeyWatcher, registerDeviceEncryptionKey, prepareEventTimestamp, _resetPrepareEventTimestampForTesting, } from './session';
 export type { ResumeOrCreateSessionInput, ResumeOrCreateSessionResult } from './session';
 export { detectInstalledAgents, pushDetectedAgents, applyPerSessionOrchestrationOverride, runOrchestrationCli, V1_ORCHESTRATION_PROMPT_KIND, V1_ORCHESTRATION_OPTIONS, mapOptionNumberToUserDecisionKind, mapOptionToUserDecisionKind, } from './orchestration';
 export type { DetectableAgent, V1OrchestrationOption, V1UserDecisionKind, } from './orchestration';
 export * as Reviewer from './reviewer';
 export * as AuditKeys from './audit-keys';
+export * as Substrate from './substrate';
+export * as CredentialBroker from './credential-broker';
+export * as SubstrateLaunch from './substrate-launch';
 export * from './types';
 export * as Planner from './planner';
+export * as Continuation from './continuation';
 export * as StructuralSummary from './structural-summary';
 export { runOrchestrationShell } from './orchestration-shell';
 export { runCompanionMode } from './companion-mode';