@clawchatsai/connector 0.1.47 → 0.1.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,15 +1,18 @@
1
1
  /**
2
- * auth-handler.ts — DataChannel authentication state machine
2
+ * auth-handler.ts — DataChannel authentication gate
3
3
  *
4
- * Manages the auth flow for each DataChannel connection:
5
- * 1. Send auth-required with nonce
6
- * 2. Wait for auth-session (cached JWT) or auth-full (Google + TOTP)
7
- * 3. Verify credentials
8
- * 4. Issue session token on success
9
- * 5. Block all non-auth messages until authenticated
4
+ * Every browser DataChannel goes through attachBrowserChannel() before anything else sees it:
5
+ * 1. Refuse (message + close) unless the config on disk is complete with TOTP set up
6
+ * 2. Send auth-required with nonce
7
+ * 3. Wait for auth-session (cached JWT) or auth-full (Google + TOTP), validating every field
8
+ * 4. Verify against the config as it is on disk at that moment
9
+ * 5. Issue session token on success; only then are messages handed to the request handlers
10
+ * A channel that does not log in within 60 s, fails too often or sends malformed login
11
+ * messages is closed. Login failures and lockouts survive a restart (auth-state.json).
10
12
  *
11
13
  * Spec: datachannel-auth-totp.md §4
12
14
  */
15
+ import { type AuthConfigResult } from './config-store.js';
13
16
  export interface AuthConfig {
14
17
  userId: string;
15
18
  totp: {
@@ -29,30 +32,45 @@ export interface AuthConfig {
29
32
  /** When true, skip Google ID token verification (accept 'dev-mode-no-google'). */
30
33
  devMode?: boolean;
31
34
  }
32
- export interface DataChannelSend {
33
- send: (data: string) => void;
35
+ /** The DataChannel surface the gate needs (webrtc-peer.ts DataChannelLike). */
36
+ export interface AuthChannel {
37
+ send(data: string): void;
38
+ close(): void;
39
+ onMessage(handler: (data: string) => void): void;
40
+ onClosed(handler: () => void): void;
34
41
  }
42
+ export interface BrowserChannelHooks {
43
+ /** Fresh read of the login settings from disk. Called on open and again at every verification. */
44
+ loadAuthConfig: () => AuthConfigResult;
45
+ /** Remove one backup code (by hash) from the config on disk; false if it is no longer there. */
46
+ consumeBackupCode: (hash: string) => boolean;
47
+ /** The channel logged in. */
48
+ onAuthenticated: () => void;
49
+ /** A message on a logged-in channel. Errors (thrown or rejected) are logged, never propagated. */
50
+ onMessage: (msg: Record<string, unknown>) => void | Promise<void>;
51
+ /** A wrong TOTP / backup code was tried (for telling already logged-in browsers). */
52
+ onLoginFailure?: (reason: string) => void;
53
+ log: {
54
+ info: (m: string) => void;
55
+ warn: (m: string) => void;
56
+ error: (m: string) => void;
57
+ };
58
+ }
59
+ /** Channels waiting to log in, gateway-wide. Further ones are refused until some finish. */
60
+ export declare const MAX_PENDING_CHANNELS = 10;
61
+ /** A channel that has not logged in by then is closed. */
62
+ export declare const AUTH_TIMEOUT_MS = 60000;
63
+ /** Load the persisted lockout state (call once at service start). Unreadable = fresh state. */
64
+ export declare function loadAuthState(file: string): void;
35
65
  /**
36
- * Initialize auth for a new DataChannel connection.
37
- * Sends auth-required and starts the timeout.
38
- *
39
- * @returns true if auth was initiated, false if connection is blocked
40
- */
41
- export declare function initAuth(dc: DataChannelSend, connectionId: string): boolean;
42
- /**
43
- * Handle an incoming message on an auth-gated DataChannel.
44
- *
45
- * @returns 'authenticated' if the message was an auth message and auth succeeded,
46
- * 'pending' if auth is still in progress,
47
- * 'pass' if the connection is already authenticated (message should be processed normally),
48
- * 'blocked' if the message was dropped (pre-auth non-auth message)
49
- */
50
- export declare function handleAuthMessage(dc: DataChannelSend, connectionId: string, msg: Record<string, unknown>, config: AuthConfig): Promise<'authenticated' | 'pending' | 'pass' | 'blocked'>;
51
- /**
52
- * Clean up auth state for a disconnected DataChannel.
66
+ * Put a new browser DataChannel behind the login gate. Nothing reaches hooks.onMessage
67
+ * before the channel has logged in.
53
68
  */
54
- export declare function cleanupAuth(connectionId: string): void;
69
+ export declare function attachBrowserChannel(dc: AuthChannel, connectionId: string, hooks: BrowserChannelHooks): void;
55
70
  /**
56
- * Check if a connection completed auth.
71
+ * The config on disk changed: close logged-in channels whose login secrets are gone
72
+ * (`reauth`, `reset`, a deleted or broken config). Returns their connection ids.
57
73
  */
58
- export declare function isAuthenticated(connectionId: string): boolean;
74
+ export declare function revokeStaleChannels(current: AuthConfigResult): string[];
75
+ /** Tests only: forget every channel and the lockout state. */
76
+ export declare function _resetAuthForTests(): void;