beddel 0.1.0

package/src/server/api/graphql.ts

@@ -0,0 +1,249 @@
+/**
+ * GraphQL helpers used by the /api/graphql route.
+ */
+
+import { agentRegistry } from "../../agents/agentRegistry";
+import {
+  getClientByApiKey,
+  getEndpointByName,
+  logExecution,
+  checkRateLimit,
+} from "../kvStore";
+import {
+  sanitizeInput,
+  isValidMethodName,
+  isValidApiKey,
+  executeInSandbox,
+  validateRequiredProps,
+} from "../runtimeSecurity";
+import {
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+} from "../errors";
+import type {
+  ExecuteMethodInput,
+  ExecuteMethodResult,
+  ExecutionContext,
+} from "../types";
+
+const schema = `
+  type Query { ping: String! }
+  type Mutation { executeMethod(methodName: String!, params: JSON!, props: JSON!): ExecutionResult! }
+  type ExecutionResult { success: Boolean!, data: JSON, error: String, executionTime: Int! }
+  scalar JSON
+`;
+
+export function getGraphQLSchema(): string {
+  return schema;
+}
+
+export async function executeRegisteredMethod(
+  input: ExecuteMethodInput,
+  clientId: string
+): Promise<ExecuteMethodResult> {
+  const startTime = Date.now();
+  const context: ExecutionContext = {
+    logs: [],
+    status: "running",
+    output: undefined,
+    error: undefined,
+    log: (message: string) =>
+      context.logs.push(`[${new Date().toISOString()}] ${message}`),
+    setOutput: (output: unknown) => {
+      context.output = output;
+      context.status = "success";
+    },
+    setError: (error: string) => {
+      context.error = error;
+      context.status = "error";
+    },
+  };
+
+  try {
+    context.log("Method execution initiated.");
+    if (!isValidMethodName(input.methodName)) {
+      throw new ValidationError("Invalid method name format");
+    }
+
+    const declarativeAgent = agentRegistry.getAgent(input.methodName);
+    if (declarativeAgent) {
+      context.log(`Found declarative agent: ${input.methodName}`);
+
+      const result = await agentRegistry.executeAgent(
+        input.methodName,
+        sanitizeInput(input.params) as Record<string, any>,
+        sanitizeInput(input.props) as Record<string, string>,
+        context
+      );
+
+      const executionTime = Date.now() - startTime;
+      await logExecution({
+        id: `log_${Date.now()}`,
+        clientId,
+        endpointName: input.methodName,
+        timestamp: new Date().toISOString(),
+        duration: executionTime,
+        success: true,
+        input: input.params,
+        output: result,
+        logs: context.logs,
+      });
+      return { success: true, data: result, executionTime };
+    }
+
+    const endpoint = await getEndpointByName(input.methodName);
+    if (!endpoint) {
+      throw new NotFoundError(`Method '${input.methodName}' not found`);
+    }
+
+    context.log(`Found endpoint: ${endpoint.name}`);
+    const sanitizedParams = sanitizeInput(input.params) as Record<
+      string,
+      unknown
+    >;
+    const sanitizedProps = sanitizeInput(input.props) as Record<string, string>;
+    const { valid, missing } = validateRequiredProps(
+      endpoint.requiredProps,
+      sanitizedProps
+    );
+    if (!valid) {
+      throw new ValidationError(
+        `Missing required props: ${missing.join(", ")}`
+      );
+    }
+
+    context.log("Props validated. Executing sandbox.");
+    await executeInSandbox(
+      endpoint.code,
+      sanitizedParams,
+      sanitizedProps,
+      context
+    );
+    context.log("Sandbox execution finished.");
+
+    if (context.status === "error") {
+      throw new Error(context.error || "Sandbox execution failed.");
+    }
+    if (context.status !== "success") {
+      throw new Error("Sandbox finished in an indeterminate state.");
+    }
+
+    const executionTime = Date.now() - startTime;
+    await logExecution({
+      id: `log_${Date.now()}`,
+      clientId,
+      endpointName: input.methodName,
+      timestamp: new Date().toISOString(),
+      duration: executionTime,
+      success: true,
+      input: sanitizedParams,
+      output: context.output,
+      logs: context.logs,
+    });
+    return { success: true, data: context.output, executionTime };
+  } catch (error) {
+    const executionTime = Date.now() - startTime;
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    if (!context.error) context.setError(errorMessage);
+
+    await logExecution({
+      id: `log_${Date.now()}`,
+      clientId,
+      endpointName: input.methodName,
+      timestamp: new Date().toISOString(),
+      duration: executionTime,
+      success: false,
+      error: errorMessage,
+      input: input.params,
+      logs: context.logs,
+    });
+    return { success: false, error: errorMessage, executionTime };
+  }
+}
+
+export async function handleGraphQLPost(request: Request) {
+  try {
+    let clientId: string;
+    const authHeader = request.headers.get("authorization");
+
+    if (authHeader && authHeader.startsWith("Bearer ")) {
+      const apiKey = authHeader.substring(7);
+      if (!isValidApiKey(apiKey)) {
+        throw new AuthenticationError("Invalid API key format");
+      }
+      const client = await getClientByApiKey(apiKey);
+      if (!client) throw new AuthenticationError("Invalid API key");
+      const rateLimitOk = await checkRateLimit(client.id, client.rateLimit);
+      if (!rateLimitOk) throw new RateLimitError("Rate limit exceeded.");
+      clientId = client.id;
+    } else if (request.headers.get("x-admin-tenant") === "true") {
+      clientId = "admin_tenant";
+    } else {
+      throw new AuthenticationError(
+        "Missing or invalid authorization header"
+      );
+    }
+
+    const body = await request.json();
+    if (!body.query) {
+      throw new ValidationError("Missing query in request body");
+    }
+
+    if (body.query && body.query.includes("executeMethod")) {
+      if (!body.variables || !body.variables.methodName) {
+        throw new ValidationError(
+          "Missing 'variables' or 'methodName' in request body"
+        );
+      }
+
+      const result = await executeRegisteredMethod(
+        {
+          methodName: body.variables.methodName,
+          params: body.variables.params || {},
+          props: body.variables.props || {},
+        },
+        clientId
+      );
+      return Response.json({ data: { executeMethod: result } });
+    }
+
+    return Response.json(
+      { errors: [{ message: "Unsupported operation" }] },
+      { status: 400 }
+    );
+  } catch (error) {
+    const status =
+      error instanceof AuthenticationError
+        ? 401
+        : error instanceof RateLimitError
+        ? 429
+        : error instanceof ValidationError
+        ? 400
+        : error instanceof NotFoundError
+        ? 404
+        : 500;
+    return Response.json(
+      {
+        errors: [
+          {
+            message:
+              error instanceof Error ? error.message : "Internal server error",
+          },
+        ],
+      },
+      { status }
+    );
+  }
+}
+
+export function handleGraphQLGet() {
+  return new Response(
+    `<!DOCTYPE html>
+    <html><head><title>Opal Support API - GraphQL</title><style>body{font-family:sans-serif;max-width:800px;margin:50px auto;padding:20px}code,pre{background:#f4f4f4;padding:4px 8px;border-radius:4px}</style></head>
+    <body><h1>Opal Support API</h1><p>GraphQL endpoint for executing registered methods.</p><h2>Endpoint</h2><code>POST /api/graphql</code><h2>Authentication</h2><p>Use Bearer token in Authorization header.</p><h2>Schema</h2><pre>${schema}</pre></body></html>`,
+    { headers: { "Content-Type": "text/html" } }
+  );
+}

package/src/server/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * Custom error classes shared across server runtimes.
+ */
+
+export class AuthenticationError extends Error {
+  constructor(message = "Authentication failed") {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class RateLimitError extends Error {
+  constructor(message = "Rate limit exceeded") {
+    super(message);
+    this.name = "RateLimitError";
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+export class ExecutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ExecutionError";
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./errors";
+export * from "./kvStore";
+export * from "./runtimeSecurity";
+export { agentRegistry } from "../agents/agentRegistry";
+export type { AgentRegistration } from "../agents/agentRegistry";

package/src/server/kvStore.ts

@@ -0,0 +1,152 @@
+/**
+ * Upstash KV helpers shared between the Next.js runtime and npm package.
+ */
+
+import { Redis } from "@upstash/redis";
+import type { Client, Endpoint, ExecutionLog } from "./types";
+
+if (!process.env.KV_REST_API_URL || !process.env.KV_REST_API_TOKEN) {
+  throw new Error("Missing Upstash Redis credentials in environment variables");
+}
+
+const redis = new Redis({
+  url: process.env.KV_REST_API_URL,
+  token: process.env.KV_REST_API_TOKEN,
+});
+
+export const KV_PREFIXES = {
+  CLIENT: "client:",
+  API_KEY: "apikey:",
+  ENDPOINT: "endpoint:",
+  ENDPOINT_NAME: "endpoint:name:",
+  EXECUTION_LOG: "log:",
+  RATE_LIMIT: "ratelimit:",
+  CLIENTS_LIST: "clients:list",
+  ENDPOINTS_LIST: "endpoints:list",
+} as const;
+
+export async function getClient(clientId: string): Promise<Client | null> {
+  return await redis.get<Client>(`${KV_PREFIXES.CLIENT}${clientId}`);
+}
+
+export async function getClientByApiKey(apiKey: string): Promise<Client | null> {
+  const clientId = await redis.get<string>(`${KV_PREFIXES.API_KEY}${apiKey}`);
+  if (!clientId) return null;
+  return await getClient(clientId);
+}
+
+export async function getAllClients(): Promise<Client[]> {
+  const clientIds =
+    (await redis.get<string[]>(KV_PREFIXES.CLIENTS_LIST)) || [];
+  if (clientIds.length === 0) return [];
+  const clients = await Promise.all(clientIds.map((id) => getClient(id)));
+  return clients.filter((c): c is Client => c !== null);
+}
+
+export async function saveClient(client: Client): Promise<void> {
+  await redis.set(`${KV_PREFIXES.CLIENT}${client.id}`, JSON.stringify(client));
+
+  for (const apiKey of client.apiKeys) {
+    await redis.set(`${KV_PREFIXES.API_KEY}${apiKey}`, client.id);
+  }
+
+  const clientIds =
+    (await redis.get<string[]>(KV_PREFIXES.CLIENTS_LIST)) || [];
+  if (!clientIds.includes(client.id)) {
+    clientIds.push(client.id);
+    await redis.set(KV_PREFIXES.CLIENTS_LIST, clientIds);
+  }
+}
+
+export async function deleteClient(clientId: string): Promise<void> {
+  const client = await getClient(clientId);
+  if (!client) return;
+
+  for (const apiKey of client.apiKeys) {
+    await redis.del(`${KV_PREFIXES.API_KEY}${apiKey}`);
+  }
+
+  let clientIds =
+    (await redis.get<string[]>(KV_PREFIXES.CLIENTS_LIST)) || [];
+  clientIds = clientIds.filter((id) => id !== clientId);
+  await redis.set(KV_PREFIXES.CLIENTS_LIST, clientIds);
+
+  await redis.del(`${KV_PREFIXES.CLIENT}${clientId}`);
+}
+
+export async function getEndpoint(endpointId: string): Promise<Endpoint | null> {
+  return await redis.get<Endpoint>(`${KV_PREFIXES.ENDPOINT}${endpointId}`);
+}
+
+export async function getEndpointByName(
+  name: string
+): Promise<Endpoint | null> {
+  const endpointId = await redis.get<string>(
+    `${KV_PREFIXES.ENDPOINT_NAME}${name}`
+  );
+  if (!endpointId) return null;
+  return await getEndpoint(endpointId);
+}
+
+export async function getAllEndpoints(): Promise<Endpoint[]> {
+  const endpointIds =
+    (await redis.get<string[]>(KV_PREFIXES.ENDPOINTS_LIST)) || [];
+  if (endpointIds.length === 0) return [];
+  const endpoints = await Promise.all(endpointIds.map((id) => getEndpoint(id)));
+  return endpoints.filter((e): e is Endpoint => e !== null);
+}
+
+export async function saveEndpoint(endpoint: Endpoint): Promise<void> {
+  await redis.set(
+    `${KV_PREFIXES.ENDPOINT}${endpoint.id}`,
+    JSON.stringify(endpoint)
+  );
+  await redis.set(`${KV_PREFIXES.ENDPOINT_NAME}${endpoint.name}`, endpoint.id);
+
+  const endpointIds =
+    (await redis.get<string[]>(KV_PREFIXES.ENDPOINTS_LIST)) || [];
+  if (!endpointIds.includes(endpoint.id)) {
+    endpointIds.push(endpoint.id);
+    await redis.set(KV_PREFIXES.ENDPOINTS_LIST, endpointIds);
+  }
+}
+
+export async function deleteEndpoint(endpointId: string): Promise<void> {
+  const endpoint = await getEndpoint(endpointId);
+  if (!endpoint) return;
+
+  await redis.del(`${KV_PREFIXES.ENDPOINT_NAME}${endpoint.name}`);
+
+  let endpointIds =
+    (await redis.get<string[]>(KV_PREFIXES.ENDPOINTS_LIST)) || [];
+  endpointIds = endpointIds.filter((id) => id !== endpointId);
+  await redis.set(KV_PREFIXES.ENDPOINTS_LIST, endpointIds);
+
+  await redis.del(`${KV_PREFIXES.ENDPOINT}${endpointId}`);
+}
+
+export async function logExecution(log: ExecutionLog): Promise<void> {
+  const key = `${KV_PREFIXES.EXECUTION_LOG}${log.id}`;
+  await redis.set(key, JSON.stringify(log), {
+    ex: 60 * 60 * 24 * 30,
+  });
+}
+
+export async function checkRateLimit(
+  clientId: string,
+  limit: number
+): Promise<boolean> {
+  const key = `${KV_PREFIXES.RATE_LIMIT}${clientId}`;
+
+  const pipeline = redis.pipeline();
+  pipeline.incr(key);
+  pipeline.ttl(key);
+
+  const [current, ttl] = await pipeline.exec<[number, number]>();
+
+  if (ttl === -1) {
+    await redis.expire(key, 60);
+  }
+
+  return current <= limit;
+}

package/src/server/runtimeSecurity.ts

@@ -0,0 +1,102 @@
+/**
+ * Security helpers used by the Next.js runtime and exported as part of the package.
+ */
+
+import type { ExecutionContext } from "./types";
+
+/**
+ * Sanitize user input to prevent code injection
+ */
+export function sanitizeInput(input: unknown): unknown {
+  if (typeof input === "string") {
+    return input
+      .replace(/[<>]/g, "")
+      .replace(/javascript:/gi, "")
+      .replace(/on\w+=/gi, "")
+      .trim();
+  }
+
+  if (Array.isArray(input)) {
+    return input.map(sanitizeInput);
+  }
+
+  if (typeof input === "object" && input !== null) {
+    const sanitized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(input)) {
+      sanitized[key] = sanitizeInput(value);
+    }
+    return sanitized;
+  }
+
+  return input;
+}
+
+/**
+ * Validate method name (alphanumeric, underscores, and hyphens)
+ */
+export function isValidMethodName(name: string): boolean {
+  return /^[a-zA-Z_-][a-zA-Z0-9_.-]*$/.test(name);
+}
+
+/**
+ * Validate API key format
+ */
+export function isValidApiKey(apiKey: string): boolean {
+  return /^opal_[a-z0-9_-]+_key_[a-zA-Z0-9]{12,}$/.test(apiKey);
+}
+
+/**
+ * Execute stored code in a sandbox scope with a time limit.
+ */
+export async function executeInSandbox(
+  code: string,
+  params: Record<string, unknown>,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<void> {
+  const executionPromise = (async () => {
+    try {
+      const executeFunction = new Function(`return ${code}`)();
+      await executeFunction(params, props, context);
+    } catch (error) {
+      console.error("[Sandbox Execution Error]:", error);
+      const errorMessage =
+        error instanceof Error ? error.message : "Internal sandbox error";
+      if (context.status !== "error") {
+        context.setError(errorMessage);
+      }
+    }
+  })();
+
+  const timeoutPromise = new Promise<void>((_, reject) =>
+    setTimeout(
+      () => reject(new Error("Execution timed out after 3000ms")),
+      3000
+    )
+  );
+
+  try {
+    await Promise.race([executionPromise, timeoutPromise]);
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown sandbox error";
+    if (context.status !== "error") {
+      context.setError(errorMessage);
+    }
+    context.log(`Sandbox execution failed: ${errorMessage}`);
+  }
+}
+
+/**
+ * Validate required props are provided
+ */
+export function validateRequiredProps(
+  requiredProps: string[],
+  providedProps: Record<string, string>
+): { valid: boolean; missing: string[] } {
+  const missing = requiredProps.filter((prop) => !providedProps[prop]);
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}

package/src/server/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared server-side types for the Opal Support App runtime.
+ * These live inside the Beddel package so both the Next.js app and
+ * the npm distribution reference exactly the same contracts.
+ */
+
+import type { ExecutionContext as DeclarativeExecutionContext } from "../types/executionContext";
+
+export interface Client {
+  id: string;
+  name: string;
+  email: string;
+  apiKeys: string[];
+  createdAt: string;
+  rateLimit: number;
+}
+
+export interface Endpoint {
+  id: string;
+  name: string;
+  description: string;
+  code: string;
+  visibility: "public" | "private";
+  requiredProps: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ExecutionLog {
+  id: string;
+  clientId: string;
+  endpointName: string;
+  timestamp: string;
+  duration: number;
+  success: boolean;
+  error?: string;
+  input?: unknown;
+  output?: unknown;
+  logs?: string[];
+}
+
+export type ExecutionContext = DeclarativeExecutionContext;
+
+export interface ExecuteMethodInput {
+  methodName: string;
+  params: Record<string, unknown>;
+  props: Record<string, string>;
+}
+
+export interface ExecuteMethodResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  executionTime: number;
+}
+
+export interface GraphQLContext {
+  clientId: string;
+  client: Client;
+}

package/src/types/executionContext.ts

@@ -0,0 +1,16 @@
+/**
+ * Project-agnostic execution context contract for declarative runtimes.
+ * Mirrors the shape used inside the Opal Support App but stays self-contained
+ * so the npm package does not depend on repository-local files.
+ */
+export interface ExecutionContext {
+  logs: string[];
+  status: "running" | "success" | "error";
+  output: unknown;
+  error?: string;
+  log: (message: string) => void;
+  setOutput: (output: unknown) => void;
+  setError: (error: string) => void;
+}
+
+export default ExecutionContext;