forgeos 0.1.0-alpha.2 → 0.1.0-alpha.4

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

@@ -51,10 +51,80 @@ export interface ForgeGenerateStructuredInput<T> {
   schema: ForgeFlexibleSchema<T>;
 }
 
+export type ForgeAiToolRisk = "read" | "write" | "external" | "destructive";
+
+export interface ForgeAiToolRuntimeContext {
+  secrets: {
+    get(name: string): string;
+    optional(name: string): string | undefined;
+    has(name: string): boolean;
+  };
+  env: Record<string, string | undefined>;
+  telemetry?: {
+    traceId?: string;
+    capture(name: string, properties?: Record<string, unknown>): Promise<void>;
+  };
+  auth?: unknown;
+}
+
+export interface ForgeAiToolDefinition<TArgs = unknown, TResult = unknown> {
+  description: string;
+  inputSchema: unknown;
+  outputSchema?: unknown;
+  strict?: boolean;
+  needsApproval?: boolean | ((args: TArgs) => boolean | Promise<boolean>);
+  risk?: ForgeAiToolRisk;
+  handler: (
+    ctx: ForgeAiToolRuntimeContext,
+    args: TArgs,
+  ) => TResult | Promise<TResult>;
+}
+
+export type ForgeAgentStopWhen =
+  | { kind: "stepCount"; maxSteps: number }
+  | { kind: "toolCall"; toolName: string };
+
+export interface ForgeRunAgentInput {
+  provider?: ForgeAiProvider;
+  model: string;
+  prompt: string;
+  instructions: string;
+  purpose?: string;
+  tools?: Record<string, ForgeAiToolDefinition>;
+  stopWhen?: ForgeAgentStopWhen;
+  maxSteps?: number;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ForgeRunAgentResult {
+  text: string;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  usage: ForgeAiUsage;
+  latencyMs: number;
+  toolCalls: Array<{
+    toolName: string;
+    input: unknown;
+  }>;
+  toolResults: Array<{
+    toolName: string;
+    output: unknown;
+  }>;
+  steps: number;
+  estimatedCostUsd?: number;
+}
+
 export interface AiContext {
   generateText(input: ForgeGenerateTextInput): Promise<ForgeGenerateTextResult>;
   streamText(input: ForgeStreamTextInput): Promise<ForgeStreamTextResult>;
   generateStructured<T>(input: ForgeGenerateStructuredInput<T>): Promise<T>;
+  runAgent(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
+}
+
+export interface AgentRuntimeContext {
+  run(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
 }
 
 export interface AiTelemetryEnvelope {

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

@@ -1,4 +1,5 @@
 import {
+  FORGE_AUTH_CLAIM_INVALID,
   FORGE_AUTH_CLAIM_MISSING,
   FORGE_AUTH_TENANT_MISSING,
 } from "../../compiler/diagnostics/codes.ts";
@@ -57,6 +58,31 @@ function asStringArray(value: unknown): string[] {
   return [];
 }
 
+function claimExists(claims: Record<string, unknown>, path: string | undefined): boolean {
+  return getClaimValue(claims, path) !== undefined;
+}
+
+function validateRoleClaim(
+  claims: Record<string, unknown>,
+  path: string | undefined,
+  label: string,
+): void {
+  const value = getClaimValue(claims, path);
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value === "string") {
+    return;
+  }
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return;
+  }
+  throw new ForgeAuthError(
+    FORGE_AUTH_CLAIM_INVALID,
+    `auth claim '${path ?? label}' must be a string or string array`,
+  );
+}
+
 function uniqueSorted(values: string[]): string[] {
   return [...new Set(values)].sort();
 }
@@ -84,6 +110,12 @@ export function mapClaimsToAuthContext(
     );
   }
 
+  if (claimExists(payload, mapping.role)) {
+    validateRoleClaim(payload, mapping.role, "role");
+  }
+  if (claimExists(payload, mapping.roles)) {
+    validateRoleClaim(payload, mapping.roles, "roles");
+  }
   const role = asString(getClaimValue(payload, mapping.role));
   const roles = uniqueSorted([
     ...(role ? [role] : []),

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

@@ -1,4 +1,5 @@
 import {
+  FORGE_AUTH_CLAIM_INVALID,
   FORGE_AUTH_CLAIM_MISSING,
   FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION,
   FORGE_AUTH_DISABLED,
@@ -20,6 +21,7 @@ export type ForgeAuthDiagnosticCode =
   | typeof FORGE_AUTH_TOKEN_EXPIRED
   | typeof FORGE_AUTH_JWKS_FAILED
   | typeof FORGE_AUTH_CLAIM_MISSING
+  | typeof FORGE_AUTH_CLAIM_INVALID
   | typeof FORGE_AUTH_TENANT_MISSING
   | typeof FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION
   | typeof FORGE_AUTH_MODE_INVALID

package/src/forge/runtime/context/create-context.ts

@@ -13,7 +13,7 @@ import { loadEnvFiles } from "../secrets/env-loader.ts";
 import { loadEnvSchema, loadSecretRegistry } from "../secrets/check.ts";
 import { createRuntimeSecretsBundle } from "../secrets/runtime-bundle.ts";
 import { createAiContext } from "../ai/context.ts";
-import type { AiContext } from "../ai/types.ts";
+import type { AgentRuntimeContext, AiContext } from "../ai/types.ts";
 import { isMockAiEnabled } from "../ai/state.ts";
 import { currentReleaseInfo, type RuntimeReleaseInfo } from "../release/runtime.ts";
 
@@ -26,6 +26,7 @@ export interface ForgeContext {
   secrets: SecretsContext;
   config: ConfigContext;
   ai: AiContext;
+  agent: AgentRuntimeContext;
   release: RuntimeReleaseInfo;
 }
 
@@ -67,11 +68,16 @@ function buildSecretsConfigAndAi(
   runtimeKind: RuntimeContext,
   store: RuntimeEnvStore,
   telemetry: TelemetryContext,
-  options?: { mockAi?: boolean },
+  options?: {
+    mockAi?: boolean;
+    auth?: AuthContext;
+    env?: Record<string, string | undefined>;
+  },
 ): {
   secrets: SecretsContext;
   config: ConfigContext;
   ai: AiContext;
+  agent: AgentRuntimeContext;
   env: Record<string, string | undefined>;
 } {
   const registry = workspaceRoot ? loadSecretRegistry(workspaceRoot) : null;
@@ -93,12 +99,20 @@ function buildSecretsConfigAndAi(
       tenantId:
         undefined,
     },
+    toolContext: {
+      env: options?.env ?? store.snapshot(),
+      auth: options?.auth,
+    },
   });
+  const agent: AgentRuntimeContext = {
+    run: (input) => ai.runAgent(input),
+  };
 
   return {
     secrets: bundle.secrets,
     config: bundle.config,
     ai,
+    agent,
     env: store.snapshot(),
   };
 }
@@ -123,12 +137,16 @@ export function createForgeContext(
     (options?.workspaceRoot
       ? getRuntimeEnvStore(options.workspaceRoot)
       : getRuntimeEnvStore());
-  const { secrets, config, ai, env } = buildSecretsConfigAndAi(
+  const { secrets, config, ai, agent, env } = buildSecretsConfigAndAi(
     options?.workspaceRoot,
     runtimeKind,
     store,
     telemetry,
-    { mockAi: options?.mockAi },
+    {
+      mockAi: options?.mockAi,
+      auth,
+      env: options?.env,
+    },
   );
 
   return {
@@ -139,6 +157,7 @@ export function createForgeContext(
     secrets,
     config,
     ai,
+    agent,
     release: currentReleaseInfo(),
     emit: async (eventType, payload) => {
       const enriched =
@@ -178,12 +197,16 @@ export function createActionContext(
     (options?.workspaceRoot
       ? getRuntimeEnvStore(options.workspaceRoot)
       : getRuntimeEnvStore());
-  const { secrets, config, ai, env } = buildSecretsConfigAndAi(
+  const { secrets, config, ai, agent, env } = buildSecretsConfigAndAi(
     options?.workspaceRoot,
     runtimeKind,
     store,
     telemetry,
-    { mockAi: options?.mockAi },
+    {
+      mockAi: options?.mockAi,
+      auth,
+      env: options?.env,
+    },
   );
 
   return {
@@ -194,6 +217,7 @@ export function createActionContext(
     secrets,
     config,
     ai,
+    agent,
     release: currentReleaseInfo(),
     emit: async () => {
       /* actions invoked by outbox worker do not emit */

package/src/forge/runtime/db/memory-adapter.ts

@@ -656,9 +656,9 @@ export class MemoryAdapter implements DbAdapter {
       return { rows: [], rowCount: before - table.rows.length };
     }
 
-    const id = params[0];
+    const rowsToDelete = new Set(this.filterRows(table.rows, sql, params));
     const before = table.rows.length;
-    table.rows = table.rows.filter((row) => row.id !== id);
+    table.rows = table.rows.filter((row) => !rowsToDelete.has(row));
     return { rows: [], rowCount: before - table.rows.length };
   }
 

package/src/forge/runtime/telemetry/scrubber.ts

@@ -16,7 +16,51 @@ export interface ScrubResult<T> {
   diagnostics: Diagnostic[];
 }
 
-function redactValue(key: string, value: unknown, diagnostics: Diagnostic[]): unknown {
+export interface ScrubOptions {
+  secretValues?: string[];
+}
+
+function normalizeSecretValues(secretValues: string[] | undefined): string[] {
+  return [...new Set((secretValues ?? []).filter((value) => value.length >= 8))]
+    .sort((left, right) => right.length - left.length);
+}
+
+function redactKnownSecretString(
+  key: string,
+  value: string,
+  diagnostics: Diagnostic[],
+  secretValues: string[],
+): string {
+  let redacted = value;
+  let didRedact = false;
+
+  for (const secret of secretValues) {
+    if (!redacted.includes(secret)) {
+      continue;
+    }
+    redacted = redacted.split(secret).join("[REDACTED]");
+    didRedact = true;
+  }
+
+  if (didRedact) {
+    diagnostics.push(
+      createDiagnostic({
+        severity: "warning",
+        code: FORGE_TELEMETRY_SECRET_REDACTED,
+        message: `redacted known secret value from telemetry field '${key}'`,
+      }),
+    );
+  }
+
+  return redacted;
+}
+
+function redactValue(
+  key: string,
+  value: unknown,
+  diagnostics: Diagnostic[],
+  secretValues: string[],
+): unknown {
   if (SECRET_KEY_PATTERN.test(key)) {
     diagnostics.push(
       createDiagnostic({
@@ -29,25 +73,30 @@ function redactValue(key: string, value: unknown, diagnostics: Diagnostic[]): un
   }
 
   if (value && typeof value === "object" && !Array.isArray(value)) {
-    return scrubObject(value as Record<string, unknown>, diagnostics);
+    return scrubObject(value as Record<string, unknown>, diagnostics, secretValues);
   }
 
   if (Array.isArray(value)) {
     return value.map((item, index) =>
-      redactValue(String(index), item, diagnostics),
+      redactValue(String(index), item, diagnostics, secretValues),
     );
   }
 
+  if (typeof value === "string" && secretValues.length > 0) {
+    return redactKnownSecretString(key, value, diagnostics, secretValues);
+  }
+
   return value;
 }
 
 function scrubObject(
   obj: Record<string, unknown>,
   diagnostics: Diagnostic[],
+  secretValues: string[],
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(obj)) {
-    result[key] = redactValue(key, value, diagnostics);
+    result[key] = redactValue(key, value, diagnostics, secretValues);
   }
   return result;
 }
@@ -80,9 +129,11 @@ function truncateString(
 
 export function scrubEnvelopePayload<T extends Record<string, unknown>>(
   payload: T,
+  options: ScrubOptions = {},
 ): ScrubResult<T> {
   const diagnostics: Diagnostic[] = [];
-  const scrubbed = scrubObject(payload, diagnostics) as T;
+  const secretValues = normalizeSecretValues(options.secretValues);
+  const scrubbed = scrubObject(payload, diagnostics, secretValues) as T;
 
   if (typeof scrubbed.exception === "object" && scrubbed.exception !== null) {
     const exception = scrubbed.exception as Record<string, unknown>;

package/src/forge/runtime/webhooks/security.ts

@@ -0,0 +1,184 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { DiagnosticCode } from "../../compiler/diagnostics/codes.ts";
+import {
+  FORGE_WEBHOOK_REPLAY_DETECTED,
+  FORGE_WEBHOOK_SIGNATURE_INVALID,
+  FORGE_WEBHOOK_TIMESTAMP_INVALID,
+} from "../../compiler/diagnostics/codes.ts";
+
+export type WebhookProvider = "generic" | "github" | "stripe";
+
+export interface WebhookReplayStore {
+  has(eventId: string): boolean | Promise<boolean>;
+  add(eventId: string): void | Promise<void>;
+}
+
+export interface WebhookVerificationInput {
+  provider: WebhookProvider;
+  secret: string;
+  payload: string | Uint8Array;
+  signatureHeader: string | null | undefined;
+  timestampHeader?: string | null;
+  eventId?: string;
+  replayStore?: WebhookReplayStore;
+  nowSeconds?: number;
+  toleranceSeconds?: number;
+}
+
+export interface WebhookVerificationResult {
+  ok: boolean;
+  code?: DiagnosticCode;
+  reason?: string;
+  provider: WebhookProvider;
+}
+
+export class MemoryWebhookReplayStore implements WebhookReplayStore {
+  private readonly seen = new Set<string>();
+
+  has(eventId: string): boolean {
+    return this.seen.has(eventId);
+  }
+
+  add(eventId: string): void {
+    this.seen.add(eventId);
+  }
+}
+
+function bytes(input: string | Uint8Array): Uint8Array {
+  return typeof input === "string" ? Buffer.from(input, "utf8") : input;
+}
+
+function hmacHex(secret: string, payload: string | Uint8Array): string {
+  return createHmac("sha256", secret).update(bytes(payload)).digest("hex");
+}
+
+function safeEqualHex(left: string | undefined, right: string): boolean {
+  if (!left || !/^[0-9a-f]+$/i.test(left) || !/^[0-9a-f]+$/i.test(right)) {
+    return false;
+  }
+  const leftBuffer = Buffer.from(left, "hex");
+  const rightBuffer = Buffer.from(right, "hex");
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function fail(
+  provider: WebhookProvider,
+  code: DiagnosticCode,
+  reason: string,
+): WebhookVerificationResult {
+  return { ok: false, provider, code, reason };
+}
+
+function parseStripeHeader(header: string): { timestamp?: number; signatures: string[] } {
+  const signatures: string[] = [];
+  let timestamp: number | undefined;
+  for (const part of header.split(",")) {
+    const [key, value] = part.split("=", 2).map((item) => item.trim());
+    if (key === "t") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) {
+        timestamp = parsed;
+      }
+    }
+    if (key === "v1" && value) {
+      signatures.push(value);
+    }
+  }
+  return { timestamp, signatures };
+}
+
+function validateTimestamp(input: {
+  provider: WebhookProvider;
+  timestamp?: number;
+  nowSeconds: number;
+  toleranceSeconds: number;
+}): WebhookVerificationResult | null {
+  if (!Number.isFinite(input.timestamp)) {
+    return fail(input.provider, FORGE_WEBHOOK_TIMESTAMP_INVALID, "missing or invalid webhook timestamp");
+  }
+  if (Math.abs(input.nowSeconds - input.timestamp!) > input.toleranceSeconds) {
+    return fail(input.provider, FORGE_WEBHOOK_TIMESTAMP_INVALID, "webhook timestamp is outside the replay window");
+  }
+  return null;
+}
+
+async function validateReplay(input: {
+  provider: WebhookProvider;
+  eventId?: string;
+  replayStore?: WebhookReplayStore;
+}): Promise<WebhookVerificationResult | null> {
+  if (!input.eventId || !input.replayStore) {
+    return null;
+  }
+  if (await input.replayStore.has(input.eventId)) {
+    return fail(input.provider, FORGE_WEBHOOK_REPLAY_DETECTED, "webhook event id was already processed");
+  }
+  await input.replayStore.add(input.eventId);
+  return null;
+}
+
+export async function verifyWebhookSignature(
+  input: WebhookVerificationInput,
+): Promise<WebhookVerificationResult> {
+  const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const toleranceSeconds = input.toleranceSeconds ?? 300;
+  const signatureHeader = input.signatureHeader ?? "";
+
+  if (!input.secret || !signatureHeader) {
+    return fail(input.provider, FORGE_WEBHOOK_SIGNATURE_INVALID, "missing webhook secret or signature");
+  }
+
+  let valid = false;
+  let timestamp: number | undefined;
+
+  if (input.provider === "stripe") {
+    const parsed = parseStripeHeader(signatureHeader);
+    timestamp = parsed.timestamp;
+    const timestampFailure = validateTimestamp({
+      provider: input.provider,
+      timestamp,
+      nowSeconds,
+      toleranceSeconds,
+    });
+    if (timestampFailure) {
+      return timestampFailure;
+    }
+    const signedPayload = `${timestamp}.${Buffer.from(bytes(input.payload)).toString("utf8")}`;
+    const expected = hmacHex(input.secret, signedPayload);
+    valid = parsed.signatures.some((signature) => safeEqualHex(signature, expected));
+  } else if (input.provider === "github") {
+    const provided = signatureHeader.startsWith("sha256=")
+      ? signatureHeader.slice("sha256=".length)
+      : signatureHeader;
+    valid = safeEqualHex(provided, hmacHex(input.secret, input.payload));
+  } else {
+    const timestampRaw = input.timestampHeader ?? undefined;
+    timestamp = timestampRaw === undefined ? undefined : Number(timestampRaw);
+    if (timestampRaw !== undefined) {
+      const timestampFailure = validateTimestamp({
+        provider: input.provider,
+        timestamp,
+        nowSeconds,
+        toleranceSeconds,
+      });
+      if (timestampFailure) {
+        return timestampFailure;
+      }
+    }
+    const signedPayload = timestampRaw === undefined
+      ? input.payload
+      : `${timestampRaw}.${Buffer.from(bytes(input.payload)).toString("utf8")}`;
+    valid = safeEqualHex(signatureHeader, hmacHex(input.secret, signedPayload));
+  }
+
+  if (!valid) {
+    return fail(input.provider, FORGE_WEBHOOK_SIGNATURE_INVALID, "webhook signature did not match payload");
+  }
+
+  const replayFailure = await validateReplay(input);
+  if (replayFailure) {
+    return replayFailure;
+  }
+
+  return { ok: true, provider: input.provider };
+}

package/src/forge/server.ts

@@ -11,11 +11,50 @@ export interface ForgeTelemetry {
   capture(name: string, payload?: Record<string, unknown>): Promise<void> | void;
 }
 
+export type ForgeAiProvider = "openai" | "anthropic" | "gateway";
+
+export interface ForgeAiUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface ForgeRunAgentInput {
+  provider?: ForgeAiProvider;
+  model: string;
+  prompt: string;
+  instructions: string;
+  purpose?: string;
+  tools?: Record<string, ForgeAiToolDefinition>;
+  stopWhen?: ForgeAgentStopWhen;
+  maxSteps?: number;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ForgeRunAgentResult {
+  text: string;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  usage: ForgeAiUsage;
+  latencyMs: number;
+  toolCalls: Array<{ toolName: string; input: unknown }>;
+  toolResults: Array<{ toolName: string; output: unknown }>;
+  steps: number;
+  estimatedCostUsd?: number;
+}
+
+export interface ForgeAgentRuntime {
+  run(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
+}
+
 export interface ForgeContext {
   db: ForgeRecord;
   emit(event: string, payload?: Record<string, unknown>): Promise<void> | void;
   telemetry: ForgeTelemetry;
   secrets: ForgeRecord;
+  agent?: ForgeAgentRuntime;
   auth?: {
     userId?: string;
     tenantId?: string;
@@ -44,6 +83,41 @@ export type ForgeActionDefinition<TEvent = unknown, TResult = unknown> = Record<
   handler: (ctx: ForgeContext, event: TEvent) => TResult | Promise<TResult>;
 };
 
+export type ForgeAiToolRisk = "read" | "write" | "external" | "destructive";
+
+export interface ForgeAiToolRuntimeContext {
+  secrets: ForgeRecord;
+  env: Record<string, string | undefined>;
+  telemetry: ForgeTelemetry;
+  auth?: ForgeContext["auth"];
+}
+
+export type ForgeAiToolDefinition<TArgs = unknown, TResult = unknown> = Record<string, unknown> & {
+  description: string;
+  inputSchema: unknown;
+  outputSchema?: unknown;
+  strict?: boolean;
+  needsApproval?: boolean | ((args: TArgs) => boolean | Promise<boolean>);
+  risk?: ForgeAiToolRisk;
+  handler: (
+    ctx: ForgeAiToolRuntimeContext,
+    args: TArgs,
+  ) => TResult | Promise<TResult>;
+};
+
+export type ForgeAgentStopWhen =
+  | { kind: "stepCount"; maxSteps: number }
+  | { kind: "toolCall"; toolName: string };
+
+export type ForgeAgentDefinition = Record<string, unknown> & {
+  provider?: "openai" | "anthropic" | "gateway";
+  model: string;
+  instructions: string;
+  tools?: Record<string, ForgeAiToolDefinition> | string[];
+  stopWhen?: ForgeAgentStopWhen;
+  maxSteps?: number;
+};
+
 export function defineTable<T extends Record<string, unknown>>(definition: T): T {
   return definition;
 }
@@ -80,6 +154,14 @@ export function action<T extends ForgeActionDefinition>(definition: T): ForgeDef
   return definition;
 }
 
+export function aiTool<T extends ForgeAiToolDefinition>(definition: T): ForgeDefinition<T> {
+  return definition;
+}
+
+export function agent<T extends ForgeAgentDefinition>(definition: T): ForgeDefinition<T> {
+  return definition;
+}
+
 export function event(name: string): { kind: "event"; name: string } {
   return { kind: "event", name };
 }
@@ -94,3 +176,14 @@ export function step<T extends (...args: any[]) => unknown>(
 export function workflow<T extends Record<string, unknown>>(definition: T): ForgeDefinition<T> {
   return definition;
 }
+
+export {
+  MemoryWebhookReplayStore,
+  verifyWebhookSignature,
+} from "./runtime/webhooks/security.ts";
+export type {
+  WebhookProvider,
+  WebhookReplayStore,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "./runtime/webhooks/security.ts";

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.2";
+export const FORGEOS_VERSION = "0.1.0-alpha.4";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;

package/templates/b2b-support-web/package.json

@@ -24,6 +24,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@types/node": "^24.0.0",
     "typescript": "^5.7.3"
   },
   "forge": {

package/templates/b2b-support-web/tsconfig.json

@@ -6,7 +6,10 @@
     "strict": true,
     "noEmit": true,
     "skipLibCheck": true,
-    "allowImportingTsExtensions": true
+    "allowImportingTsExtensions": true,
+    "types": [
+      "node"
+    ]
   },
   "include": [
     "src/**/*.ts"