bkb.arcnode.xyz
AtAuth
1/**
2 * AT Protocol authentication types
3 */
4
5/**
6 * Decoded token payload from AT Protocol auth gateway
7 */
8export interface TokenPayload {
9 /** Decentralized Identifier (e.g., "did:plc:abc123") */
10 did: string;
11
12 /** AT Protocol handle (e.g., "user.bsky.social") */
13 handle: string;
14
15 /** Application-specific user ID (optional) */
16 user_id?: number | null;
17
18 /** Application/game identifier */
19 app_id?: string | null;
20
21 /** Token issued-at timestamp (Unix seconds) */
22 iat: number;
23
24 /** Token expiration timestamp (Unix seconds) */
25 exp: number;
26
27 /** Unique nonce for this token */
28 nonce: string;
29
30 /** Additional custom claims */
31 [key: string]: unknown;
32}
33
34/**
35 * Authentication state
36 */
37export interface AuthState {
38 /** Whether user is authenticated */
39 isAuthenticated: boolean;
40
41 /** Whether authentication is in progress */
42 isLoading: boolean;
43
44 /** Current user info (if authenticated) */
45 user: TokenPayload | null;
46
47 /** Raw token string */
48 token: string | null;
49
50 /** Authentication error message */
51 error: string | null;
52}
53
54/**
55 * Auth store actions
56 */
57export interface AuthActions {
58 /** Set authentication token and decode user info */
59 setToken: (token: string) => void;
60
61 /** Clear authentication state (logout) */
62 clearAuth: () => void;
63
64 /** Set loading state */
65 setLoading: (loading: boolean) => void;
66
67 /** Set error message */
68 setError: (error: string | null) => void;
69
70 /** Refresh token from storage */
71 refreshFromStorage: () => void;
72}
73
74/**
75 * Combined auth store type
76 */
77export type AuthStore = AuthState & AuthActions;
78
79/**
80 * Configuration for AT Protocol authentication
81 */
82export interface AtAuthConfig {
83 /** URL of the auth gateway */
84 gatewayUrl: string;
85
86 /** Application identifier */
87 appId?: string;
88
89 /** Storage key for persisting token */
90 storageKey?: string;
91
92 /** Whether to use localStorage (true) or sessionStorage (false) */
93 persistSession?: boolean;
94
95 /** OAuth callback URL */
96 callbackUrl?: string;
97
98 /** Token refresh threshold in seconds (refresh if less than this remaining) */
99 refreshThreshold?: number;
100}
101
102/**
103 * OAuth state passed to auth gateway
104 */
105export interface OAuthState {
106 /** Return URL after authentication */
107 returnTo?: string;
108
109 /** CSRF protection nonce */
110 nonce?: string;
111
112 /** Additional state data */
113 [key: string]: unknown;
114}
115
116/**
117 * OAuth callback result
118 */
119export interface OAuthCallbackResult {
120 /** Whether authentication was successful */
121 success: boolean;
122
123 /** Token if successful */
124 token?: string;
125
126 /** Decoded user payload if successful */
127 user?: TokenPayload;
128
129 /** Error message if failed */
130 error?: string;
131
132 /** Original return URL from state */
133 returnTo?: string;
134}