@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 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
- { t: Lit("hello"), token: Type.String(), resumeKey: Type.Optional(Type.String()), code: Type.Optional(Type.String({ pattern: "^[0-9]{6}$" })) },
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: Type2.Integer() }, strict),
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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-protocol",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Wire protocol shared by the Unstuck engine, viewer and relays (frames, RPC, end-to-end encryption).",
5
5
  "keywords": [
6
6
  "ai",