tijs.org
Framework-agnostic session management for AT Protocol applications using Iron Session encryption
1/**
2 * Logger interface for custom logging implementations.
3 * Compatible with oauth-client-deno's Logger interface.
4 */
5export interface Logger {
6 debug(...args: unknown[]): void;
7 info(...args: unknown[]): void;
8 warn(...args: unknown[]): void;
9 error(...args: unknown[]): void;
10}
11
12/**
13 * Configuration for SessionManager
14 */
15export interface SessionConfig {
16 /**
17 * Secret for Iron Session cookie encryption.
18 * Must be at least 32 characters for secure encryption.
19 */
20 cookieSecret: string;
21
22 /**
23 * Cookie name for session storage.
24 * @default "sid"
25 */
26 cookieName?: string;
27
28 /**
29 * Session TTL (time-to-live) in seconds.
30 * Controls how long sessions remain valid.
31 * @default 604800 (7 days)
32 */
33 sessionTtl?: number;
34
35 /**
36 * Optional logger for debugging and monitoring.
37 * Defaults to a no-op logger.
38 */
39 logger?: Logger;
40}
41
42/**
43 * Session data stored in the encrypted cookie.
44 * Contains user identity and timing information.
45 *
46 * Named CookieSessionData to avoid collision with oauth-client-deno's
47 * SessionData which represents full OAuth session state.
48 */
49export interface CookieSessionData {
50 /** User's DID (Decentralized Identifier) */
51 did: string;
52
53 /** Timestamp when session was created */
54 createdAt: number;
55
56 /** Timestamp of last access (for session refresh) */
57 lastAccessed: number;
58}
59
60/**
61 * @deprecated Use CookieSessionData instead. Will be removed in 1.0.
62 */
63export type SessionData = CookieSessionData;
64
65/**
66 * Error types for session operations
67 */
68export type SessionErrorType =
69 | "NO_COOKIE"
70 | "INVALID_COOKIE"
71 | "SESSION_EXPIRED"
72 | "UNKNOWN";
73
74/**
75 * Error information from session operations
76 */
77export interface SessionErrorInfo {
78 /** Type of error for programmatic handling */
79 type: SessionErrorType;
80
81 /** Human-readable error message */
82 message: string;
83
84 /** Additional error details (e.g., original error) */
85 details?: unknown;
86}
87
88/**
89 * Result from session operations.
90 * Contains either data or error information.
91 */
92export interface SessionResult<T = unknown> {
93 /** Session data, or null if not found/invalid */
94 data: T | null;
95
96 /** Set-Cookie header for session refresh (when data is valid) */
97 setCookieHeader?: string;
98
99 /** Error information if session retrieval failed */
100 error?: SessionErrorInfo;
101}