@velmlabs/unstuck-protocol 0.1.3 → 0.1.5
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/dist/index.d.ts +26 -1
- package/dist/index.js +41 -5
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -74,6 +74,8 @@ interface TakeoverParams {
|
|
|
74
74
|
site?: string;
|
|
75
75
|
/** Ask the human for a 6-digit code delivered with the link (relay spec §5.8). */
|
|
76
76
|
requireCode?: boolean;
|
|
77
|
+
/** Sites besides the page's own the human may navigate to, e.g. ["accounts.google.com"] (page lock). */
|
|
78
|
+
allowedSites?: string[];
|
|
77
79
|
}
|
|
78
80
|
interface CdpSendParams {
|
|
79
81
|
pageId: string;
|
|
@@ -123,6 +125,8 @@ declare const ViewerToEngineSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
|
|
|
123
125
|
token: _sinclair_typebox.TString;
|
|
124
126
|
resumeKey: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
125
127
|
code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
128
|
+
/** The viewer's random value for this connection; engines that announce v: 2 echo it in ready (anti-replay). */
|
|
129
|
+
vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
126
130
|
}>, _sinclair_typebox.TObject<{
|
|
127
131
|
t: _sinclair_typebox.TLiteral<"mouse">;
|
|
128
132
|
action: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"down">, _sinclair_typebox.TLiteral<"up">, _sinclair_typebox.TLiteral<"move">]>;
|
|
@@ -179,6 +183,7 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
|
|
|
179
183
|
site: _sinclair_typebox.TString;
|
|
180
184
|
expiresAt: _sinclair_typebox.TNumber;
|
|
181
185
|
resumeKey: _sinclair_typebox.TString;
|
|
186
|
+
vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
182
187
|
}>, _sinclair_typebox.TObject<{
|
|
183
188
|
t: _sinclair_typebox.TLiteral<"state">;
|
|
184
189
|
status: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<string>[]>;
|
|
@@ -214,6 +219,7 @@ type EngineToViewer = {
|
|
|
214
219
|
site: string;
|
|
215
220
|
expiresAt: number;
|
|
216
221
|
resumeKey: string;
|
|
222
|
+
vn?: string;
|
|
217
223
|
} | {
|
|
218
224
|
t: 'state';
|
|
219
225
|
status: SessionStatus;
|
|
@@ -234,6 +240,11 @@ type EngineToViewer = {
|
|
|
234
240
|
field?: Field;
|
|
235
241
|
};
|
|
236
242
|
declare function parseViewerMessage(raw: string): ViewerToEngine | null;
|
|
243
|
+
/**
|
|
244
|
+
* How long a human who left the viewer (switched apps to read a code, lost signal) can come back and resume.
|
|
245
|
+
* The engine frees the agent after this; the viewer stops retrying after it.
|
|
246
|
+
*/
|
|
247
|
+
declare const RESUME_WINDOW_MS: number;
|
|
237
248
|
|
|
238
249
|
declare const RELAY_SUBPROTOCOL = "unstuck-relay.1";
|
|
239
250
|
declare const KEY_SUBPROTOCOL_PREFIX = "key.";
|
|
@@ -242,6 +253,11 @@ declare const RELAY_LIMITS: {
|
|
|
242
253
|
readonly agentPayloadMax: 2097152;
|
|
243
254
|
readonly viewerPayloadMax: 65536;
|
|
244
255
|
readonly viewersPerSession: 4;
|
|
256
|
+
/** Viewers that haven't been confirmed (see relay-core attachViewer) one client IP may hold in one session. */
|
|
257
|
+
readonly unconfirmedViewersPerIp: 2;
|
|
258
|
+
/** Viewer → agent bytes one viewer connection may send per window. */
|
|
259
|
+
readonly viewerBytesPerWindow: 2097152;
|
|
260
|
+
readonly viewerByteWindowMs: 10000;
|
|
245
261
|
readonly idleMs: 120000;
|
|
246
262
|
readonly heartbeatMs: 30000;
|
|
247
263
|
readonly graceMs: 60000;
|
|
@@ -250,12 +266,16 @@ declare const RELAY_LIMITS: {
|
|
|
250
266
|
readonly backpressureBytes: 4194304;
|
|
251
267
|
readonly viewerUpgradesPerMinPerIp: 30;
|
|
252
268
|
readonly agentUpgradesPerMinPerKey: 20;
|
|
269
|
+
/** Agent upgrades per client IP per minute, counted on refused authorizations only (key brute force). */
|
|
270
|
+
readonly agentAuthFailuresPerMinPerIp: 10;
|
|
253
271
|
};
|
|
254
272
|
declare const RELAY_CLOSE: {
|
|
255
273
|
readonly agentReconnecting: 1012;
|
|
256
274
|
readonly replaced: 4409;
|
|
257
275
|
readonly badMessage: 1003;
|
|
258
276
|
readonly tooBig: 1009;
|
|
277
|
+
readonly policy: 1008;
|
|
278
|
+
readonly tryAgainLater: 1013;
|
|
259
279
|
/** A refused agent: 4000 + the HTTP status (4401, 4402, 4403, 4429). Clients can't read upgrade statuses. */
|
|
260
280
|
readonly refused: (status: number) => number;
|
|
261
281
|
};
|
|
@@ -308,6 +328,11 @@ declare function b64urlEncode(b: Uint8Array): string;
|
|
|
308
328
|
declare function b64urlDecode(s: string): Uint8Array | null;
|
|
309
329
|
/** Plaintext JSON messages start with '{'; screen frames start with their type byte (0x01). */
|
|
310
330
|
declare const isJsonPlaintext: (p: Uint8Array) => boolean;
|
|
331
|
+
/**
|
|
332
|
+
* Pads a JSON plaintext with trailing spaces (still valid JSON for any peer) to 256 bytes, then to the next power of
|
|
333
|
+
* two up to what still fits 64 KB once sealed, so a relay can't tell keys, digits or the length of typed text from message sizes.
|
|
334
|
+
*/
|
|
335
|
+
declare function padPlaintext(p: Uint8Array): Uint8Array;
|
|
311
336
|
/**
|
|
312
337
|
* Replay protection (relay spec §5.4): every message on a viewer connection is bound to that connection's random
|
|
313
338
|
* nonce (sent by the engine in a sealed challenge) and carries a sequence number the receiver requires to increase.
|
|
@@ -321,5 +346,5 @@ declare function openMsg(key: CryptoKey, sessionId: string, dir: Direction, conn
|
|
|
321
346
|
plain: Uint8Array;
|
|
322
347
|
} | null>;
|
|
323
348
|
|
|
324
|
-
export { EngineToViewerSchema, FRAME_TYPE_JPEG, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, importE2eKey, isJsonPlaintext, newConnNonce, newE2eKey, open, openMsg, parseAgentToRelay, parseRelayToAgent, parseViewerMessage, seal, sealMsg };
|
|
349
|
+
export { EngineToViewerSchema, FRAME_TYPE_JPEG, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RESUME_WINDOW_MS, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, importE2eKey, isJsonPlaintext, newConnNonce, newE2eKey, open, openMsg, padPlaintext, parseAgentToRelay, parseRelayToAgent, parseViewerMessage, seal, sealMsg };
|
|
325
350
|
export type { AgentToRelay, CdpClosedParams, CdpEventParams, CdpSendParams, CdpSubscribeParams, Direction, EngineToViewer, Field, FieldKind, Frame, HelloParams, HelloResult, PagePopupParams, RelayToAgent, RpcError, RpcNotification, RpcPeer, RpcRequest, RpcResponse, SessionStatus, TakeoverLinkParams, TakeoverParams, TakeoverResult, TakeoverStatus, ViewerErrorCode, ViewerInput, ViewerToEngine };
|
package/dist/index.js
CHANGED
|
@@ -126,7 +126,14 @@ var Num = Type.Number();
|
|
|
126
126
|
var Lit = (v) => Type.Literal(v);
|
|
127
127
|
var ViewerToEngineSchema = Type.Union([
|
|
128
128
|
Type.Object(
|
|
129
|
-
{
|
|
129
|
+
{
|
|
130
|
+
t: Lit("hello"),
|
|
131
|
+
token: Type.String(),
|
|
132
|
+
resumeKey: Type.Optional(Type.String()),
|
|
133
|
+
code: Type.Optional(Type.String({ pattern: "^[0-9]{6}$" })),
|
|
134
|
+
/** The viewer's random value for this connection; engines that announce v: 2 echo it in ready (anti-replay). */
|
|
135
|
+
vn: Type.Optional(Type.String({ pattern: "^[A-Za-z0-9_-]{16,64}$" }))
|
|
136
|
+
},
|
|
130
137
|
{ additionalProperties: false }
|
|
131
138
|
),
|
|
132
139
|
Type.Object(
|
|
@@ -155,7 +162,7 @@ var ViewerToEngineSchema = Type.Union([
|
|
|
155
162
|
),
|
|
156
163
|
Type.Object({ t: Lit("text"), text: Type.String() }, { additionalProperties: false }),
|
|
157
164
|
Type.Object({ t: Lit("done") }, { additionalProperties: false }),
|
|
158
|
-
Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String()) }, { additionalProperties: false }),
|
|
165
|
+
Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String({ maxLength: 200 })) }, { additionalProperties: false }),
|
|
159
166
|
Type.Object({ t: Lit("ping") }, { additionalProperties: false })
|
|
160
167
|
]);
|
|
161
168
|
var ViewerErrorCodes = ["token_invalid", "token_used", "expired", "session_closed", "bad_message", "code_required", "code_invalid"];
|
|
@@ -163,7 +170,7 @@ var FieldKinds = ["text", "numeric", "otp", "email", "password"];
|
|
|
163
170
|
var FieldKindSchema = Type.Union(FieldKinds.map((k) => Lit(k)));
|
|
164
171
|
var FieldSchema = Type.Object({ x: Num, y: Num, w: Num, h: Num, kind: FieldKindSchema }, { additionalProperties: false });
|
|
165
172
|
var EngineToViewerSchema = Type.Union([
|
|
166
|
-
Type.Object({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String() }),
|
|
173
|
+
Type.Object({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String(), vn: Type.Optional(Type.String()) }),
|
|
167
174
|
Type.Object({ t: Lit("state"), status: SessionStatusSchema }),
|
|
168
175
|
Type.Object({ t: Lit("error"), code: Type.Union(ViewerErrorCodes.map((c) => Lit(c))), message: Type.String() }),
|
|
169
176
|
Type.Object({ t: Lit("pong") }),
|
|
@@ -179,6 +186,7 @@ function parseViewerMessage(raw) {
|
|
|
179
186
|
}
|
|
180
187
|
return Value.Check(ViewerToEngineSchema, v) ? v : null;
|
|
181
188
|
}
|
|
189
|
+
var RESUME_WINDOW_MS = 5 * 6e4;
|
|
182
190
|
|
|
183
191
|
// src/relay.ts
|
|
184
192
|
import { Type as Type2 } from "@sinclair/typebox";
|
|
@@ -190,6 +198,11 @@ var RELAY_LIMITS = {
|
|
|
190
198
|
agentPayloadMax: 2097152,
|
|
191
199
|
viewerPayloadMax: 65536,
|
|
192
200
|
viewersPerSession: 4,
|
|
201
|
+
/** Viewers that haven't been confirmed (see relay-core attachViewer) one client IP may hold in one session. */
|
|
202
|
+
unconfirmedViewersPerIp: 2,
|
|
203
|
+
/** Viewer → agent bytes one viewer connection may send per window. */
|
|
204
|
+
viewerBytesPerWindow: 2097152,
|
|
205
|
+
viewerByteWindowMs: 1e4,
|
|
193
206
|
idleMs: 12e4,
|
|
194
207
|
heartbeatMs: 3e4,
|
|
195
208
|
graceMs: 6e4,
|
|
@@ -197,18 +210,27 @@ var RELAY_LIMITS = {
|
|
|
197
210
|
billableBytes: 4096,
|
|
198
211
|
backpressureBytes: 4194304,
|
|
199
212
|
viewerUpgradesPerMinPerIp: 30,
|
|
200
|
-
agentUpgradesPerMinPerKey: 20
|
|
213
|
+
agentUpgradesPerMinPerKey: 20,
|
|
214
|
+
/** Agent upgrades per client IP per minute, counted on refused authorizations only (key brute force). */
|
|
215
|
+
agentAuthFailuresPerMinPerIp: 10
|
|
201
216
|
};
|
|
202
217
|
var RELAY_CLOSE = {
|
|
203
218
|
agentReconnecting: 1012,
|
|
204
219
|
replaced: 4409,
|
|
205
220
|
badMessage: 1003,
|
|
206
221
|
tooBig: 1009,
|
|
222
|
+
policy: 1008,
|
|
223
|
+
tryAgainLater: 1013,
|
|
207
224
|
/** A refused agent: 4000 + the HTTP status (4401, 4402, 4403, 4429). Clients can't read upgrade statuses. */
|
|
208
225
|
refused: (status) => 4e3 + status
|
|
209
226
|
};
|
|
210
227
|
var C = Type2.Integer({ minimum: 1, maximum: 4294967295 });
|
|
211
228
|
var strict = { additionalProperties: false };
|
|
229
|
+
var CloseCode = Type2.Union([
|
|
230
|
+
Type2.Integer({ minimum: 1e3, maximum: 1003 }),
|
|
231
|
+
Type2.Integer({ minimum: 1007, maximum: 1014 }),
|
|
232
|
+
Type2.Integer({ minimum: 3e3, maximum: 4999 })
|
|
233
|
+
]);
|
|
212
234
|
var RelayToAgentSchema = Type2.Union([
|
|
213
235
|
Type2.Object({ t: Type2.Literal("open"), c: C }, strict),
|
|
214
236
|
Type2.Object({ t: Type2.Literal("close"), c: C }, strict),
|
|
@@ -217,7 +239,7 @@ var RelayToAgentSchema = Type2.Union([
|
|
|
217
239
|
]);
|
|
218
240
|
var AgentToRelaySchema = Type2.Union([
|
|
219
241
|
Type2.Object({ t: Type2.Literal("hello"), expiresAt: Type2.Number(), secret: Type2.String({ minLength: 1, maxLength: 128 }) }, strict),
|
|
220
|
-
Type2.Object({ t: Type2.Literal("close"), c: C, code:
|
|
242
|
+
Type2.Object({ t: Type2.Literal("close"), c: C, code: CloseCode }, strict),
|
|
221
243
|
Type2.Object({ t: Type2.Literal("pong") }, strict),
|
|
222
244
|
Type2.Object({ t: Type2.Literal("end") }, strict),
|
|
223
245
|
Type2.Object({ t: Type2.Literal("event"), name: Type2.String({ maxLength: 64 }) }, strict)
|
|
@@ -292,6 +314,18 @@ function b64urlDecode(s) {
|
|
|
292
314
|
}
|
|
293
315
|
}
|
|
294
316
|
var isJsonPlaintext = (p) => p[0] === 123;
|
|
317
|
+
var PAD_MIN = 256;
|
|
318
|
+
var PAD_MAX = 65536 - 32;
|
|
319
|
+
function padPlaintext(p) {
|
|
320
|
+
if (p.length >= PAD_MAX) return p;
|
|
321
|
+
let size = PAD_MIN;
|
|
322
|
+
while (size < p.length) size *= 2;
|
|
323
|
+
size = Math.min(size, PAD_MAX);
|
|
324
|
+
if (size === p.length) return p;
|
|
325
|
+
const out = new Uint8Array(size).fill(32);
|
|
326
|
+
out.set(p);
|
|
327
|
+
return out;
|
|
328
|
+
}
|
|
295
329
|
var newConnNonce = () => b64urlEncode(crypto.getRandomValues(new Uint8Array(16)));
|
|
296
330
|
var msgAad = (sessionId, dir, conn, seq) => enc.encode(`unstuck/1|${sessionId}|${dir}|${conn}|${seq}`);
|
|
297
331
|
async function sealMsg(key, sessionId, dir, conn, seq, plain) {
|
|
@@ -328,6 +362,7 @@ export {
|
|
|
328
362
|
RELAY_CLOSE,
|
|
329
363
|
RELAY_LIMITS,
|
|
330
364
|
RELAY_SUBPROTOCOL,
|
|
365
|
+
RESUME_WINDOW_MS,
|
|
331
366
|
RpcCallError,
|
|
332
367
|
SESSION_ID_RE,
|
|
333
368
|
SessionStatusSchema,
|
|
@@ -346,6 +381,7 @@ export {
|
|
|
346
381
|
newE2eKey,
|
|
347
382
|
open,
|
|
348
383
|
openMsg,
|
|
384
|
+
padPlaintext,
|
|
349
385
|
parseAgentToRelay,
|
|
350
386
|
parseRelayToAgent,
|
|
351
387
|
parseViewerMessage,
|