@jack-kernel/sdk 1.0.0 → 1.2.1

package/dist/esm/yellow/event-mapper.js

@@ -0,0 +1,248 @@
+/**
+ * Yellow Network Event-to-Status Mapper
+ *
+ * Maps Yellow Network events, channel statuses, and state intents to JACK
+ * ExecutionStatus values. These are pure functions with no side effects,
+ * extracted from the dashboard's route.ts mapping tables into SDK-level
+ * reusable functions.
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+import { ExecutionStatus } from '../types.js';
+// ============================================================================
+// Terminal statuses — only SETTLED, ABORTED, and EXPIRED are terminal
+// ============================================================================
+const TERMINAL_STATUSES = new Set([
+    ExecutionStatus.SETTLED,
+    ExecutionStatus.ABORTED,
+    ExecutionStatus.EXPIRED,
+]);
+// ============================================================================
+// Yellow Event Mapping Table
+// ============================================================================
+const EVENT_STATUS_MAP = {
+    quote_accepted: {
+        executionStatus: ExecutionStatus.QUOTED,
+        stepLabel: 'Solver Quote Accepted (Yellow Network)',
+        stepStatus: 'COMPLETED',
+        isTerminal: false,
+    },
+    solver_quoted: {
+        executionStatus: ExecutionStatus.QUOTED,
+        stepLabel: 'Solver Quote Received (Yellow Network)',
+        stepStatus: 'COMPLETED',
+        isTerminal: false,
+    },
+    execution_started: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'Execution Started (Yellow Network)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    routing_started: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'Cross-Chain Routing Started (Yellow Network)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    settlement_submitted: {
+        executionStatus: ExecutionStatus.SETTLING,
+        stepLabel: 'Settlement Submitted (Yellow Network)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    settled: {
+        executionStatus: ExecutionStatus.SETTLED,
+        stepLabel: 'Settlement Finalized (Yellow Network)',
+        stepStatus: 'COMPLETED',
+        isTerminal: true,
+    },
+    settlement_finalized: {
+        executionStatus: ExecutionStatus.SETTLED,
+        stepLabel: 'Settlement Finalized (Yellow Network)',
+        stepStatus: 'COMPLETED',
+        isTerminal: true,
+    },
+    failed: {
+        executionStatus: ExecutionStatus.ABORTED,
+        stepLabel: 'Execution Failed (Yellow Network)',
+        stepStatus: 'FAILED',
+        isTerminal: true,
+    },
+    execution_failed: {
+        executionStatus: ExecutionStatus.ABORTED,
+        stepLabel: 'Execution Failed (Yellow Network)',
+        stepStatus: 'FAILED',
+        isTerminal: true,
+    },
+    settlement_failed: {
+        executionStatus: ExecutionStatus.ABORTED,
+        stepLabel: 'Settlement Failed (Yellow Network)',
+        stepStatus: 'FAILED',
+        isTerminal: true,
+    },
+    expired: {
+        executionStatus: ExecutionStatus.EXPIRED,
+        stepLabel: 'Intent Expired (Yellow Network)',
+        stepStatus: 'FAILED',
+        isTerminal: true,
+    },
+    canceled: {
+        executionStatus: ExecutionStatus.ABORTED,
+        stepLabel: 'Intent Canceled (Yellow Network)',
+        stepStatus: 'FAILED',
+        isTerminal: true,
+    },
+};
+// ============================================================================
+// Channel Status Mapping Table
+// ============================================================================
+const CHANNEL_STATUS_MAP = {
+    void: {
+        executionStatus: ExecutionStatus.CREATED,
+        stepLabel: 'Channel Status: VOID (ERC-7824)',
+        stepStatus: 'COMPLETED',
+        isTerminal: false,
+    },
+    initial: {
+        executionStatus: ExecutionStatus.QUOTED,
+        stepLabel: 'Channel Status: INITIAL (ERC-7824)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    active: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'Channel Status: ACTIVE (ERC-7824)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    dispute: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'Channel Status: DISPUTE (ERC-7824)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    final: {
+        executionStatus: ExecutionStatus.SETTLED,
+        stepLabel: 'Channel Status: FINAL (ERC-7824)',
+        stepStatus: 'COMPLETED',
+        isTerminal: true,
+    },
+};
+// ============================================================================
+// State Intent Mapping Table
+// ============================================================================
+const STATE_INTENT_MAP = {
+    initialize: {
+        executionStatus: ExecutionStatus.QUOTED,
+        stepLabel: 'State Intent: INITIALIZE (ERC-7824)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    operate: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'State Intent: OPERATE (ERC-7824)',
+        stepStatus: 'IN_PROGRESS',
+        isTerminal: false,
+    },
+    resize: {
+        executionStatus: ExecutionStatus.EXECUTING,
+        stepLabel: 'State Intent: RESIZE (ERC-7824)',
+        stepStatus: 'COMPLETED',
+        isTerminal: false,
+    },
+    finalize: {
+        executionStatus: ExecutionStatus.SETTLED,
+        stepLabel: 'State Intent: FINALIZE (ERC-7824)',
+        stepStatus: 'COMPLETED',
+        isTerminal: true,
+    },
+};
+// ============================================================================
+// Normalization Helper
+// ============================================================================
+/**
+ * Normalizes an event/status/intent string to lowercase with underscores.
+ * Trims whitespace and replaces spaces and hyphens with underscores.
+ */
+function normalizeKey(value) {
+    return value.trim().toLowerCase().replace(/[\s-]+/g, '_');
+}
+// ============================================================================
+// Public Mapping Functions
+// ============================================================================
+/**
+ * Map a Yellow Network event name to a JACK MappedEvent.
+ *
+ * Accepts event names in any casing; normalizes to lowercase with underscores.
+ * Returns undefined for unknown events.
+ *
+ * @param event - The Yellow Network event name (e.g., "quote_accepted", "settled")
+ * @returns The corresponding MappedEvent, or undefined if the event is unknown
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5
+ */
+export function mapYellowEvent(event) {
+    const key = normalizeKey(event);
+    return Object.hasOwn(EVENT_STATUS_MAP, key) ? EVENT_STATUS_MAP[key] : undefined;
+}
+/**
+ * Map a channel status to a JACK MappedEvent.
+ *
+ * Accepts channel statuses in any casing (e.g., "ACTIVE", "active", "Active").
+ * Returns undefined for unknown statuses.
+ *
+ * @param status - The ERC-7824 channel status (e.g., "VOID", "ACTIVE", "FINAL")
+ * @returns The corresponding MappedEvent, or undefined if the status is unknown
+ *
+ * Requirement: 9.6
+ */
+export function mapChannelStatus(status) {
+    const key = normalizeKey(status);
+    return Object.hasOwn(CHANNEL_STATUS_MAP, key) ? CHANNEL_STATUS_MAP[key] : undefined;
+}
+/**
+ * Map a state intent to a JACK MappedEvent.
+ *
+ * Accepts state intents in any casing (e.g., "FINALIZE", "finalize", "Finalize").
+ * Returns undefined for unknown intents.
+ *
+ * @param intent - The ERC-7824 state intent (e.g., "INITIALIZE", "OPERATE", "FINALIZE")
+ * @returns The corresponding MappedEvent, or undefined if the intent is unknown
+ *
+ * Requirement: 9.6
+ */
+export function mapStateIntent(intent) {
+    const key = normalizeKey(intent);
+    return Object.hasOwn(STATE_INTENT_MAP, key) ? STATE_INTENT_MAP[key] : undefined;
+}
+/**
+ * Infer the best mapping from a notification payload.
+ *
+ * Checks fields in priority order: event → channelStatus → stateIntent.
+ * Returns the first successful mapping, or undefined if no field matches.
+ *
+ * @param notification - An object with optional event, channelStatus, and stateIntent fields
+ * @returns The best matching MappedEvent, or undefined if no mapping is found
+ *
+ * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+export function inferMapping(notification) {
+    if (notification.event) {
+        const mapped = mapYellowEvent(notification.event);
+        if (mapped)
+            return mapped;
+    }
+    if (notification.channelStatus) {
+        const mapped = mapChannelStatus(notification.channelStatus);
+        if (mapped)
+            return mapped;
+    }
+    if (notification.stateIntent) {
+        const mapped = mapStateIntent(notification.stateIntent);
+        if (mapped)
+            return mapped;
+    }
+    return undefined;
+}
+//# sourceMappingURL=event-mapper.js.map

package/dist/esm/yellow/event-mapper.js.map

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

package/dist/esm/yellow/serialization.js

@@ -0,0 +1,125 @@
+/**
+ * Yellow Network Integration - BigInt Serialization Utilities
+ *
+ * Provides helpers to ensure all BigInt values from NitroliteClient responses
+ * are converted to string representations in public-facing types, making
+ * ChannelState and YellowQuote objects fully JSON-serializable via JSON.stringify.
+ *
+ * Requirements: 11.1, 11.2, 11.5
+ */
+// ============================================================================
+// Core BigInt-to-string conversion
+// ============================================================================
+/**
+ * Recursively converts any BigInt values in an object (or nested objects/arrays)
+ * to their string representation. All other value types are left unchanged.
+ *
+ * This is the foundational utility used by the type-specific helpers below.
+ * It handles the case where NitroliteClient responses may contain raw BigInt
+ * values that would cause JSON.stringify to throw.
+ *
+ * @param value - Any value that may contain BigInt values at any nesting level
+ * @returns A new value with all BigInt instances replaced by their string form
+ *
+ * Requirement 11.5: Convert BigInt values to string representation for JSON compatibility
+ */
+export function serializeBigIntToString(value) {
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serializeBigIntToString(item));
+    }
+    if (typeof value === 'object') {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = serializeBigIntToString(val);
+        }
+        return result;
+    }
+    // Primitive types (string, number, boolean) pass through unchanged
+    return value;
+}
+// ============================================================================
+// Type-specific serialization helpers
+// ============================================================================
+/**
+ * Ensures a ChannelState object is fully JSON-serializable.
+ *
+ * Converts any BigInt values that may be present in the ChannelState
+ * (particularly in allocation amounts, challengePeriod, challengeExpiration,
+ * stateVersion, chainId, createdAt, updatedAt) to their appropriate
+ * JSON-compatible types (string for amounts, number for numeric fields).
+ *
+ * @param state - A ChannelState that may contain BigInt values from NitroliteClient
+ * @returns A new ChannelState with all values JSON-serializable
+ *
+ * Requirements: 11.1, 11.5
+ */
+export function toSerializableChannelState(state) {
+    return {
+        channelId: String(state.channelId),
+        status: state.status,
+        chainId: Number(state.chainId),
+        token: String(state.token),
+        allocations: state.allocations.map(toSerializableAllocation),
+        stateVersion: Number(state.stateVersion),
+        stateIntent: String(state.stateIntent),
+        stateHash: state.stateHash !== undefined ? String(state.stateHash) : undefined,
+        adjudicator: String(state.adjudicator),
+        challengePeriod: Number(state.challengePeriod),
+        challengeExpiration: state.challengeExpiration !== undefined ? Number(state.challengeExpiration) : undefined,
+        createdAt: Number(state.createdAt),
+        updatedAt: Number(state.updatedAt),
+    };
+}
+/**
+ * Ensures a ChannelAllocation object is fully JSON-serializable.
+ *
+ * The `amount` field is the most likely to contain a BigInt from NitroliteClient
+ * responses. This helper converts it to a string representation.
+ *
+ * @param allocation - A ChannelAllocation that may contain BigInt amount
+ * @returns A new ChannelAllocation with amount as string
+ *
+ * Requirement 11.5
+ */
+function toSerializableAllocation(allocation) {
+    return {
+        destination: String(allocation.destination),
+        token: String(allocation.token),
+        amount: typeof allocation.amount === 'bigint'
+            ? allocation.amount.toString()
+            : String(allocation.amount),
+    };
+}
+/**
+ * Ensures a YellowQuote object is fully JSON-serializable.
+ *
+ * Converts any BigInt values that may be present in the YellowQuote
+ * (particularly amountIn and amountOut from solver responses) to their
+ * string representation.
+ *
+ * @param quote - A YellowQuote that may contain BigInt values from ClearNode
+ * @returns A new YellowQuote with all values JSON-serializable
+ *
+ * Requirement 11.2
+ */
+export function toSerializableYellowQuote(quote) {
+    return {
+        solverId: String(quote.solverId),
+        channelId: String(quote.channelId),
+        amountIn: typeof quote.amountIn === 'bigint'
+            ? quote.amountIn.toString()
+            : String(quote.amountIn),
+        amountOut: typeof quote.amountOut === 'bigint'
+            ? quote.amountOut.toString()
+            : String(quote.amountOut),
+        estimatedTime: Number(quote.estimatedTime),
+        timestamp: Number(quote.timestamp),
+    };
+}
+//# sourceMappingURL=serialization.js.map

package/dist/esm/yellow/serialization.js.map

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

package/dist/esm/yellow/session-key-manager.js

@@ -0,0 +1,302 @@
+/**
+ * Session Key Manager for Yellow Network ClearNode Authentication
+ *
+ * Handles session key generation, EIP-712 authentication flow, and session lifecycle.
+ *
+ * Authentication flow:
+ * 1. Generate session keypair via viem's generatePrivateKey + privateKeyToAccount
+ * 2. Send auth_request message with session key address, allowances, expiry, scope
+ * 3. Receive auth_challenge from ClearNode
+ * 4. Sign challenge with main wallet via EIP-712 typed data
+ * 5. Send auth_verify with signed challenge
+ * 6. Receive confirmation and store session state
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
+ */
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+// ============================================================================
+// Message Factory Functions (local stubs for @erc7824/nitrolite)
+// ============================================================================
+/**
+ * Create an auth_request message for ClearNode.
+ *
+ * This is a local implementation matching the @erc7824/nitrolite
+ * createAuthRequestMessage API. It constructs a JSON-RPC style message
+ * with the session key details and allowances.
+ *
+ * @param params - Auth request parameters
+ * @returns JSON string of the auth_request message
+ */
+export function createAuthRequestMessage(params) {
+    return JSON.stringify({
+        method: 'auth_request',
+        params: {
+            wallet: params.wallet,
+            participant: params.participant,
+            allowances: params.allowances,
+            expire: params.expire,
+            scope: params.scope,
+        },
+    });
+}
+/**
+ * Create an EIP-712 auth message signer using the provided wallet client.
+ *
+ * This is a local implementation matching the @erc7824/nitrolite
+ * createEIP712AuthMessageSigner API. It returns a function that signs
+ * a challenge string using EIP-712 typed data via the wallet client.
+ *
+ * The EIP-712 domain and types follow the Yellow Network auth protocol:
+ * - Domain: { name: "Yellow ClearNode", version: "1" }
+ * - Types: { Auth: [{ name: "challenge", type: "string" }] }
+ *
+ * @param walletClient - The viem WalletClient to sign with
+ * @returns A function that takes a challenge string and returns the EIP-712 signature
+ */
+export function createEIP712AuthMessageSigner(walletClient) {
+    return async (challenge) => {
+        const account = walletClient.account;
+        if (!account) {
+            throw new Error('WalletClient must have an account attached for EIP-712 signing');
+        }
+        const signature = await walletClient.signTypedData({
+            account,
+            domain: {
+                name: 'Yellow ClearNode',
+                version: '1',
+            },
+            types: {
+                Auth: [{ name: 'challenge', type: 'string' }],
+            },
+            primaryType: 'Auth',
+            message: {
+                challenge,
+            },
+        });
+        return signature;
+    };
+}
+// ============================================================================
+// SessionKeyManager
+// ============================================================================
+/** Default session expiry: 1 hour in seconds */
+const DEFAULT_SESSION_EXPIRY = 3600;
+/** Default application scope */
+const DEFAULT_SCOPE = 'jack-kernel';
+/** Timeout for auth messages in milliseconds */
+const AUTH_TIMEOUT = 30_000;
+/**
+ * Manages session key generation, ClearNode authentication, and session lifecycle.
+ *
+ * The SessionKeyManager generates ephemeral session keypairs for signing offchain
+ * messages, authenticates them with ClearNode via EIP-712, and tracks session expiry
+ * to support automatic re-authentication when the session expires.
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
+ */
+export class SessionKeyManager {
+    walletClient;
+    connection;
+    sessionAccount = null;
+    sessionPrivateKey = null;
+    _sessionInfo = null;
+    lastAuthParams = null;
+    /**
+     * @param walletClient - The main wallet's viem WalletClient for EIP-712 signing
+     * @param connection - The ClearNodeConnection for sending/receiving auth messages
+     */
+    constructor(walletClient, connection) {
+        this.walletClient = walletClient;
+        this.connection = connection;
+    }
+    /**
+     * Generate a session keypair and authenticate with ClearNode.
+     *
+     * Flow:
+     * 1. Generate session keypair (Requirement 2.1)
+     * 2. Send auth_request with session address, allowances, expiry, scope (Requirement 2.2)
+     * 3. Receive auth_challenge from ClearNode
+     * 4. Sign challenge with main wallet via EIP-712 (Requirement 2.3)
+     * 5. Send auth_verify with signed challenge
+     * 6. Receive confirmation and store session state (Requirement 2.4)
+     *
+     * @param params - Authentication parameters including allowances and optional expiry/scope
+     * @returns Session information including address, expiry, and authentication status
+     * @throws Error if authentication fails or times out (Requirement 2.5)
+     */
+    async authenticate(params) {
+        // Store params for potential re-authentication (Requirement 2.6)
+        this.lastAuthParams = params;
+        // Step 1: Generate session keypair (Requirement 2.1)
+        this.sessionPrivateKey = generatePrivateKey();
+        this.sessionAccount = privateKeyToAccount(this.sessionPrivateKey);
+        const sessionAddress = this.sessionAccount.address;
+        const walletAddress = this.walletClient.account?.address;
+        if (!walletAddress) {
+            throw new Error('WalletClient must have an account attached for authentication');
+        }
+        const expiresAt = params.expiresAt ?? Math.floor(Date.now() / 1000) + DEFAULT_SESSION_EXPIRY;
+        const scope = params.scope ?? DEFAULT_SCOPE;
+        // Step 2: Send auth_request (Requirement 2.2)
+        const authRequestMsg = createAuthRequestMessage({
+            wallet: walletAddress,
+            participant: sessionAddress,
+            allowances: params.allowances,
+            expire: expiresAt,
+            scope,
+        });
+        let challengeResponse;
+        try {
+            challengeResponse = await this.connection.sendAndWait(authRequestMsg, 'auth_challenge', AUTH_TIMEOUT);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Authentication failed: could not receive auth_challenge - ${message}`);
+        }
+        // Step 3: Extract challenge and sign with main wallet via EIP-712 (Requirement 2.3)
+        const challenge = challengeResponse.challenge
+            ?? challengeResponse.data?.challenge;
+        if (!challenge || typeof challenge !== 'string') {
+            throw new Error('Authentication failed: invalid auth_challenge response - missing challenge string');
+        }
+        const eip712Signer = createEIP712AuthMessageSigner(this.walletClient);
+        let signature;
+        try {
+            signature = await eip712Signer(challenge);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Authentication failed: EIP-712 signing error - ${message}`);
+        }
+        // Step 4: Send auth_verify with signed challenge
+        const authVerifyMsg = JSON.stringify({
+            method: 'auth_verify',
+            params: {
+                participant: sessionAddress,
+                signature,
+                challenge,
+            },
+        });
+        let verifyResponse;
+        try {
+            verifyResponse = await this.connection.sendAndWait(authVerifyMsg, 'auth_verify', AUTH_TIMEOUT);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Authentication failed: could not receive auth_verify confirmation - ${message}`);
+        }
+        // Step 5: Validate confirmation and store session state (Requirement 2.4)
+        const isConfirmed = verifyResponse.data?.authenticated === true
+            || verifyResponse.status === 'ok'
+            || verifyResponse.data?.status === 'ok'
+            || verifyResponse.data?.status === 'authenticated';
+        if (!isConfirmed) {
+            throw new Error('Authentication failed: ClearNode rejected the auth_verify request');
+        }
+        this._sessionInfo = {
+            sessionAddress,
+            expiresAt,
+            authenticated: true,
+        };
+        return { ...this._sessionInfo };
+    }
+    /**
+     * Check if the current session is valid and not expired.
+     *
+     * Returns false if:
+     * - No session has been established
+     * - The session has been invalidated
+     * - The session has expired (Requirement 2.6)
+     */
+    get isAuthenticated() {
+        if (!this._sessionInfo || !this._sessionInfo.authenticated) {
+            return false;
+        }
+        // Check expiry (Requirement 2.6)
+        const now = Math.floor(Date.now() / 1000);
+        if (now >= this._sessionInfo.expiresAt) {
+            // Session has expired - mark as not authenticated
+            this._sessionInfo.authenticated = false;
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get the session signer function for signing offchain messages.
+     *
+     * The returned function signs arbitrary payloads using the session private key.
+     * This is used for signing state channel messages without exposing the main wallet.
+     *
+     * @throws Error if no authenticated session exists
+     */
+    get sessionSigner() {
+        if (!this.sessionAccount) {
+            throw new Error('No authenticated session - call authenticate() first');
+        }
+        const account = this.sessionAccount;
+        return async (payload) => {
+            const signature = await account.signMessage({
+                message: { raw: payload },
+            });
+            return signature;
+        };
+    }
+    /**
+     * Get the session key's Ethereum address.
+     *
+     * @throws Error if no session key has been generated
+     */
+    get sessionAddress() {
+        if (!this.sessionAccount) {
+            throw new Error('No session key generated - call authenticate() first');
+        }
+        return this.sessionAccount.address;
+    }
+    /**
+     * Invalidate the current session.
+     *
+     * Clears all session state including the keypair and authentication status.
+     * After invalidation, a new authenticate() call is required.
+     */
+    invalidate() {
+        this.sessionAccount = null;
+        this.sessionPrivateKey = null;
+        this._sessionInfo = null;
+    }
+    /**
+     * Re-authenticate using the last authentication parameters.
+     *
+     * This is called internally when a session has expired and a new operation
+     * requires an active session (Requirement 2.6).
+     *
+     * @returns Session information from the new authentication
+     * @throws Error if no previous auth params exist or re-authentication fails
+     */
+    async reauthenticate() {
+        if (!this.lastAuthParams) {
+            throw new Error('Cannot re-authenticate: no previous authentication parameters available');
+        }
+        // Invalidate current session before re-authenticating
+        this.invalidate();
+        return this.authenticate(this.lastAuthParams);
+    }
+    /**
+     * Ensure the session is authenticated, re-authenticating if expired.
+     *
+     * This is a convenience method for use by other components that need
+     * to ensure an active session before performing operations.
+     *
+     * Requirement 2.6: Auto-reauthentication on next operation when expired.
+     *
+     * @returns The current or newly created session info
+     * @throws Error if authentication fails
+     */
+    async ensureAuthenticated() {
+        if (this.isAuthenticated && this._sessionInfo) {
+            return { ...this._sessionInfo };
+        }
+        // Session expired or not established - re-authenticate
+        return this.reauthenticate();
+    }
+}
+//# sourceMappingURL=session-key-manager.js.map