Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

20.8 KB
Raw Blame
/**
 * Project-scoped Penguin Go key authorization.
 *
 * The Web App presents this like any other provider's "authorize a key" action. Penguin Go's
 * wire protocol is different from OAuth/PKCE, though: the server registers a device secret,
 * polls the one-time delivery, validates its API key and model catalog, then adds newly
 * advertised models while writing the key across the provider group. Account and balance
 * metadata remain outside Adelie.
 */
import { randomBytes } from "node:crypto";
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import { PENGUIN_GO_PROVIDER_ID } from "@adelie/core/model-catalog";
import { HttpError } from "../http/errors.js";
import { normalizePenguinGoOrigin } from "../config.js";
import { Config } from "../hmr/capabilities.js";
import type { ProjectConfigStore } from "../mechanisms/projects.js";
import type { PlatformAuthFlowStatusResponse } from "../api/types.js";
import {
  PLATFORM_CLIENT_ID,
  type PlatformCatalogPricing,
  type PlatformModelApplyResult,
  type PlatformModelCatalog,
} from "./platform-auth-types.js";

const FLOW_TTL_MS = 10 * 60 * 1000;
const MAX_FLOWS_PER_OWNER = 8;
const MAX_RESPONSE_BYTES = 512 * 1024;
const REQUEST_TIMEOUT_MS = 10_000;
const MAX_API_KEY_LENGTH = 1024;
const MAX_CATALOG_MODELS = 512;
const MAX_MODEL_ID_LENGTH = 256;
const MAX_DISPLAY_NAME_LENGTH = 256;
const MAX_ENDPOINT_LENGTH = 2048;
const DEFAULT_RETRY_AFTER_MS = 1_000;
const MAX_RETRY_AFTER_MS = 60_000;

type FlowStatus = "pending" | "applying" | "completed" | "cancelled" | "apply_failed" | "error";

interface Flow {
  flowId: string;
  projectId: string;
  userId: string;
  code: string | null;
  deviceSecret: string | null;
  authorizeUrl: string;
  expiresAt: number;
  status: FlowStatus;
  error?: PlatformAuthFlowStatusResponse["error"];
  applied?: number;
  apiKey?: string;
  catalog?: PlatformModelCatalog;
  polling?: Promise<void>;
  retryPollAt?: number;
  changed?: boolean;
}

export type PlatformAuthStatusResult = PlatformAuthFlowStatusResponse & { changed?: true };

interface PlatformAuthDeps {
  origin: string;
  getKey: (projectId: string) => Promise<string | undefined>;
  applyCatalog: (
    projectId: string,
    catalog: PlatformModelCatalog,
    apiKey: string,
    applyKeyToExisting: boolean,
  ) => Promise<PlatformModelApplyResult>;
  fetchImpl?: typeof fetch;
  now?: () => number;
}

function asRecord(value: unknown): Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

async function readJsonBounded(response: Response): Promise<unknown> {
  if (response.body === null) return null;
  const reader = response.body.getReader();
  const chunks: Uint8Array[] = [];
  let size = 0;
  try {
    while (true) {
      const part = await reader.read();
      if (part.done) break;
      size += part.value.byteLength;
      if (size > MAX_RESPONSE_BYTES) {
        await reader.cancel("Platform response is too large.");
        throw new Error("Platform response is too large.");
      }
      chunks.push(part.value);
    }
  } finally {
    reader.releaseLock();
  }
  const body = Buffer.concat(chunks).toString("utf8");
  return body === "" ? null : JSON.parse(body);
}

function requiredString(value: unknown, maxLength: number, label: string): string {
  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
    throw new Error(`The platform returned an invalid ${label}.`);
  }
  return value;
}

function platformEndpoint(value: unknown): string {
  const raw = requiredString(value, MAX_ENDPOINT_LENGTH, "endpoint");
  const parsed = new URL(raw);
  if (
    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
    parsed.username ||
    parsed.password
  ) {
    throw new Error("The platform returned an invalid endpoint.");
  }
  return raw.replace(/\/+$/, "");
}

function platformPrice(value: unknown, label: string): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
    throw new Error(`The platform returned an invalid ${label} price.`);
  }
  return value;
}

function platformPricing(value: unknown, label: string): PlatformCatalogPricing {
  const pricing = asRecord(value);
  if (pricing.unit !== "usd_per_mtok") {
    throw new Error(`The platform returned an unsupported ${label} pricing unit.`);
  }
  return {
    unit: "usd_per_mtok",
    cacheRead: platformPrice(pricing.cacheRead, `${label} cache read`),
    cacheWrite: platformPrice(pricing.cacheWrite, `${label} cache write`),
    output: platformPrice(pricing.output, `${label} output`),
  };
}

/**
 * The promotion a platform model carries, if any: its list price and the fraction off it. The
 * wire sends both or neither, and the billed `pricing` must be that list price less the fraction.
 */
function platformPromotion(
  model: Record<string, unknown>,
  billed: PlatformCatalogPricing,
): { listPricing: PlatformCatalogPricing; discount: number } | undefined {
  const hasListPricing = model.listPricing !== undefined;
  const hasDiscount = model.discount !== undefined;
  if (hasListPricing !== hasDiscount) {
    throw new Error("The platform returned incomplete discount metadata.");
  }
  if (!hasListPricing) return undefined;
  if (
    typeof model.discount !== "number" ||
    !Number.isFinite(model.discount) ||
    model.discount <= 0 ||
    model.discount >= 1
  ) {
    throw new Error("The platform returned an invalid discount.");
  }
  const discount = model.discount;
  const listPricing = platformPricing(model.listPricing, "list");
  const close = (actual: number, list: number): boolean =>
    Math.abs(actual - list * (1 - discount)) <= 1e-9 * Math.max(1, Math.abs(actual));
  if (
    !close(billed.cacheRead, listPricing.cacheRead) ||
    !close(billed.cacheWrite, listPricing.cacheWrite) ||
    !close(billed.output, listPricing.output)
  ) {
    throw new Error("The platform returned inconsistent discount metadata.");
  }
  return { listPricing, discount };
}

function platformCatalog(value: unknown, requireEnvelope: boolean): PlatformModelCatalog {
  const body = asRecord(value);
  if (requireEnvelope && body.schemaVersion !== 1) {
    throw new Error("The platform returned an unsupported model catalog.");
  }
  if (requireEnvelope) requiredString(body.catalogVersion, 128, "catalog version");
  const endpoints = asRecord(body.endpoints);
  const endpointByName = {
    openai: platformEndpoint(endpoints.openai),
    google: platformEndpoint(endpoints.google),
  } as const;
  if (!Array.isArray(body.models) || body.models.length > MAX_CATALOG_MODELS) {
    throw new Error("The platform returned an invalid model catalog.");
  }
  const seen = new Set<string>();
  const models = body.models.map((value) => {
    const model = asRecord(value);
    const modelId = requiredString(model.modelId, MAX_MODEL_ID_LENGTH, "model id");
    if (seen.has(modelId)) throw new Error("The platform returned duplicate model ids.");
    seen.add(modelId);
    const displayName = requiredString(
      model.displayName,
      MAX_DISPLAY_NAME_LENGTH,
      "model display name",
    );
    const contextWindow = model.contextWindow;
    if (!Number.isSafeInteger(contextWindow) || Number(contextWindow) <= 0) {
      throw new Error("The platform returned an invalid context window.");
    }
    const maxOutputTokens = model.maxOutputTokens;
    if (
      maxOutputTokens !== undefined &&
      (!Number.isSafeInteger(maxOutputTokens) || Number(maxOutputTokens) <= 0)
    ) {
      throw new Error("The platform returned an invalid maximum output length.");
    }
    if (typeof model.supportsVision !== "boolean") {
      throw new Error("The platform returned an invalid vision capability.");
    }
    const billed = platformPricing(model.pricing, "effective");
    const promotion = platformPromotion(model, billed);
    const route = asRecord(model.recommendedRoute);
    const provider = model.provider;
    const googleRoute =
      provider === "google" &&
      route.protocol === "google-generative-language" &&
      route.endpoint === "google";
    const deepSeekRoute =
      provider === "deepseek" &&
      route.protocol === "deepseek-responses" &&
      route.endpoint === "openai";
    if (!googleRoute && !deepSeekRoute) {
      throw new Error("The platform returned an unsupported model route.");
    }
    return {
      modelId,
      displayName,
      contextWindow: Number(contextWindow),
      supportsVision: model.supportsVision,
      // A Project stores the list price; the promotion travels apart, as the fraction.
      pricing: promotion?.listPricing ?? billed,
      ...(promotion !== undefined ? { discount: promotion.discount } : {}),
      baseUrl: endpointByName[googleRoute ? "google" : "openai"],
      clientType: googleRoute ? ("gemini-3.8" as const) : ("deepseek-v4" as const),
    };
  });
  return { models };
}

/** Validates the one-time authorization payload and extracts only connection data. */
export function platformConnection(value: unknown): {
  apiKey: string;
  catalog: PlatformModelCatalog;
} {
  const body = asRecord(value);
  const client = asRecord(body.client);
  if (client.id !== PLATFORM_CLIENT_ID) throw new Error("The platform returned another client.");
  const connection = asRecord(body.connection);
  return {
    apiKey: requiredString(connection.apiKey, MAX_API_KEY_LENGTH, "API key"),
    catalog: platformCatalog(connection, false),
  };
}

function retryAfterMs(value: unknown): number {
  const seconds = asRecord(value).retryAfterSeconds;
  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
    return DEFAULT_RETRY_AFTER_MS;
  }
  return Math.min(MAX_RETRY_AFTER_MS, Math.ceil(seconds * 1000));
}

function retryAfterSeconds(value: unknown): number {
  return Math.ceil(retryAfterMs(value) / 1000);
}

export class PlatformAuthService {
  private readonly flows = new Map<string, Flow>();
  private readonly fetchImpl: typeof fetch;
  private readonly now: () => number;

  constructor(private readonly deps: PlatformAuthDeps) {
    this.fetchImpl = deps.fetchImpl ?? ((...args) => fetch(...args));
    this.now = deps.now ?? (() => Date.now());
  }

  private url(path: string): string {
    return `${this.deps.origin}${path}`;
  }

  private isPending(flow: Flow): boolean {
    return (
      this.flows.get(flow.flowId) === flow &&
      flow.status === "pending" &&
      flow.expiresAt > this.now()
    );
  }

  private async request(path: string, init: RequestInit): Promise<Response> {
    return this.fetchImpl(this.url(path), {
      ...init,
      redirect: "manual",
      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
    });
  }

  async start(input: { projectId: string; userId: string }): Promise<{
    flowId: string;
    authorizeUrl: string;
    expiresAt: string;
  }> {
    this.sweep();
    const flowId = randomBytes(32).toString("base64url");
    const code = randomBytes(32).toString("base64url");
    const deviceSecret = randomBytes(32).toString("base64url");
    let response: Response;
    try {
      response = await this.request("/api/auth/desktop/start", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ code, deviceSecret, client: { id: PLATFORM_CLIENT_ID } }),
      });
    } catch {
      throw new HttpError(502, "platform_unreachable", "Penguin Go could not be reached.");
    }
    if (response.status === 429) {
      let body: unknown = null;
      try {
        body = await readJsonBounded(response);
      } catch {
        // A malformed rate-limit response still gets the bounded default delay.
      }
      const retryAfter = retryAfterSeconds(body);
      throw new HttpError(
        429,
        "platform_rate_limited",
        "Penguin Go is receiving too many authorization requests. Try again shortly.",
        retryAfter,
      );
    }
    if (response.status !== 201) {
      throw new HttpError(502, "platform_start_failed", "Penguin Go refused the key flow.");
    }
    let body: Record<string, unknown>;
    try {
      body = asRecord(await readJsonBounded(response));
    } catch {
      throw new HttpError(502, "platform_start_failed", "Penguin Go returned an invalid response.");
    }
    const expiresAt = typeof body.expiresAt === "string" ? Date.parse(body.expiresAt) : NaN;
    if (!Number.isFinite(expiresAt) || expiresAt <= this.now()) {
      throw new HttpError(502, "platform_start_failed", "Penguin Go returned an invalid expiry.");
    }
    this.evictOldest(input.userId, input.projectId);
    const authorizeUrl = `${this.deps.origin}/desktop/authorize?code=${encodeURIComponent(code)}`;
    const localExpiresAt = Math.min(expiresAt, this.now() + FLOW_TTL_MS);
    this.flows.set(flowId, {
      flowId,
      projectId: input.projectId,
      userId: input.userId,
      code,
      deviceSecret,
      authorizeUrl,
      expiresAt: localExpiresAt,
      status: "pending",
    });
    return { flowId, authorizeUrl, expiresAt: new Date(localExpiresAt).toISOString() };
  }

  async status(input: {
    flowId: string;
    projectId: string;
    userId: string;
  }): Promise<PlatformAuthStatusResult> {
    const flow = this.requireFlow(input);
    if (
      flow.status === "pending" &&
      (flow.retryPollAt === undefined || flow.retryPollAt <= this.now())
    ) {
      flow.polling ??= this.pollPlatform(flow).finally(() => {
        flow.polling = undefined;
      });
      await flow.polling;
    }
    return this.publicFlow(flow);
  }

  async retryApply(input: {
    flowId: string;
    projectId: string;
    userId: string;
  }): Promise<PlatformAuthStatusResult> {
    const flow = this.requireFlow(input);
    if (flow.status !== "apply_failed" || flow.apiKey === undefined || flow.catalog === undefined) {
      throw new HttpError(409, "platform_auth_not_retryable", "This key cannot be applied again.");
    }
    await this.apply(flow);
    return this.publicFlow(flow);
  }

  /** Refreshes the platform catalog with the Project's existing key, without a browser login. */
  async sync(projectId: string): Promise<PlatformModelApplyResult> {
    const apiKey = await this.deps.getKey(projectId);
    if (apiKey === undefined) {
      throw new HttpError(
        409,
        "platform_reauthorization_required",
        "Penguin Go authorization is required.",
      );
    }
    let response: Response;
    try {
      response = await this.request("/api/client/models", {
        method: "GET",
        headers: { authorization: `Bearer ${apiKey}` },
      });
    } catch {
      throw new HttpError(502, "platform_unreachable", "Penguin Go could not be reached.");
    }
    if (response.status === 401 || response.status === 403) {
      throw new HttpError(
        409,
        "platform_reauthorization_required",
        "The Penguin Go key is no longer valid. Authorize it again.",
      );
    }
    if (!response.ok) {
      throw new HttpError(502, "platform_sync_failed", "Penguin Go refused model sync.");
    }
    let catalog: PlatformModelCatalog;
    try {
      catalog = platformCatalog(await readJsonBounded(response), true);
    } catch {
      throw new HttpError(
        502,
        "platform_sync_failed",
        "Penguin Go returned an invalid model catalog.",
      );
    }
    return this.deps.applyCatalog(projectId, catalog, apiKey, false);
  }

  cancel(input: { flowId: string; projectId: string; userId: string }): void {
    const flow = this.requireFlow(input);
    if (flow.status === "completed" || flow.status === "applying") {
      throw new HttpError(
        409,
        "platform_auth_flow_used",
        "This key flow can no longer be cancelled.",
      );
    }
    flow.status = "cancelled";
    flow.code = null;
    flow.deviceSecret = null;
    flow.apiKey = undefined;
    flow.catalog = undefined;
  }

  private async pollPlatform(flow: Flow): Promise<void> {
    if (!this.isPending(flow) || flow.code === null || flow.deviceSecret === null) return;
    let response: Response;
    try {
      response = await this.request("/api/auth/desktop/poll", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ code: flow.code, deviceSecret: flow.deviceSecret }),
      });
    } catch {
      if (!this.isPending(flow)) return;
      flow.status = "error";
      flow.error = "unreachable";
      return;
    }
    if (!this.isPending(flow)) return;
    if (response.status === 429) {
      let body: unknown = null;
      try {
        body = await readJsonBounded(response);
      } catch {
        // A malformed rate-limit response still gets a bounded default backoff.
      }
      if (!this.isPending(flow)) return;
      flow.retryPollAt = this.now() + retryAfterMs(body);
      return;
    }
    if (!response.ok) {
      flow.status = "error";
      flow.error = "upstream_failed";
      return;
    }
    flow.retryPollAt = undefined;
    let body: unknown;
    try {
      body = await readJsonBounded(response);
    } catch {
      if (!this.isPending(flow)) return;
      flow.status = "error";
      flow.error = "invalid_key";
      return;
    }
    if (!this.isPending(flow)) return;
    const status = asRecord(body).status;
    if (status === "pending") return;
    if (status === "claimed") {
      try {
        const connection = platformConnection(body);
        flow.apiKey = connection.apiKey;
        flow.catalog = connection.catalog;
      } catch {
        flow.status = "error";
        flow.error = "invalid_key";
        flow.code = null;
        flow.deviceSecret = null;
        return;
      }
      flow.code = null;
      flow.deviceSecret = null;
      await this.apply(flow);
      return;
    }
    flow.status = status === "cancelled" ? "cancelled" : "error";
    flow.error =
      status === "expired"
        ? "expired"
        : status === "locked"
          ? "locked"
          : status === "delivered"
            ? "already_delivered"
            : status === "cancelled"
              ? undefined
              : "upstream_failed";
    flow.code = null;
    flow.deviceSecret = null;
  }

  private async apply(flow: Flow): Promise<void> {
    if (flow.apiKey === undefined || flow.catalog === undefined) return;
    flow.status = "applying";
    flow.error = undefined;
    try {
      const result = await this.deps.applyCatalog(flow.projectId, flow.catalog, flow.apiKey, true);
      if (result.applied === 0) throw new Error("The Penguin Go catalog is empty.");
      flow.applied = result.applied;
      flow.apiKey = undefined;
      flow.catalog = undefined;
      flow.status = "completed";
      flow.changed = true;
    } catch {
      flow.status = "apply_failed";
      flow.error = "apply_failed";
    }
  }

  private publicFlow(flow: Flow): PlatformAuthStatusResult {
    const changed = flow.changed === true;
    flow.changed = false;
    return {
      status: flow.status,
      ...(flow.error !== undefined ? { error: flow.error } : {}),
      ...(flow.applied !== undefined ? { applied: flow.applied } : {}),
      ...(changed ? { changed: true as const } : {}),
    };
  }

  private requireFlow(input: { flowId: string; projectId: string; userId: string }): Flow {
    this.sweep();
    const flow = this.flows.get(input.flowId);
    if (
      flow === undefined ||
      flow.projectId !== input.projectId ||
      flow.userId !== input.userId ||
      flow.expiresAt <= this.now()
    ) {
      throw new HttpError(
        404,
        "platform_auth_flow_not_found",
        "This key flow has expired or does not exist.",
      );
    }
    return flow;
  }

  private sweep(): void {
    const now = this.now();
    for (const [id, flow] of this.flows) if (flow.expiresAt <= now) this.flows.delete(id);
  }

  private evictOldest(userId: string, projectId: string): void {
    const mine = [...this.flows.values()].filter(
      (flow) => flow.userId === userId && flow.projectId === projectId,
    );
    for (const flow of mine.slice(0, Math.max(0, mine.length - (MAX_FLOWS_PER_OWNER - 1)))) {
      this.flows.delete(flow.flowId);
    }
  }
}

/** The per-App key authorization capability consumed by Project model routes. */
export abstract class PlatformAuth extends Interface<
  Pick<PlatformAuthService, "start" | "status" | "retryApply" | "sync" | "cancel">
>() {}

/** Keep in-flight flows on the current platform App, like ModelOAuthService. */
@Module()
export class PlatformAuthProvider {
  @Use() private readonly config!: Config;
  @Use() private readonly projectConfig!: ProjectConfigStore;
  @Provide() auth!: PlatformAuth;

  setup() {
    this.auth = new PlatformAuthService({
      // A runtime older than the field publishes none; the default is the production origin.
      origin: this.config.penguinGoOrigin ?? normalizePenguinGoOrigin(undefined),
      getKey: (projectId) => this.projectConfig.getGroupApiKey(projectId, PENGUIN_GO_PROVIDER_ID),
      applyCatalog: (projectId, catalog, apiKey, applyKeyToExisting) =>
        this.projectConfig.mergePlatformModels(
          projectId,
          PENGUIN_GO_PROVIDER_ID,
          catalog,
          apiKey,
          applyKeyToExisting,
        ),
    });
  }
}