@lookover-ai/webagent-device 0.0.0-stage → 0.1.0
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.
- package/LICENSE +55 -0
- package/README.md +109 -2
- package/dist/cli.js +30114 -0
- package/dist/index.d.ts +120 -0
- package/dist/index.js +29318 -0
- package/package.json +53 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { OpenErrCode } from '@lookover-ai/webagent-contracts';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
/** True for every address a device must not dial by default. Unparseable input counts as blocked. */
|
|
5
|
+
declare function isPrivateAddress(ip: string): boolean;
|
|
6
|
+
/** An allow-list of IPs and CIDRs (`10.0.0.0/8`, `fd00::/8`, `192.168.1.5`). Throws on a bad entry. */
|
|
7
|
+
declare class AllowList {
|
|
8
|
+
private readonly list;
|
|
9
|
+
constructor(entries?: readonly string[]);
|
|
10
|
+
matches(ip: string): boolean;
|
|
11
|
+
}
|
|
12
|
+
declare function isDefaultBlockedPort(port: number): boolean;
|
|
13
|
+
|
|
14
|
+
type Lookup = (host: string) => Promise<string[]>;
|
|
15
|
+
type Resolved = {
|
|
16
|
+
ok: true;
|
|
17
|
+
ip: string;
|
|
18
|
+
} | {
|
|
19
|
+
ok: false;
|
|
20
|
+
code: OpenErrCode;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Resolve the OPEN target on the device (never trust the relay's or runner's DNS) and pick the
|
|
24
|
+
* address to dial. Only addresses that pass the filter are candidates, and the caller dials that
|
|
25
|
+
* IP, so a second lookup (DNS rebinding) cannot change the destination.
|
|
26
|
+
*/
|
|
27
|
+
declare function resolveTarget(host: string, allow: AllowList, lookup?: Lookup): Promise<Resolved>;
|
|
28
|
+
|
|
29
|
+
interface DeviceClientOptions {
|
|
30
|
+
/** IPs and CIDRs the owner allows even though they are private (`10.0.0.0/8`, `192.168.1.5`). */
|
|
31
|
+
allowPrivate?: readonly string[];
|
|
32
|
+
/**
|
|
33
|
+
* Only these destination ports. Default: any port except the ones a browser never needs (mail,
|
|
34
|
+
* SSH, databases, ..., see `isDefaultBlockedPort`); naming a port here opts it in.
|
|
35
|
+
*/
|
|
36
|
+
allowPorts?: readonly number[];
|
|
37
|
+
/**
|
|
38
|
+
* Alias-only mode (R82): serve the app on these ports of this machine to the owner's test
|
|
39
|
+
* sessions as the alias derived from `deviceId`. Exclusive with `allowPrivate` and `allowPorts`.
|
|
40
|
+
*/
|
|
41
|
+
localApp?: {
|
|
42
|
+
deviceId: string;
|
|
43
|
+
ports: readonly number[];
|
|
44
|
+
};
|
|
45
|
+
/** Local cap on concurrent streams, on top of the account limit (default 8). */
|
|
46
|
+
maxStreams?: number;
|
|
47
|
+
/** Longest wait to reach a destination (ms, default 8000). */
|
|
48
|
+
dialTimeoutMs?: number;
|
|
49
|
+
/** Alias-only mode: how long the one-time "does this port speak TLS" probe waits (ms, default 1000). */
|
|
50
|
+
tlsProbeTimeoutMs?: number;
|
|
51
|
+
platform?: string;
|
|
52
|
+
clientVersion?: string;
|
|
53
|
+
/** For tests: replaces DNS. */
|
|
54
|
+
lookup?: Lookup;
|
|
55
|
+
/** Notified of every OPEN outcome (destination host and port, no payload). */
|
|
56
|
+
onOpen?: (e: {
|
|
57
|
+
host: string;
|
|
58
|
+
port: number;
|
|
59
|
+
result: "ok" | OpenErrCode;
|
|
60
|
+
}) => void;
|
|
61
|
+
/** Notified each time the number of live streams changes (for the status line). */
|
|
62
|
+
onStreams?: (count: number) => void;
|
|
63
|
+
}
|
|
64
|
+
interface DeviceClient {
|
|
65
|
+
readonly paused: boolean;
|
|
66
|
+
readonly activeStreams: number;
|
|
67
|
+
/** Refuse every OPEN with `paused` until `resume()`; tells the relay. */
|
|
68
|
+
pause(): void;
|
|
69
|
+
resume(): void;
|
|
70
|
+
/** Close the connection and every stream. */
|
|
71
|
+
close(): Promise<void>;
|
|
72
|
+
/** Resolves when the connection is gone: the close code (4001 = kicked or revoked, 4000 = replaced). */
|
|
73
|
+
readonly closed: Promise<{
|
|
74
|
+
code: number;
|
|
75
|
+
reason: string;
|
|
76
|
+
}>;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Connect to the relay (`wss://relay.<region>/v1/connect`) as a proxy device. Resolves when the
|
|
80
|
+
* WebSocket is open, rejects with the HTTP status when the relay refuses the token. From then on
|
|
81
|
+
* the relay sends OPEN for each runner connection; the device resolves the host itself, refuses
|
|
82
|
+
* private destinations unless allow-listed, dials the pinned IP, and pipes bytes with credit-based
|
|
83
|
+
* flow control. Reconnecting is the caller's job (see the CLI's `start`).
|
|
84
|
+
*/
|
|
85
|
+
declare function connect(relayUrl: string, token: string, opts?: DeviceClientOptions): Promise<DeviceClient>;
|
|
86
|
+
|
|
87
|
+
declare const deviceConfigSchema: z.ZodObject<{
|
|
88
|
+
deviceId: z.ZodString;
|
|
89
|
+
deviceToken: z.ZodString;
|
|
90
|
+
relayUrl: z.ZodString;
|
|
91
|
+
apiUrl: z.ZodOptional<z.ZodString>;
|
|
92
|
+
allowPrivate: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
93
|
+
allowPorts: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
|
|
94
|
+
maxStreams: z.ZodOptional<z.ZodNumber>;
|
|
95
|
+
purpose: z.ZodOptional<z.ZodEnum<{
|
|
96
|
+
proxy: "proxy";
|
|
97
|
+
local_app: "local_app";
|
|
98
|
+
}>>;
|
|
99
|
+
localApp: z.ZodOptional<z.ZodObject<{
|
|
100
|
+
ports: z.ZodArray<z.ZodNumber>;
|
|
101
|
+
}, z.core.$strip>>;
|
|
102
|
+
}, z.core.$strip>;
|
|
103
|
+
type DeviceConfig = z.infer<typeof deviceConfigSchema>;
|
|
104
|
+
/** `~/.config/webagent-device/config.json` (override the directory with `WEBAGENT_DEVICE_CONFIG_DIR`). */
|
|
105
|
+
declare function configPath(env?: Record<string, string | undefined>): string;
|
|
106
|
+
/** Write the config with mode 0600 in a 0700 directory (it holds the device token). */
|
|
107
|
+
declare function writeConfig(path: string, config: DeviceConfig): Promise<void>;
|
|
108
|
+
declare function readConfig(path: string): Promise<DeviceConfig | undefined>;
|
|
109
|
+
|
|
110
|
+
/** Trade a pairing code for a device token (`POST /v1/proxy-devices/claim`, no auth) and store it. */
|
|
111
|
+
declare function pairDevice(opts: {
|
|
112
|
+
code: string;
|
|
113
|
+
apiUrl: string;
|
|
114
|
+
configPath: string;
|
|
115
|
+
platform: string;
|
|
116
|
+
clientVersion: string;
|
|
117
|
+
fetchImpl?: typeof fetch;
|
|
118
|
+
}): Promise<DeviceConfig>;
|
|
119
|
+
|
|
120
|
+
export { AllowList, type DeviceClient, type DeviceClientOptions, type DeviceConfig, configPath, connect, isDefaultBlockedPort, isPrivateAddress, pairDevice, readConfig, resolveTarget, writeConfig };
|