forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

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

@@ -4,6 +4,7 @@ import {
   FORGE_TELEMETRY_SECRET_REDACTED,
 } from "../../compiler/diagnostics/codes.ts";
 import type { Diagnostic } from "../../compiler/types/diagnostic.ts";
+import { hashStable } from "../../compiler/primitives/hash.ts";
 
 const SECRET_KEY_PATTERN =
   /password|secret|token|apikey|authorization|cookie/i;
@@ -16,7 +17,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,29 +74,56 @@ 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;
 }
 
+function summarizeValue(value: unknown): Record<string, unknown> {
+  if (Array.isArray(value)) {
+    return { type: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      type: "object",
+      keys: Object.keys(value as Record<string, unknown>).sort().slice(0, 20),
+    };
+  }
+  if (typeof value === "string") {
+    return { type: "string", length: value.length };
+  }
+  return { type: value === null ? "null" : typeof value };
+}
+
+function summarizePayload(payload: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(payload).map(([key, value]) => [key, summarizeValue(value)]),
+  );
+}
+
 function truncateString(
   value: string,
   maxBytes: number,
@@ -80,9 +152,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>;
@@ -97,7 +171,8 @@ export function scrubEnvelopePayload<T extends Record<string, unknown>>(
   }
 
   const serialized = JSON.stringify(scrubbed);
-  if (Buffer.byteLength(serialized, "utf8") > MAX_PAYLOAD_BYTES) {
+  const originalBytes = Buffer.byteLength(serialized, "utf8");
+  if (originalBytes > MAX_PAYLOAD_BYTES) {
     diagnostics.push(
       createDiagnostic({
         severity: "warning",
@@ -105,10 +180,16 @@ export function scrubEnvelopePayload<T extends Record<string, unknown>>(
         message: `truncated telemetry payload to ${MAX_PAYLOAD_BYTES} bytes`,
       }),
     );
-    const parsed = JSON.parse(
-      truncateString(serialized, MAX_PAYLOAD_BYTES, diagnostics, "payload"),
-    ) as T;
-    return { value: parsed, diagnostics };
+    return {
+      value: {
+        truncated: true,
+        originalBytes,
+        maxBytes: MAX_PAYLOAD_BYTES,
+        hash: hashStable(serialized),
+        summary: summarizePayload(scrubbed),
+      } as unknown as T,
+      diagnostics,
+    };
   }
 
   return { value: scrubbed, diagnostics };

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 };
 }
@@ -91,6 +173,22 @@ export function step<T extends (...args: any[]) => unknown>(
   return { kind: "step", name, handler };
 }
 
-export function workflow<T extends Record<string, unknown>>(definition: T): ForgeDefinition<T> {
-  return definition;
+export function workflow<T extends Record<string, unknown>>(
+  definition: T,
+): ForgeDefinition<T & { __forge: { kind: "workflow" } }> {
+  return {
+    ...definition,
+    __forge: { kind: "workflow" },
+  };
 }
+
+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.21";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;