forgeos 0.1.0-alpha.0

package/src/forge/runtime/ai/mock.ts

@@ -0,0 +1,49 @@
+import type { ForgeAiUsage } from "./types.ts";
+
+export interface MockAiQueuedResponse {
+  text: string;
+  usage?: Partial<ForgeAiUsage>;
+}
+
+let mockQueue: MockAiQueuedResponse[] = [];
+let defaultMockText = "mock-ai-response";
+
+export function resetMockAiQueue(): void {
+  mockQueue = [];
+  defaultMockText = "mock-ai-response";
+}
+
+export function enqueueMockAiResponse(response: MockAiQueuedResponse): void {
+  mockQueue.push(response);
+}
+
+export function setDefaultMockAiText(text: string): void {
+  defaultMockText = text;
+}
+
+export function dequeueMockAiResponse(): MockAiQueuedResponse {
+  const next = mockQueue.shift();
+  if (next) {
+    return next;
+  }
+  return {
+    text: defaultMockText,
+    usage: { promptTokens: 10, completionTokens: 20, totalTokens: 30 },
+  };
+}
+
+export function createMockAiUsage(override?: Partial<ForgeAiUsage>): ForgeAiUsage {
+  return {
+    promptTokens: override?.promptTokens ?? 10,
+    completionTokens: override?.completionTokens ?? 20,
+    totalTokens: override?.totalTokens ?? 30,
+  };
+}
+
+export function createMockAiProvider() {
+  return {
+    enqueue: enqueueMockAiResponse,
+    reset: resetMockAiQueue,
+    setDefaultText: setDefaultMockAiText,
+  };
+}

package/src/forge/runtime/ai/providers.ts

@@ -0,0 +1,78 @@
+import type { LanguageModel } from "ai";
+import {
+  FORGE_AI_MODEL_MISSING,
+  FORGE_AI_PROVIDER_UNKNOWN,
+  FORGE_AI_SECRET_MISSING,
+} from "../../compiler/diagnostics/codes.ts";
+import type { SecretsContext } from "../secrets/types.ts";
+import type { ForgeAiProvider } from "./types.ts";
+
+function forgeError(code: string, message: string): never {
+  const error = new Error(message);
+  (error as Error & { code: string }).code = code;
+  throw error;
+}
+
+const PROVIDER_SECRETS: Record<ForgeAiProvider, string> = {
+  openai: "OPENAI_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  gateway: "AI_GATEWAY_API_KEY",
+};
+
+export function resolveProviderSecret(provider: ForgeAiProvider): string {
+  return PROVIDER_SECRETS[provider];
+}
+
+export async function resolveLanguageModel(
+  provider: ForgeAiProvider,
+  model: string,
+  secrets: SecretsContext,
+): Promise<LanguageModel> {
+  if (!model || model.trim().length === 0) {
+    forgeError(FORGE_AI_MODEL_MISSING, "AI model is required");
+  }
+
+  switch (provider) {
+    case "openai": {
+      const apiKey = secrets.optional(PROVIDER_SECRETS.openai);
+      if (!apiKey) {
+        forgeError(
+          FORGE_AI_SECRET_MISSING,
+          `required secret '${PROVIDER_SECRETS.openai}' is not set for openai provider`,
+        );
+      }
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      const openai = createOpenAI({ apiKey });
+      return openai(model);
+    }
+    case "anthropic": {
+      const apiKey = secrets.optional(PROVIDER_SECRETS.anthropic);
+      if (!apiKey) {
+        forgeError(
+          FORGE_AI_SECRET_MISSING,
+          `required secret '${PROVIDER_SECRETS.anthropic}' is not set for anthropic provider`,
+        );
+      }
+      const { createAnthropic } = await import("@ai-sdk/anthropic");
+      const anthropic = createAnthropic({ apiKey });
+      return anthropic(model);
+    }
+    case "gateway": {
+      const apiKey = secrets.optional(PROVIDER_SECRETS.gateway);
+      if (!apiKey) {
+        forgeError(
+          FORGE_AI_SECRET_MISSING,
+          `required secret '${PROVIDER_SECRETS.gateway}' is not set for gateway provider`,
+        );
+      }
+      const { createGateway } = await import("ai");
+      const gateway = createGateway({ apiKey });
+      return gateway(model);
+    }
+    default:
+      forgeError(
+        FORGE_AI_PROVIDER_UNKNOWN,
+        `unknown AI provider '${String(provider)}'`,
+      );
+  }
+}

package/src/forge/runtime/ai/state.ts

@@ -0,0 +1,17 @@
+export function isMockAiEnabled(options?: { mockAi?: boolean }): boolean {
+  if (options?.mockAi) {
+    return true;
+  }
+  if (process.env.FORGE_MOCK_AI === "1") {
+    return true;
+  }
+  return false;
+}
+
+export function setMockAiMode(enabled: boolean): void {
+  if (enabled) {
+    process.env.FORGE_MOCK_AI = "1";
+  } else {
+    delete process.env.FORGE_MOCK_AI;
+  }
+}

package/src/forge/runtime/ai/types.ts

@@ -0,0 +1,67 @@
+export type ForgeAiProvider = "openai" | "anthropic" | "gateway";
+
+export type ForgeFlexibleSchema<T> = unknown & {
+  readonly __forgeStructuredOutput?: T;
+};
+
+export interface ForgeAiUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface ForgeGenerateTextInput {
+  provider: ForgeAiProvider;
+  model: string;
+  prompt: string;
+  system?: string;
+  purpose?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ForgeGenerateTextResult {
+  text: string;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  usage: ForgeAiUsage;
+  latencyMs: number;
+  estimatedCostUsd?: number;
+}
+
+export interface ForgeStreamTextInput extends ForgeGenerateTextInput {}
+
+export interface ForgeStreamTextResult {
+  textStream: AsyncIterable<string>;
+  text: Promise<string>;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  usage: Promise<ForgeAiUsage>;
+  latencyMs: number;
+}
+
+export interface ForgeGenerateStructuredInput<T> {
+  provider: ForgeAiProvider;
+  model: string;
+  prompt: string;
+  system?: string;
+  purpose?: string;
+  schema: ForgeFlexibleSchema<T>;
+}
+
+export interface AiContext {
+  generateText(input: ForgeGenerateTextInput): Promise<ForgeGenerateTextResult>;
+  streamText(input: ForgeStreamTextInput): Promise<ForgeStreamTextResult>;
+  generateStructured<T>(input: ForgeGenerateStructuredInput<T>): Promise<T>;
+}
+
+export interface AiTelemetryEnvelope {
+  traceId?: string;
+  workflowRunId?: string;
+  workflowStepId?: string;
+  actionRunId?: string;
+  tenantId?: string;
+  userId?: string;
+}

package/src/forge/runtime/auth/authenticate.ts

@@ -0,0 +1,58 @@
+import {
+  FORGE_AUTH_DISABLED,
+  FORGE_AUTH_MISSING_TOKEN,
+  FORGE_AUTH_MODE_INVALID,
+} from "../../compiler/diagnostics/codes.ts";
+import type { ForgeAuthConfig } from "./config.ts";
+import { mapClaimsToAuthContext } from "./claims.ts";
+import { ForgeAuthError } from "./errors.ts";
+import { parseAuthHeaders } from "./resolve.ts";
+import type { AuthContext } from "./types.ts";
+import { verifyJwtToken } from "./verifier.ts";
+
+export function extractBearerToken(headers: Headers): string | null {
+  const authorization = headers.get("authorization");
+  if (!authorization) {
+    return null;
+  }
+  const match = authorization.match(/^Bearer\s+(.+)$/i);
+  return match?.[1]?.trim() || null;
+}
+
+export async function authenticateHeaders(
+  headers: Headers,
+  config: ForgeAuthConfig,
+): Promise<AuthContext> {
+  if (config.mode === "dev-headers") {
+    return parseAuthHeaders(headers);
+  }
+
+  if (config.mode === "disabled") {
+    return { kind: "anonymous" };
+  }
+
+  if (config.mode === "jwt" || config.mode === "oidc") {
+    const token = extractBearerToken(headers);
+    if (!token) {
+      throw new ForgeAuthError(
+        FORGE_AUTH_MISSING_TOKEN,
+        "missing Authorization: Bearer token",
+      );
+    }
+    const verified = await verifyJwtToken(token, config);
+    return mapClaimsToAuthContext(verified.payload, config, verified.token);
+  }
+
+  throw new ForgeAuthError(
+    FORGE_AUTH_MODE_INVALID,
+    `unsupported auth mode '${String(config.mode)}'`,
+  );
+}
+
+export function disabledAuthWarning(): ForgeAuthError {
+  return new ForgeAuthError(
+    FORGE_AUTH_DISABLED,
+    "FORGE_AUTH_MODE=disabled leaves this runtime unauthenticated",
+    { status: 200 },
+  );
+}

package/src/forge/runtime/auth/claims.ts

@@ -0,0 +1,119 @@
+import {
+  FORGE_AUTH_CLAIM_MISSING,
+  FORGE_AUTH_TENANT_MISSING,
+} from "../../compiler/diagnostics/codes.ts";
+import type { AuthClaimsMapping, ForgeAuthConfig } from "./config.ts";
+import { ForgeAuthError } from "./errors.ts";
+import type { AuthContext } from "./types.ts";
+
+export interface VerifiedTokenMetadata {
+  issuer?: string;
+  audience?: string | string[];
+  subject?: string;
+  expiresAt?: number;
+  issuedAt?: number;
+  authProvider: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getClaimValue(
+  claims: Record<string, unknown>,
+  path: string | undefined,
+): unknown {
+  if (!path) {
+    return undefined;
+  }
+  if (Object.prototype.hasOwnProperty.call(claims, path)) {
+    return claims[path];
+  }
+
+  let current: unknown = claims;
+  for (const part of path.split(".")) {
+    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, part)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string");
+  }
+  if (typeof value === "string" && value.length > 0) {
+    return value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export function mapClaimsToAuthContext(
+  payload: Record<string, unknown>,
+  config: ForgeAuthConfig,
+  token: VerifiedTokenMetadata,
+): AuthContext {
+  const mapping: AuthClaimsMapping = config.claims;
+  const userId = asString(getClaimValue(payload, mapping.userId));
+  if (!userId) {
+    throw new ForgeAuthError(
+      FORGE_AUTH_CLAIM_MISSING,
+      `required auth claim '${mapping.userId}' is missing`,
+    );
+  }
+
+  const tenantId = asString(getClaimValue(payload, mapping.tenantId));
+  if (config.requiresTenant && !tenantId) {
+    throw new ForgeAuthError(
+      FORGE_AUTH_TENANT_MISSING,
+      "tenant claim is required for this Forge project",
+      { status: 403 },
+    );
+  }
+
+  const role = asString(getClaimValue(payload, mapping.role));
+  const roles = uniqueSorted([
+    ...(role ? [role] : []),
+    ...asStringArray(getClaimValue(payload, mapping.roles)),
+  ]);
+  const permissions = uniqueSorted(
+    asStringArray(getClaimValue(payload, mapping.permissions)),
+  );
+
+  return {
+    kind: "user",
+    userId,
+    ...(tenantId ? { tenantId } : {}),
+    ...(role ? { role } : roles[0] ? { role: roles[0] } : {}),
+    roles,
+    permissions,
+    ...(asString(getClaimValue(payload, mapping.email))
+      ? { email: asString(getClaimValue(payload, mapping.email)) }
+      : {}),
+    ...(asString(getClaimValue(payload, mapping.name))
+      ? { name: asString(getClaimValue(payload, mapping.name)) }
+      : {}),
+    token: {
+      issuer: token.issuer ?? "",
+      audience: token.audience ?? "",
+      subject: token.subject ?? userId,
+      ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
+      ...(token.issuedAt ? { issuedAt: token.issuedAt } : {}),
+      authProvider: token.authProvider,
+    },
+    claims: payload,
+  };
+}

package/src/forge/runtime/auth/config.ts

@@ -0,0 +1,148 @@
+import { nodeFileSystem } from "../../compiler/fs/index.ts";
+import { join } from "node:path";
+import { GENERATED_DIR } from "../../compiler/emitter/constants.ts";
+import { stripDeterministicHeader } from "../../compiler/primitives/header.ts";
+
+export type ForgeAuthMode = "dev-headers" | "jwt" | "oidc" | "disabled";
+
+export interface AuthClaimsMapping {
+  userId: string;
+  tenantId?: string;
+  role?: string;
+  roles?: string;
+  permissions?: string;
+  email?: string;
+  name?: string;
+}
+
+export interface AuthRegistryArtifact {
+  schemaVersion: string;
+  defaultMode: ForgeAuthMode;
+  modes: ForgeAuthMode[];
+  issuerEnv: string;
+  audienceEnv: string;
+  jwksUriEnv: string;
+  algorithmsEnv: string;
+  claims: AuthClaimsMapping;
+  requiresTenant: boolean;
+}
+
+export interface ForgeAuthConfig {
+  mode: ForgeAuthMode;
+  issuer?: string;
+  audience?: string | string[];
+  jwksUri?: string;
+  algorithms: string[];
+  claims: AuthClaimsMapping;
+  requiresTenant: boolean;
+  authProvider?: string;
+}
+
+export const DEFAULT_AUTH_CLAIMS: AuthClaimsMapping = {
+  userId: "sub",
+  tenantId: "tenant_id",
+  role: "role",
+  roles: "roles",
+  permissions: "permissions",
+  email: "email",
+  name: "name",
+};
+
+export const AUTH_ENV = {
+  mode: "FORGE_AUTH_MODE",
+  issuer: "FORGE_AUTH_ISSUER",
+  audience: "FORGE_AUTH_AUDIENCE",
+  jwksUri: "FORGE_AUTH_JWKS_URI",
+  algorithms: "FORGE_AUTH_ALGORITHMS",
+} as const;
+
+export function isForgeAuthMode(value: string): value is ForgeAuthMode {
+  return (
+    value === "dev-headers" ||
+    value === "jwt" ||
+    value === "oidc" ||
+    value === "disabled"
+  );
+}
+
+function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
+  const absolute = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  const raw = stripDeterministicHeader((nodeFileSystem.readText(absolute) ?? ""));
+  return JSON.parse(raw) as T;
+}
+
+export function loadAuthRegistry(
+  workspaceRoot: string,
+): AuthRegistryArtifact | null {
+  return readGeneratedJson<AuthRegistryArtifact>(
+    workspaceRoot,
+    `${GENERATED_DIR}/authRegistry.json`,
+  );
+}
+
+function parseAudience(value: string | undefined): string | string[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const values = value
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return values.length > 1 ? values : values[0];
+}
+
+function parseAlgorithms(value: string | undefined): string[] {
+  const algorithms = (value ?? "RS256")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return algorithms.length > 0 ? algorithms : ["RS256"];
+}
+
+export function resolveAuthMode(
+  value: string | undefined,
+  fallback: ForgeAuthMode,
+): ForgeAuthMode {
+  return value && isForgeAuthMode(value) ? value : fallback;
+}
+
+export function loadAuthConfigFromEnv(
+  workspaceRoot: string,
+  options: { defaultMode?: ForgeAuthMode; requiresTenant?: boolean } = {},
+): ForgeAuthConfig {
+  const registry = loadAuthRegistry(workspaceRoot);
+  const mode = resolveAuthMode(
+    process.env[AUTH_ENV.mode],
+    options.defaultMode ?? registry?.defaultMode ?? "dev-headers",
+  );
+
+  return {
+    mode,
+    issuer: process.env[AUTH_ENV.issuer],
+    audience: parseAudience(process.env[AUTH_ENV.audience]),
+    jwksUri: process.env[AUTH_ENV.jwksUri],
+    algorithms: parseAlgorithms(process.env[AUTH_ENV.algorithms]),
+    claims: registry?.claims ?? DEFAULT_AUTH_CLAIMS,
+    requiresTenant: options.requiresTenant ?? registry?.requiresTenant ?? false,
+    authProvider: mode,
+  };
+}
+
+export function buildDefaultAuthRegistry(
+  requiresTenant: boolean,
+): AuthRegistryArtifact {
+  return {
+    schemaVersion: "0.1.0",
+    defaultMode: "dev-headers",
+    modes: ["dev-headers", "jwt", "oidc", "disabled"],
+    issuerEnv: AUTH_ENV.issuer,
+    audienceEnv: AUTH_ENV.audience,
+    jwksUriEnv: AUTH_ENV.jwksUri,
+    algorithmsEnv: AUTH_ENV.algorithms,
+    claims: DEFAULT_AUTH_CLAIMS,
+    requiresTenant,
+  };
+}

package/src/forge/runtime/auth/errors.ts

@@ -0,0 +1,45 @@
+import {
+  FORGE_AUTH_CLAIM_MISSING,
+  FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION,
+  FORGE_AUTH_DISABLED,
+  FORGE_AUTH_INVALID_AUDIENCE,
+  FORGE_AUTH_INVALID_ISSUER,
+  FORGE_AUTH_INVALID_TOKEN,
+  FORGE_AUTH_JWKS_FAILED,
+  FORGE_AUTH_MISSING_TOKEN,
+  FORGE_AUTH_MODE_INVALID,
+  FORGE_AUTH_TENANT_MISSING,
+  FORGE_AUTH_TOKEN_EXPIRED,
+} from "../../compiler/diagnostics/codes.ts";
+
+export type ForgeAuthDiagnosticCode =
+  | typeof FORGE_AUTH_MISSING_TOKEN
+  | typeof FORGE_AUTH_INVALID_TOKEN
+  | typeof FORGE_AUTH_INVALID_ISSUER
+  | typeof FORGE_AUTH_INVALID_AUDIENCE
+  | typeof FORGE_AUTH_TOKEN_EXPIRED
+  | typeof FORGE_AUTH_JWKS_FAILED
+  | typeof FORGE_AUTH_CLAIM_MISSING
+  | typeof FORGE_AUTH_TENANT_MISSING
+  | typeof FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION
+  | typeof FORGE_AUTH_MODE_INVALID
+  | typeof FORGE_AUTH_DISABLED;
+
+export class ForgeAuthError extends Error {
+  code: ForgeAuthDiagnosticCode;
+  status: number;
+
+  constructor(
+    code: ForgeAuthDiagnosticCode,
+    message: string,
+    options: { status?: number; cause?: unknown } = {},
+  ) {
+    super(message);
+    this.name = "ForgeAuthError";
+    this.code = code;
+    this.status = options.status ?? 401;
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+  }
+}

package/src/forge/runtime/auth/evaluate.ts

@@ -0,0 +1,126 @@
+import { FORGE_POLICY_DENIED } from "../../compiler/diagnostics/codes.ts";
+import type { CommandAuthBinding, PermissionMatrix, QueryAuthBinding } from "../../compiler/types/policy-registry.ts";
+import type { AuthContext } from "./types.ts";
+
+export interface PolicyEvaluationResult {
+  allowed: boolean;
+  code?: typeof FORGE_POLICY_DENIED;
+  message?: string;
+  policy?: string;
+  role?: string;
+}
+
+function roleAllowed(
+  matrix: PermissionMatrix,
+  policy: string,
+  roles: string[],
+): boolean {
+  const entry = matrix.entries.find((candidate) => candidate.policy === policy);
+  if (!entry) {
+    return false;
+  }
+  return roles.some((role) => entry.roles.includes(role));
+}
+
+function authRoles(auth: Extract<AuthContext, { kind: "user" }>): string[] {
+  return [...new Set([...(auth.role ? [auth.role] : []), ...(auth.roles ?? [])])];
+}
+
+function primaryRole(roles: string[]): string {
+  return roles[0] ?? "unknown";
+}
+
+export function evaluateCommandAuth(
+  auth: AuthContext,
+  binding: CommandAuthBinding | undefined,
+  matrix: PermissionMatrix,
+): PolicyEvaluationResult {
+  return evaluateAuthRequirement(auth, binding?.auth, matrix, "command");
+}
+
+export function evaluateQueryAuth(
+  auth: AuthContext,
+  binding: QueryAuthBinding | undefined,
+  matrix: PermissionMatrix,
+): PolicyEvaluationResult {
+  return evaluateAuthRequirement(auth, binding?.auth, matrix, "query");
+}
+
+function evaluateAuthRequirement(
+  auth: AuthContext,
+  requirement:
+    | CommandAuthBinding["auth"]
+    | QueryAuthBinding["auth"]
+    | undefined,
+  matrix: PermissionMatrix,
+  entryKind: "command" | "query",
+): PolicyEvaluationResult {
+  const resolved = requirement ?? { kind: "public" as const };
+
+  if (resolved.kind === "public") {
+    return { allowed: true };
+  }
+
+  if (resolved.kind === "system") {
+    if (auth.kind === "system") {
+      return { allowed: true };
+    }
+    return {
+      allowed: false,
+      code: FORGE_POLICY_DENIED,
+      message: `${entryKind} requires system auth context`,
+    };
+  }
+
+  if (auth.kind === "anonymous") {
+    return {
+      allowed: false,
+      code: FORGE_POLICY_DENIED,
+      message: `${entryKind} requires authenticated user`,
+    };
+  }
+
+  if (auth.kind === "system") {
+    return {
+      allowed: false,
+      code: FORGE_POLICY_DENIED,
+      message: `${entryKind} requires user auth context`,
+    };
+  }
+
+  if (resolved.kind === "user") {
+    return { allowed: true };
+  }
+
+  const roles = authRoles(auth);
+  const allowed = roleAllowed(matrix, resolved.policy, roles);
+  const role = primaryRole(roles);
+  if (allowed) {
+    return { allowed: true, policy: resolved.policy, role };
+  }
+
+  return {
+    allowed: false,
+    code: FORGE_POLICY_DENIED,
+    message: `role '${role}' denied for policy '${resolved.policy}'`,
+    policy: resolved.policy,
+    role,
+  };
+}
+
+export function simulatePolicy(
+  matrix: PermissionMatrix,
+  policy: string,
+  role: string,
+): PolicyEvaluationResult {
+  const allowed = roleAllowed(matrix, policy, [role]);
+  return allowed
+    ? { allowed: true, policy, role }
+    : {
+        allowed: false,
+        code: FORGE_POLICY_DENIED,
+        message: `role '${role}' denied for policy '${policy}'`,
+        policy,
+        role,
+      };
+}