aigetwey 1.0.1

package/src/core/authStore.ts

@@ -0,0 +1,86 @@
+/**
+ * Admin password store — the single source of truth for the admin password,
+ * persisted as a scrypt hash (no plaintext, no native deps). Seeded once from
+ * AIGETWEY_ADMIN_PASSWORD (default 123456 via the launcher); after that it is
+ * changed at runtime from the dashboard and the env var is only a fallback seed.
+ *
+ * File: <dataDir>/auth.json — { algo, salt, hash } (all hex). Absent → seeded.
+ */
+import { scryptSync, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+interface AuthRecord {
+  algo: "scrypt";
+  salt: string;
+  hash: string;
+}
+
+function hashPassword(password: string, salt: Buffer): Buffer {
+  // 64-byte derived key; scrypt's default cost is fine for a local admin gate.
+  return scryptSync(password, salt, 64);
+}
+
+function makeRecord(password: string): AuthRecord {
+  const salt = randomBytes(16);
+  return { algo: "scrypt", salt: salt.toString("hex"), hash: hashPassword(password, salt).toString("hex") };
+}
+
+export class AuthStore {
+  private record: AuthRecord | null = null;
+
+  constructor(private file: string) {}
+
+  /** Load the stored hash, seeding it from `seed` (the env password) on first run. */
+  static open(dataDir: string, seed: string | undefined): AuthStore {
+    const store = new AuthStore(join(dataDir, "auth.json"));
+    if (existsSync(store.file)) {
+      try {
+        store.record = JSON.parse(readFileSync(store.file, "utf8")) as AuthRecord;
+      } catch {
+        store.record = null;
+      }
+    }
+    // seed from the env password when there's nothing stored yet.
+    if (!store.record && seed) store.persist(makeRecord(seed));
+    return store;
+  }
+
+  /** In-memory store seeded from a password — for tests (file under tmpdir). */
+  static memory(seed: string): AuthStore {
+    const store = new AuthStore(join(tmpdir(), `aigetwey-auth-${randomBytes(4).toString("hex")}.json`));
+    store.record = makeRecord(seed);
+    return store;
+  }
+
+  /** True once a password is set (stored or seeded). */
+  get enabled(): boolean {
+    return this.record !== null;
+  }
+
+  private persist(rec: AuthRecord): void {
+    mkdirSync(dirname(this.file), { recursive: true });
+    writeFileSync(this.file, JSON.stringify(rec));
+    this.record = rec;
+  }
+
+  /** Constant-time check of a presented password against the stored hash. */
+  verify(password: string): boolean {
+    if (!this.record) return false;
+    const salt = Buffer.from(this.record.salt, "hex");
+    const expected = Buffer.from(this.record.hash, "hex");
+    const got = hashPassword(password, salt);
+    return got.length === expected.length && timingSafeEqual(got, expected);
+  }
+
+  /** Change the password after verifying the current one. */
+  change(current: string, next: string): { ok: boolean; error?: string } {
+    if (!this.verify(current)) return { ok: false, error: "current password is incorrect" };
+    if (typeof next !== "string" || next.length < 4) {
+      return { ok: false, error: "new password must be at least 4 characters" };
+    }
+    this.persist(makeRecord(next));
+    return { ok: true };
+  }
+}

package/src/core/canonical.ts

@@ -0,0 +1,93 @@
+/**
+ * Canonical message format = OpenAI Chat Completions shape.
+ *
+ * Every ingress format is translated INTO this shape, and every provider format
+ * is translated OUT of it. Picking OpenAI as the pivot makes a new provider cost
+ * one adapter (N adapters) instead of N×N pairwise translators.
+ */
+
+export type Role = "system" | "user" | "assistant" | "tool";
+
+export interface CanonicalTextPart {
+  type: "text";
+  text: string;
+}
+
+export interface CanonicalImagePart {
+  type: "image_url";
+  image_url: { url: string };
+}
+
+export type CanonicalContentPart = CanonicalTextPart | CanonicalImagePart;
+
+export interface CanonicalToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    /** raw JSON string of args, exactly as OpenAI emits it */
+    arguments: string;
+  };
+}
+
+export interface CanonicalMessage {
+  role: Role;
+  /** string for simple text, multi-part array for mixed content, or null */
+  content: string | CanonicalContentPart[] | null;
+  /** assistant turns that call tools */
+  tool_calls?: CanonicalToolCall[];
+  /** present on role="tool" messages, links back to a tool_call id */
+  tool_call_id?: string;
+  /** tool/function name on tool messages */
+  name?: string;
+}
+
+export interface CanonicalToolDef {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+
+export interface CanonicalRequest {
+  model: string;
+  messages: CanonicalMessage[];
+  stream?: boolean;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stop?: string | string[];
+  tools?: CanonicalToolDef[];
+  tool_choice?: unknown;
+  /** anything else passes through untouched */
+  [k: string]: unknown;
+}
+
+export interface CanonicalUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  /** cached input tokens, normalized across providers */
+  cached_tokens?: number;
+  cache_creation_tokens?: number;
+  reasoning_tokens?: number;
+}
+
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;
+
+export interface CanonicalResponse {
+  id: string;
+  model: string;
+  created: number;
+  choices: Array<{
+    index: number;
+    message: CanonicalMessage;
+    finish_reason: FinishReason;
+  }>;
+  usage?: CanonicalUsage;
+}
+
+/** Wire format spoken by a provider or expected by a client. */
+export type WireFormat = "openai" | "anthropic" | "gemini";

package/src/core/console-buffer.ts

@@ -0,0 +1,39 @@
+type LogLevel = "LOG" | "INFO" | "WARN" | "ERROR" | "DEBUG";
+
+interface LogEntry {
+  ts: number;
+  level: LogLevel;
+  message: string;
+}
+
+type Listener = (entry: LogEntry) => void;
+
+const MAX_ENTRIES = 500;
+
+class ConsoleBuffer {
+  private entries: LogEntry[] = [];
+  private listeners = new Set<Listener>();
+
+  push(level: LogLevel, message: string): void {
+    const entry: LogEntry = { ts: Date.now(), level, message };
+    this.entries.push(entry);
+    if (this.entries.length > MAX_ENTRIES) this.entries.shift();
+    for (const fn of this.listeners) fn(entry);
+  }
+
+  recent(): LogEntry[] {
+    return this.entries.slice();
+  }
+
+  subscribe(fn: Listener): () => void {
+    this.listeners.add(fn);
+    return () => { this.listeners.delete(fn); };
+  }
+
+  clear(): void {
+    this.entries = [];
+  }
+}
+
+export const consoleBuffer = new ConsoleBuffer();
+export type { LogEntry, LogLevel };

package/src/core/fallback.ts

@@ -0,0 +1,116 @@
+/**
+ * Fallback engine. Walks a prioritized chain of routes, rotating keys within
+ * each provider, until one succeeds or the chain is exhausted.
+ *
+ * Streaming note: callUpstream() throws BEFORE returning a stream when the
+ * upstream status is >= 400, so the commit point is a 200 response. A failure
+ * mid-stream surfaces later during body iteration (in the handler), which we
+ * deliberately do NOT retry — fail clean, no duplicate output.
+ */
+import type { ResolvedRoute } from "../config.js";
+import type { CanonicalRequest } from "./canonical.js";
+import type { ThinkingConfig } from "../translator/thinkingUnified.js";
+import type { KeyPool } from "./keypool.js";
+import {
+  callUpstream,
+  type NonStreamResult,
+  type StreamResult,
+  type UpstreamError,
+} from "../upstream/client.js";
+
+export interface AttemptLog {
+  provider: string;
+  model: string;
+  status?: number;
+  outcome: "success" | "retry" | "fallback" | "fatal" | "skip";
+  detail?: string;
+}
+
+export interface FallbackOpts {
+  stream: boolean;
+  signal?: AbortSignal;
+  onAttempt?: (log: AttemptLog) => void;
+  /** which key the pool handed out for the winning attempt (handler uses it for usage). */
+  onServed?: (route: ResolvedRoute, key: string) => void;
+  /** when set, a provider this returns true for is skipped (quota exhausted). */
+  isExhausted?: (provider: ResolvedRoute["provider"]) => boolean;
+  /** captured client thinking intent, applied per-attempt in the provider's format. */
+  thinkingIntent?: ThinkingConfig | null;
+}
+
+export interface FallbackResult {
+  /** the route that actually served the request (for response translation) */
+  route: ResolvedRoute;
+  result: NonStreamResult | StreamResult;
+}
+
+export async function executeWithFallback(
+  routes: ResolvedRoute[],
+  pool: KeyPool,
+  req: CanonicalRequest,
+  opts: FallbackOpts,
+): Promise<FallbackResult> {
+  let lastError: UpstreamError | undefined;
+  const log = opts.onAttempt ?? (() => {});
+
+  for (const route of routes) {
+    const { provider } = route;
+
+    // skip a provider whose token budget is spent for this window — like a key
+    // cooling down, but for the whole provider. Falls through to the next route.
+    if (opts.isExhausted?.(provider)) {
+      log({ provider: provider.id, model: route.model, outcome: "skip", detail: "quota exhausted" });
+      continue;
+    }
+
+    const attempts = provider.max_retries + 1;
+
+    for (let i = 0; i < attempts; i++) {
+      const key = pool.pick(provider);
+      if (key === null) {
+        // every key for this provider is cooling down
+        log({ provider: provider.id, model: route.model, outcome: "skip", detail: "all keys cooling down" });
+        break;
+      }
+
+      try {
+        const result = await callUpstream(provider, req, route.model, {
+          stream: opts.stream,
+          key,
+          signal: opts.signal,
+          thinkingIntent: opts.thinkingIntent,
+        });
+        pool.success(provider, key);
+        opts.onServed?.(route, key);
+        log({ provider: provider.id, model: route.model, status: 200, outcome: "success" });
+        return { route, result };
+      } catch (e) {
+        const err = e as UpstreamError;
+        lastError = err;
+
+        if (!err.retryable) {
+          // the request itself is bad — falling back won't help
+          log({ provider: provider.id, model: route.model, status: err.status, outcome: "fatal" });
+          throw err;
+        }
+
+        pool.penalize(provider, key, { message: err.message ?? `HTTP ${err.status}`, status: err.status });
+        const moreKeysHere = i < attempts - 1 && pool.hasAvailable(provider);
+        log({
+          provider: provider.id,
+          model: route.model,
+          status: err.status,
+          outcome: moreKeysHere ? "retry" : "fallback",
+        });
+        if (!moreKeysHere) break; // move to the next provider in the chain
+      }
+    }
+  }
+
+  // chain exhausted
+  if (lastError) throw lastError;
+  const err = new Error("no available provider for this model") as UpstreamError;
+  err.status = 503;
+  err.retryable = false;
+  throw err;
+}

package/src/core/handler.ts

@@ -0,0 +1,236 @@
+/**
+ * Core request pipeline, independent of which client endpoint was hit.
+ *
+ *   client body (clientFormat)
+ *     -> ingress adapter        -> canonical request
+ *     -> config.resolve(model)  -> prioritized provider chain + upstream model
+ *     -> fallback engine        -> rotate keys, walk the chain until one serves
+ *     -> provider reply         -> canonical -> egress adapter -> client body
+ *
+ * Streaming (Phase 3): provider SSE -> canonical chunks -> client SSE. Fallback
+ * + key rotation (Phase 4) run here. RTK compression + caveman/ponytail
+ * injection (Phase 6) transform the request before routing; usage logging
+ * (Phase 5) records each served request.
+ */
+import type { GatewayConfig, ResolvedRoute } from "../config.js";
+import type { WireFormat, CanonicalUsage } from "./canonical.js";
+import { adapterFor } from "../adapters/index.js";
+import type { UpstreamError } from "../upstream/client.js";
+import { parseSSE, encodeSSE } from "../stream/sse.js";
+import { streamAdapterFor } from "../stream/index.js";
+import type { CanonicalChunk } from "../stream/chunk.js";
+import type { KeyPool } from "./keypool.js";
+import type { QuotaTracker } from "./quota.js";
+import { executeWithFallback } from "./fallback.js";
+import { type UsageDB, computeCost } from "../db.js";
+import { compressMessages } from "../rtk/index.js";
+import { injectInto } from "../inject/index.js";
+import { parseSuffix, captureThinking, type ThinkingConfig } from "../translator/thinkingUnified.js";
+import { compressWithHeadroom, formatHeadroomLog } from "../headroom/compress.js";
+import { getPricingForModel } from "../providers/pricing.js";
+
+export interface HandleResult {
+  status: number;
+  /** non-streaming JSON reply */
+  json?: unknown;
+  /** streaming reply: an async iterable of SSE bytes */
+  sse?: AsyncIterable<Uint8Array>;
+}
+
+export class GatewayError extends Error {
+  constructor(
+    readonly status: number,
+    readonly payload: unknown,
+  ) {
+    super(typeof payload === "string" ? payload : JSON.stringify(payload));
+  }
+}
+
+export interface HandleDeps {
+  config: GatewayConfig;
+  pool: KeyPool;
+  db?: UsageDB;
+  quota?: QuotaTracker;
+  log?: (msg: string) => void;
+  now?: () => number;
+}
+
+function recordUsage(
+  deps: HandleDeps,
+  route: ResolvedRoute,
+  usage: CanonicalUsage | undefined,
+  status: number,
+  latencyMs: number,
+  stream: boolean,
+): void {
+  const tokensIn = usage?.prompt_tokens ?? 0;
+  const tokensOut = usage?.completion_tokens ?? 0;
+  // count the full request against the served provider's window budget.
+  deps.quota?.consume(route.provider, tokensIn + tokensOut);
+  if (!deps.db) return;
+  // Cost: a combo/route may set explicit prices; otherwise fall back to the ported
+  // aigetwey pricing table so cost auto-resolves per model instead of showing $0.
+  const pricing = getPricingForModel(route.provider.id, route.model);
+  const priceIn = route.price_in ?? pricing?.input;
+  const priceOut = route.price_out ?? pricing?.output;
+  deps.db.record({
+    alias: route.alias,
+    provider: route.provider.id,
+    model: route.model,
+    tokens_in: tokensIn,
+    tokens_out: tokensOut,
+    cached_tokens: usage?.cached_tokens ?? 0,
+    cost: computeCost(tokensIn, tokensOut, priceIn, priceOut),
+    status,
+    latency_ms: latencyMs,
+    stream: stream ? 1 : 0,
+  });
+}
+
+export async function handle(
+  deps: HandleDeps,
+  clientFormat: WireFormat,
+  body: unknown,
+  signal?: AbortSignal,
+): Promise<HandleResult> {
+  const { config, pool } = deps;
+  const now = deps.now ?? Date.now;
+  const startedAt = now();
+  const ingress = adapterFor(clientFormat);
+  const canonical = ingress.requestToCanonical(body);
+
+  if (!canonical.model) {
+    throw new GatewayError(400, { error: "missing 'model' in request" });
+  }
+
+  // Thinking: a model-name suffix like "claude-opus-4-6(high)" or "alias(none)"
+  // carries the client's thinking intent. Strip it so routing matches the clean
+  // model, and capture the intent (suffix wins, else any reasoning param already
+  // in the body). It's applied per-attempt in the served provider's native format
+  // (upstream/client.ts), driven by the capabilities table — a no-op for models
+  // that can't reason. Matches aigetwey's capture-before-translate flow.
+  const { cleanModel, override } = parseSuffix(canonical.model);
+  canonical.model = cleanModel;
+  const thinkingIntent: ThinkingConfig | null =
+    override ?? captureThinking(canonical as Record<string, unknown>);
+
+  const routes = config.resolve(canonical.model);
+  if (routes.length === 0) {
+    throw new GatewayError(404, { error: `unknown model "${canonical.model}"` });
+  }
+
+  // Pipeline order matters: RTK compresses tool_result in the INPUT first, then
+  // inject prepends the output-style system prompt. They touch different parts
+  // of the request and stack cleanly. Both run before routing so every fallback
+  // attempt sends the same transformed request.
+  if (config.endpoint.rtk) {
+    const stats = compressMessages(canonical.messages);
+    if (stats.hits > 0) {
+      const pct = Math.round((1 - stats.bytesOut / stats.bytesIn) * 100);
+      deps.log?.(
+        `[rtk] compressed ${stats.hits} tool output(s): ${stats.bytesIn}B -> ${stats.bytesOut}B (${pct}%) via [${stats.shapes.join(",")}]`,
+      );
+    }
+  }
+
+  // fail-open: an injection error must never break the request.
+  try {
+    const injected = injectInto(canonical, {
+      caveman: config.endpoint.caveman,
+      ponytail: config.endpoint.ponytail,
+    });
+    if (injected) deps.log?.(`[inject] caveman=${config.endpoint.caveman} ponytail=${config.endpoint.ponytail}`);
+  } catch (e) {
+    deps.log?.(`[inject] skipped (error): ${(e as Error).message}`);
+  }
+
+  // Headroom: pipe the (OpenAI-shaped) messages through the external compression
+  // proxy when enabled. Fail-open — on any error the original messages stand and
+  // the request proceeds. Runs after RTK/inject so it compresses the final context.
+  if (config.endpoint.headroom.enabled) {
+    const hr = await compressWithHeadroom(canonical.messages, {
+      url: config.endpoint.headroom.url,
+      model: canonical.model,
+      compressUserMessages: config.endpoint.headroom.compress_user_messages,
+    });
+    if (hr) {
+      canonical.messages = hr.messages;
+      const line = formatHeadroomLog(hr);
+      if (line) deps.log?.(`[headroom] ${line}`);
+    }
+  }
+
+  const wantStream = canonical.stream === true;
+
+  let won;
+  try {
+    won = await executeWithFallback(routes, pool, canonical, {
+      stream: wantStream,
+      signal,
+      thinkingIntent,
+      isExhausted: deps.quota ? (p) => deps.quota!.isExhausted(p) : undefined,
+      onAttempt: (a) =>
+        deps.log?.(`[fallback] ${a.provider}/${a.model} ${a.status ?? "-"} -> ${a.outcome}${a.detail ? ` (${a.detail})` : ""}`),
+    });
+  } catch (e) {
+    const err = e as UpstreamError;
+    const status = err.status ?? 502;
+    let payload: unknown = { error: err.message };
+    if (err.body) {
+      try {
+        payload = JSON.parse(err.body);
+      } catch {
+        payload = { error: err.body };
+      }
+    }
+    throw new GatewayError(status, payload);
+  }
+
+  const { route, result } = won;
+
+  if (!result.stream) {
+    const clientBody = ingress.responseFromCanonical(result.response);
+    recordUsage(deps, route, result.response.usage, 200, now() - startedAt, false);
+    return { status: 200, json: clientBody };
+  }
+
+  // streaming: provider SSE -> canonical chunks -> client SSE bytes. The
+  // provider and client formats may differ (e.g. an Anthropic client talking to
+  // an OpenAI provider), so both ends translate through the canonical chunk.
+  const providerStream = streamAdapterFor(route.provider.format);
+  const clientStream = streamAdapterFor(clientFormat);
+  const canonicalChunks = providerStream.streamToCanonical(parseSSE(result.body));
+
+  // tap the canonical chunk stream to capture usage from the final chunk(s),
+  // which arrive as partial fields across multiple chunks.
+  let lastUsage: CanonicalUsage | undefined;
+  async function* tap(): AsyncGenerator<CanonicalChunk> {
+    for await (const chunk of canonicalChunks) {
+      if (chunk.usage) {
+        lastUsage = {
+          prompt_tokens: chunk.usage.prompt_tokens ?? lastUsage?.prompt_tokens ?? 0,
+          completion_tokens: chunk.usage.completion_tokens ?? lastUsage?.completion_tokens ?? 0,
+          total_tokens: 0,
+          cached_tokens: chunk.usage.cached_tokens ?? lastUsage?.cached_tokens,
+        };
+      }
+      yield chunk;
+    }
+  }
+
+  const clientEvents = clientStream.streamFromCanonical(tap());
+
+  async function* toBytes(): AsyncGenerator<Uint8Array> {
+    try {
+      for await (const ev of clientEvents) {
+        yield encodeSSE(ev);
+      }
+    } finally {
+      // record once the stream drains (or the client disconnects) so usage is
+      // captured even on early termination.
+      recordUsage(deps, route, lastUsage, 200, now() - startedAt, true);
+    }
+  }
+
+  return { status: 200, sse: toBytes() };
+}