@ganju/utils 0.0.1

package/src/sdkConstants.ts

@@ -0,0 +1,44 @@
+// The handful of constants that get bundled into every customer's deployed
+// script, split out from the main constants module for exactly that reason.
+//
+// `@ganju/utils/constants` is one large object literal, so a bundler cannot drop
+// the keys a consumer doesn't touch — importing it from the SDK pulled ~70KB of
+// plan limits, MIME tables and vendor scopes into every uploaded Worker to reach
+// fourteen strings. These live here instead, and the main module re-exports them
+// so there is still one definition of each.
+//
+// The rule for this file: nothing lands here unless the SDK reads it at runtime,
+// and it imports nothing.
+
+// Bindings injected into every user script at upload time. The token is a
+// secret_text binding rotated on each publish; the broker is a service binding.
+// Names are part of the SDK's contract with the script, so they can't be
+// renamed without breaking already-deployed code.
+export const CUSTOM_CODE_BINDING_TOKEN = 'GANJU_TOOL_TOKEN';
+export const CUSTOM_CODE_BINDING_BROKER = 'GANJU_BROKER';
+
+// Broker routes, called by user code through the service binding above with
+// `Authorization: Bearer <GANJU_TOOL_TOKEN>`. The origin is arbitrary — a
+// service binding ignores the hostname.
+export const CUSTOM_CODE_BROKER_ORIGIN = 'https://broker.ganju.internal';
+export const CUSTOM_CODE_BROKER_PATH_CONNECTION = '/connection';
+export const CUSTOM_CODE_BROKER_PATH_SECRET = '/secret';
+export const CUSTOM_CODE_BROKER_PATH_RESOURCES_SEARCH = '/resources/search';
+export const CUSTOM_CODE_BROKER_PATH_RESOURCES_READ = '/resources/read';
+export const CUSTOM_CODE_BROKER_PATH_RESOURCES_LIST = '/resources/list';
+export const CUSTOM_CODE_BROKER_PATH_RESOURCES_CREATE = '/resources/create';
+export const CUSTOM_CODE_BROKER_PATH_RESOURCES_DELETE = '/resources/delete';
+export const CUSTOM_CODE_BROKER_PATH_SEND_FILE = '/send-file';
+
+// The reserved tool name the publish pipeline calls against a freshly uploaded
+// script to ask which tools it actually exports — which is what turns "the
+// manifest declares lookup-order but the code exports lookupOrder" from a
+// call-time mystery into a publish-time error. Underscore-prefixed so it can
+// never collide with a declared name.
+export const CUSTOM_CODE_HEALTH_TOOL = '__ganju_health';
+
+// How many ctx.log() lines travel back with a result. Logs are buffered inside
+// the isolate and returned in the response rather than sent to the broker line
+// by line — a log call shouldn't cost a network round trip.
+export const CUSTOM_CODE_MAX_LOGS = 50;
+export const CUSTOM_CODE_MAX_LOG_LENGTH = 2_000;

package/src/slackSend.ts

@@ -0,0 +1,65 @@
+// Wire protocol shared between the MCP worker (which builds the request) and
+// the resource-handler container (which talks to the Slack Web API).
+//
+// post-message: simple chat.postMessage. No attachments. Worker could call
+// Slack directly, but we route through the container to keep one auth/error
+// path for the slack provider and so future block-kit composition can grow
+// without bloating the worker bundle.
+//
+// upload-file: Slack's new external-upload flow is three round trips
+// (files.getUploadURLExternal → PUT bytes → files.completeUploadExternal).
+// The bytes ride in as a multipart `attachment` field; the container
+// streams them out to Slack's signed URL.
+
+export type SlackOperation = 'post-message' | 'upload-file';
+
+export interface SlackSendRequest {
+  accessToken: string;
+  operation: SlackOperation;
+
+  // chat.postMessage / files.completeUploadExternal share these
+  channel: string;            // channel ID (C…/G…/D…) or name (#general)
+  threadTs?: string;          // reply in-thread when set
+
+  // post-message
+  text?: string;              // required for post-message
+  mrkdwn?: boolean;           // defaults to true on Slack's side
+  blocks?: unknown[];         // optional Block Kit payload
+
+  // upload-file
+  title?: string;             // shown in the Slack file viewer
+  initialComment?: string;    // message body posted alongside the file
+}
+
+// Wire protocol for sending a PROXIED (remote MCP) resource as a Slack file.
+// Mirrors TelegramSendRemoteResourceRequest: the worker sends only the remote
+// connection details + resolved auth header as JSON, and the resource-handler
+// container does the remote read + decode + Slack external-upload itself — so a
+// large file's bytes never transit the 128 MiB worker.
+export interface SlackSendRemoteResourceRequest {
+  slack: {
+    accessToken: string;
+    channel: string;
+    threadTs?: string;
+    title?: string;
+    initialComment?: string;
+  };
+  remote: {
+    url: string;
+    transport: string;
+    // Single header injected on the remote MCP connection (e.g. Authorization).
+    authHeader?: { name: string; value: string } | null;
+    uri: string;
+    timeoutMs: number;
+  };
+}
+
+export interface SlackSendResponse {
+  // chat.postMessage returns ts; files.completeUploadExternal returns the
+  // file id. Empty string when Slack returns ok:true with no id (shouldn't
+  // happen, but defensively typed).
+  id: string;
+  channel?: string;           // resolved channel id
+  ts?: string;                // message timestamp (post-message only)
+  permalink?: string;         // file permalink (upload-file only)
+}

package/src/slug.ts

@@ -0,0 +1,37 @@
+import { constants } from './constants';
+
+const SLUG_BYTES = 16;
+const SLUG_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const RESERVED = new Set(constants.RESERVED_SLUGS);
+
+const toHex = (bytes: Uint8Array): string => {
+  let hex = '';
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, '0');
+  }
+  return hex;
+};
+
+export const generateRandomSlug = (): string => {
+  const bytes = new Uint8Array(SLUG_BYTES);
+  crypto.getRandomValues(bytes);
+  return toHex(bytes);
+};
+
+// Opaque, unguessable token — used as the public handle for an invitation.
+export const generateRandomToken = (
+  byteLength = constants.INVITATION_TOKEN_BYTES
+): string => {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return toHex(bytes);
+};
+
+export const isReservedSlug = (slug: string): boolean =>
+  RESERVED.has(slug.toLowerCase());
+
+export const isValidSlugFormat = (slug: string): boolean =>
+  typeof slug === 'string' &&
+  slug.length >= 3 &&
+  slug.length <= 63 &&
+  SLUG_PATTERN.test(slug);

package/src/slugifyTitle.ts

@@ -0,0 +1,8 @@
+// Lowercase a human title into a slug usable as a command name / MCP id —
+// shared by prompts and resources (anything titled), so it's deliberately
+// generic rather than prompt-specific.
+export const slugifyTitle = (title: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');

package/src/sources.ts

@@ -0,0 +1,117 @@
+import { constants } from './constants';
+
+export interface Source {
+  resourceId: string;
+  uri: string;
+  title: string;
+  sourceType: 'FILE' | 'WEBSITE' | 'CUSTOM_CODE';
+  mimeType: string;
+  fileName: string | null;
+  pageNumber?: number;
+  chunkIndex?: number;
+  score?: number;
+  excerpt?: string;
+}
+
+export interface ResourceUrlContext {
+  apiUrl: string;
+  organizationId: string;
+  projectId: string;
+}
+
+/**
+ * Does this source resolve to bytes we serve, rather than to a URL a reader can
+ * open?
+ *
+ * The distinction the two formatters below need is "download link or web link",
+ * and for a long time that was the same question as "is it a FILE". It stopped
+ * being once a tool could write a resource: a script-created one holds bytes
+ * exactly as an upload does, and its uri is a `resource://` address that means
+ * nothing to a browser. Formatting it as a web link produced a dead button in
+ * whichever channel the answer went to.
+ */
+export const isDownloadableSource = (sourceType: Source['sourceType']): boolean =>
+  sourceType === constants.RESOURCE_SOURCE_TYPE_FILE ||
+  sourceType === constants.RESOURCE_SOURCE_TYPE_CUSTOM_CODE;
+
+export const isResourceSourceEnabled = (
+  resource: { showSource?: string | null } | null | undefined
+): boolean =>
+  (resource?.showSource ?? constants.STATUS_ACTIVE) !==
+  constants.STATUS_DISABLED;
+
+export const safeHostname = (url: string): string | null => {
+  if (!URL.canParse(url)) return null;
+  return new URL(url).hostname.replace(/^www\./, '');
+};
+
+export const buildResourceDownloadUrl = (
+  ctx: ResourceUrlContext,
+  resourceId: string,
+  pageNumber?: number
+): string => {
+  const fragment = pageNumber ? `#page=${pageNumber}` : '';
+  return `${ctx.apiUrl}/organization/${ctx.organizationId}/project/${ctx.projectId}/artifact/resource/${resourceId}/download${fragment}`;
+};
+
+export interface SourceButton {
+  text: string;
+  url: string;
+}
+
+const truncateLabel = (text: string, max: number): string =>
+  text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+
+export const formatSourcesAsButtons = (
+  sources: Source[],
+  ctx: ResourceUrlContext,
+  options?: { maxLabelLength?: number }
+): SourceButton[] => {
+  const maxLabelLength = options?.maxLabelLength ?? 60;
+  return sources.map((source, index) => {
+    const position = index + 1;
+    if (isDownloadableSource(source.sourceType)) {
+      const label = source.fileName || source.title;
+      const pageSuffix = source.pageNumber ? ` · p.${source.pageNumber}` : '';
+      const url = buildResourceDownloadUrl(
+        ctx,
+        source.resourceId,
+        source.pageNumber
+      );
+      return {
+        text: truncateLabel(`${position} ${label}${pageSuffix}`, maxLabelLength),
+        url
+      };
+    }
+    const domain = safeHostname(source.uri);
+    const base = domain ? `${domain} — ${source.title}` : source.title;
+    return {
+      text: truncateLabel(`${position} ${base}`, maxLabelLength),
+      url: source.uri
+    };
+  });
+};
+
+export const formatSourcesAsMarkdown = (
+  sources: Source[],
+  ctx: ResourceUrlContext
+): string => {
+  if (sources.length === 0) return '';
+  const lines = sources.map((source, index) => {
+    const position = index + 1;
+    if (isDownloadableSource(source.sourceType)) {
+      const label = source.fileName || source.title;
+      const pageSuffix = source.pageNumber ? ` · p. ${source.pageNumber}` : '';
+      const url = buildResourceDownloadUrl(
+        ctx,
+        source.resourceId,
+        source.pageNumber
+      );
+      return `${position}. [${label}${pageSuffix}](${url})`;
+    }
+    const domain = safeHostname(source.uri);
+    const label = domain ? `${domain} — ${source.title}` : source.title;
+    return `${position}. [${label}](${source.uri})`;
+  });
+  return `**Sources**\n${lines.join('\n')}`;
+};

package/src/ssrf.ts

@@ -0,0 +1,34 @@
+// Literal-host SSRF screening shared by the proxied tool dispatchers
+// (http-endpoint, mcp-proxy). The Workers runtime can't resolve DNS, so we can
+// only screen literal hosts and IPs (not DNS rebinding). Private/loopback/
+// link-local ranges are always rejected; callers may further narrow with an
+// allowlist.
+export const ipv4InPrivateRange = (host: string): boolean => {
+  const parts = host.split('.');
+  if (parts.length !== 4) return false;
+  const octets = parts.map(p => Number(p));
+  if (octets.some(o => !Number.isInteger(o) || o < 0 || o > 255)) return false;
+  const [a, b] = octets;
+  if (a === 127 || a === 10 || a === 0) return true; // loopback / private / "this host"
+  if (a === 169 && b === 254) return true; // link-local (incl. cloud metadata)
+  if (a === 192 && b === 168) return true; // private
+  if (a === 172 && b >= 16 && b <= 31) return true; // private
+  return false;
+};
+
+export const isBlockedHost = (hostname: string): boolean => {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (!host) return true;
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (host === '::1' || host === '::') return true;
+  // IPv6 link-local (fe80::/10) and unique-local (fc00::/7).
+  if (
+    host.startsWith('fe80:') ||
+    host.startsWith('fc') ||
+    host.startsWith('fd')
+  ) {
+    return true;
+  }
+  if (ipv4InPrivateRange(host)) return true;
+  return false;
+};

package/src/tallyUsageKinds.ts

@@ -0,0 +1,20 @@
+import { constants } from './constants';
+
+export interface UsageTally {
+  tool: number;
+  prompt: number;
+  resource: number;
+}
+
+// Count a batch of invocations by usage kind. Shared by the channel runner and
+// the MCP flush so both feed the artifact's denormalized usage totals the same
+// way (anything that isn't tool/prompt/resource — protocol noise — is ignored).
+export const tallyUsageKinds = (items: { kind: string }[]): UsageTally => {
+  const tally: UsageTally = { tool: 0, prompt: 0, resource: 0 };
+  for (const { kind } of items) {
+    if (kind === constants.USAGE_KIND_TOOL) tally.tool += 1;
+    else if (kind === constants.USAGE_KIND_PROMPT) tally.prompt += 1;
+    else if (kind === constants.USAGE_KIND_RESOURCE) tally.resource += 1;
+  }
+  return tally;
+};

package/src/telegramSend.ts

@@ -0,0 +1,39 @@
+// Wire protocol shared between the worker (which constructs the request) and
+// the resource-handler container (which parses it and calls the Telegram Bot
+// API). Worker sends a multipart/form-data POST with one `metadata` field
+// (JSON matching TelegramSendRequest) and exactly one `file` field (binary).
+//
+// Telegram supports one media object per send call, so unlike Gmail this is
+// always a single attachment.
+
+export interface TelegramSendRequest {
+  botToken: string;
+  chatId: number;
+  replyToMessageId?: number;
+  caption?: string;
+  parseMode?: 'HTML' | 'Markdown' | 'MarkdownV2';
+}
+
+export interface TelegramSendResponse {
+  ok: boolean;
+  result?: { message_id: number };
+  description?: string;
+}
+
+// Wire protocol for sending a PROXIED (remote MCP) resource as a file. Unlike
+// TelegramSendRequest (where the worker has already read the bytes and posts
+// them as multipart), here the worker sends only the connection details as
+// JSON and the resource-handler container does the remote read + decode + send
+// itself — so a large file's bytes never transit the 128 MiB worker. The worker
+// resolves the (small) auth header; the file itself stays in the container.
+export interface TelegramSendRemoteResourceRequest {
+  telegram: TelegramSendRequest;
+  remote: {
+    url: string;
+    transport: string;
+    // Single header injected on the remote MCP connection (e.g. Authorization).
+    authHeader?: { name: string; value: string } | null;
+    uri: string;
+    timeoutMs: number;
+  };
+}