@synthient/synthient 1.0.1 → 2.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.
@@ -0,0 +1,243 @@
1
+ import type { UnixTime } from "./types.ts";
2
+ /** New values may be added. */
3
+ export type ServiceCategory = "FREE_VPN" | "COMMERCIAL_VPN" | "ENTERPRISE_VPN" | "MOBILE_PROXY" | "BLOCKCHAIN_PROXY" | "RESIDENTIAL_PROXY" | "PUBLIC_PROXY" | "DATACENTER_PROXY" | "TOR_NODE" | "PRIVATE_RELAY" | "BOTNET" | "SEARCH_ENGINE" | "AI_CRAWLER" | "SOCIAL_MEDIA" | "UPTIME_MONITOR" | "LINK_PREVIEW" | "SEO_CRAWLER" | "WEB_ARCHIVER" | "WEBHOOK_PROVIDER" | "PAYMENT_PROCESSOR" | "INTERNET_SCANNER" | (string & {});
4
+ export interface ProxyEvent {
5
+ /** The proxy exit address. */
6
+ ip?: string;
7
+ /** The proxy service tag. */
8
+ provider?: string;
9
+ type?: ServiceCategory;
10
+ /** The ISO 3166-1 alpha-2 country of the address. */
11
+ country_code?: string;
12
+ asn?: number;
13
+ timestamp?: UnixTime;
14
+ }
15
+ export interface AnonymizerEvent {
16
+ /** The first address of the range. */
17
+ range_start?: string;
18
+ /** The last address of the range. */
19
+ range_end?: string;
20
+ /** The service tag. */
21
+ provider?: string;
22
+ type?: ServiceCategory;
23
+ /** The ISO 3166-1 alpha-2 country of `range_start`. */
24
+ country_code?: string;
25
+ /** The autonomous system number of `range_start`. */
26
+ asn?: number;
27
+ /** When the range was seen, in Unix milliseconds. */
28
+ timestamp?: UnixTime;
29
+ }
30
+ /** A torrent observed on the BitTorrent DHT or a tracker. */
31
+ export interface TorrentEvent {
32
+ /** The hex-encoded SHA-1 info hash. */
33
+ info_hash?: string;
34
+ name?: string;
35
+ magnet_uri?: string;
36
+ /** The total size of the torrent's files in bytes. */
37
+ total_size?: number;
38
+ /** The piece size in bytes. */
39
+ piece_length?: number;
40
+ file_count?: number;
41
+ files?: TorrentFile[];
42
+ peers?: TorrentPeer[];
43
+ timestamp?: UnixTime;
44
+ }
45
+ export interface TorrentFile {
46
+ path?: string;
47
+ /** The file size in bytes. */
48
+ length?: number;
49
+ }
50
+ export interface TorrentPeer {
51
+ ip?: string;
52
+ port?: number;
53
+ /** Where the peer was found, such as "DHT", "PEX", or "tracker". */
54
+ source?: string;
55
+ /** Whether the peer supports encrypted connections. */
56
+ encrypted?: boolean;
57
+ }
58
+ export interface JA4TEvent {
59
+ ip?: string;
60
+ ja4t?: string;
61
+ /** The service tag of the address. */
62
+ provider?: string;
63
+ type?: ServiceCategory;
64
+ /** The ISO 3166-1 alpha-2 country of the address. */
65
+ country_code?: string;
66
+ asn?: number;
67
+ timestamp?: UnixTime;
68
+ }
69
+ /** The tunnel transport a Helios event arrived over. New values may be added. */
70
+ export type HeliosTransport = "tcp" | "udp" | "quic" | (string & {});
71
+ /** The Helios honeypot sensor that captured an event. */
72
+ export interface HeliosMeta {
73
+ /** The proxy exit address the traffic arrived through. */
74
+ proxy_ip?: string;
75
+ /** The sensor that captured the traffic. */
76
+ server?: string;
77
+ /** The sensor pool. */
78
+ pool_id?: string;
79
+ /** The proxy service the traffic arrived through. */
80
+ provider?: string;
81
+ }
82
+ /** An HTTP request captured by a Helios honeypot. */
83
+ export interface HeliosHTTPEvent {
84
+ /** When the request was captured, in Unix milliseconds. */
85
+ timestamp: UnixTime;
86
+ /**
87
+ * The proxy tunnel the request arrived through, as the exact decimal digits of an
88
+ * unsigned 64-bit integer.
89
+ */
90
+ tunnel_id: string;
91
+ /** The destination host the tunnel was opened to. */
92
+ domain: string;
93
+ /** The destination port. */
94
+ port: number;
95
+ protocol: "http";
96
+ meta: HeliosMeta;
97
+ details?: HTTPRequestDetails;
98
+ /** The raw request bytes, base64-encoded. */
99
+ raw?: string;
100
+ }
101
+ export interface HTTPRequestDetails {
102
+ method?: string;
103
+ /** The request target. */
104
+ uri?: string;
105
+ /** The HTTP version, such as "HTTP/1.1". */
106
+ version?: string;
107
+ headers?: Record<string, string>;
108
+ }
109
+ /** A TLS ClientHello captured by a Helios honeypot. */
110
+ export interface HeliosHTTPSEvent {
111
+ /** When the handshake was captured, in Unix milliseconds. */
112
+ timestamp: UnixTime;
113
+ /**
114
+ * The proxy tunnel the handshake arrived through, as the exact decimal digits of an
115
+ * unsigned 64-bit integer.
116
+ */
117
+ tunnel_id: string;
118
+ /** The destination host the tunnel was opened to. */
119
+ domain: string;
120
+ /** The destination port. */
121
+ port: number;
122
+ protocol: "https";
123
+ meta: HeliosMeta;
124
+ transport: HeliosTransport;
125
+ /** The parsed ClientHello, or null when the sensor could not parse the handshake. */
126
+ details?: TLSClientHello | null;
127
+ /** Always null: the HTTPS sensors do not capture handshake bytes. */
128
+ raw?: string | null;
129
+ }
130
+ /**
131
+ * A TLS ClientHello as parsed by the Helios sensors. Fields the sensor could not parse
132
+ * are absent, and new fields may appear.
133
+ */
134
+ export interface TLSClientHello {
135
+ /** The record layer version, such as "TLS 1.0". */
136
+ record_version?: string;
137
+ /** The handshake version, such as "TLS 1.2". */
138
+ handshake_version?: string;
139
+ /** The hex-encoded 32-byte client random. */
140
+ client_random?: string;
141
+ /** The hex-encoded session ID. */
142
+ session_id?: string;
143
+ /** The session ID length in bytes. */
144
+ session_id_length?: number;
145
+ cipher_suites?: TLSCodeName[];
146
+ compression_methods?: number[];
147
+ /** The extensions in wire order. */
148
+ extensions?: TLSExtension[];
149
+ /** The server_name extension value. */
150
+ sni?: string;
151
+ alpn?: string[];
152
+ supported_versions?: string[];
153
+ /** The supported key exchange groups. */
154
+ supported_groups?: TLSCodeName[];
155
+ signature_algorithms?: TLSCodeName[];
156
+ key_share_groups?: string[];
157
+ ec_point_formats?: string[];
158
+ psk_key_exchange_modes?: string[];
159
+ /** The supported certificate compression algorithms. */
160
+ compress_certificate?: string[];
161
+ has_grease?: boolean;
162
+ /** Whether the application_settings extension is present. */
163
+ application_settings?: boolean;
164
+ /** Whether the delegated_credentials extension is present. */
165
+ delegated_credentials?: boolean;
166
+ /** Whether the encrypt_then_mac extension is present. */
167
+ encrypt_then_mac?: boolean;
168
+ /** Whether the extended_master_secret extension is present. */
169
+ extended_master_secret?: boolean;
170
+ /** Whether the post_handshake_auth extension is present. */
171
+ post_handshake_auth?: boolean;
172
+ /** Whether the renegotiation_info extension is present. */
173
+ renegotiation_info?: boolean;
174
+ /** Whether the signed_certificate_timestamp extension is present. */
175
+ signed_certificate_timestamps?: boolean;
176
+ /** Whether the status_request extension is present. */
177
+ status_request?: boolean;
178
+ /** False when the sensor captured only part of the ClientHello. */
179
+ complete?: boolean;
180
+ /** Present and true when the ClientHello was cut short. */
181
+ truncated?: boolean;
182
+ /** The transport the handshake was read from, as the sensor reports it. */
183
+ transport?: HeliosTransport;
184
+ /** `record_version` as its wire code point, such as 769. */
185
+ record_version_code?: number;
186
+ /** `handshake_version` as its wire code point, such as 771. */
187
+ handshake_version_code?: number;
188
+ /** The `supported_versions` entries as wire code points, in order, including GREASE values. */
189
+ supported_version_codes?: number[];
190
+ /** The `alpn` entries hex-encoded, in order. */
191
+ alpn_hex?: string[];
192
+ /** The TLS 1.3 signature_algorithms_cert extension. */
193
+ signature_algorithms_cert?: TLSCodeName[];
194
+ /** The record_size_limit extension value. */
195
+ record_size_limit?: number;
196
+ /** The max_fragment_length extension value. */
197
+ max_fragment_length?: number;
198
+ }
199
+ /** A TLS registry value, such as a cipher suite or group, with its name. */
200
+ export interface TLSCodeName {
201
+ code?: number;
202
+ name?: string;
203
+ }
204
+ export interface TLSExtension {
205
+ code?: number;
206
+ name?: string;
207
+ /** The extension data length in bytes. */
208
+ length?: number;
209
+ }
210
+ /** A DNS tunnel captured by a Helios honeypot. */
211
+ export interface HeliosDNSEvent {
212
+ /** When the tunnel was captured, in Unix milliseconds. */
213
+ timestamp: UnixTime;
214
+ /** The proxy tunnel, as the exact decimal digits of an unsigned 64-bit integer. */
215
+ tunnel_id: string;
216
+ /** The destination host the tunnel was opened to. */
217
+ domain: string;
218
+ /** The destination port. */
219
+ port: number;
220
+ protocol: "dns";
221
+ meta: HeliosMeta;
222
+ transport: HeliosTransport;
223
+ }
224
+ /**
225
+ * An Android Debug Bridge shell command captured by a Helios honeypot. The sensor sends
226
+ * no timestamp.
227
+ */
228
+ export interface HeliosADBEvent {
229
+ /** Identifies the ADB session, as 32 hex characters. */
230
+ session: string;
231
+ /** The 1-based position of the command within its session. */
232
+ sequential_id: number;
233
+ /** The shell command as plain text. Invalid UTF-8 bytes become U+FFFD. */
234
+ command: string;
235
+ /**
236
+ * The SHA-256 the sensor assigns to the session's payload, as 64 hex characters. It is
237
+ * not a hash of `command`; every command in a session shares it, as do sessions that
238
+ * replay the same script.
239
+ */
240
+ hash: string;
241
+ /** Null from sensors that don't send it yet. */
242
+ meta: HeliosMeta | null;
243
+ }
package/dist/events.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/feed.d.ts ADDED
@@ -0,0 +1,146 @@
1
+ import { type RequestOptions, type Transport } from "./transport.ts";
2
+ import type { Export, ExportFormat, ExportMeta, ExportPage, ExportVariant, ExportVolume } from "./types.ts";
3
+ type Reviver = (key: string, value: unknown, context?: {
4
+ source: string;
5
+ }) => unknown;
6
+ /**
7
+ * Keeps each `tunnel_id` as the exact decimal digits sent on the wire, since these
8
+ * unsigned 64-bit IDs lose precision as numbers above 2^53.
9
+ */
10
+ export declare const exactTunnelID: Reviver;
11
+ export interface ListExportsOptions extends RequestOptions {
12
+ /** The page size. The API default is 100, and it clamps values above 500. */
13
+ limit?: number | undefined;
14
+ /** Continues a listing from a previous page's `next_cursor`. */
15
+ cursor?: string | undefined;
16
+ /** Lists only the exports of this UTC day, as "YYYY-MM-DD" like {@link dailyExport} returns. */
17
+ day?: string | undefined;
18
+ /**
19
+ * Lists the lite files instead, which only the proxies, anonymizers, and JA4T feeds
20
+ * have; on other feeds the lite listing is empty. A lite export has the same `id` as
21
+ * the full one, so pass the variant again to download it.
22
+ */
23
+ variant?: ExportVariant | undefined;
24
+ }
25
+ export interface ExportOptions extends RequestOptions {
26
+ /**
27
+ * Uses the export's lite file, which only the proxies, anonymizers, and JA4T feeds
28
+ * have. A lite file is published shortly after its export. Until then, and on other
29
+ * feeds, a lite export rejects with an APIError with status 404.
30
+ */
31
+ variant?: ExportVariant | undefined;
32
+ }
33
+ export interface ExportVolumeOptions extends RequestOptions {
34
+ /** The number of UTC days to cover, including today. The API default is 90, and it accepts 1 to 366. */
35
+ days?: number | undefined;
36
+ }
37
+ export type ListDatasetExportsOptions = Omit<ListExportsOptions, "variant">;
38
+ export interface DatasetExportOptions extends RequestOptions {
39
+ /**
40
+ * The file to use. Geolocation has "parquet", the default, "csv", which is
41
+ * gzip-compressed with a header row, and "mmdb", a MaxMind DB. WHOIS has only
42
+ * "tar.gz". A format the day doesn't have rejects with an APIError with status 404.
43
+ */
44
+ format?: ExportFormat | undefined;
45
+ }
46
+ /**
47
+ * Returns the ID of the daily export for the UTC day containing `date`. Daily exports
48
+ * roll up a day's hourly exports once the day ends.
49
+ */
50
+ export declare function dailyExport(date: Date): string;
51
+ /**
52
+ * Returns the ID of the hourly export for the UTC hour containing `date`, with the hour
53
+ * unpadded as in `Export.id`.
54
+ */
55
+ export declare function hourlyExport(date: Date): string;
56
+ /**
57
+ * A Synthient data feed. Each feed has a real-time stream of events of type `T` and
58
+ * hourly parquet exports that roll up into daily exports. Access feeds through the
59
+ * client, such as `client.proxies`.
60
+ *
61
+ * Export IDs are "latest" for the most recent hourly export, a UTC day as
62
+ * "YYYY-MM-DD", or a UTC hour as "YYYY-MM-DD/H" (a zero-padded hour is also accepted).
63
+ * `Export.id` values and the results of {@link dailyExport} and {@link hourlyExport} can
64
+ * be passed as they are.
65
+ */
66
+ export declare class Feed<T> {
67
+ #private;
68
+ /** @internal Feeds are created by the client. */
69
+ constructor(transport: Transport, path: string, reviver?: Reviver);
70
+ /**
71
+ * Streams the feed's real-time events. The connection opens on the first `next()`,
72
+ * which throws any connection error, such as an APIError with status 403 for a
73
+ * missing scope. The server can close a stream at any time, such as during a deploy,
74
+ * which ends the iteration normally; any other failure throws. Breaking out of the
75
+ * loop closes the connection. Events sent between connections are missed, so call
76
+ * `stream` again to reconnect. The client's `timeout` bounds the gap between data,
77
+ * and the server sends a keepalive about every 15 seconds.
78
+ */
79
+ stream(options?: RequestOptions): AsyncGenerator<T, void, undefined>;
80
+ /** Returns one page of the feed's exports, newest first. Use `allExports` to iterate every page. */
81
+ listExports(options?: ListExportsOptions): Promise<ExportPage>;
82
+ /**
83
+ * Iterates over the feed's exports, newest first, fetching pages lazily. `options` is
84
+ * copied when `allExports` is called; errors, including invalid parameters, are
85
+ * thrown from the iteration.
86
+ */
87
+ allExports(options?: ListExportsOptions): AsyncGenerator<Export, void, undefined>;
88
+ /** Returns the rows and bytes the feed exported per UTC day, oldest first. */
89
+ exportVolume(options?: ExportVolumeOptions): Promise<ExportVolume>;
90
+ /** Returns the checksum, size, row count, and parquet schema of an export. */
91
+ exportMeta(id: string, options?: ExportOptions): Promise<ExportMeta>;
92
+ /**
93
+ * Returns a presigned URL for an export's parquet file, for tools that read parquet
94
+ * over HTTPS directly. The URL is valid for 24 hours and grants access without an API
95
+ * key, so treat it as a secret.
96
+ */
97
+ downloadURL(id: string, options?: ExportOptions): Promise<URL>;
98
+ /**
99
+ * Downloads an export's parquet file as a byte stream. Read it to the end or cancel it
100
+ * to release the connection. The API key is sent only to the Synthient API, never to
101
+ * the storage host that serves the file, and errors never include the presigned URL.
102
+ * A non-success response from either returns an APIError.
103
+ */
104
+ download(id: string, options?: ExportOptions): Promise<ReadableStream<Uint8Array>>;
105
+ }
106
+ /**
107
+ * A Synthient dataset, published as one export per UTC day with no stream and no hourly
108
+ * exports. Access datasets through the client, such as `client.geolocation`.
109
+ *
110
+ * Export IDs are "latest" for the newest day or a UTC day as "YYYY-MM-DD". `Export.id`
111
+ * values and the results of {@link dailyExport} can be passed as they are.
112
+ */
113
+ export declare class Dataset {
114
+ #private;
115
+ /** @internal Datasets are created by the client. */
116
+ constructor(transport: Transport, path: string);
117
+ /** Returns one page of the dataset's exports, newest first. Use `allExports` to iterate every page. */
118
+ listExports(options?: ListDatasetExportsOptions): Promise<ExportPage>;
119
+ /**
120
+ * Iterates over the dataset's exports, newest first, fetching pages lazily. `options`
121
+ * is copied when `allExports` is called; errors, including invalid parameters, are
122
+ * thrown from the iteration.
123
+ */
124
+ allExports(options?: ListDatasetExportsOptions): AsyncGenerator<Export, void, undefined>;
125
+ /** Returns the rows and bytes the dataset exported per UTC day, oldest first. */
126
+ exportVolume(options?: ExportVolumeOptions): Promise<ExportVolume>;
127
+ /**
128
+ * Returns the checksum, size, row count, and schema of an export's file in the
129
+ * requested format, and lists every file of the day.
130
+ */
131
+ exportMeta(id: string, options?: DatasetExportOptions): Promise<ExportMeta>;
132
+ /**
133
+ * Returns a presigned URL for an export's file. The URL is valid for 24 hours and
134
+ * grants access without an API key, so treat it as a secret.
135
+ */
136
+ downloadURL(id: string, options?: DatasetExportOptions): Promise<URL>;
137
+ /**
138
+ * Downloads an export's file as a byte stream, exactly as served: a "csv" file stays
139
+ * gzip-compressed and a WHOIS archive stays packed. Read it to the end or cancel it to
140
+ * release the connection. The API key is sent only to the Synthient API, never to the
141
+ * storage host that serves the file, and errors never include the presigned URL. A
142
+ * non-success response from either returns an APIError.
143
+ */
144
+ download(id: string, options?: DatasetExportOptions): Promise<ReadableStream<Uint8Array>>;
145
+ }
146
+ export {};