within-sdk 1.0.0

package/dist/modules/logging.js

@@ -0,0 +1,74 @@
+import { createRequire } from "module";
+// Lazy-loaded module references for Node.js file logging
+// These are loaded dynamically to support edge environments (Cloudflare Workers, etc.)
+let fsModule = null;
+let logFilePath = null;
+let initAttempted = false;
+let useConsoleFallback = false;
+let diagnosticsSink = null;
+export function setDiagnosticsSink(fn) {
+    diagnosticsSink = fn;
+}
+/**
+ * Attempts to initialize Node.js file logging.
+ * Falls back to console.log in edge environments where fs/os modules are unavailable.
+ */
+function tryInitSync() {
+    if (initAttempted)
+        return;
+    initAttempted = true;
+    try {
+        // Use createRequire for ESM compatibility
+        // Works in Node.js ESM/CJS, fails gracefully in Workers/edge environments
+        const require = createRequire(import.meta.url);
+        const fs = require("fs");
+        const os = require("os");
+        const path = require("path");
+        const home = os.homedir?.();
+        if (home) {
+            fsModule = fs;
+            logFilePath = path.join(home, "within-sdk.log");
+        }
+        else {
+            // homedir() returned null/undefined - use console fallback
+            useConsoleFallback = true;
+        }
+    }
+    catch {
+        // Module not available or homedir() not implemented - use console fallback
+        useConsoleFallback = true;
+        fsModule = null;
+        logFilePath = null;
+    }
+}
+export function writeToLog(message) {
+    tryInitSync();
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${message}`;
+    // Tee to diagnostics if registered. Must never break logging.
+    try {
+        diagnosticsSink?.(logEntry);
+    }
+    catch {
+        // diagnostics must never break logging
+    }
+    if (useConsoleFallback) {
+        console.log(`[within-sdk] ${logEntry}`);
+        return;
+    }
+    // Node.js environment: write to file
+    if (!logFilePath || !fsModule) {
+        return;
+    }
+    try {
+        if (!fsModule.existsSync(logFilePath)) {
+            fsModule.writeFileSync(logFilePath, logEntry + "\n");
+        }
+        else {
+            fsModule.appendFileSync(logFilePath, logEntry + "\n");
+        }
+    }
+    catch {
+        // Silently fail to avoid breaking the server
+    }
+}

package/dist/modules/mcp-sdk-compat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MCP SDK Compatibility Helpers
+ *
+ * Internal utilities for handling differences between MCP SDK versions.
+ * These helpers abstract away SDK-internal details like:
+ * - Tool callback/handler property names (changed in SDK 1.24)
+ * - Zod schema internal structures (v3 vs v4)
+ */
+import { RegisteredTool, ToolCallback } from "../types.js";
+export type ToolFunctionKey = "callback" | "handler";
+/**
+ * Returns the tool function (callback/handler) from a RegisteredTool.
+ * Supports both MCP SDK 1.23- (callback) and 1.24+ (handler).
+ */
+export declare function getToolFunction(tool: RegisteredTool): ToolCallback;
+/**
+ * Returns the property key name used for the tool function ("callback" or "handler").
+ * This preserves the original property name when wrapping tools.
+ */
+export declare function getToolFunctionKey(tool: RegisteredTool): ToolFunctionKey;
+/**
+ * Returns true if the tool has a callback or handler property.
+ */
+export declare function hasToolFunction(tool: unknown): tool is RegisteredTool;
+/**
+ * Creates a new tool object with the wrapped function, preserving the original property name.
+ * This ensures MCP SDK 1.24+ gets back a tool with "handler" and 1.23- gets "callback".
+ */
+export declare function createWrappedTool(originalTool: RegisteredTool, wrappedFunction: ToolCallback): RegisteredTool;
+export declare function isZ4Schema(schema: unknown): boolean;
+export declare function getObjectShape(schema: unknown): Record<string, unknown> | undefined;
+export declare function getLiteralValue(schema: unknown): unknown;

package/dist/modules/mcp-sdk-compat.js

@@ -0,0 +1,111 @@
+/**
+ * MCP SDK Compatibility Helpers
+ *
+ * Internal utilities for handling differences between MCP SDK versions.
+ * These helpers abstract away SDK-internal details like:
+ * - Tool callback/handler property names (changed in SDK 1.24)
+ * - Zod schema internal structures (v3 vs v4)
+ */
+/**
+ * Returns the tool function (callback/handler) from a RegisteredTool.
+ * Supports both MCP SDK 1.23- (callback) and 1.24+ (handler).
+ */
+export function getToolFunction(tool) {
+    if ("handler" in tool && typeof tool.handler === "function") {
+        return tool.handler;
+    }
+    if ("callback" in tool && typeof tool.callback === "function") {
+        return tool.callback;
+    }
+    throw new Error("Tool has neither callback nor handler property");
+}
+/**
+ * Returns the property key name used for the tool function ("callback" or "handler").
+ * This preserves the original property name when wrapping tools.
+ */
+export function getToolFunctionKey(tool) {
+    if ("handler" in tool && typeof tool.handler === "function") {
+        return "handler";
+    }
+    return "callback";
+}
+/**
+ * Returns true if the tool has a callback or handler property.
+ */
+export function hasToolFunction(tool) {
+    if (!tool || typeof tool !== "object")
+        return false;
+    const t = tool;
+    return (("handler" in t && typeof t.handler === "function") ||
+        ("callback" in t && typeof t.callback === "function"));
+}
+/**
+ * Creates a new tool object with the wrapped function, preserving the original property name.
+ * This ensures MCP SDK 1.24+ gets back a tool with "handler" and 1.23- gets "callback".
+ */
+export function createWrappedTool(originalTool, wrappedFunction) {
+    const key = getToolFunctionKey(originalTool);
+    return {
+        ...originalTool,
+        [key]: wrappedFunction,
+    };
+}
+export function isZ4Schema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    return !!schema._zod;
+}
+export function getObjectShape(schema) {
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    let rawShape;
+    if (isZ4Schema(schema)) {
+        const v4Schema = schema;
+        rawShape = v4Schema._zod?.def?.shape;
+    }
+    else {
+        const v3Schema = schema;
+        // Try .shape first, then fall back to _def.shape (some v3 schema types store it there)
+        rawShape = v3Schema.shape ?? v3Schema._def?.shape;
+    }
+    if (!rawShape)
+        return undefined;
+    if (typeof rawShape === "function") {
+        try {
+            return rawShape();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return rawShape;
+}
+export function getLiteralValue(schema) {
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    if (isZ4Schema(schema)) {
+        const v4Schema = schema;
+        const def = v4Schema._zod?.def;
+        if (def?.value !== undefined)
+            return def.value;
+        // Fallback: values array (for enums)
+        if (Array.isArray(def?.values) && def.values.length > 0) {
+            return def.values[0];
+        }
+    }
+    else {
+        const v3Schema = schema;
+        const def = v3Schema._def;
+        if (def?.value !== undefined)
+            return def.value;
+        // Fallback: values array (for enums)
+        if (Array.isArray(def?.values) && def.values.length > 0) {
+            return def.values[0];
+        }
+    }
+    // Final fallback: direct .value property (some Zod versions)
+    const directValue = schema.value;
+    if (directValue !== undefined)
+        return directValue;
+    return undefined;
+}

package/dist/modules/privacy.d.ts

@@ -0,0 +1,15 @@
+export interface RedactionOptions {
+    maxFieldBytes?: number;
+    maxEventBytes?: number;
+    redactKeys?: string[];
+}
+export interface UserIdentityLike {
+    userId: string;
+    userName?: string;
+    userData?: Record<string, unknown>;
+}
+export declare function hashWithinSubject(vendorSlug: string, subject: string): string;
+export declare function hashWithinAnonymous(vendorSlug: string, value: string): string;
+export declare function sanitizeIdentity(vendorSlug: string, identity: UserIdentityLike, options?: RedactionOptions): UserIdentityLike;
+export declare function redactWithinValue(value: unknown, options?: RedactionOptions): unknown;
+export declare function stripForbiddenIdentityFields(value: unknown): unknown;

package/dist/modules/privacy.js

@@ -0,0 +1,179 @@
+import { createHash } from "node:crypto";
+const DEFAULT_SECRET_KEY_PATTERNS = [
+    "auth",
+    "authorization",
+    "cookie",
+    "email",
+    "e_mail",
+    "full_name",
+    "identity",
+    "firstname",
+    "first_name",
+    "lastname",
+    "last_name",
+    "org_domain",
+    "orgdomain",
+    "phone",
+    "requester_name",
+    "author_name",
+    "customer_name",
+    "user_name",
+    "username",
+    "token",
+    "secret",
+    "password",
+    "api_key",
+    "apikey",
+    "access_token",
+    "refresh_token",
+    "ssn",
+    "card",
+    "cvv",
+];
+const FORBIDDEN_IDENTITY_KEYS = new Set([
+    "identity",
+    "email",
+    "org_domain",
+    "orgdomain",
+    "full_name",
+    "firstname",
+    "first_name",
+    "lastname",
+    "last_name",
+    "phone",
+    "username",
+    "user_name",
+]);
+export function hashWithinSubject(vendorSlug, subject) {
+    return createHash("sha256")
+        .update(`subject:${vendorSlug.trim().toLowerCase()}:${subject.trim()}`)
+        .digest("hex");
+}
+export function hashWithinAnonymous(vendorSlug, value) {
+    return createHash("sha256")
+        .update(`anonymous:${vendorSlug.trim().toLowerCase()}:${value.trim()}`)
+        .digest("hex");
+}
+export function sanitizeIdentity(vendorSlug, identity, options = {}) {
+    return {
+        userId: hashWithinSubject(vendorSlug, identity.userId),
+        userData: redactWithinValue(identity.userData ?? {}, options),
+    };
+}
+export function redactWithinValue(value, options = {}) {
+    const seen = new WeakSet();
+    const redacted = redactAny(stripForbiddenIdentityFields(value), {
+        maxFieldBytes: options.maxFieldBytes ?? 10_000,
+        maxEventBytes: options.maxEventBytes ?? 128_000,
+        redactKeys: options.redactKeys,
+    }, seen, "");
+    return enforceEventLimit(redacted, options.maxEventBytes ?? 128_000);
+}
+export function stripForbiddenIdentityFields(value) {
+    if (Array.isArray(value))
+        return value.map(stripForbiddenIdentityFields);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (FORBIDDEN_IDENTITY_KEYS.has(normalizeKey(key)))
+            continue;
+        out[key] = stripForbiddenIdentityFields(child);
+    }
+    return out;
+}
+function redactAny(value, options, seen, key) {
+    if (isSecretKey(key, options.redactKeys))
+        return "[redacted]";
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return truncateString(redactSensitiveString(value), options.maxFieldBytes);
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "function" || typeof value === "symbol")
+        return undefined;
+    if (value instanceof ArrayBuffer || ArrayBuffer.isView(value))
+        return "[binary omitted]";
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: truncateString(redactSensitiveString(value.message), options.maxFieldBytes),
+        };
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        return value.slice(0, 100).map((item) => redactAny(item, options, seen, key));
+    }
+    if (typeof value === "object") {
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        const out = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            const redacted = redactAny(childValue, options, seen, childKey);
+            if (redacted !== undefined)
+                out[childKey] = redacted;
+        }
+        return out;
+    }
+    return String(value);
+}
+function isSecretKey(key, extra) {
+    const normalized = normalizeKey(key);
+    const patterns = extra && extra.length > 0
+        ? [...DEFAULT_SECRET_KEY_PATTERNS, ...extra.map((v) => normalizeKey(v))]
+        : DEFAULT_SECRET_KEY_PATTERNS;
+    return patterns.some((pattern) => normalized.includes(pattern));
+}
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[-\s]/g, "_");
+}
+function redactSensitiveString(value) {
+    if (isSensitiveString(value))
+        return "[redacted]";
+    return value
+        .replace(EMAIL_GLOBAL_RE, "[redacted]")
+        .replace(BEARER_GLOBAL_RE, "[redacted]")
+        .replace(API_KEY_GLOBAL_RE, "[redacted]");
+}
+function isSensitiveString(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    return EMAIL_RE.test(trimmed)
+        || PHONE_RE.test(trimmed)
+        || SSN_RE.test(trimmed)
+        || CREDIT_CARD_RE.test(trimmed)
+        || BEARER_RE.test(trimmed)
+        || API_KEY_RE.test(trimmed);
+}
+function truncateString(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    return `${value.slice(0, maxBytes)}[truncated ${Buffer.byteLength(value, "utf8")} bytes]`;
+}
+function enforceEventLimit(value, maxBytes) {
+    try {
+        const json = JSON.stringify(value);
+        if (!json || Buffer.byteLength(json, "utf8") <= maxBytes)
+            return value;
+        return { omitted: true, reason: `payload exceeded ${maxBytes} bytes` };
+    }
+    catch {
+        return { omitted: true, reason: "payload was not serializable" };
+    }
+}
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const EMAIL_GLOBAL_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const PHONE_RE = /^\+?[\d().\-\s]{8,}$/;
+const SSN_RE = /^\d{3}-?\d{2}-?\d{4}$/;
+const CREDIT_CARD_RE = /^(?:\d[ -]*?){13,19}$/;
+const BEARER_RE = /^bearer\s+[a-z0-9._~+/=-]+$/i;
+const API_KEY_RE = /^(?:sk|pk|api|key)_[a-z0-9_\-]{16,}$/i;
+const BEARER_GLOBAL_RE = /\bbearer\s+[a-z0-9._~+/=-]+/gi;
+const API_KEY_GLOBAL_RE = /\b(?:sk|pk|api|key)_[a-z0-9_\-]{16,}\b/gi;

package/dist/modules/redaction.d.ts

@@ -0,0 +1,11 @@
+import { Event, RedactFunction, UnredactedEvent } from "../types.js";
+/**
+ * Applies the customer's redaction function to all string fields in an Event object.
+ * This is the main entry point for redacting sensitive information from events
+ * before they are sent to the analytics service.
+ *
+ * @param event - The event to redact
+ * @param redactFn - The customer's redaction function
+ * @returns A new event object with all strings redacted
+ */
+export declare function redactEvent(event: UnredactedEvent, redactFn: RedactFunction): Promise<Event>;

package/dist/modules/redaction.js

@@ -0,0 +1,81 @@
+/**
+ * Set of field names that should be protected from redaction.
+ * These fields contain system-level identifiers and metadata that
+ * need to be preserved for analytics tracking.
+ */
+const PROTECTED_FIELDS = new Set([
+    "sessionId",
+    "id",
+    "projectId",
+    "server",
+    "identifyActorGivenId",
+    "identifyActorName",
+    "identifyData",
+    "resourceName",
+    "eventType",
+    "actorId",
+    "tags",
+    "properties",
+]);
+/**
+ * Recursively applies a redaction function to all string values in an object.
+ * This ensures that sensitive information is removed from all string fields
+ * before events are sent to the analytics service.
+ *
+ * @param obj - The object to redact strings from
+ * @param redactFn - The redaction function to apply to each string
+ * @param path - The current path in the object tree (used to check protected fields)
+ * @param isProtected - Whether the current object/value is within a protected field
+ * @returns A new object with all strings redacted
+ */
+async function redactStringsInObject(obj, redactFn, path = "", isProtected = false) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    // Handle strings
+    if (typeof obj === "string") {
+        // Don't redact if this field or any parent field is protected
+        if (isProtected) {
+            return obj;
+        }
+        return await redactFn(obj);
+    }
+    // Handle arrays
+    if (Array.isArray(obj)) {
+        return Promise.all(obj.map((item, index) => redactStringsInObject(item, redactFn, `${path}[${index}]`, isProtected)));
+    }
+    // Handle dates (don't redact)
+    if (obj instanceof Date) {
+        return obj;
+    }
+    // Handle objects
+    if (typeof obj === "object") {
+        const redactedObj = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // Skip functions and undefined values
+            if (typeof value === "function" || value === undefined) {
+                continue;
+            }
+            // Build the path for nested fields
+            const fieldPath = path ? `${path}.${key}` : key;
+            // Check if this field is protected (only check at top level)
+            const isFieldProtected = isProtected || (path === "" && PROTECTED_FIELDS.has(key));
+            redactedObj[key] = await redactStringsInObject(value, redactFn, fieldPath, isFieldProtected);
+        }
+        return redactedObj;
+    }
+    // For all other types (numbers, booleans, etc.), return as-is
+    return obj;
+}
+/**
+ * Applies the customer's redaction function to all string fields in an Event object.
+ * This is the main entry point for redacting sensitive information from events
+ * before they are sent to the analytics service.
+ *
+ * @param event - The event to redact
+ * @param redactFn - The customer's redaction function
+ * @returns A new event object with all strings redacted
+ */
+export async function redactEvent(event, redactFn) {
+    return redactStringsInObject(event, redactFn, "", false);
+}

package/dist/modules/sanitization.d.ts

@@ -0,0 +1,9 @@
+import { Event, UnredactedEvent } from "../types.js";
+/**
+ * Sanitizes an event by redacting non-text content blocks from responses
+ * and large base64-encoded strings from parameters.
+ *
+ * This is a synchronous operation that returns a new object without mutating the original.
+ * It should run after customer redaction in the event pipeline.
+ */
+export declare function sanitizeEvent<T extends Event | UnredactedEvent>(event: T): T;

package/dist/modules/sanitization.js

@@ -0,0 +1,111 @@
+const BASE64_PATTERN = /^[A-Za-z0-9+/\n\r]+=*$/;
+const SIZE_GATE = 10240; // 10KB - skip strings shorter than this
+/**
+ * Sanitizes an event by redacting non-text content blocks from responses
+ * and large base64-encoded strings from parameters.
+ *
+ * This is a synchronous operation that returns a new object without mutating the original.
+ * It should run after customer redaction in the event pipeline.
+ */
+export function sanitizeEvent(event) {
+    const result = { ...event };
+    if (result.response != null) {
+        result.response = sanitizeResponse(result.response);
+    }
+    if (result.parameters != null) {
+        result.parameters = sanitizeParameters(result.parameters);
+    }
+    return result;
+}
+/**
+ * Sanitizes response content blocks by replacing non-text content types
+ * with informative redaction messages.
+ */
+function sanitizeResponse(response) {
+    if (response == null || typeof response !== "object") {
+        return response;
+    }
+    const result = { ...response };
+    if (Array.isArray(result.content)) {
+        result.content = result.content.map(sanitizeContentBlock);
+    }
+    if (result.structuredContent != null &&
+        typeof result.structuredContent === "object") {
+        result.structuredContent = sanitizeParameters(result.structuredContent);
+    }
+    return result;
+}
+/**
+ * Sanitizes a single content block based on its type discriminator.
+ */
+function sanitizeContentBlock(block) {
+    if (block == null || typeof block !== "object") {
+        return block;
+    }
+    switch (block.type) {
+        case "text":
+            return block;
+        case "image":
+            return {
+                type: "text",
+                text: "[image content redacted - not supported by Within SDK]",
+            };
+        case "audio":
+            return {
+                type: "text",
+                text: "[audio content redacted - not supported by Within SDK]",
+            };
+        case "resource":
+            return sanitizeResourceBlock(block);
+        case "resource_link":
+            return block;
+        default:
+            return {
+                type: "text",
+                text: `[unsupported content type "${block.type}" redacted - not supported by Within SDK]`,
+            };
+    }
+}
+/**
+ * Sanitizes an embedded resource content block.
+ * BlobResourceContents (has `blob` field) are redacted.
+ * TextResourceContents (has `text` field) pass through.
+ */
+function sanitizeResourceBlock(block) {
+    if (block.resource && block.resource.blob !== undefined) {
+        return {
+            type: "text",
+            text: "[binary resource content redacted - not supported by Within SDK]",
+        };
+    }
+    return block;
+}
+/**
+ * Recursively scans parameters for large base64-encoded strings and replaces them.
+ * Uses a size gate (10KB) to avoid regex testing on small strings.
+ */
+function sanitizeParameters(obj) {
+    if (obj == null) {
+        return obj;
+    }
+    if (typeof obj === "string") {
+        if (obj.length >= SIZE_GATE && BASE64_PATTERN.test(obj)) {
+            return "[binary data redacted - not supported by Within SDK]";
+        }
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sanitizeParameters);
+    }
+    if (obj instanceof Date) {
+        return obj;
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = sanitizeParameters(value);
+        }
+        return result;
+    }
+    return obj;
+}

package/dist/modules/session.d.ts

@@ -0,0 +1,22 @@
+import { WithinTrackingData, MCPServerLike, SessionInfo, CompatibleRequestHandlerExtra } from "../types.js";
+export declare function newSessionId(): string;
+/**
+ * Creates a deterministic KSUID session ID from an MCP sessionId and optional projectId.
+ * The same inputs will always produce the same session ID, enabling correlation across server restarts.
+ *
+ * @param mcpSessionId - The session ID from the MCP protocol
+ * @param projectId - Optional Within project ID to include in the hash
+ * @returns A KSUID with "ses" prefix derived deterministically from the inputs
+ */
+export declare function deriveSessionIdFromMCPSession(mcpSessionId: string, projectId?: string): string;
+/**
+ * Gets or generates a session ID for the server.
+ * Prioritizes MCP protocol sessionId over Within-generated sessionId.
+ *
+ * @param server - The MCP server instance
+ * @param extra - Optional extra data containing MCP sessionId
+ * @returns The session ID to use for events
+ */
+export declare function getServerSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string;
+export declare function setLastActivity(server: MCPServerLike): void;
+export declare function getSessionInfo(server: MCPServerLike, data: WithinTrackingData | undefined): SessionInfo;