worktrust 0.11.0 → 0.11.2
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/README.md +18 -0
- package/engine-release.json +1 -1
- package/package-release.json +1 -1
- package/package.json +10 -1
- package/remote-adapter-claude-code.mjs +5 -3
- package/remote-adapter-codex.mjs +45 -5
- package/remote-adapter-terminal.mjs +248 -0
- package/remote-approval-bridge.mjs +30 -7
- package/remote-approvals.mjs +13 -3
- package/remote-cdp.mjs +60 -0
- package/remote-cli.mjs +25 -6
- package/remote-daemon.mjs +28 -4
- package/remote-endorse.mjs +43 -0
- package/remote-inventory.mjs +14 -3
- package/remote-live-preview.mjs +205 -0
- package/remote-protocol.mjs +542 -338
- package/remote-run.mjs +21 -3
- package/remote-screen-approvals.mjs +79 -0
- package/remote-screen-push.mjs +76 -0
- package/remote-screen-states.mjs +113 -0
- package/remote-session-list.mjs +25 -2
- package/remote-sessions.mjs +10 -21
- package/remote-store.mjs +11 -4
- package/remote-terminal-cli.mjs +85 -0
- package/remote-terminal-sessions.mjs +291 -0
- package/worktrust.mjs +2 -2
package/remote-protocol.mjs
CHANGED
|
@@ -644,12 +644,203 @@ export function availableActions(report ) {
|
|
|
644
644
|
};
|
|
645
645
|
}
|
|
646
646
|
|
|
647
|
+
/**
|
|
648
|
+
* The report a session or a start means: its adapter in its mode (release 19: one adapter may be reported twice, structured
|
|
649
|
+
* and terminal). An absent mode is structured, as every report before release 19 was.
|
|
650
|
+
*/
|
|
651
|
+
export function reportFor (reports , adapter , mode ) {
|
|
652
|
+
const want = mode ?? "structured";
|
|
653
|
+
return reports?.find((r) => r.adapter === adapter && r.mode === want) ?? null;
|
|
654
|
+
}
|
|
655
|
+
|
|
647
656
|
/** A model may be named only if the computer listed it; null asks for the agent's own default. */
|
|
648
657
|
export function isModelReported(report , model ) {
|
|
649
658
|
if (model === null) return true;
|
|
650
659
|
return report.models !== null && report.models.includes(model);
|
|
651
660
|
}
|
|
652
661
|
|
|
662
|
+
// ---- packages/remote-protocol/src/transfer.ts
|
|
663
|
+
/**
|
|
664
|
+
* FILES FROM THE PHONE, AND A LOCAL PREVIEW BACK (owner, 2026-11-07 22:50). docs/remote-agents/PROTOCOL.md "Attachments"
|
|
665
|
+
* and "Local preview". Everything here is sealed: the relay sees the types, their timing and size classes, never a name,
|
|
666
|
+
* a byte of a file or of a picture.
|
|
667
|
+
*
|
|
668
|
+
* ATTACHMENTS. An image, a PDF or a document travels in chunks of at most 512 KiB (`attachment.put`), each naming the whole
|
|
669
|
+
* file's size, its chunk count and its SHA-256; the computer keeps the chunks apart, joins them when all arrived, checks the
|
|
670
|
+
* hash and that the bytes are what the type says (a PNG starts like a PNG), and only then writes ONE file into the
|
|
671
|
+
* session's project at `.worktrust/inbox/<session_id>/<safe name>` (mode 0600, never executable). `attachment.stored`
|
|
672
|
+
* answers every chunk with the count received (a measured progress) and, once whole, the file's path relative to the
|
|
673
|
+
* project, which a later `agent.start` / `agent.prompt` names by its id (`attachments`), so the agent is told to read it.
|
|
674
|
+
* Caps: 25 MB a file, 100 MB a session. `attachment.clear` deletes the session's inbox.
|
|
675
|
+
*
|
|
676
|
+
* LOCAL PREVIEW. The phone's "Deploy" segment is a LOCAL preview, never a production deploy: `preview.render` asks the
|
|
677
|
+
* computer to render a page of a dev server on 127.0.0.1 at a port the person granted for that project at the keyboard
|
|
678
|
+
* (`worktrust remote preview allow <port>`), or a built HTML file in the project the person granted, at a phone, tablet or
|
|
679
|
+
* desktop viewport, with the person's own installed Chrome or Chromium (headless; nothing is installed). The answer is a
|
|
680
|
+
* PNG in chunks (`preview.image`) and its record (`preview.rendered`: the page's title and HTTP status as the computer saw
|
|
681
|
+
* them). `preview.targets` lists what is granted and whether something listens. Never a URL the phone writes, never
|
|
682
|
+
* another host, never a port forward.
|
|
683
|
+
*/
|
|
684
|
+
|
|
685
|
+
export const ATTACHMENT_CHUNK_BYTES = 524_288;
|
|
686
|
+
export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
|
|
687
|
+
export const MAX_SESSION_ATTACHMENT_BYTES = 100 * 1024 * 1024;
|
|
688
|
+
export const MAX_ATTACHMENT_CHUNKS = Math.ceil(MAX_ATTACHMENT_BYTES / ATTACHMENT_CHUNK_BYTES);
|
|
689
|
+
export const ATTACHMENT_TYPES = [
|
|
690
|
+
"image/png", "image/jpeg", "image/heic", "image/webp", "application/pdf", "text/plain", "text/markdown", "text/csv",
|
|
691
|
+
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
|
692
|
+
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
|
693
|
+
] ;
|
|
694
|
+
|
|
695
|
+
export const MAX_ATTACHMENTS_PER_PROMPT = 20;
|
|
696
|
+
|
|
697
|
+
export const PREVIEW_VIEWPORTS = { mobile: { width: 390, height: 844 }, tablet: { width: 820, height: 1180 }, desktop: { width: 1440, height: 900 } } ;
|
|
698
|
+
export const PREVIEW_CHUNK_BYTES = 524_288;
|
|
699
|
+
export const MAX_PREVIEW_BYTES = 8 * 1024 * 1024;
|
|
700
|
+
export const MAX_PREVIEW_CHUNKS = Math.ceil(MAX_PREVIEW_BYTES / PREVIEW_CHUNK_BYTES);
|
|
701
|
+
/** A path on the granted dev server: starts with one slash, URL characters only, never `//` (another host). */
|
|
702
|
+
export const PREVIEW_PATH = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@%\/?#-]{0,299}$/;
|
|
703
|
+
|
|
704
|
+
export const TRANSFER_COMMAND_SPECS = {
|
|
705
|
+
"attachment.put": object({
|
|
706
|
+
attachment_id: id("att"),
|
|
707
|
+
name: text(200, 1),
|
|
708
|
+
content_type: oneOf(ATTACHMENT_TYPES),
|
|
709
|
+
size: int(1, MAX_ATTACHMENT_BYTES),
|
|
710
|
+
sha256: b64({ exact: 32 }),
|
|
711
|
+
chunk: int(0, MAX_ATTACHMENT_CHUNKS - 1),
|
|
712
|
+
chunks: int(1, MAX_ATTACHMENT_CHUNKS),
|
|
713
|
+
data: b64({ max: ATTACHMENT_CHUNK_BYTES }),
|
|
714
|
+
}),
|
|
715
|
+
"attachment.clear": object({}),
|
|
716
|
+
"preview.targets": object({ project_id: id("prj") }),
|
|
717
|
+
"preview.render": object({
|
|
718
|
+
preview_id: id("pvw"),
|
|
719
|
+
project_id: id("prj"),
|
|
720
|
+
target: oneOf(["port", "file"]),
|
|
721
|
+
port: nullable(int(1, 65_535)),
|
|
722
|
+
/** For a port: the path on that server ("/" by default). For a file: its path inside the project. */
|
|
723
|
+
path: text(300, 1),
|
|
724
|
+
viewport: oneOf(["mobile", "tablet", "desktop"]),
|
|
725
|
+
full_page: bool(),
|
|
726
|
+
}),
|
|
727
|
+
} ;
|
|
728
|
+
|
|
729
|
+
export const TRANSFER_EVENT_SPECS = {
|
|
730
|
+
"attachment.stored": object({
|
|
731
|
+
attachment_id: id("att"),
|
|
732
|
+
received: int(0, MAX_ATTACHMENT_CHUNKS),
|
|
733
|
+
chunks: int(1, MAX_ATTACHMENT_CHUNKS),
|
|
734
|
+
/** Once whole and checked: the file's path relative to the project; null while chunks are still coming. */
|
|
735
|
+
path: nullable(text(400, 1)),
|
|
736
|
+
size: int(1, MAX_ATTACHMENT_BYTES),
|
|
737
|
+
content_type: oneOf(ATTACHMENT_TYPES),
|
|
738
|
+
}),
|
|
739
|
+
"attachment.cleared": object({ removed: int(0) }),
|
|
740
|
+
"preview.targets": object({
|
|
741
|
+
project_id: id("prj"),
|
|
742
|
+
ports: list(object({ port: int(1, 65_535), listening: bool() }), 20),
|
|
743
|
+
files: list(text(300, 1), 50),
|
|
744
|
+
browser: bool(),
|
|
745
|
+
}),
|
|
746
|
+
"preview.image": object({ preview_id: id("pvw"), chunk: int(0, MAX_PREVIEW_CHUNKS - 1), chunks: int(1, MAX_PREVIEW_CHUNKS), data: b64({ max: PREVIEW_CHUNK_BYTES }) }),
|
|
747
|
+
"preview.rendered": object({
|
|
748
|
+
preview_id: id("pvw"),
|
|
749
|
+
project_id: id("prj"),
|
|
750
|
+
viewport: oneOf(["mobile", "tablet", "desktop"]),
|
|
751
|
+
width: int(1, 4096),
|
|
752
|
+
height: int(1, 16_384),
|
|
753
|
+
/** The page's own <title>, or null. */
|
|
754
|
+
title: nullable(text(300, 1)),
|
|
755
|
+
/** The dev server's HTTP status as the computer read it; null for a file. */
|
|
756
|
+
http_status: nullable(int(100, 599)),
|
|
757
|
+
bytes: int(1, MAX_PREVIEW_BYTES),
|
|
758
|
+
sha256: b64({ exact: 32 }),
|
|
759
|
+
chunks: int(1, MAX_PREVIEW_CHUNKS),
|
|
760
|
+
}),
|
|
761
|
+
} ;
|
|
762
|
+
|
|
763
|
+
export const attachmentRule = (a ) =>
|
|
764
|
+
a.chunk >= a.chunks ? "a chunk past the count" : a.chunks !== Math.ceil(a.size / ATTACHMENT_CHUNK_BYTES) ? "a chunk count that is not the size's" : null;
|
|
765
|
+
export const previewRule = (r ) =>
|
|
766
|
+
r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null) : r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
|
|
767
|
+
|
|
768
|
+
// ---- packages/remote-protocol/src/live-preview.ts
|
|
769
|
+
/**
|
|
770
|
+
* THE LIVE PREVIEW (release 19, 2026-11-09; owner's preview option A): the session's granted dev page (or built file), live
|
|
771
|
+
* and touchable on the phone. The computer runs the person's own Chrome headless in a throw-away profile, drives it over
|
|
772
|
+
* the DevTools protocol through a PIPE (never a debugging port), and sends what it draws as JPEG frames on the session's
|
|
773
|
+
* transient lane (envelopes.ts: never journaled, never buffered, newest wins); the phone's taps, scrolls and typed text
|
|
774
|
+
* go back as these commands and are applied to the page.
|
|
775
|
+
*
|
|
776
|
+
* What a phone may say is closed: a granted target and a PATH on it (never a URL or a host), a viewport preset, a tap or a
|
|
777
|
+
* scroll at page coordinates inside the viewport, literal text, one of three keys, follow or stop. The computer holds the
|
|
778
|
+
* page to the granted origin: every navigation or request elsewhere, a file:// page, a download, a popup and a permission
|
|
779
|
+
* prompt is blocked and counted in `blocked`, never followed. One live preview per computer; it stops when nobody follows
|
|
780
|
+
* it (the computer's timeout) or the session closes, and the browser and its profile are removed.
|
|
781
|
+
*/
|
|
782
|
+
|
|
783
|
+
export const LIVE_VIEWPORTS = ["mobile", "tablet", "desktop"] ;
|
|
784
|
+
|
|
785
|
+
/** The keys a phone may press in a live page, besides typing literal text. */
|
|
786
|
+
export const LIVE_KEYS = ["Enter", "Backspace", "Tab"] ;
|
|
787
|
+
export const MAX_LIVE_TEXT = 1000;
|
|
788
|
+
/** A frame's JPEG, at most (a sealed body holds 1 MiB of plaintext; base64 grows it by a third). */
|
|
789
|
+
export const MAX_FRAME_BYTES = 393_216;
|
|
790
|
+
export const LIVE_BLOCK_KINDS = ["navigation", "request", "popup", "download", "permission", "file"] ;
|
|
791
|
+
export const LIVE_STATES = ["starting", "live", "stopped", "failed"] ;
|
|
792
|
+
export const LIVE_REASONS = ["no_browser", "not_listening", "not_granted", "busy", "unfollowed", "closed", "browser_exited", "stopped", "failed"] ;
|
|
793
|
+
|
|
794
|
+
const x = int(0, 4095);
|
|
795
|
+
const y = int(0, 16_383);
|
|
796
|
+
|
|
797
|
+
export const LIVE_COMMAND_SPECS = {
|
|
798
|
+
/** Start the session project's granted port (with a path on it) or granted file, in a viewport preset. */
|
|
799
|
+
"preview.live_start": object({ target: oneOf(["port", "file"]), port: nullable(int(1, 65_535)), path: text(300, 1), viewport: oneOf(LIVE_VIEWPORTS) }),
|
|
800
|
+
/** One touch: a tap or a scroll at page coordinates, literal text, or one allowed key. */
|
|
801
|
+
"preview.live_input": union("kind", {
|
|
802
|
+
tap: object({ kind: oneOf(["tap"]), x, y }),
|
|
803
|
+
scroll: object({ kind: oneOf(["scroll"]), x, y, dy: int(-4000, 4000) }),
|
|
804
|
+
text: object({ kind: oneOf(["text"]), text: text(MAX_LIVE_TEXT, 1) }),
|
|
805
|
+
key: object({ kind: oneOf(["key"]), key: oneOf(LIVE_KEYS) }),
|
|
806
|
+
}),
|
|
807
|
+
/** Another preset, live (the page stays; its viewport changes). */
|
|
808
|
+
"preview.live_viewport": object({ viewport: oneOf(LIVE_VIEWPORTS) }),
|
|
809
|
+
/** true: keep it going (renewed, the computer's own timeout); false: stop it now. */
|
|
810
|
+
"preview.live_follow": object({ follow: bool() }),
|
|
811
|
+
} ;
|
|
812
|
+
|
|
813
|
+
const counts = object({ navigation: int(0), request: int(0), popup: int(0), download: int(0), permission: int(0), file: int(0) });
|
|
814
|
+
|
|
815
|
+
export const LIVE_EVENT_SPECS = {
|
|
816
|
+
/** The live preview's state, on every change: ordered and kept like any session event (small, no picture). */
|
|
817
|
+
"preview.live": object({
|
|
818
|
+
state: oneOf(LIVE_STATES),
|
|
819
|
+
viewport: oneOf(LIVE_VIEWPORTS),
|
|
820
|
+
width: int(1, 4096),
|
|
821
|
+
height: int(1, 16_384),
|
|
822
|
+
/** The page's own <title> and its path on the granted origin, as the computer read them; null when unknown. */
|
|
823
|
+
title: nullable(text(300, 1)),
|
|
824
|
+
path: nullable(text(300, 1)),
|
|
825
|
+
/** What the computer refused the page, counted since the start. */
|
|
826
|
+
blocked: counts,
|
|
827
|
+
reason: nullable(oneOf(LIVE_REASONS)),
|
|
828
|
+
}),
|
|
829
|
+
/** One frame as the browser drew it, JPEG; only ever on the transient lane (envelopes.ts). */
|
|
830
|
+
"preview.frame": object({ width: int(1, 4096), height: int(1, 16_384), data: b64({ max: MAX_FRAME_BYTES }) }),
|
|
831
|
+
} ;
|
|
832
|
+
|
|
833
|
+
export const NO_BLOCKS = { navigation: 0, request: 0, popup: 0, download: 0, permission: 0, file: 0 };
|
|
834
|
+
|
|
835
|
+
/** A port and a path on it, or a granted .html file and no port: never a URL, a host, a scheme or `..`. */
|
|
836
|
+
export const liveStartRule = (r ) =>
|
|
837
|
+
r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null)
|
|
838
|
+
: r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
|
|
839
|
+
|
|
840
|
+
/** Text a page may be typed: printable, no control character (a newline is the Enter key). */
|
|
841
|
+
// eslint-disable-next-line no-control-regex
|
|
842
|
+
export const liveTextOk = (t ) => !/[\u0000-\u001f\u007f-\u009f]/.test(t);
|
|
843
|
+
|
|
653
844
|
// ---- packages/remote-protocol/src/attention.ts
|
|
654
845
|
/**
|
|
655
846
|
* "NEEDS YOU" AND "FOLLOW". A session's activity in five words:
|
|
@@ -1439,112 +1630,6 @@ export function deliveryHops(r )
|
|
|
1439
1630
|
return { to_relay_ms: span(r.sent_at, r.relay_ack_seen_at), on_computer_ms: span(r.received_at, r.accepted_at) };
|
|
1440
1631
|
}
|
|
1441
1632
|
|
|
1442
|
-
// ---- packages/remote-protocol/src/transfer.ts
|
|
1443
|
-
/**
|
|
1444
|
-
* FILES FROM THE PHONE, AND A LOCAL PREVIEW BACK (owner, 2026-11-07 22:50). docs/remote-agents/PROTOCOL.md "Attachments"
|
|
1445
|
-
* and "Local preview". Everything here is sealed: the relay sees the types, their timing and size classes, never a name,
|
|
1446
|
-
* a byte of a file or of a picture.
|
|
1447
|
-
*
|
|
1448
|
-
* ATTACHMENTS. An image, a PDF or a document travels in chunks of at most 512 KiB (`attachment.put`), each naming the whole
|
|
1449
|
-
* file's size, its chunk count and its SHA-256; the computer keeps the chunks apart, joins them when all arrived, checks the
|
|
1450
|
-
* hash and that the bytes are what the type says (a PNG starts like a PNG), and only then writes ONE file into the
|
|
1451
|
-
* session's project at `.worktrust/inbox/<session_id>/<safe name>` (mode 0600, never executable). `attachment.stored`
|
|
1452
|
-
* answers every chunk with the count received (a measured progress) and, once whole, the file's path relative to the
|
|
1453
|
-
* project, which a later `agent.start` / `agent.prompt` names by its id (`attachments`), so the agent is told to read it.
|
|
1454
|
-
* Caps: 25 MB a file, 100 MB a session. `attachment.clear` deletes the session's inbox.
|
|
1455
|
-
*
|
|
1456
|
-
* LOCAL PREVIEW. The phone's "Deploy" segment is a LOCAL preview, never a production deploy: `preview.render` asks the
|
|
1457
|
-
* computer to render a page of a dev server on 127.0.0.1 at a port the person granted for that project at the keyboard
|
|
1458
|
-
* (`worktrust remote preview allow <port>`), or a built HTML file in the project the person granted, at a phone, tablet or
|
|
1459
|
-
* desktop viewport, with the person's own installed Chrome or Chromium (headless; nothing is installed). The answer is a
|
|
1460
|
-
* PNG in chunks (`preview.image`) and its record (`preview.rendered`: the page's title and HTTP status as the computer saw
|
|
1461
|
-
* them). `preview.targets` lists what is granted and whether something listens. Never a URL the phone writes, never
|
|
1462
|
-
* another host, never a port forward.
|
|
1463
|
-
*/
|
|
1464
|
-
|
|
1465
|
-
export const ATTACHMENT_CHUNK_BYTES = 524_288;
|
|
1466
|
-
export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
|
|
1467
|
-
export const MAX_SESSION_ATTACHMENT_BYTES = 100 * 1024 * 1024;
|
|
1468
|
-
export const MAX_ATTACHMENT_CHUNKS = Math.ceil(MAX_ATTACHMENT_BYTES / ATTACHMENT_CHUNK_BYTES);
|
|
1469
|
-
export const ATTACHMENT_TYPES = [
|
|
1470
|
-
"image/png", "image/jpeg", "image/heic", "image/webp", "application/pdf", "text/plain", "text/markdown", "text/csv",
|
|
1471
|
-
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
|
1472
|
-
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
|
1473
|
-
] ;
|
|
1474
|
-
|
|
1475
|
-
export const MAX_ATTACHMENTS_PER_PROMPT = 20;
|
|
1476
|
-
|
|
1477
|
-
export const PREVIEW_VIEWPORTS = { mobile: { width: 390, height: 844 }, tablet: { width: 820, height: 1180 }, desktop: { width: 1440, height: 900 } } ;
|
|
1478
|
-
export const PREVIEW_CHUNK_BYTES = 524_288;
|
|
1479
|
-
export const MAX_PREVIEW_BYTES = 8 * 1024 * 1024;
|
|
1480
|
-
export const MAX_PREVIEW_CHUNKS = Math.ceil(MAX_PREVIEW_BYTES / PREVIEW_CHUNK_BYTES);
|
|
1481
|
-
/** A path on the granted dev server: starts with one slash, URL characters only, never `//` (another host). */
|
|
1482
|
-
export const PREVIEW_PATH = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@%\/?#-]{0,299}$/;
|
|
1483
|
-
|
|
1484
|
-
export const TRANSFER_COMMAND_SPECS = {
|
|
1485
|
-
"attachment.put": object({
|
|
1486
|
-
attachment_id: id("att"),
|
|
1487
|
-
name: text(200, 1),
|
|
1488
|
-
content_type: oneOf(ATTACHMENT_TYPES),
|
|
1489
|
-
size: int(1, MAX_ATTACHMENT_BYTES),
|
|
1490
|
-
sha256: b64({ exact: 32 }),
|
|
1491
|
-
chunk: int(0, MAX_ATTACHMENT_CHUNKS - 1),
|
|
1492
|
-
chunks: int(1, MAX_ATTACHMENT_CHUNKS),
|
|
1493
|
-
data: b64({ max: ATTACHMENT_CHUNK_BYTES }),
|
|
1494
|
-
}),
|
|
1495
|
-
"attachment.clear": object({}),
|
|
1496
|
-
"preview.targets": object({ project_id: id("prj") }),
|
|
1497
|
-
"preview.render": object({
|
|
1498
|
-
preview_id: id("pvw"),
|
|
1499
|
-
project_id: id("prj"),
|
|
1500
|
-
target: oneOf(["port", "file"]),
|
|
1501
|
-
port: nullable(int(1, 65_535)),
|
|
1502
|
-
/** For a port: the path on that server ("/" by default). For a file: its path inside the project. */
|
|
1503
|
-
path: text(300, 1),
|
|
1504
|
-
viewport: oneOf(["mobile", "tablet", "desktop"]),
|
|
1505
|
-
full_page: bool(),
|
|
1506
|
-
}),
|
|
1507
|
-
} ;
|
|
1508
|
-
|
|
1509
|
-
export const TRANSFER_EVENT_SPECS = {
|
|
1510
|
-
"attachment.stored": object({
|
|
1511
|
-
attachment_id: id("att"),
|
|
1512
|
-
received: int(0, MAX_ATTACHMENT_CHUNKS),
|
|
1513
|
-
chunks: int(1, MAX_ATTACHMENT_CHUNKS),
|
|
1514
|
-
/** Once whole and checked: the file's path relative to the project; null while chunks are still coming. */
|
|
1515
|
-
path: nullable(text(400, 1)),
|
|
1516
|
-
size: int(1, MAX_ATTACHMENT_BYTES),
|
|
1517
|
-
content_type: oneOf(ATTACHMENT_TYPES),
|
|
1518
|
-
}),
|
|
1519
|
-
"attachment.cleared": object({ removed: int(0) }),
|
|
1520
|
-
"preview.targets": object({
|
|
1521
|
-
project_id: id("prj"),
|
|
1522
|
-
ports: list(object({ port: int(1, 65_535), listening: bool() }), 20),
|
|
1523
|
-
files: list(text(300, 1), 50),
|
|
1524
|
-
browser: bool(),
|
|
1525
|
-
}),
|
|
1526
|
-
"preview.image": object({ preview_id: id("pvw"), chunk: int(0, MAX_PREVIEW_CHUNKS - 1), chunks: int(1, MAX_PREVIEW_CHUNKS), data: b64({ max: PREVIEW_CHUNK_BYTES }) }),
|
|
1527
|
-
"preview.rendered": object({
|
|
1528
|
-
preview_id: id("pvw"),
|
|
1529
|
-
project_id: id("prj"),
|
|
1530
|
-
viewport: oneOf(["mobile", "tablet", "desktop"]),
|
|
1531
|
-
width: int(1, 4096),
|
|
1532
|
-
height: int(1, 16_384),
|
|
1533
|
-
/** The page's own <title>, or null. */
|
|
1534
|
-
title: nullable(text(300, 1)),
|
|
1535
|
-
/** The dev server's HTTP status as the computer read it; null for a file. */
|
|
1536
|
-
http_status: nullable(int(100, 599)),
|
|
1537
|
-
bytes: int(1, MAX_PREVIEW_BYTES),
|
|
1538
|
-
sha256: b64({ exact: 32 }),
|
|
1539
|
-
chunks: int(1, MAX_PREVIEW_CHUNKS),
|
|
1540
|
-
}),
|
|
1541
|
-
} ;
|
|
1542
|
-
|
|
1543
|
-
export const attachmentRule = (a ) =>
|
|
1544
|
-
a.chunk >= a.chunks ? "a chunk past the count" : a.chunks !== Math.ceil(a.size / ATTACHMENT_CHUNK_BYTES) ? "a chunk count that is not the size's" : null;
|
|
1545
|
-
export const previewRule = (r ) =>
|
|
1546
|
-
r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null) : r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
|
|
1547
|
-
|
|
1548
1633
|
// ---- packages/remote-protocol/src/state-machine.ts
|
|
1549
1634
|
/**
|
|
1550
1635
|
* DELIVERY AND EXECUTION, AS A PURE FUNCTION. One command's state, from the phone's draft to its end:
|
|
@@ -1696,57 +1781,308 @@ export function confirmationOf(state ) {
|
|
|
1696
1781
|
export const shouldResend = (state , now , expiresAt ) =>
|
|
1697
1782
|
(state === "SUBMITTED_TO_RELAY" || state === "UNKNOWN_DELIVERY") && now < expiresAt;
|
|
1698
1783
|
|
|
1699
|
-
// ---- packages/remote-protocol/src/control.ts
|
|
1784
|
+
// ---- packages/remote-protocol/src/control.ts
|
|
1785
|
+
/**
|
|
1786
|
+
* PAUSE, RESUME AND STOP, AS ASKED AND AS SEEN. A control request is not its effect: "pause requested" is what the
|
|
1787
|
+
* phone did, "paused" is what the computer reported. The UI shows the one it knows.
|
|
1788
|
+
*
|
|
1789
|
+
* none -> pause_requested -> paused | unable_to_pause
|
|
1790
|
+
* paused -> resume_requested -> none
|
|
1791
|
+
* any (but stopped) -> stop_requested -> stopped
|
|
1792
|
+
*
|
|
1793
|
+
* Stop wins: once requested, a pause or a resume is not offered and a late `paused` does not hide the stop.
|
|
1794
|
+
* `unable_to_pause` is the computer saying this agent cannot pause (command.rejected for agent.pause); it is shown,
|
|
1795
|
+
* and stop is still offered.
|
|
1796
|
+
*/
|
|
1797
|
+
|
|
1798
|
+
export const CONTROL_STATES = ["none", "pause_requested", "paused", "resume_requested", "stop_requested", "stopped", "unable_to_pause"] ;
|
|
1799
|
+
|
|
1800
|
+
export function controlTransition(state , input ) {
|
|
1801
|
+
if (state === "stopped") return state;
|
|
1802
|
+
const stopping = state === "stop_requested";
|
|
1803
|
+
switch (input) {
|
|
1804
|
+
case "stop_sent":
|
|
1805
|
+
return "stop_requested";
|
|
1806
|
+
case "stopped_observed":
|
|
1807
|
+
return "stopped";
|
|
1808
|
+
case "pause_sent":
|
|
1809
|
+
return state === "none" || state === "unable_to_pause" ? "pause_requested" : state;
|
|
1810
|
+
case "paused_observed":
|
|
1811
|
+
return stopping ? state : "paused";
|
|
1812
|
+
case "pause_refused":
|
|
1813
|
+
return state === "pause_requested" ? "unable_to_pause" : state;
|
|
1814
|
+
case "resume_sent":
|
|
1815
|
+
return state === "paused" ? "resume_requested" : state;
|
|
1816
|
+
case "resumed_observed":
|
|
1817
|
+
return stopping ? state : "none";
|
|
1818
|
+
case "resume_refused":
|
|
1819
|
+
return state === "resume_requested" ? "paused" : state;
|
|
1820
|
+
case "run_ended":
|
|
1821
|
+
return stopping ? state : "none";
|
|
1822
|
+
}
|
|
1823
|
+
}
|
|
1824
|
+
|
|
1825
|
+
/** Which control buttons exist right now: the adapter's own capabilities, the run's state and the control state. */
|
|
1826
|
+
export function controlsOffered(actions , delivery , control ) {
|
|
1827
|
+
const live = !isTerminal(delivery) && DELIVERY_RANK[delivery] >= DELIVERY_RANK.RELAY_ACKNOWLEDGED;
|
|
1828
|
+
const stopping = control === "stop_requested" || control === "stopped";
|
|
1829
|
+
const running = delivery === "RUNNING" || delivery === "WAITING_APPROVAL";
|
|
1830
|
+
return {
|
|
1831
|
+
pause: actions.pause && live && !stopping && running && (control === "none"),
|
|
1832
|
+
resume: actions.resume && live && !stopping && (delivery === "PAUSED" || control === "paused"),
|
|
1833
|
+
stop: actions.stop && live && !stopping,
|
|
1834
|
+
};
|
|
1835
|
+
}
|
|
1836
|
+
|
|
1837
|
+
// ---- packages/remote-protocol/src/crypto/keys.ts
|
|
1838
|
+
/**
|
|
1839
|
+
* REMOTE DEVICE KEYS. Each computer and each phone install has its own pair: Ed25519 to sign, X25519 to agree keys.
|
|
1840
|
+
* They are NOT the computer's measurement key: a different key, a different store entry, a different audience. A
|
|
1841
|
+
* stolen remote key cannot sign a measurement, and a measurement key cannot steer an agent; every signature here is
|
|
1842
|
+
* also domain-separated ("worktrust-remote/v1/..."), so a signature made for one purpose verifies for no other.
|
|
1843
|
+
*
|
|
1844
|
+
* A FINGERPRINT FOR PEOPLE. 80 bits of SHA-256 over both public keys, as sixteen Crockford base32 characters in four
|
|
1845
|
+
* groups (no I, L, O or U to misread). Shown on the computer's screen and on the phone when a phone is confirmed at
|
|
1846
|
+
* the computer's keyboard, so a compromised issuer cannot slip in a key of its own unnoticed.
|
|
1847
|
+
*/
|
|
1848
|
+
|
|
1849
|
+
export function generateDeviceKeys(random ) {
|
|
1850
|
+
return { ed25519: random(KEY_BYTES), x25519: random(KEY_BYTES) };
|
|
1851
|
+
}
|
|
1852
|
+
|
|
1853
|
+
export function publicKeysOf(secret ) {
|
|
1854
|
+
return { ed25519_pub: toBase64Url(ed25519PublicKey(secret.ed25519)), x25519_pub: toBase64Url(x25519PublicKey(secret.x25519)) };
|
|
1855
|
+
}
|
|
1856
|
+
|
|
1857
|
+
/** For a store that holds strings (expo-secure-store, the CLI's credential store). */
|
|
1858
|
+
export const exportSecretKeys = (secret ) => ({
|
|
1859
|
+
ed25519: toBase64Url(secret.ed25519),
|
|
1860
|
+
x25519: toBase64Url(secret.x25519),
|
|
1861
|
+
});
|
|
1862
|
+
|
|
1863
|
+
export function importSecretKeys(stored ) {
|
|
1864
|
+
const ed = fromBase64Url(stored.ed25519);
|
|
1865
|
+
const x = fromBase64Url(stored.x25519);
|
|
1866
|
+
return ed?.length === KEY_BYTES && x?.length === KEY_BYTES ? { ed25519: ed, x25519: x } : null;
|
|
1867
|
+
}
|
|
1868
|
+
|
|
1869
|
+
const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
|
|
1870
|
+
const FINGERPRINT_DOMAIN = utf8Encode("worktrust-remote/v1/fingerprint\n");
|
|
1871
|
+
|
|
1872
|
+
function base32Groups(bytes ) {
|
|
1873
|
+
let bits = 0;
|
|
1874
|
+
let acc = 0;
|
|
1875
|
+
let out = "";
|
|
1876
|
+
for (const b of bytes) {
|
|
1877
|
+
acc = (acc << 8) | b;
|
|
1878
|
+
bits += 8;
|
|
1879
|
+
while (bits >= 5) {
|
|
1880
|
+
bits -= 5;
|
|
1881
|
+
out += CROCKFORD[(acc >> bits) & 31] ;
|
|
1882
|
+
}
|
|
1883
|
+
acc &= (1 << bits) - 1;
|
|
1884
|
+
}
|
|
1885
|
+
return out.match(/.{1,4}/g) .join("-");
|
|
1886
|
+
}
|
|
1887
|
+
|
|
1888
|
+
function decodeKey(text ) {
|
|
1889
|
+
const bytes = fromBase64Url(text);
|
|
1890
|
+
if (bytes?.length !== KEY_BYTES) throw new TypeError("a public key is 32 bytes of base64url");
|
|
1891
|
+
return bytes;
|
|
1892
|
+
}
|
|
1893
|
+
|
|
1894
|
+
/** "ABCD-EFGH-JKMN-PQRS" for one device's public keys. */
|
|
1895
|
+
export function deviceFingerprint(keys ) {
|
|
1896
|
+
const digest = sha256(concatBytes(FINGERPRINT_DOMAIN, decodeKey(keys.ed25519_pub), decodeKey(keys.x25519_pub)));
|
|
1897
|
+
return base32Groups(digest.subarray(0, 10));
|
|
1898
|
+
}
|
|
1899
|
+
|
|
1900
|
+
// ---- packages/remote-protocol/src/crypto/jws.ts
|
|
1901
|
+
/**
|
|
1902
|
+
* COMPACT SIGNED TOKENS: JWS (RFC 7515) with EdDSA over Ed25519 (RFC 8037), so the gateway can verify an assertion
|
|
1903
|
+
* with any standard library, and so can the phone and the computer with this package. Three token types, told apart
|
|
1904
|
+
* by `typ` and never interchangeable:
|
|
1905
|
+
* wt-remote-binding+jwt the Passport app binds a device's remote keys to an account
|
|
1906
|
+
* wt-remote-auth+jwt the Passport app authorizes one device at the gateway for five minutes
|
|
1907
|
+
* wt-remote-approval+jwt a phone decides one pending approval
|
|
1908
|
+
* The verifier fixes alg, typ and the key set before it looks at the token: a token cannot choose how it is checked.
|
|
1909
|
+
* Header and payload are canonical JSON, so one claim set has one signing input.
|
|
1910
|
+
*/
|
|
1911
|
+
|
|
1912
|
+
export const TOKEN_TYPES = ["wt-remote-binding+jwt", "wt-remote-auth+jwt", "wt-remote-approval+jwt"] ;
|
|
1913
|
+
|
|
1914
|
+
export const MAX_TOKEN_CHARS = 4096;
|
|
1915
|
+
|
|
1916
|
+
/** Public keys by key id: the issuer's keys (pinned in the app and CLI builds), or a phone's bound key. */
|
|
1917
|
+
|
|
1918
|
+
export function signToken(typ , kid , claims , secret ) {
|
|
1919
|
+
const header = toBase64Url(utf8Encode(canonicalJson({ alg: "EdDSA", kid, typ })));
|
|
1920
|
+
const payload = toBase64Url(utf8Encode(canonicalJson(claims)));
|
|
1921
|
+
const signature = ed25519Sign(utf8Encode(`${header}.${payload}`), secret);
|
|
1922
|
+
return `${header}.${payload}.${toBase64Url(signature)}`;
|
|
1923
|
+
}
|
|
1924
|
+
|
|
1925
|
+
const decodeJson = (part ) => {
|
|
1926
|
+
const bytes = fromBase64Url(part);
|
|
1927
|
+
const text = bytes === null ? null : utf8Decode(bytes);
|
|
1928
|
+
return text === null ? undefined : parseJson(text);
|
|
1929
|
+
};
|
|
1930
|
+
|
|
1931
|
+
export function verifyToken(token , typ , keys ) {
|
|
1932
|
+
if (token.length > MAX_TOKEN_CHARS) return refuse("shape", "token: too long");
|
|
1933
|
+
const parts = token.split(".");
|
|
1934
|
+
if (parts.length !== 3) return refuse("shape", "token: not three parts");
|
|
1935
|
+
const [h, p, s] = parts ;
|
|
1936
|
+
const header = decodeJson(h);
|
|
1937
|
+
if (typeof header !== "object" || header === null || Array.isArray(header)) return refuse("shape", "token: header");
|
|
1938
|
+
const hd = header ;
|
|
1939
|
+
if (Object.keys(hd).sort().join(",") !== "alg,kid,typ") return refuse("shape", "token: header fields");
|
|
1940
|
+
if (hd.alg !== "EdDSA") return refuse("shape", "token: alg");
|
|
1941
|
+
if (hd.typ !== typ) return refuse("shape", "token: typ");
|
|
1942
|
+
if (typeof hd.kid !== "string" || !Object.hasOwn(keys, hd.kid)) return refuse("unknown_key", "token: kid");
|
|
1943
|
+
const key = keys[hd.kid] ;
|
|
1944
|
+
const signature = fromBase64Url(s);
|
|
1945
|
+
if (key.length !== KEY_BYTES || signature === null) return refuse("signature", "token: signature encoding");
|
|
1946
|
+
if (!ed25519Verify(signature, utf8Encode(`${h}.${p}`), key)) return refuse("signature", "token: signature");
|
|
1947
|
+
const claims = decodeJson(p);
|
|
1948
|
+
if (typeof claims !== "object" || claims === null || Array.isArray(claims)) return refuse("shape", "token: payload");
|
|
1949
|
+
// The signed bytes must BE the canonical encoding, so one claim set has exactly one valid token form.
|
|
1950
|
+
if (toBase64Url(utf8Encode(canonicalJson(claims))) !== p) return refuse("shape", "token: payload not canonical");
|
|
1951
|
+
if (toBase64Url(utf8Encode(canonicalJson(hd))) !== h) return refuse("shape", "token: header not canonical");
|
|
1952
|
+
return accept({ kid: hd.kid, claims: claims });
|
|
1953
|
+
}
|
|
1954
|
+
|
|
1955
|
+
/** iat/exp checks shared by every token kind; seconds, with the protocol's skew. */
|
|
1956
|
+
export function checkTimes(iat , exp , nowMs , maxLifetimeS , skewMs ) {
|
|
1957
|
+
if (exp <= iat) return refuse("lifetime", "token: exp not after iat");
|
|
1958
|
+
if (exp - iat > maxLifetimeS) return refuse("lifetime", "token: lives too long");
|
|
1959
|
+
if (iat * 1000 > nowMs + skewMs) return refuse("not_yet_valid", "token: issued in the future");
|
|
1960
|
+
if (exp * 1000 + skewMs < nowMs) return refuse("expired", "token: expired");
|
|
1961
|
+
return accept(true);
|
|
1962
|
+
}
|
|
1963
|
+
|
|
1964
|
+
// ---- packages/remote-protocol/src/crypto/binding.ts
|
|
1965
|
+
/**
|
|
1966
|
+
* A REMOTE KEY BINDING: the Passport app's signed word that these public keys belong to this device of this account.
|
|
1967
|
+
* The person approves the device in app.worktrust.io, signed in with a second factor; the app signs
|
|
1968
|
+
* { iss, aud, sub, device_id, kind, ed25519_pub, x25519_pub, iat, exp, jti }
|
|
1969
|
+
* with a WorkTrust issuer key. `sub` is an opaque account reference for the remote system (an HMAC of the owner id
|
|
1970
|
+
* under a Passport secret, prefixed usr_), never the Passport owner id, so the relay's records join to nothing else.
|
|
1971
|
+
*
|
|
1972
|
+
* Endpoints verify bindings against the issuer's public keys PINNED in the app and CLI builds, never against a key the
|
|
1973
|
+
* relay hands them. The relay cannot forge a binding. The issuer alone cannot add a controller either: a new phone is
|
|
1974
|
+
* pending on the computer until the person confirms its fingerprint at the computer's keyboard (handshake.ts).
|
|
1975
|
+
*/
|
|
1976
|
+
|
|
1977
|
+
export const DEVICE_KINDS = ["phone", "computer"] ;
|
|
1978
|
+
|
|
1979
|
+
export const BINDING_CLAIMS_SPEC = object({
|
|
1980
|
+
iss: oneOf([PASSPORT_ISSUER]),
|
|
1981
|
+
aud: oneOf([GATEWAY_AUDIENCE]),
|
|
1982
|
+
sub: id("usr"),
|
|
1983
|
+
device_id: id("dev"),
|
|
1984
|
+
kind: oneOf(DEVICE_KINDS),
|
|
1985
|
+
ed25519_pub: b64({ exact: 32 }),
|
|
1986
|
+
x25519_pub: b64({ exact: 32 }),
|
|
1987
|
+
iat: int(0),
|
|
1988
|
+
exp: int(0),
|
|
1989
|
+
jti: id("jti"),
|
|
1990
|
+
});
|
|
1991
|
+
|
|
1992
|
+
/** For the Passport app: validate, then sign. */
|
|
1993
|
+
export function issueBinding(claims , issuerSecret , kid ) {
|
|
1994
|
+
const checked = validate(BINDING_CLAIMS_SPEC, claims, "$binding");
|
|
1995
|
+
if (!checked.ok) throw new TypeError(checked.detail);
|
|
1996
|
+
if (claims.exp - claims.iat > MAX_BINDING_LIFETIME_S || claims.exp <= claims.iat) throw new RangeError("binding lifetime");
|
|
1997
|
+
return signToken("wt-remote-binding+jwt", kid, claims, issuerSecret);
|
|
1998
|
+
}
|
|
1999
|
+
|
|
2000
|
+
export function verifyBinding(token , expect ) {
|
|
2001
|
+
const verified = verifyToken(token, "wt-remote-binding+jwt", expect.issuerKeys);
|
|
2002
|
+
if (!verified.ok) return refuse(verified.code === "shape" ? "binding" : verified.code, verified.detail);
|
|
2003
|
+
const shaped = validate(BINDING_CLAIMS_SPEC, verified.value.claims, "$binding");
|
|
2004
|
+
if (!shaped.ok) return refuse("binding", shaped.detail);
|
|
2005
|
+
const b = shaped.value;
|
|
2006
|
+
const times = checkTimes(b.iat, b.exp, expect.now, MAX_BINDING_LIFETIME_S, CLOCK_SKEW_MS);
|
|
2007
|
+
if (!times.ok) return times;
|
|
2008
|
+
if (expect.kind !== undefined && b.kind !== expect.kind) return refuse("binding", "$binding.kind: not the expected kind");
|
|
2009
|
+
if (expect.deviceId !== undefined && b.device_id !== expect.deviceId) return refuse("wrong_device", "$binding.device_id");
|
|
2010
|
+
if (expect.sub !== undefined && b.sub !== expect.sub) return refuse("account_mismatch", "$binding.sub");
|
|
2011
|
+
if (expect.isRevoked?.(b)) return refuse("revoked", "$binding: revoked");
|
|
2012
|
+
return accept(b);
|
|
2013
|
+
}
|
|
2014
|
+
|
|
2015
|
+
/** The signing key a verified binding names, as bytes. */
|
|
2016
|
+
export const bindingSigningKey = (b ) => fromBase64Url(b.ed25519_pub) ;
|
|
2017
|
+
export const bindingAgreementKey = (b ) => fromBase64Url(b.x25519_pub) ;
|
|
2018
|
+
export const bindingFingerprint = (b ) =>
|
|
2019
|
+
deviceFingerprint({ ed25519_pub: b.ed25519_pub, x25519_pub: b.x25519_pub });
|
|
2020
|
+
|
|
2021
|
+
// ---- packages/remote-protocol/src/crypto/endorse.ts
|
|
1700
2022
|
/**
|
|
1701
|
-
*
|
|
1702
|
-
*
|
|
1703
|
-
*
|
|
1704
|
-
*
|
|
1705
|
-
*
|
|
1706
|
-
*
|
|
2023
|
+
* A PHONE ADDS A BROWSER (owner, 2026-11-09: "your phone approves a new browser"; docs/remote-agents/PROTOCOL.md §A phone
|
|
2024
|
+
* endorses a browser). Like linking a messenger's web client: the browser shows a QR code with its issuer binding (its
|
|
2025
|
+
* keys, its device id, its account), a one-time nonce and a short expiry; a CONFIRMED phone scans it, asks the device
|
|
2026
|
+
* unlock, and sends each chosen computer a sealed, signed `browser.endorse` command carrying exactly those three. The
|
|
2027
|
+
* computer adds the browser as a controller only if it allowed endorsements at its keyboard (`worktrust remote phones
|
|
2028
|
+
* allow-endorse on`), the sender is a controller confirmed there or by a scanned QR (never one added by endorsement), the
|
|
2029
|
+
* binding verifies for the computer's OWN account, the endorsement is in time and its nonce was never spent.
|
|
1707
2030
|
*
|
|
1708
|
-
*
|
|
1709
|
-
*
|
|
1710
|
-
*
|
|
2031
|
+
* The QR holds one link, everything in the fragment, which no browser sends to a server:
|
|
2032
|
+
* https://app.worktrust.io/remote/endorse#v=1&b=<binding>&n=<16-byte nonce>&e=<expiry, unix s>
|
|
2033
|
+
* This file is the only reader and writer of that link and the one check both the phone and the computer run.
|
|
1711
2034
|
*/
|
|
1712
2035
|
|
|
1713
|
-
export const
|
|
2036
|
+
export const ENDORSE_VERSION = 1;
|
|
2037
|
+
/** Five minutes at most from the browser showing it to the computer taking it. */
|
|
2038
|
+
export const ENDORSE_LIFETIME_S = 300;
|
|
2039
|
+
export const ENDORSE_LINK_BASE = "https://app.worktrust.io/remote/endorse";
|
|
1714
2040
|
|
|
1715
|
-
|
|
1716
|
-
|
|
1717
|
-
|
|
1718
|
-
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1722
|
-
|
|
1723
|
-
|
|
1724
|
-
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
|
-
|
|
1728
|
-
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
|
|
1735
|
-
|
|
1736
|
-
|
|
2041
|
+
/** What travels: the QR's three fields, and the sealed `browser.endorse` payload, the same three. */
|
|
2042
|
+
export const ENDORSEMENT_SPEC = object({ binding: token(4096), nonce: b64({ exact: 16 }), expires_at: int(0) });
|
|
2043
|
+
|
|
2044
|
+
/** The browser makes one for its own binding: a fresh nonce, five minutes. */
|
|
2045
|
+
export function createEndorsement(binding , nowMs , random ) {
|
|
2046
|
+
return { binding, nonce: toBase64Url(random(16)), expires_at: Math.floor(nowMs / 1000) * 1000 + ENDORSE_LIFETIME_S * 1000 };
|
|
2047
|
+
}
|
|
2048
|
+
|
|
2049
|
+
export function encodeEndorseLink(e , base = ENDORSE_LINK_BASE) {
|
|
2050
|
+
return `${base}#v=${ENDORSE_VERSION}&b=${encodeURIComponent(e.binding)}&n=${e.nonce}&e=${Math.floor(e.expires_at / 1000)}`;
|
|
2051
|
+
}
|
|
2052
|
+
|
|
2053
|
+
export function decodeEndorseLink(link ) {
|
|
2054
|
+
if (typeof link !== "string" || link.length > 6000) return refuse("shape", "$link");
|
|
2055
|
+
const hash = link.indexOf("#");
|
|
2056
|
+
if (hash < 0 || link.slice(0, hash) !== ENDORSE_LINK_BASE) return refuse("shape", "$link: not a WorkTrust browser link");
|
|
2057
|
+
const raw = {};
|
|
2058
|
+
for (const part of link.slice(hash + 1).split("&")) {
|
|
2059
|
+
const eq = part.indexOf("=");
|
|
2060
|
+
const key = eq > 0 ? part.slice(0, eq) : "";
|
|
2061
|
+
if (!["v", "b", "n", "e"].includes(key) || Object.hasOwn(raw, key)) return refuse("shape", "$link: an unknown or repeated key");
|
|
2062
|
+
try { raw[key] = decodeURIComponent(part.slice(eq + 1)); } catch { return refuse("shape", "$link: encoding"); }
|
|
1737
2063
|
}
|
|
2064
|
+
if (raw.v !== String(ENDORSE_VERSION) || !/^[1-9][0-9]{0,11}$/.test(raw.e ?? "")) return refuse("shape", "$link: version or expiry");
|
|
2065
|
+
const shaped = validate(ENDORSEMENT_SPEC, { binding: raw.b, nonce: raw.n, expires_at: Number(raw.e) * 1000 }, "$endorsement");
|
|
2066
|
+
return shaped.ok ? accept(shaped.value) : refuse("shape", shaped.detail);
|
|
1738
2067
|
}
|
|
1739
2068
|
|
|
1740
|
-
/**
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
2069
|
+
/**
|
|
2070
|
+
* THE CHECK, on the phone before it asks the unlock and on the computer before it adds anyone: the binding verifies against
|
|
2071
|
+
* the pinned issuer keys as a controller (kind phone), for `account` (the checker's own binding's `sub`: a phone of account
|
|
2072
|
+
* A never endorses a browser of account B, and a computer never takes a browser of another account), and the endorsement
|
|
2073
|
+
* is in time and never lives longer than five minutes. Single use is the computer's spent-nonce list, not this function.
|
|
2074
|
+
*/
|
|
2075
|
+
export function checkEndorsement(input , o ) {
|
|
2076
|
+
const shaped = validate(ENDORSEMENT_SPEC, input, "$endorsement");
|
|
2077
|
+
if (!shaped.ok) return refuse("shape", shaped.detail);
|
|
2078
|
+
const e = shaped.value;
|
|
2079
|
+
if (e.expires_at <= o.now) return refuse("expired", "$endorsement.expires_at");
|
|
2080
|
+
if (e.expires_at > o.now + ENDORSE_LIFETIME_S * 1000 + CLOCK_SKEW_MS) return refuse("lifetime", "$endorsement.expires_at");
|
|
2081
|
+
const bound = verifyBinding(e.binding, { issuerKeys: o.issuerKeys, now: o.now, kind: "phone" });
|
|
2082
|
+
if (!bound.ok) return refuse(bound.code, bound.detail);
|
|
2083
|
+
if (bound.value.sub !== o.account) return refuse("account_mismatch", "$endorsement.binding.sub");
|
|
2084
|
+
const keys = { ed25519_pub: bound.value.ed25519_pub, x25519_pub: bound.value.x25519_pub };
|
|
2085
|
+
return accept({ device_id: bound.value.device_id, fingerprint: deviceFingerprint(keys), keys, binding: bound.value, nonce: e.nonce, expires_at: e.expires_at });
|
|
1750
2086
|
}
|
|
1751
2087
|
|
|
1752
2088
|
// ---- packages/remote-protocol/src/commands.ts
|
|
@@ -1788,6 +2124,11 @@ export const COMMAND_PAYLOAD_SPECS = {
|
|
|
1788
2124
|
prompt: nullable(text(MAX_PROMPT_CHARS, 1)),
|
|
1789
2125
|
/** The session's name on the phone's project tree (2026-11-07), sealed; renameable with session.rename. */
|
|
1790
2126
|
name: optional(nullable(text(MAX_SESSION_NAME, 1))),
|
|
2127
|
+
/**
|
|
2128
|
+
* Which of the adapter's reports to start (release 19, 2026-11-09): `terminal` runs the agent in a terminal session the
|
|
2129
|
+
* person can also attach at the desk. Absent means structured, as before.
|
|
2130
|
+
*/
|
|
2131
|
+
mode: optional(oneOf(ADAPTER_MODES)),
|
|
1791
2132
|
}),
|
|
1792
2133
|
/**
|
|
1793
2134
|
* A new turn for an agent that waits for input. Sent while a turn runs, it waits (command.queued) and runs when the turn
|
|
@@ -1830,7 +2171,11 @@ export const COMMAND_PAYLOAD_SPECS = {
|
|
|
1830
2171
|
/** A new name for the session (2026-11-07); answered with device.inventory, which lists every session by name. */
|
|
1831
2172
|
"session.rename": object({ name: text(MAX_SESSION_NAME, 1) }),
|
|
1832
2173
|
/** The last lines of a terminal session's screen, answered with agent.screen. */
|
|
1833
|
-
|
|
2174
|
+
/**
|
|
2175
|
+
* `follow` (release 19, 2026-11-09): true asks the computer to send the screen again whenever it changes (agent.screen,
|
|
2176
|
+
* coalesced) for a while (the computer's limit, renewed by every read that follows), false stops it. Absent: one read.
|
|
2177
|
+
*/
|
|
2178
|
+
"screen.read": object({ lines: int(1, 2000), follow: optional(bool()) }),
|
|
1834
2179
|
/** Ask for a device.inventory; `refresh_models` runs the agents' own model listers first. */
|
|
1835
2180
|
"inventory.get": object({ refresh_models: bool() }),
|
|
1836
2181
|
/** This computer's remote settings, each optional. Pausing from the phone is soft; `worktrust remote disable` at the
|
|
@@ -1846,11 +2191,19 @@ export const COMMAND_PAYLOAD_SPECS = {
|
|
|
1846
2191
|
"pairing.revoke": object({}),
|
|
1847
2192
|
/** Files from the phone and a local preview back (transfer.ts, 2026-11-07). */
|
|
1848
2193
|
...TRANSFER_COMMAND_SPECS,
|
|
2194
|
+
/** The live preview (release 19, live-preview.ts): session commands. */
|
|
2195
|
+
...LIVE_COMMAND_SPECS,
|
|
1849
2196
|
/**
|
|
1850
2197
|
* One new, empty project folder named `name` inside the root `root_id` (2026-11-07), granted as a project; `git init`
|
|
1851
2198
|
* in it only when the person enabled that for the root at the keyboard. Answered with project.created.
|
|
1852
2199
|
*/
|
|
1853
2200
|
"project.create": object({ name: text(100, 1), root_id: id("rot") }),
|
|
2201
|
+
/**
|
|
2202
|
+
* A confirmed phone adds a browser it scanned as a controller of this computer (2026-11-09, crypto/endorse.ts): the
|
|
2203
|
+
* browser's issuer binding, the QR's one-time nonce and its expiry. Taken only when the computer allowed endorsements at
|
|
2204
|
+
* its keyboard, from a phone confirmed there or by a scanned QR, for the computer's own account, in time, nonce unspent.
|
|
2205
|
+
*/
|
|
2206
|
+
"browser.endorse": ENDORSEMENT_SPEC,
|
|
1854
2207
|
/** A release: a bundle of tasks in one project (release.ts). Ids are minted by the phone, once. */
|
|
1855
2208
|
"release.create": object({
|
|
1856
2209
|
release_id: id("rel"),
|
|
@@ -1895,7 +2248,7 @@ export const COMMAND_PAYLOAD_SPECS = {
|
|
|
1895
2248
|
export const COMMAND_TYPES = Object.keys(COMMAND_PAYLOAD_SPECS) ;
|
|
1896
2249
|
|
|
1897
2250
|
export const RELEASE_COMMANDS = new Set (["release.create", "release.add_task", "release.reorder", "release.cancel_task", "release.start", "release.list", "pipeline.start", "pipeline.cancel"]);
|
|
1898
|
-
export const DEVICE_COMMANDS = new Set (["inventory.get", "device.configure", "pairing.revoke", "project.create", "preview.targets", "preview.render", ...RELEASE_COMMANDS]);
|
|
2251
|
+
export const DEVICE_COMMANDS = new Set (["inventory.get", "device.configure", "pairing.revoke", "project.create", "browser.endorse", "preview.targets", "preview.render", ...RELEASE_COMMANDS]);
|
|
1899
2252
|
export const commandScope = (type ) => (DEVICE_COMMANDS.has(type) ? "device" : "session");
|
|
1900
2253
|
|
|
1901
2254
|
/** Commands whose acceptance starts a run with steps, approvals and an end (state-machine.ts follows those through
|
|
@@ -1922,11 +2275,16 @@ export const COMMAND_TTL_MS = {
|
|
|
1922
2275
|
"session.close": 5 * MINUTE,
|
|
1923
2276
|
"session.rename": 5 * MINUTE,
|
|
1924
2277
|
"project.create": 10 * MINUTE,
|
|
2278
|
+
"browser.endorse": 5 * MINUTE,
|
|
1925
2279
|
"attachment.put": 60 * MINUTE,
|
|
1926
2280
|
"attachment.clear": 10 * MINUTE,
|
|
1927
2281
|
"preview.targets": 1 * MINUTE,
|
|
1928
2282
|
"preview.render": 2 * MINUTE,
|
|
1929
2283
|
"screen.read": 1 * MINUTE,
|
|
2284
|
+
"preview.live_start": 2 * MINUTE,
|
|
2285
|
+
"preview.live_input": 1 * MINUTE,
|
|
2286
|
+
"preview.live_viewport": 1 * MINUTE,
|
|
2287
|
+
"preview.live_follow": 1 * MINUTE,
|
|
1930
2288
|
"inventory.get": 5 * MINUTE,
|
|
1931
2289
|
"device.configure": 10 * MINUTE,
|
|
1932
2290
|
"pairing.revoke": 24 * 60 * MINUTE,
|
|
@@ -1960,6 +2318,8 @@ export function validateCommandPayload (type , value
|
|
|
1960
2318
|
if (type === "device.configure" && Object.keys(payload).length === 0) return refuse("payload", "$payload: names no setting");
|
|
1961
2319
|
if (type === "attachment.put") { const bad = attachmentRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
|
|
1962
2320
|
if (type === "preview.render") { const bad = previewRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
|
|
2321
|
+
if (type === "preview.live_start") { const bad = liveStartRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
|
|
2322
|
+
if (type === "preview.live_input") { const i = payload ; if (i.kind === "text" && !liveTextOk(i.text)) return refuse("payload", "$payload.text: literal text, no control character"); }
|
|
1963
2323
|
if (type === "project.create" && !projectNameOk((payload ).name))
|
|
1964
2324
|
return refuse("payload", "$payload.name: one folder name of [A-Za-z0-9._-], not starting with a dot");
|
|
1965
2325
|
if (type === "release.reorder") {
|
|
@@ -2071,6 +2431,7 @@ export const REJECT_REASONS = [
|
|
|
2071
2431
|
"conflict", // a command id reused for different bytes
|
|
2072
2432
|
"busy", // the agent is mid-turn and the command needs it idle (a release: its tasks still run, or no slot for a pipeline)
|
|
2073
2433
|
"unreviewed", // the project's pipeline file was not reviewed at the keyboard, or changed since (2026-11-07)
|
|
2434
|
+
"not_allowed", // the computer did not allow it at its keyboard (a browser endorsement without allow-endorse), or the sender may not (2026-11-09)
|
|
2074
2435
|
] ;
|
|
2075
2436
|
|
|
2076
2437
|
export const FAIL_REASONS = ["agent_exited", "adapter_error", "not_ready", "timeout", "internal"] ;
|
|
@@ -2124,6 +2485,8 @@ export const EVENT_BODY_SPECS = {
|
|
|
2124
2485
|
project_label: nullable(label(256)),
|
|
2125
2486
|
/** The name the phone gave it (agent.start's name, a release task's label), or null. */
|
|
2126
2487
|
name: optional(nullable(label(100))),
|
|
2488
|
+
/** `terminal` for a session in a terminal the desk can attach (release 19); absent means structured. */
|
|
2489
|
+
mode: optional(oneOf(ADAPTER_MODES)),
|
|
2127
2490
|
}),
|
|
2128
2491
|
"command.device_received": object({}),
|
|
2129
2492
|
/** started_at: the computer's clock when the acceptance began a turn (usage.ts); absent for any other acceptance. */
|
|
@@ -2227,6 +2590,8 @@ export const EVENT_BODY_SPECS = {
|
|
|
2227
2590
|
task_id: optional(nullable(id("tsk"))),
|
|
2228
2591
|
/** Background jobs its agent reports still running (2026-11-08: "ready, but a job is still running"); absent when it cannot tell. */
|
|
2229
2592
|
background_jobs: optional(int(0, 99)),
|
|
2593
|
+
/** `terminal` for a terminal session (release 19); absent means structured. */
|
|
2594
|
+
mode: optional(oneOf(ADAPTER_MODES)),
|
|
2230
2595
|
}),
|
|
2231
2596
|
100,
|
|
2232
2597
|
),
|
|
@@ -2243,6 +2608,8 @@ export const EVENT_BODY_SPECS = {
|
|
|
2243
2608
|
"agents.active": AGENTS_ACTIVE_SPEC,
|
|
2244
2609
|
/** Attachments (session) and the local preview (device), transfer.ts. */
|
|
2245
2610
|
...TRANSFER_EVENT_SPECS,
|
|
2611
|
+
/** The live preview (release 19, live-preview.ts): its state, and its frames on the transient lane only. */
|
|
2612
|
+
...LIVE_EVENT_SPECS,
|
|
2246
2613
|
} ;
|
|
2247
2614
|
|
|
2248
2615
|
export const DEVICE_EVENT_TYPES = Object.keys(EVENT_BODY_SPECS) ;
|
|
@@ -2317,7 +2684,8 @@ export function validateEventBody (type , value
|
|
|
2317
2684
|
const r = validateAdapterReport(report);
|
|
2318
2685
|
if (!r.ok) return refuse("payload", `$body.adapters: ${r.detail}`);
|
|
2319
2686
|
}
|
|
2320
|
-
|
|
2687
|
+
// One report per (adapter, mode) since release 19: Claude Code structured and in a terminal are two reports.
|
|
2688
|
+
if (new Set(inv.adapters.map((a) => `${a.adapter}/${a.mode}`)).size !== inv.adapters.length) return refuse("payload", "$body.adapters: an adapter twice");
|
|
2321
2689
|
}
|
|
2322
2690
|
return checked;
|
|
2323
2691
|
}
|
|
@@ -2393,6 +2761,20 @@ export const COMMAND_ENVELOPE_SPEC = object({
|
|
|
2393
2761
|
authorization: b64({ exact: 64 }),
|
|
2394
2762
|
});
|
|
2395
2763
|
|
|
2764
|
+
/**
|
|
2765
|
+
* THE TRANSIENT LANE (release 19, 2026-11-09). A pushed terminal screen (agent.screen with no command) is news only
|
|
2766
|
+
* until the next one: the computer keeps none, the relay buffers and records none, and a phone that reconnects asks for
|
|
2767
|
+
* the screen again (screen.read). It travels beside the session's ordered stream, never in it: its `event_seq` is the
|
|
2768
|
+
* lane's own number (rising per session; a computer starts it from its clock, so a restart never goes back), it never
|
|
2769
|
+
* moves the stream's cursor, and a phone applies one only when its number is above the last transient one it applied.
|
|
2770
|
+
* So the stream stays gap-free for every phone, whoever followed. Only the types below may take the lane.
|
|
2771
|
+
*/
|
|
2772
|
+
export const EVENT_LANES = ["transient"] ;
|
|
2773
|
+
export const TRANSIENT_EVENT_TYPES = new Set (["agent.screen", "preview.frame"]);
|
|
2774
|
+
/** Types that may ONLY travel on the transient lane (a live preview's frames: never journaled, never replayed). */
|
|
2775
|
+
export const TRANSIENT_ONLY_TYPES = new Set (["preview.frame"]);
|
|
2776
|
+
export const isTransientEvent = (e ) => e.lane === "transient";
|
|
2777
|
+
|
|
2396
2778
|
export const EVENT_ENVELOPE_SPEC = object({
|
|
2397
2779
|
protocol_version: version,
|
|
2398
2780
|
session_id: nullable(id("ses")),
|
|
@@ -2405,6 +2787,8 @@ export const EVENT_ENVELOPE_SPEC = object({
|
|
|
2405
2787
|
command_id: nullable(id("cmd")),
|
|
2406
2788
|
/** The content-free push hint (attention.ts). */
|
|
2407
2789
|
notify: oneOf(NOTIFY_HINTS),
|
|
2790
|
+
/** Absent: the session's ordered stream. `transient`: beside it (EVENT_LANES above), kept by nobody. */
|
|
2791
|
+
lane: optional(oneOf(EVENT_LANES)),
|
|
2408
2792
|
body_ciphertext: sealed(),
|
|
2409
2793
|
});
|
|
2410
2794
|
|
|
@@ -2529,6 +2913,9 @@ export function validateEventEnvelope(value ) {
|
|
|
2529
2913
|
if (!COMMAND_RECEIPT_EVENTS.has(type) && DEVICE_SCOPED_EVENTS.has(type) !== (e.session_id === null))
|
|
2530
2914
|
return refuse("shape", "$event.session_id: a session event names a session, a device event none");
|
|
2531
2915
|
if (COMMAND_RECEIPT_EVENTS.has(type) && e.command_id === null) return refuse("shape", "$event.command_id: a receipt names its command");
|
|
2916
|
+
if (isTransientEvent(e) && (!TRANSIENT_EVENT_TYPES.has(type) || e.command_id !== null || e.session_id === null || e.notify !== "none"))
|
|
2917
|
+
return refuse("shape", "$event.lane: only a pushed screen or frame, of a session, without a command or a push hint, is transient");
|
|
2918
|
+
if (TRANSIENT_ONLY_TYPES.has(type) && !isTransientEvent(e)) return refuse("shape", "$event.lane: a live preview's frame travels on the transient lane only");
|
|
2532
2919
|
return checked;
|
|
2533
2920
|
}
|
|
2534
2921
|
|
|
@@ -2651,11 +3038,12 @@ export function replayAfter (
|
|
|
2651
3038
|
* A START IS CHECKED TWICE. The phone offers only what the computer reported; the computer checks again on receipt,
|
|
2652
3039
|
* against its own current report, because a report the phone saw may be old and a phone may be wrong. A start that
|
|
2653
3040
|
* names a model the adapter did not list, a permission mode it does not offer, or a resume id where the adapter
|
|
2654
|
-
* cannot resume, is refused (command.rejected) and nothing is started
|
|
3041
|
+
* cannot resume, is refused (command.rejected) and nothing is started; so is a start whose mode (structured, terminal) is not
|
|
3042
|
+
* the report's own (release 19).
|
|
2655
3043
|
*/
|
|
2656
3044
|
|
|
2657
3045
|
export function checkStart(payload , report ) {
|
|
2658
|
-
if (!report || report.adapter !== payload.adapter || !report.installed || !report.capabilities.start) return "unsupported";
|
|
3046
|
+
if (!report || report.adapter !== payload.adapter || report.mode !== (payload.mode ?? "structured") || !report.installed || !report.capabilities.start) return "unsupported";
|
|
2659
3047
|
if (!isModelReported(report, payload.model)) return "unknown_model";
|
|
2660
3048
|
if (!report.capabilities.permission_modes.includes(payload.permission_mode)) return "unsupported";
|
|
2661
3049
|
if (payload.resume !== null && !report.capabilities.resume_by_id) return "unsupported";
|
|
@@ -2767,190 +3155,6 @@ export function readSteeredLedger(textValue )
|
|
|
2767
3155
|
return { byRef, unreadable, pipelines };
|
|
2768
3156
|
}
|
|
2769
3157
|
|
|
2770
|
-
// ---- packages/remote-protocol/src/crypto/keys.ts
|
|
2771
|
-
/**
|
|
2772
|
-
* REMOTE DEVICE KEYS. Each computer and each phone install has its own pair: Ed25519 to sign, X25519 to agree keys.
|
|
2773
|
-
* They are NOT the computer's measurement key: a different key, a different store entry, a different audience. A
|
|
2774
|
-
* stolen remote key cannot sign a measurement, and a measurement key cannot steer an agent; every signature here is
|
|
2775
|
-
* also domain-separated ("worktrust-remote/v1/..."), so a signature made for one purpose verifies for no other.
|
|
2776
|
-
*
|
|
2777
|
-
* A FINGERPRINT FOR PEOPLE. 80 bits of SHA-256 over both public keys, as sixteen Crockford base32 characters in four
|
|
2778
|
-
* groups (no I, L, O or U to misread). Shown on the computer's screen and on the phone when a phone is confirmed at
|
|
2779
|
-
* the computer's keyboard, so a compromised issuer cannot slip in a key of its own unnoticed.
|
|
2780
|
-
*/
|
|
2781
|
-
|
|
2782
|
-
export function generateDeviceKeys(random ) {
|
|
2783
|
-
return { ed25519: random(KEY_BYTES), x25519: random(KEY_BYTES) };
|
|
2784
|
-
}
|
|
2785
|
-
|
|
2786
|
-
export function publicKeysOf(secret ) {
|
|
2787
|
-
return { ed25519_pub: toBase64Url(ed25519PublicKey(secret.ed25519)), x25519_pub: toBase64Url(x25519PublicKey(secret.x25519)) };
|
|
2788
|
-
}
|
|
2789
|
-
|
|
2790
|
-
/** For a store that holds strings (expo-secure-store, the CLI's credential store). */
|
|
2791
|
-
export const exportSecretKeys = (secret ) => ({
|
|
2792
|
-
ed25519: toBase64Url(secret.ed25519),
|
|
2793
|
-
x25519: toBase64Url(secret.x25519),
|
|
2794
|
-
});
|
|
2795
|
-
|
|
2796
|
-
export function importSecretKeys(stored ) {
|
|
2797
|
-
const ed = fromBase64Url(stored.ed25519);
|
|
2798
|
-
const x = fromBase64Url(stored.x25519);
|
|
2799
|
-
return ed?.length === KEY_BYTES && x?.length === KEY_BYTES ? { ed25519: ed, x25519: x } : null;
|
|
2800
|
-
}
|
|
2801
|
-
|
|
2802
|
-
const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
|
|
2803
|
-
const FINGERPRINT_DOMAIN = utf8Encode("worktrust-remote/v1/fingerprint\n");
|
|
2804
|
-
|
|
2805
|
-
function base32Groups(bytes ) {
|
|
2806
|
-
let bits = 0;
|
|
2807
|
-
let acc = 0;
|
|
2808
|
-
let out = "";
|
|
2809
|
-
for (const b of bytes) {
|
|
2810
|
-
acc = (acc << 8) | b;
|
|
2811
|
-
bits += 8;
|
|
2812
|
-
while (bits >= 5) {
|
|
2813
|
-
bits -= 5;
|
|
2814
|
-
out += CROCKFORD[(acc >> bits) & 31] ;
|
|
2815
|
-
}
|
|
2816
|
-
acc &= (1 << bits) - 1;
|
|
2817
|
-
}
|
|
2818
|
-
return out.match(/.{1,4}/g) .join("-");
|
|
2819
|
-
}
|
|
2820
|
-
|
|
2821
|
-
function decodeKey(text ) {
|
|
2822
|
-
const bytes = fromBase64Url(text);
|
|
2823
|
-
if (bytes?.length !== KEY_BYTES) throw new TypeError("a public key is 32 bytes of base64url");
|
|
2824
|
-
return bytes;
|
|
2825
|
-
}
|
|
2826
|
-
|
|
2827
|
-
/** "ABCD-EFGH-JKMN-PQRS" for one device's public keys. */
|
|
2828
|
-
export function deviceFingerprint(keys ) {
|
|
2829
|
-
const digest = sha256(concatBytes(FINGERPRINT_DOMAIN, decodeKey(keys.ed25519_pub), decodeKey(keys.x25519_pub)));
|
|
2830
|
-
return base32Groups(digest.subarray(0, 10));
|
|
2831
|
-
}
|
|
2832
|
-
|
|
2833
|
-
// ---- packages/remote-protocol/src/crypto/jws.ts
|
|
2834
|
-
/**
|
|
2835
|
-
* COMPACT SIGNED TOKENS: JWS (RFC 7515) with EdDSA over Ed25519 (RFC 8037), so the gateway can verify an assertion
|
|
2836
|
-
* with any standard library, and so can the phone and the computer with this package. Three token types, told apart
|
|
2837
|
-
* by `typ` and never interchangeable:
|
|
2838
|
-
* wt-remote-binding+jwt the Passport app binds a device's remote keys to an account
|
|
2839
|
-
* wt-remote-auth+jwt the Passport app authorizes one device at the gateway for five minutes
|
|
2840
|
-
* wt-remote-approval+jwt a phone decides one pending approval
|
|
2841
|
-
* The verifier fixes alg, typ and the key set before it looks at the token: a token cannot choose how it is checked.
|
|
2842
|
-
* Header and payload are canonical JSON, so one claim set has one signing input.
|
|
2843
|
-
*/
|
|
2844
|
-
|
|
2845
|
-
export const TOKEN_TYPES = ["wt-remote-binding+jwt", "wt-remote-auth+jwt", "wt-remote-approval+jwt"] ;
|
|
2846
|
-
|
|
2847
|
-
export const MAX_TOKEN_CHARS = 4096;
|
|
2848
|
-
|
|
2849
|
-
/** Public keys by key id: the issuer's keys (pinned in the app and CLI builds), or a phone's bound key. */
|
|
2850
|
-
|
|
2851
|
-
export function signToken(typ , kid , claims , secret ) {
|
|
2852
|
-
const header = toBase64Url(utf8Encode(canonicalJson({ alg: "EdDSA", kid, typ })));
|
|
2853
|
-
const payload = toBase64Url(utf8Encode(canonicalJson(claims)));
|
|
2854
|
-
const signature = ed25519Sign(utf8Encode(`${header}.${payload}`), secret);
|
|
2855
|
-
return `${header}.${payload}.${toBase64Url(signature)}`;
|
|
2856
|
-
}
|
|
2857
|
-
|
|
2858
|
-
const decodeJson = (part ) => {
|
|
2859
|
-
const bytes = fromBase64Url(part);
|
|
2860
|
-
const text = bytes === null ? null : utf8Decode(bytes);
|
|
2861
|
-
return text === null ? undefined : parseJson(text);
|
|
2862
|
-
};
|
|
2863
|
-
|
|
2864
|
-
export function verifyToken(token , typ , keys ) {
|
|
2865
|
-
if (token.length > MAX_TOKEN_CHARS) return refuse("shape", "token: too long");
|
|
2866
|
-
const parts = token.split(".");
|
|
2867
|
-
if (parts.length !== 3) return refuse("shape", "token: not three parts");
|
|
2868
|
-
const [h, p, s] = parts ;
|
|
2869
|
-
const header = decodeJson(h);
|
|
2870
|
-
if (typeof header !== "object" || header === null || Array.isArray(header)) return refuse("shape", "token: header");
|
|
2871
|
-
const hd = header ;
|
|
2872
|
-
if (Object.keys(hd).sort().join(",") !== "alg,kid,typ") return refuse("shape", "token: header fields");
|
|
2873
|
-
if (hd.alg !== "EdDSA") return refuse("shape", "token: alg");
|
|
2874
|
-
if (hd.typ !== typ) return refuse("shape", "token: typ");
|
|
2875
|
-
if (typeof hd.kid !== "string" || !Object.hasOwn(keys, hd.kid)) return refuse("unknown_key", "token: kid");
|
|
2876
|
-
const key = keys[hd.kid] ;
|
|
2877
|
-
const signature = fromBase64Url(s);
|
|
2878
|
-
if (key.length !== KEY_BYTES || signature === null) return refuse("signature", "token: signature encoding");
|
|
2879
|
-
if (!ed25519Verify(signature, utf8Encode(`${h}.${p}`), key)) return refuse("signature", "token: signature");
|
|
2880
|
-
const claims = decodeJson(p);
|
|
2881
|
-
if (typeof claims !== "object" || claims === null || Array.isArray(claims)) return refuse("shape", "token: payload");
|
|
2882
|
-
// The signed bytes must BE the canonical encoding, so one claim set has exactly one valid token form.
|
|
2883
|
-
if (toBase64Url(utf8Encode(canonicalJson(claims))) !== p) return refuse("shape", "token: payload not canonical");
|
|
2884
|
-
if (toBase64Url(utf8Encode(canonicalJson(hd))) !== h) return refuse("shape", "token: header not canonical");
|
|
2885
|
-
return accept({ kid: hd.kid, claims: claims });
|
|
2886
|
-
}
|
|
2887
|
-
|
|
2888
|
-
/** iat/exp checks shared by every token kind; seconds, with the protocol's skew. */
|
|
2889
|
-
export function checkTimes(iat , exp , nowMs , maxLifetimeS , skewMs ) {
|
|
2890
|
-
if (exp <= iat) return refuse("lifetime", "token: exp not after iat");
|
|
2891
|
-
if (exp - iat > maxLifetimeS) return refuse("lifetime", "token: lives too long");
|
|
2892
|
-
if (iat * 1000 > nowMs + skewMs) return refuse("not_yet_valid", "token: issued in the future");
|
|
2893
|
-
if (exp * 1000 + skewMs < nowMs) return refuse("expired", "token: expired");
|
|
2894
|
-
return accept(true);
|
|
2895
|
-
}
|
|
2896
|
-
|
|
2897
|
-
// ---- packages/remote-protocol/src/crypto/binding.ts
|
|
2898
|
-
/**
|
|
2899
|
-
* A REMOTE KEY BINDING: the Passport app's signed word that these public keys belong to this device of this account.
|
|
2900
|
-
* The person approves the device in app.worktrust.io, signed in with a second factor; the app signs
|
|
2901
|
-
* { iss, aud, sub, device_id, kind, ed25519_pub, x25519_pub, iat, exp, jti }
|
|
2902
|
-
* with a WorkTrust issuer key. `sub` is an opaque account reference for the remote system (an HMAC of the owner id
|
|
2903
|
-
* under a Passport secret, prefixed usr_), never the Passport owner id, so the relay's records join to nothing else.
|
|
2904
|
-
*
|
|
2905
|
-
* Endpoints verify bindings against the issuer's public keys PINNED in the app and CLI builds, never against a key the
|
|
2906
|
-
* relay hands them. The relay cannot forge a binding. The issuer alone cannot add a controller either: a new phone is
|
|
2907
|
-
* pending on the computer until the person confirms its fingerprint at the computer's keyboard (handshake.ts).
|
|
2908
|
-
*/
|
|
2909
|
-
|
|
2910
|
-
export const DEVICE_KINDS = ["phone", "computer"] ;
|
|
2911
|
-
|
|
2912
|
-
export const BINDING_CLAIMS_SPEC = object({
|
|
2913
|
-
iss: oneOf([PASSPORT_ISSUER]),
|
|
2914
|
-
aud: oneOf([GATEWAY_AUDIENCE]),
|
|
2915
|
-
sub: id("usr"),
|
|
2916
|
-
device_id: id("dev"),
|
|
2917
|
-
kind: oneOf(DEVICE_KINDS),
|
|
2918
|
-
ed25519_pub: b64({ exact: 32 }),
|
|
2919
|
-
x25519_pub: b64({ exact: 32 }),
|
|
2920
|
-
iat: int(0),
|
|
2921
|
-
exp: int(0),
|
|
2922
|
-
jti: id("jti"),
|
|
2923
|
-
});
|
|
2924
|
-
|
|
2925
|
-
/** For the Passport app: validate, then sign. */
|
|
2926
|
-
export function issueBinding(claims , issuerSecret , kid ) {
|
|
2927
|
-
const checked = validate(BINDING_CLAIMS_SPEC, claims, "$binding");
|
|
2928
|
-
if (!checked.ok) throw new TypeError(checked.detail);
|
|
2929
|
-
if (claims.exp - claims.iat > MAX_BINDING_LIFETIME_S || claims.exp <= claims.iat) throw new RangeError("binding lifetime");
|
|
2930
|
-
return signToken("wt-remote-binding+jwt", kid, claims, issuerSecret);
|
|
2931
|
-
}
|
|
2932
|
-
|
|
2933
|
-
export function verifyBinding(token , expect ) {
|
|
2934
|
-
const verified = verifyToken(token, "wt-remote-binding+jwt", expect.issuerKeys);
|
|
2935
|
-
if (!verified.ok) return refuse(verified.code === "shape" ? "binding" : verified.code, verified.detail);
|
|
2936
|
-
const shaped = validate(BINDING_CLAIMS_SPEC, verified.value.claims, "$binding");
|
|
2937
|
-
if (!shaped.ok) return refuse("binding", shaped.detail);
|
|
2938
|
-
const b = shaped.value;
|
|
2939
|
-
const times = checkTimes(b.iat, b.exp, expect.now, MAX_BINDING_LIFETIME_S, CLOCK_SKEW_MS);
|
|
2940
|
-
if (!times.ok) return times;
|
|
2941
|
-
if (expect.kind !== undefined && b.kind !== expect.kind) return refuse("binding", "$binding.kind: not the expected kind");
|
|
2942
|
-
if (expect.deviceId !== undefined && b.device_id !== expect.deviceId) return refuse("wrong_device", "$binding.device_id");
|
|
2943
|
-
if (expect.sub !== undefined && b.sub !== expect.sub) return refuse("account_mismatch", "$binding.sub");
|
|
2944
|
-
if (expect.isRevoked?.(b)) return refuse("revoked", "$binding: revoked");
|
|
2945
|
-
return accept(b);
|
|
2946
|
-
}
|
|
2947
|
-
|
|
2948
|
-
/** The signing key a verified binding names, as bytes. */
|
|
2949
|
-
export const bindingSigningKey = (b ) => fromBase64Url(b.ed25519_pub) ;
|
|
2950
|
-
export const bindingAgreementKey = (b ) => fromBase64Url(b.x25519_pub) ;
|
|
2951
|
-
export const bindingFingerprint = (b ) =>
|
|
2952
|
-
deviceFingerprint({ ed25519_pub: b.ed25519_pub, x25519_pub: b.x25519_pub });
|
|
2953
|
-
|
|
2954
3158
|
// ---- packages/remote-protocol/src/crypto/assertion.ts
|
|
2955
3159
|
/**
|
|
2956
3160
|
* THE GATEWAY'S ADMISSION TICKET. The gateway holds no Passport credential and reads no Passport database: it trusts
|