/**
 * session/manager.ts — x402 V2 session lifecycle management.
 *
 * This module implements the "wallet-based access & reusable sessions" concept
 * introduced in x402 V2. Agents pay once to establish a cryptographically
 * authenticated session, then make N subsequent calls without additional
 * on-chain transactions.
 *
 * Non-custodial design:
 *   - Session tokens are signed locally by the agent's private key
 *   - No third party holds or validates keys
 *   - Servers receive a self-contained signed token they can independently verify
 *   - The SessionManager has zero knowledge of private keys; it only receives
 *     a signMessage callback injected at creation time
 *
 * Token format:
 *   X-Session-Token: <base64url(JSON payload)>.<hex signature>
 *   Compatible with x402 V2 SIGN-IN-WITH-X (SIWx) header pattern
 *   Servers can ecrecover the wallet address without any external service
 */
import type { SessionRecord, SessionTokenPayload, CreateSessionOptions, SessionLookupResult } from './types.js';
/**
 * HTTP header name for session tokens.
 * x402 V2 uses modernised header names (no X- prefix per IETF conventions
 * for new standard headers). We use PAYMENT-SESSION for the session token
 * and retain X-Session-Token as an alias for broad compatibility.
 */
export declare const SESSION_TOKEN_HEADER = "X-Session-Token";
export declare const SESSION_WALLET_HEADER = "X-Session-Wallet";
export declare const PAYMENT_SESSION_HEADER = "PAYMENT-SESSION";
/**
 * Create a new session after a successful x402 payment.
 *
 * Signs a canonical token payload with the agent's private key, creating
 * a self-verifiable session token that servers can use to grant access
 * without requiring a new on-chain payment.
 */
export declare function createSession(opts: CreateSessionOptions): Promise<SessionRecord>;
/**
 * Look up a session by ID.
 * Returns the record and whether it has expired.
 */
export declare function lookupSession(sessionId: string): SessionLookupResult;
/**
 * Record a call made within a session.
 * Updates callCount and lastUsedAt in-place.
 */
export declare function recordSessionCall(sessionId: string): void;
/**
 * Explicitly end a session LOCALLY: force-expire the record and discard the
 * stored token material (sessionToken + signature are overwritten) so the
 * credential can no longer be read back out of this process.
 *
 * IMPORTANT — this is not revocation. The session token is a self-contained
 * bearer credential signed at creation with its expiresAt baked into the
 * signed payload; remote servers verify it offline (ecrecover) with no
 * revocation registry to consult. Any copy of the token that already left
 * this process (it is transmitted on every session fetch) remains
 * technically valid to the remote endpoint until that baked-in expiry.
 * Callers reporting on this operation must not claim otherwise — and the
 * baked-in expiry is preserved in `tokenExpiresAt` precisely so they can
 * report it truthfully after `expiresAt` has been forced to 0.
 *
 * Returns true if the session was found and ended.
 */
export declare function endSession(sessionId: string): boolean;
/**
 * True if this session was explicitly ended locally (endSession) rather than
 * simply reaching its natural expiry.
 */
export declare function wasEndedLocally(session: SessionRecord): boolean;
/**
 * When the ISSUED token stops being valid at the remote endpoint.
 *
 * For a live or naturally expired session this is just `expiresAt`. For an
 * ended session `expiresAt` is the 0 sentinel that makes the record unusable,
 * so the real expiry comes from `tokenExpiresAt`. Always use this for display:
 * reporting the sentinel would claim the token lapsed in 1970.
 */
export declare function tokenExpiryOf(session: SessionRecord): number;
/**
 * List all active (non-expired) sessions.
 */
export declare function listActiveSessions(): SessionRecord[];
/**
 * List all sessions (including expired).
 */
export declare function listAllSessions(): SessionRecord[];
/**
 * Find the best matching active session for a given URL.
 * Prefers exact-scope matches over prefix-scope. Among overlapping
 * prefix sessions, prefers the longest (most specific) endpoint path,
 * then the narrower required-query constraint, then recency.
 * Used to auto-attach a session to x402_pay when available.
 */
export declare function findSessionForUrl(url: string): SessionRecord | undefined;
/**
 * Check if a URL is covered by a session's endpoint + scope.
 *
 * Prefix sessions cover the endpoint path itself, query strings on that path,
 * and descendants below that path. They do not cover raw string lookalikes such
 * as /v10 for /v1, or host/path prefixes on a different origin. Trailing
 * slashes are normalised, so a session for /v1/ behaves identically to one
 * for /v1 (and a request to /v1/ matches an endpoint of /v1).
 *
 * Query parameters on the session endpoint are treated as REQUIRED
 * parameters: the requested URL must carry every endpoint parameter with an
 * equal value. Parameter order never matters (comparison goes through
 * URLSearchParams, with duplicate keys compared as value multisets). For a
 * key the endpoint pins, the request's values for that key must equal the
 * endpoint's exactly — a contradictory duplicate such as ?user=alice&user=bob
 * against a pin of user=alice is rejected (HTTP parameter pollution).
 * Extra request parameters under OTHER keys are allowed. The requirement
 * applies to the
 * endpoint path itself and to sub-paths alike — e.g. /v1/users?version=2 is
 * covered by a session for /v1?version=2, but /v1/users without it is not.
 * That last case fails CLOSED deliberately: dropping a required parameter
 * changes what the server serves, so requiring it everywhere is the safe
 * reading.
 */
export declare function isUrlCoveredBySession(url: string, session: {
    endpoint: string;
    scope: 'prefix' | 'exact';
}): boolean;
/**
 * Build the HTTP headers to include in a session-authenticated request.
 * These headers are inspired by x402 V2's SIGN-IN-WITH-X (SIWx) pattern
 * and the PAYMENT-SESSION header spec.
 */
export declare function buildSessionHeaders(session: SessionRecord): Record<string, string>;
/**
 * Decode a session token string into its payload and signature.
 * Useful for display / debugging purposes.
 */
export declare function decodeSessionToken(token: string): {
    payload: SessionTokenPayload;
    signature: string;
} | null;
/**
 * Get total sessions count (active + expired).
 */
export declare function getStoreSize(): number;
/**
 * Clear all sessions — for testing only.
 */
export declare function _clearAllSessions(): void;
//# sourceMappingURL=manager.d.ts.map