@decocms/runtime 0.0.1-testing-beta.1

package/src/auth.ts

@@ -0,0 +1,233 @@
+import { JWK, jwtVerify } from "jose";
+import type { DefaultEnv } from "./index.ts";
+
+const DECO_APP_AUTH_COOKIE_NAME = "deco_page_auth";
+const MAX_COOKIE_SIZE = 4000; // Leave some buffer below the 4096 limit
+
+export interface State {
+  next?: string;
+}
+
+export const StateParser = {
+  parse: (state: string) => {
+    return JSON.parse(decodeURIComponent(atob(state))) as State;
+  },
+  stringify: (state: State) => {
+    return btoa(encodeURIComponent(JSON.stringify(state)));
+  },
+};
+
+// Helper function to chunk a value into multiple cookies
+const chunkValue = (value: string): string[] => {
+  if (value.length <= MAX_COOKIE_SIZE) {
+    return [value];
+  }
+
+  const chunks: string[] = [];
+  for (let i = 0; i < value.length; i += MAX_COOKIE_SIZE) {
+    chunks.push(value.slice(i, i + MAX_COOKIE_SIZE));
+  }
+  return chunks;
+};
+
+// Helper function to reassemble chunked cookies
+const reassembleChunkedCookies = (
+  cookies: Record<string, string>,
+  baseName: string,
+): string | undefined => {
+  // First try the base cookie (non-chunked)
+  if (cookies[baseName]) {
+    return cookies[baseName];
+  }
+
+  // Try to reassemble from chunks
+  const chunks: string[] = [];
+  let index = 0;
+
+  while (true) {
+    const chunkName = `${baseName}_${index}`;
+    if (!cookies[chunkName]) {
+      break;
+    }
+    chunks.push(cookies[chunkName]);
+    index++;
+  }
+
+  return chunks.length > 0 ? chunks.join("") : undefined;
+};
+
+// Helper function to parse cookies from request
+const parseCookies = (cookieHeader: string): Record<string, string> => {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(";").forEach((cookie) => {
+    const [name, ...rest] = cookie.trim().split("=");
+    if (name && rest.length > 0) {
+      cookies[name] = decodeURIComponent(rest.join("="));
+    }
+  });
+
+  return cookies;
+};
+
+const parseJWK = (jwk: string): JWK => JSON.parse(atob(jwk)) as JWK;
+
+export const getReqToken = async (req: Request, env: DefaultEnv) => {
+  const token = () => {
+    // First try to get token from Authorization header
+    const authHeader = req.headers.get("Authorization");
+    if (authHeader) {
+      return authHeader.split(" ")[1];
+    }
+
+    // If not found, try to get from cookie
+    const cookieHeader = req.headers.get("Cookie");
+    if (cookieHeader) {
+      const cookies = parseCookies(cookieHeader);
+      return reassembleChunkedCookies(cookies, DECO_APP_AUTH_COOKIE_NAME);
+    }
+
+    return undefined;
+  };
+
+  const authToken = token();
+  if (!authToken) {
+    return undefined;
+  }
+
+  env.DECO_API_JWT_PUBLIC_KEY &&
+    (await jwtVerify(authToken, parseJWK(env.DECO_API_JWT_PUBLIC_KEY), {
+      issuer: "https://api.decocms.com",
+      algorithms: ["RS256"],
+      typ: "JWT",
+    }).catch((err) => {
+      console.error(
+        `[auth-token]: error validating: ${err} ${env.DECO_API_JWT_PUBLIC_KEY}`,
+      );
+    }));
+
+  return authToken;
+};
+
+export interface AuthCallbackOptions {
+  apiUrl?: string;
+  appName: string;
+}
+
+export const handleAuthCallback = async (
+  req: Request,
+  options: AuthCallbackOptions,
+): Promise<Response> => {
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+
+  if (!code) {
+    return new Response("Missing authorization code", { status: 400 });
+  }
+
+  // Parse state to get the next URL
+  let next = "/";
+  if (state) {
+    try {
+      const parsedState = StateParser.parse(state);
+      next = parsedState.next || "/";
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  try {
+    // Exchange code for token
+    const apiUrl = options.apiUrl ?? "https://api.decocms.com";
+    const exchangeResponse = await fetch(`${apiUrl}/apps/code-exchange`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        code,
+        client_id: options.appName,
+      }),
+    });
+
+    if (!exchangeResponse.ok) {
+      console.error(
+        "authentication failed",
+        code,
+        options.appName,
+        await exchangeResponse.text().catch((_) => ""),
+      );
+      return new Response("Authentication failed", { status: 401 });
+    }
+
+    const { access_token } = (await exchangeResponse.json()) as {
+      access_token: string;
+    };
+
+    if (!access_token) {
+      return new Response("No access token received", { status: 401 });
+    }
+
+    // Chunk the token if it's too large
+    const chunks = chunkValue(access_token);
+    const headers = new Headers();
+    headers.set("Location", next);
+
+    // Set cookies for each chunk
+    if (chunks.length === 1) {
+      // Single cookie for small tokens
+      headers.set(
+        "Set-Cookie",
+        `${DECO_APP_AUTH_COOKIE_NAME}=${access_token}; HttpOnly; SameSite=None; Secure; Path=/`,
+      );
+    } else {
+      // Multiple cookies for large tokens
+      chunks.forEach((chunk, index) => {
+        headers.append(
+          "Set-Cookie",
+          `${DECO_APP_AUTH_COOKIE_NAME}_${index}=${chunk}; HttpOnly; SameSite=None; Secure; Path=/`,
+        );
+      });
+    }
+
+    return new Response(null, {
+      status: 302,
+      headers,
+    });
+  } catch (err) {
+    return new Response(`Authentication failed ${err}`, { status: 500 });
+  }
+};
+
+const removeAuthCookie = (headers: Headers) => {
+  // Clear the base cookie
+  headers.append(
+    "Set-Cookie",
+    `${DECO_APP_AUTH_COOKIE_NAME}=; HttpOnly; SameSite=None; Secure; Path=/; Max-Age=0`,
+  );
+
+  // Clear all potential chunked cookies
+  // We'll try to clear up to 10 chunks (which would support tokens up to 40KB)
+  // This is a reasonable upper limit
+  for (let i = 0; i < 10; i++) {
+    headers.append(
+      "Set-Cookie",
+      `${DECO_APP_AUTH_COOKIE_NAME}_${i}=; HttpOnly; SameSite=None; Secure; Path=/; Max-Age=0`,
+    );
+  }
+};
+
+export const handleLogout = (req: Request) => {
+  const url = new URL(req.url);
+  const next = url.searchParams.get("next");
+  const redirectTo = new URL("/", url);
+  const headers = new Headers();
+  removeAuthCookie(headers);
+  headers.set("Location", next ?? redirectTo.href);
+  return new Response(null, {
+    status: 302,
+    headers,
+  });
+};

package/src/bindings/README.md

@@ -0,0 +1,132 @@
+# Bindings
+
+Bindings are a core concept for defining and enforcing standardized interfaces
+that MCPs (Model Context Protocols) can implement. They provide a type-safe,
+declarative way to specify what methods and schemas an integration (MCP) must
+expose to be compatible with certain parts of the system, similar to how
+TypeScript interfaces work.
+
+## Purpose
+
+- **Standardization:** Bindings define contracts (schemas and method names) that
+  MCPs must implement to be considered compatible with a given integration
+  point.
+- **Type Safety:** Bindings leverage Zod schemas and TypeScript types to ensure
+  correct data structures and method signatures.
+- **Extensibility:** You can define new bindings for any use case, not just the
+  built-in triggers.
+
+## How Bindings Work
+
+1. **Define a Binding:**\
+   A binding is a list of required tool definitions (name, input/output schema).
+2. **Implement the Binding:**\
+   An MCP "implements" a binding by exposing all required tools with the correct
+   names and schemas.
+3. **Check Implementation:**\
+   The system can check if an MCP or a set of tools implements a binding using
+   helper functions.
+4. **Typed Client:**\
+   You can create a type-safe client for interacting with an MCP that implements
+   a binding.
+
+## Example: Trigger Bindings
+
+- **Input Binding (`ON_AGENT_INPUT`):**\
+  Used for MCPs that handle incoming events, such as webhooks.
+
+These are defined in [`trigger.ts`](./trigger.ts) and exported for use.
+
+## API
+
+### binder.ts
+
+- `bindingClient(binder)`\
+  Creates a binding client for a given binding definition.
+  - `.implements(connectionOrTools)` — Checks if a connection or tool list
+    implements the binding.
+  - `.forConnection(mcpConnection)` — Returns a type-safe client for calling the
+    bound tools.
+
+- `TriggerInputBinding`\
+  Predefined binding for agent input triggers.
+
+### utils.ts
+
+- `Binding(binder)`\
+  Utility for checking if a set of tools implements a binding (by name).
+
+## Usage Example
+
+```ts
+import { TriggerInputBinding } from "./bindings/trigger.ts";
+
+// Check if a connection implements the input trigger binding
+const isImplemented = await TriggerInputBinding.implements(connection);
+
+// Create a client for a connection that implements the binding
+const triggerClient = TriggerInputBinding.forConnection(connection);
+await triggerClient.ON_AGENT_INPUT({ payload: ..., callbacks: ... });
+```
+
+## Creating a New Binding
+
+To create a new binding:
+
+1. **Create a new file** in the `/bindings` folder (e.g., `my-binding.ts`).
+2. **Define your binding** using the `Binder` type and Zod schemas for
+   input/output:
+
+```ts
+import { z } from "zod";
+import type { Binder } from "../index.ts";
+
+const myInputSchema = z.object({ ... });
+const myOutputSchema = z.object({ ... });
+
+export const MY_BINDING_SCHEMA = [{
+  name: "MY_BINDING_METHOD" as const,
+  inputSchema: myInputSchema,
+  outputSchema: myOutputSchema,
+}] as const satisfies Binder;
+```
+
+3. **Export your binding** in `index.ts`:
+
+```ts
+export * from "./my-binding.ts";
+```
+
+4. **Use your binding** in the UI or backend as needed.
+
+## Using Bindings in the UI
+
+Bindings are integrated into the UI to allow users to select integrations that
+implement a specific binding. For example:
+
+- The
+  [`BindingSelector`](../../../apps/web/src/components/toolsets/binding-selector.tsx)
+  component lets users pick an integration that implements a given binding. It
+  uses the `Binding` utility to check if an integration's tools match the
+  binding.
+- The
+  [`WebhookTriggerForm`](../../../apps/web/src/components/triggers/webhookTriggerForm.tsx)
+  uses `BindingSelector` to let users select an integration for the webhook
+  trigger, passing the `TRIGGER_INPUT_BINDING_SCHEMA` as the required binding.
+
+This pattern allows you to:
+
+- Ask the user to select an integration that implements a specific binding
+  through the UI
+- Ensure only compatible integrations are selectable
+
+## Extending Bindings
+
+You can define your own bindings by specifying the required tool names and
+schemas, then use the same pattern to check and interact with MCPs that
+implement them.
+
+---
+
+For more details, see the code in this folder and the UI components that consume
+bindings.

package/src/bindings/binder.ts

@@ -0,0 +1,143 @@
+/* oxlint-disable no-explicit-any */
+import { z } from "zod";
+import type { MCPConnection } from "../connection.ts";
+import { createPrivateTool } from "../mastra.ts";
+import {
+  createMCPFetchStub,
+  type MCPClientFetchStub,
+  type ToolBinder,
+} from "../mcp.ts";
+import { CHANNEL_BINDING_SCHEMA } from "./channels.ts";
+import { VIEW_BINDING_SCHEMA } from "./views.ts";
+
+// ToolLike is a simplified version of the Tool interface that matches what we need for bindings
+export interface ToolLike<
+  TName extends string = string,
+  TInput = any,
+  TReturn extends object | null | boolean = object,
+> {
+  name: TName;
+  description: string;
+  inputSchema: z.ZodType<TInput>;
+  outputSchema?: z.ZodType<TReturn>;
+  handler: (props: TInput) => Promise<TReturn> | TReturn;
+}
+
+export type Binder<
+  TDefinition extends readonly ToolBinder[] = readonly ToolBinder[],
+> = TDefinition;
+
+export type BinderImplementation<
+  TBinder extends Binder<any>,
+  TContext = any,
+> = TBinder extends Binder<infer TDefinition>
+  ? {
+      [K in keyof TDefinition]: Omit<
+        ToolLike<
+          TDefinition[K]["name"],
+          z.infer<TDefinition[K]["inputSchema"]>,
+          TDefinition[K] extends { outputSchema: infer Schema }
+            ? Schema extends z.ZodType
+              ? z.infer<Schema>
+              : never
+            : never
+        >,
+        "name" | "inputSchema" | "outputSchema" | "handler"
+      > & {
+        handler: (
+          props: z.infer<TDefinition[K]["inputSchema"]>,
+          c?: TContext,
+        ) => ReturnType<
+          ToolLike<
+            TDefinition[K]["name"],
+            z.infer<TDefinition[K]["inputSchema"]>,
+            TDefinition[K] extends { outputSchema: infer Schema }
+              ? Schema extends z.ZodType
+                ? z.infer<Schema>
+                : never
+              : never
+          >["handler"]
+        >;
+      };
+    }
+  : never;
+
+export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
+  binder: TDefinition,
+) => {
+  return {
+    implements: (tools: ToolBinder[]) => {
+      return binder.every(
+        (tool) =>
+          tool.opt === true || (tools ?? []).some((t) => t.name === tool.name),
+      );
+    },
+    forConnection: (
+      mcpConnection: MCPConnection,
+    ): MCPClientFetchStub<TDefinition> => {
+      const stub = createMCPFetchStub<TDefinition>({
+        connection: mcpConnection,
+      });
+      return new Proxy<MCPClientFetchStub<TDefinition>>(
+        {} as MCPClientFetchStub<TDefinition>,
+        {
+          get(_, name) {
+            if (typeof name !== "string") {
+              throw new Error("Name must be a string");
+            }
+
+            return (args: Record<string, unknown>) => {
+              return (
+                stub[name as keyof MCPClientFetchStub<TDefinition>] as (
+                  args: Record<string, unknown>,
+                ) => Promise<unknown>
+              )(args);
+            };
+          },
+        },
+      );
+    },
+  };
+};
+
+export type MCPBindingClient<T extends ReturnType<typeof bindingClient>> =
+  ReturnType<T["forConnection"]>;
+
+export const ChannelBinding = bindingClient(CHANNEL_BINDING_SCHEMA);
+
+export const ViewBinding = bindingClient(VIEW_BINDING_SCHEMA);
+
+export type { Callbacks } from "./channels.ts";
+
+export const impl = <TBinder extends Binder>(
+  schema: TBinder,
+  implementation: BinderImplementation<TBinder>,
+  createToolFn = createPrivateTool,
+) => {
+  const impl: ReturnType<typeof createToolFn>[] = [];
+  for (const key in schema) {
+    const toolSchema = schema[key];
+    const toolImplementation = implementation[key];
+
+    if (toolSchema.opt && !toolImplementation) {
+      continue;
+    }
+
+    if (!toolImplementation) {
+      throw new Error(`Implementation for ${key} is required`);
+    }
+
+    const { name, handler, ...toolLike }: ToolLike = {
+      ...toolSchema,
+      ...toolImplementation,
+    };
+    impl.push(
+      createToolFn({
+        ...toolLike,
+        id: name,
+        execute: ({ context }) => Promise.resolve(handler(context)),
+      }),
+    );
+  }
+  return impl;
+};

package/src/bindings/channels.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { ToolBinder } from "../mcp.ts";
+
+const callbacksSchema = z.object({
+  stream: z.string(),
+  generate: z.string(),
+  generateObject: z.string(),
+});
+
+const channelIdSchema = z.object({
+  workspace: z.string(),
+  discriminator: z.string(),
+});
+
+const channelBindingSchema = channelIdSchema.extend({
+  agentId: z.string(),
+  agentName: z.string(),
+  agentLink: z.string(),
+});
+
+const joinChannelSchema = channelBindingSchema.extend({
+  callbacks: callbacksSchema,
+});
+
+const listChannelsSchema = z.object({
+  channels: z.array(
+    z.object({
+      label: z.string(),
+      value: z.string(),
+    }),
+  ),
+});
+
+export type Callbacks = z.infer<typeof callbacksSchema>;
+export type JoinedChannelPayload = z.infer<typeof joinChannelSchema>;
+export type ListChannelsSchema = z.infer<typeof listChannelsSchema>;
+export const CHANNEL_BINDING_SCHEMA = [
+  {
+    name: "DECO_CHAT_CHANNELS_JOIN" as const,
+    inputSchema: joinChannelSchema,
+    outputSchema: z.any(),
+  },
+  {
+    name: "DECO_CHAT_CHANNELS_LEAVE" as const,
+    inputSchema: channelIdSchema,
+    outputSchema: z.any(),
+  },
+  {
+    name: "DECO_CHAT_CHANNELS_LIST" as const,
+    inputSchema: z.any(),
+    outputSchema: listChannelsSchema,
+    opt: true,
+  },
+] as const satisfies readonly ToolBinder[];

package/src/bindings/deconfig/helpers.ts

@@ -0,0 +1,107 @@
+// Helper functions for DeconfigResource
+
+export const normalizeDirectory = (dir: string) => {
+  // Ensure directory starts with / and doesn't end with /
+  const normalized = dir.startsWith("/") ? dir : `/${dir}`;
+  return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+};
+
+export const ResourcePath = {
+  build: (directory: string, resourceId: string) => {
+    const normalizedDir = normalizeDirectory(directory);
+    return `${normalizedDir}/${resourceId}.json`;
+  },
+  extract: (path: string) => {
+    const match = path.match(/^(.+)\/(.+)\.json$/);
+    if (!match) {
+      throw new Error("Invalid resource path");
+    }
+    return { directory: match[1], resourceId: match[2] };
+  },
+};
+
+export const ResourceUri = {
+  build: (integrationId: string, resourceName: string, resourceId: string) => {
+    return `rsc://${integrationId}/${resourceName}/${resourceId}`;
+  },
+  unwind: (uri: string) => {
+    const match = uri.match(/^rsc:\/\/[^/]+\/([^/]+)\/(.+)$/);
+    if (!match) {
+      throw new Error("Invalid Resources 2.0 URI format");
+    }
+    return { resourceName: match[1], resourceId: match[2] };
+  },
+};
+
+export function getMetadataValue(metadata: unknown, key: string): unknown {
+  if (!metadata || typeof metadata !== "object") return undefined;
+  const metaObj = metadata as Record<string, unknown>;
+  if (key in metaObj) return metaObj[key];
+  const nested = metaObj.metadata;
+  if (nested && typeof nested === "object" && key in nested) {
+    return (nested as Record<string, unknown>)[key];
+  }
+  return undefined;
+}
+
+export function getMetadataString(
+  metadata: unknown,
+  key: string,
+): string | undefined {
+  const value = getMetadataValue(metadata, key);
+  return typeof value === "string" ? value : undefined;
+}
+
+export const toAsyncIterator = <T>(
+  emitter: EventSource,
+  eventType: string = "message",
+): AsyncIterable<T> => {
+  const queue: T[] = [];
+  let done = false;
+  let waitPromise: ((data?: T) => void) | null = null;
+
+  const triggerLoop = () => {
+    if (waitPromise) {
+      waitPromise();
+      waitPromise = null;
+    }
+  };
+
+  const messageHandler = (data: MessageEvent) => {
+    try {
+      queue.push(JSON.parse(data.data));
+    } catch {
+      // Silently ignore malformed data or optionally log error
+      return;
+    }
+    triggerLoop();
+  };
+
+  const errorHandler = () => {
+    done = true;
+    triggerLoop();
+  };
+
+  emitter.addEventListener(eventType, messageHandler);
+  emitter.addEventListener("error", errorHandler);
+
+  return {
+    async *[Symbol.asyncIterator]() {
+      try {
+        while (true) {
+          const value = queue.shift();
+          if (value) {
+            yield value;
+          } else {
+            if (done) return;
+            await new Promise((resolve) => (waitPromise = resolve));
+          }
+        }
+      } finally {
+        emitter.removeEventListener(eventType, messageHandler);
+        emitter.removeEventListener("error", errorHandler);
+        emitter.close();
+      }
+    },
+  };
+};

package/src/bindings/deconfig/index.ts

@@ -0,0 +1 @@
+export * from "./resources.ts";