@ductape/sdk 0.1.8 → 0.1.10

package/dist/sessions/sessions.helper.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Sessions Helper
+ *
+ * Utility functions for session verification and context extraction
+ * to be used across all executors (actions, database, graph, vector, etc.)
+ *
+ * Session token format: session_tag:jwt_token
+ * The token contains both the session tag and JWT in a single string.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAndExtractSession = verifyAndExtractSession;
+exports.getSessionLogFields = getSessionLogFields;
+exports.resolveSessionReferences = resolveSessionReferences;
+exports.processSessionForExecution = processSessionForExecution;
+const sessions_resolver_1 = require("./sessions.resolver");
+/**
+ * Verify a session token and extract context for logging
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param env - Current environment slug
+ * @param selector - Optional selector path for identifier extraction
+ * @returns Session verification result with context for logging
+ */
+async function verifyAndExtractSession(sessionToken, privateKey, env, selector) {
+    // No session provided - return valid (session is optional)
+    if (!sessionToken) {
+        return { valid: true };
+    }
+    // Parse the token format (session_tag:jwt)
+    const parts = (0, sessions_resolver_1.parseSessionToken)(sessionToken);
+    if (!parts) {
+        return {
+            valid: false,
+            error: 'Invalid session token format. Expected format: session_tag:jwt_token',
+        };
+    }
+    // Verify the JWT
+    const sessionData = await (0, sessions_resolver_1.verifySessionToken)(sessionToken, privateKey, parts.tag, env);
+    if (!sessionData) {
+        // Try to give a more specific error by decoding (without verifying) to check env/tag/exp/signature
+        let reason = 'Token may be invalid or expired.';
+        try {
+            const JWT = await Promise.resolve().then(() => __importStar(require('jsonwebtoken')));
+            const decoded = JWT.decode(parts.jwt);
+            if (decoded) {
+                if (env != null && decoded.env !== env) {
+                    reason = `Environment mismatch: token has env "${decoded.env}" but request has env "${env}". Use the same env as when the session was created.`;
+                }
+                else if (parts.tag && decoded.session && parts.tag !== decoded.session) {
+                    reason = `Session tag mismatch: token tag "${decoded.session}" does not match "${parts.tag}".`;
+                }
+                else if (decoded.exp && decoded.exp * 1000 < Date.now()) {
+                    reason = 'Token has expired.';
+                }
+                else {
+                    reason =
+                        'JWT signature verification failed. Ensure the request uses the same product and workspace as when the session was created (e.g. publishable key must resolve to that workspace).';
+                }
+            }
+        }
+        catch (_a) {
+            // ignore decode errors
+        }
+        return {
+            valid: false,
+            error: `Session token verification failed. ${reason}`,
+        };
+    }
+    // Extract session context for logging
+    const context = (0, sessions_resolver_1.extractSessionContext)(sessionData, selector);
+    return {
+        valid: true,
+        sessionData,
+        context,
+    };
+}
+/**
+ * Extract log fields from session context
+ */
+function getSessionLogFields(context) {
+    if (!context) {
+        return {};
+    }
+    return {
+        session_user_id: context.identifier,
+        session_id: context.session_id,
+        session_tag: context.session_tag,
+    };
+}
+/**
+ * Resolve $Session{key}{...} references in input data
+ *
+ * @param input - Input data that may contain session references
+ * @param sessionData - Verified session data
+ * @returns Resolved input with session references replaced
+ */
+function resolveSessionReferences(input, sessionData) {
+    if (!sessionData || !(0, sessions_resolver_1.mightContainSessions)(input)) {
+        return input;
+    }
+    const resolver = (0, sessions_resolver_1.createSessionsResolver)(sessionData);
+    const result = resolver.resolveObject(input);
+    return result.value;
+}
+/**
+ * Combined helper that verifies session and resolves references in one call
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param input - Input data that may contain $Session{} references
+ * @param env - Current environment slug
+ * @param selectorOrOptions - Optional selector path OR options object with fetchSessionSelector
+ */
+async function processSessionForExecution(sessionToken, privateKey, input, env, selectorOrOptions) {
+    // No session - return input as-is
+    if (!sessionToken) {
+        return { input, logFields: {} };
+    }
+    // Parse options
+    let selector;
+    let fetchSessionSelector;
+    if (typeof selectorOrOptions === 'string') {
+        selector = selectorOrOptions;
+    }
+    else if (selectorOrOptions) {
+        selector = selectorOrOptions.selector;
+        fetchSessionSelector = selectorOrOptions.fetchSessionSelector;
+    }
+    // If no selector provided but we have a fetch function, try to get it from config
+    if (!selector && fetchSessionSelector) {
+        const parts = (0, sessions_resolver_1.parseSessionToken)(sessionToken);
+        if (parts) {
+            selector = await fetchSessionSelector(parts.tag);
+        }
+    }
+    // Verify session
+    const verification = await verifyAndExtractSession(sessionToken, privateKey, env, selector);
+    if (!verification.valid) {
+        return {
+            input,
+            logFields: {},
+            error: verification.error,
+        };
+    }
+    // Resolve session references in input
+    const resolvedInput = resolveSessionReferences(input, verification.sessionData);
+    // Get log fields
+    const logFields = getSessionLogFields(verification.context);
+    return {
+        input: resolvedInput,
+        logFields,
+        sessionData: verification.sessionData,
+    };
+}
+//# sourceMappingURL=sessions.helper.js.map

package/dist/sessions/sessions.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.helper.js","sourceRoot":"","sources":["../../src/sessions/sessions.helper.ts"],"names":[],"mappings":"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"}

package/dist/sessions/sessions.resolver.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Sessions Resolver
+ *
+ * Utility for detecting and resolving $Session{key}{...path} patterns at runtime.
+ * This module handles:
+ * - Pattern detection in strings and objects
+ * - Session token verification and data extraction
+ * - Nested key path resolution (e.g., $Session{user}{address}{city})
+ * - Recursive resolution of nested objects
+ * - Internal caching of verified session tokens to avoid repeated JWT verification
+ */
+/**
+ * Redis client interface (compatible with ioredis)
+ */
+interface IRedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, exMode?: string, exValue?: number): Promise<string | null>;
+    setex(key: string, seconds: number, value: string): Promise<string | null>;
+}
+/**
+ * Set the Redis client for 2-tier session caching
+ * When set, oldest local cache entries will be moved to Redis when local cache fills up
+ */
+export declare function setSessionCacheRedisClient(client: IRedisClient | null): void;
+/**
+ * Clear all cached sessions (local and Redis)
+ */
+export declare function clearSessionCache(): void;
+/**
+ * Get session cache statistics (for debugging/monitoring)
+ */
+export declare function getSessionCacheStats(): {
+    localSize: number;
+    maxLocalSize: number;
+    hasRedis: boolean;
+};
+/**
+ * Regex pattern to detect $Session{key} or $Session{key}{nested}{path} syntax (full string match)
+ * Matches: $Session{user}, $Session{user}{id}, $Session{user}{address}{city}
+ * Also supports array indices: $Session{users}{0}{name}, $Session{data}{items}{2}{value}
+ */
+export declare const SESSION_PATTERN: RegExp;
+/**
+ * Regex pattern to find all $Session{key}{...} occurrences in a string
+ * Supports both object keys and array indices
+ */
+export declare const SESSION_PATTERN_GLOBAL: RegExp;
+/**
+ * Result of parsing a session token
+ */
+export interface ISessionTokenParts {
+    /** The session tag extracted from the token */
+    tag: string;
+    /** The JWT portion of the token */
+    jwt: string;
+}
+/**
+ * Result of verifying and decoding a session token
+ */
+export interface ISessionData {
+    /** The session tag */
+    tag: string;
+    /** The session ID */
+    sessionId: string;
+    /** The user identifier from session creation */
+    identifier?: string;
+    /** The session data payload */
+    data: Record<string, unknown>;
+    /** Session expiration timestamp */
+    expiresAt?: number;
+    /** Environment slug */
+    env?: string;
+}
+/**
+ * Result of checking if a value is a session reference
+ */
+export interface ISessionCheck {
+    /** Whether the value is a session reference */
+    isSession: boolean;
+    /** The key path segments if it's a session reference */
+    keyPath?: string[];
+}
+/**
+ * Options for resolving sessions at runtime
+ */
+export interface IResolveSessionOptions {
+    /** Current environment slug */
+    env?: string;
+}
+/**
+ * Result of session resolution
+ */
+export interface ISessionResolutionResult<T = unknown> {
+    /** The resolved value with session references replaced */
+    value: T;
+    /** Keys that were resolved */
+    resolvedKeys: string[];
+    /** Keys that failed to resolve */
+    failedKeys: string[];
+}
+/**
+ * Session context containing identifier and session metadata
+ */
+export interface ISessionContext {
+    /** User identifier from session */
+    identifier: string;
+    /** Session ID */
+    session_id: string;
+    /** Session tag */
+    session_tag: string;
+    /** Session data payload */
+    data: Record<string, unknown>;
+}
+/**
+ * Parse a session token in format "session_tag:jwt_token"
+ */
+export declare function parseSessionToken(token: string): ISessionTokenParts | null;
+/**
+ * Check if a string value is a session reference
+ */
+export declare function isSessionReference(value: string): ISessionCheck;
+/**
+ * Check if a string contains any session references (partial matches)
+ */
+export declare function containsSessionReferences(value: string): boolean;
+/**
+ * Extract all session references from a string
+ */
+export declare function extractSessionReferences(value: string): Array<{
+    full: string;
+    keyPath: string[];
+}>;
+/**
+ * Get a nested value from an object using a key path
+ * Supports both object keys and array indices (numeric keys)
+ *
+ * @example
+ * getNestedValue({ users: [{ name: 'John' }] }, ['users', '0', 'name']) // returns 'John'
+ * getNestedValue({ data: { items: ['a', 'b', 'c'] } }, ['data', 'items', '1']) // returns 'b'
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, keyPath: string[]): unknown;
+/**
+ * Verify and decode a session JWT token
+ * Returns the session data if valid, null otherwise
+ *
+ * Uses 2-tier caching (local memory + Redis) to avoid repeated JWT verification.
+ * Cache entries expire 30 seconds before the actual session expiration.
+ * When local cache fills up (100 entries), oldest 50 are moved to Redis.
+ */
+export declare function verifySessionToken(token: string, privateKey: string, expectedTag?: string, expectedEnv?: string): Promise<ISessionData | null>;
+/**
+ * Extract session context from a verified session
+ * This includes identifier, session_id, session_tag for logging
+ */
+export declare function extractSessionContext(sessionData: ISessionData, selector?: string): ISessionContext;
+/**
+ * Type guard to check if a value might contain session references
+ */
+export declare function mightContainSessions(value: unknown): boolean;
+/**
+ * Recursively find all session references in an object
+ */
+export declare function findAllSessionReferences(obj: unknown): Array<{
+    full: string;
+    keyPath: string[];
+}>;
+/**
+ * Replace a single session reference with its resolved value
+ */
+export declare function replaceSessionInString(value: string, reference: string, resolvedValue: unknown): string;
+/**
+ * Create a sessions resolver instance
+ */
+export declare function createSessionsResolver(sessionData: ISessionData): {
+    resolveReference: (keyPath: string[]) => unknown;
+    resolveString: (value: string) => ISessionResolutionResult<string>;
+    resolveObject: <T>(obj: T) => ISessionResolutionResult<T>;
+    getSessionData: () => ISessionData;
+};
+/**
+ * Error class for session resolution
+ */
+export declare class SessionResolutionError extends Error {
+    code: string;
+    details?: unknown;
+    constructor(message: string, code: string, details?: unknown);
+}
+export {};