@hadoku/host-wire 0.0.0-stage → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hadoku-cardtable contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/wire.d.ts ADDED
@@ -0,0 +1,304 @@
1
+ /**
2
+ * The host agent's wire: what the coordinator (this server) and the agent on a
3
+ * hosting claw (`apps/agent`) say to each other, and how every word from the
4
+ * coordinator is signed. Both sides import this one file; it uses node
5
+ * builtins only, because the agent bundles it for node 22.
6
+ *
7
+ * ## Requests
8
+ *
9
+ * Plain HTTP on the agent's port (`CARDTABLE_AGENT_PORT`, 7621 on a claw).
10
+ * Every request carries
11
+ *
12
+ * x-agent-ts unix ms, within `SKEW_MS` of the agent's clock
13
+ * x-agent-body sha256 hex of the body (of the empty string when there is none)
14
+ * x-agent-sig base64 Ed25519 over "<METHOD>\n<path>\n<ts>\n<body sha>"
15
+ *
16
+ * The coordinator holds the private key; the agent build embeds the public
17
+ * half. A signature is accepted once (`ReplayGuard`) and only while its
18
+ * timestamp is fresh, so a captured request can be neither replayed nor saved
19
+ * for later. The body is hashed as it arrives and refused on a mismatch.
20
+ * Loopback is not trusted: CI on the same claw reaches it.
21
+ *
22
+ * ## The relay
23
+ *
24
+ * `GET /relay` with `Upgrade: cardtable-relay`, signed as above, turns the
25
+ * connection into one long-lived stream of newline-delimited JSON frames. The
26
+ * agent answers `101` with `x-agent-nonce`, a fresh random session id. Every
27
+ * coordinator frame is `{seq, m, sig}`: `seq` counts up from 1 in this session
28
+ * and `sig` signs "relay\n<nonce>\n<seq>\n<JSON of m>", so a frame captured
29
+ * from one session is refused in every other, and a frame dropped, replayed or
30
+ * reordered inside one is refused too. A refused frame ends the session.
31
+ * Agent frames are plain JSON (`FromAgent`); the agent holds no key.
32
+ *
33
+ * A newer session replaces the older one: one coordinator at a time.
34
+ */
35
+ import { type KeyObject } from 'node:crypto';
36
+ /** The agent's port on a claw (fleet-manager's `CARDTABLE_AGENT_PORT`). */
37
+ export declare const AGENT_PORT = 7621;
38
+ /** A request's timestamp must be within this of the agent's clock. */
39
+ export declare const SKEW_MS = 30000;
40
+ /** The agent heartbeats this often; the coordinator pings back as often. */
41
+ export declare const HEARTBEAT_MS = 2000;
42
+ /**
43
+ * The fencing window: an agent that has heard nothing from the coordinator for
44
+ * this long kills every JVM it runs, and a coordinator that has heard no
45
+ * heartbeat for this long fails the claw over. Five missed heartbeats, from the
46
+ * 48 h link probe (`docs/planning/forge-hosting-plan.md` §4.1).
47
+ */
48
+ export declare const FENCE_MS = 10000;
49
+ /**
50
+ * The longest a coordinator going down may ask an agent to hold its JVMs past the fencing window
51
+ * (`{op:'hold'}`). A deploy's restart re-attaches in seconds; the cap keeps a coordinator that
52
+ * never comes back from holding a claw's matches for long.
53
+ */
54
+ export declare const HOLD_MAX_MS: number;
55
+ /** What a JVM costs beyond its heap (H8: RSS 1.24–1.27 GB at `-Xmx1000m`). */
56
+ export declare const JVM_OVERHEAD_MB = 400;
57
+ /** What the agent itself is allowed in the slice, beside its JVMs. */
58
+ export declare const AGENT_RESERVE_MB = 100;
59
+ /**
60
+ * The draft bot service's memory cap (its leaf's `memory.max`), and what it reserves in the slice.
61
+ * Measured on a hosting node (2026-11-06): 1.15–1.31 GB RSS answering one pod's 7 seats a call, 1.88 GB
62
+ * after 56-seat calls. 1.5 GB still leaves a 4 GB unit room for one 2 GB-heap JVM; a call too big
63
+ * for it is OOM-killed, the agent restarts it, and the backup answers meanwhile.
64
+ */
65
+ export declare const DRAFTBOT_MB = 1536;
66
+ /**
67
+ * The agent's fit rule, shared so the coordinator places by the same arithmetic the agent refuses
68
+ * by: the memory the slice must hold for JVMs of these heaps, the agent included, and the draft bot
69
+ * service when the claw runs it.
70
+ */
71
+ export declare function sliceNeedMb(xmxMbs: readonly number[], draftbot?: boolean): number;
72
+ /** A heap past this share of `-Xmx` after GC is reported as `recycleWanted`. */
73
+ export declare const RECYCLE_HEAP_SHARE = 0.85;
74
+ export declare const RELAY_PROTOCOL = "cardtable-relay";
75
+ export declare const SHA256: RegExp;
76
+ /** A JVM's host id: also a directory and a cgroup name on the claw. */
77
+ export declare const HOST_ID: RegExp;
78
+ export declare const sha256Hex: (bytes: string | Buffer) => string;
79
+ export declare const EMPTY_SHA: string;
80
+ /**
81
+ * The coordinator's Ed25519 private key, as a PEM or as base64 PKCS#8 DER (one
82
+ * line, which survives an environment variable and a vault item unchanged).
83
+ */
84
+ export declare function privateKeyFrom(text: string): KeyObject;
85
+ /** The public half as a PEM, which is what an agent build embeds. */
86
+ export declare function publicPemOf(key: KeyObject): string;
87
+ export interface SignedHeaders {
88
+ 'x-agent-ts': string;
89
+ 'x-agent-body': string;
90
+ 'x-agent-sig': string;
91
+ }
92
+ export declare function signRequest(key: KeyObject, method: string, path: string, bodySha: string, now?: number): SignedHeaders;
93
+ /** Each accepted signature, kept until it could no longer pass the skew check anyway. */
94
+ export declare class ReplayGuard {
95
+ private readonly seen;
96
+ private readonly now;
97
+ constructor(now?: () => number);
98
+ /** True the first time `sig` is offered; false after. */
99
+ first(sig: string): boolean;
100
+ }
101
+ /** Null when the request is the coordinator's, fresh and first; otherwise why not. */
102
+ export declare function checkRequest(key: KeyObject, guard: ReplayGuard, req: {
103
+ method: string;
104
+ path: string;
105
+ headers: Record<string, string | string[] | undefined>;
106
+ }, now?: number): string | null;
107
+ export interface SignedFrame {
108
+ seq: number;
109
+ m: ToAgent;
110
+ sig: string;
111
+ }
112
+ /** One coordinator frame, as the line that goes on the wire (no newline). */
113
+ export declare function signFrame(key: KeyObject, nonce: string, seq: number, m: ToAgent): string;
114
+ /**
115
+ * The message, when `line` is the next signed frame of session `nonce`;
116
+ * otherwise why not. The signature covers `m` exactly as it was sent: the
117
+ * frame is cut at `"m":`, never re-serialised.
118
+ */
119
+ export declare function openFrame(key: KeyObject, nonce: string, expectSeq: number, line: string): {
120
+ m: ToAgent;
121
+ } | {
122
+ error: string;
123
+ };
124
+ /** The artifacts one JVM runs on, each a sha256 the agent has installed. */
125
+ export interface ArtifactSet {
126
+ jdk: string;
127
+ jar: string;
128
+ res: string;
129
+ bridge: string;
130
+ }
131
+ export type JvmArtifactKind = keyof ArtifactSet;
132
+ export declare const JVM_ARTIFACT_KINDS: readonly JvmArtifactKind[];
133
+ /** Every kind the agent keeps: a JVM's four, and the draft bot service's installed tree. */
134
+ export type ArtifactKind = JvmArtifactKind | 'draftbot';
135
+ export declare const ARTIFACT_KINDS: readonly ArtifactKind[];
136
+ /**
137
+ * The coordinator's draft bot calls, proxied by the agent to the service on its loopback: the body
138
+ * is `{inputs}` and the answer the service's own (`{success, results}`).
139
+ */
140
+ export declare const DRAFTBOT_PATH = "/draftbot/batchdraft";
141
+ /**
142
+ * What a JVM-hosted engine's runtime needs to launch, once named by a `kind` rather than carried
143
+ * as `LaunchSpec`'s own top-level fields. The one kind today is Forge's bridge JVM; another
144
+ * engine's agent would add its own `kind` rather than reuse these fields for something else.
145
+ */
146
+ export interface JvmRuntimeSpec {
147
+ kind: 'jvm';
148
+ xmxMb: number;
149
+ /** The bridge's main class inside the `bridge` artifact. */
150
+ main: string;
151
+ /** `BRIDGE_JVM_FLAGS` from `host.ts`: the coordinator's, so the agent never keeps a copy. */
152
+ jvmFlags: string[];
153
+ /** Written to `user/preferences/forge.preferences` (`host.ts` `FORGE_PREFERENCES`). */
154
+ forgePreferences: Record<string, string>;
155
+ }
156
+ export interface LaunchSpec {
157
+ hostId: string;
158
+ artifacts: ArtifactSet;
159
+ /**
160
+ * What the JVM needs to launch, named by `kind` rather than flattened onto `LaunchSpec` itself —
161
+ * the only shape a `launch` carries. It was additive for one rollout: a server sent both this
162
+ * and four flat fields (`xmxMb`, `main`, `jvmFlags`, `forgePreferences`) so an agent built before
163
+ * `runtime` existed could still launch off the flat ones, with `runtimeOf` picking between them.
164
+ * Every agent in the fleet reads `runtime` now (confirmed per-claw before this dropped), so the
165
+ * flat fields and `runtimeOf`'s fallback both went with them — in either order, safely: the old
166
+ * agent's own `runtimeOf` already preferred `runtime` whenever one was sent, flat fields or not,
167
+ * and a new agent (built after the drop) only ever meets a server that still sends `runtime`.
168
+ */
169
+ runtime: JvmRuntimeSpec;
170
+ }
171
+ /**
172
+ * `spec.runtime`, named for the callers that read a JVM's shape through a `LaunchSpec` rather than
173
+ * holding a `JvmRuntimeSpec` directly (`jvm.ts`, `agent.ts`). No fallback any more — the flat fields
174
+ * it used to fall back to no longer exist on `LaunchSpec` at all.
175
+ */
176
+ export declare function runtimeOf(spec: LaunchSpec): JvmRuntimeSpec;
177
+ export type ToAgent = ({
178
+ op: 'launch';
179
+ } & LaunchSpec) | {
180
+ op: 'line';
181
+ h: string;
182
+ line: string;
183
+ } | {
184
+ op: 'kill';
185
+ h: string;
186
+ }
187
+ /** Stop relaying `h`; its lines from byte `off` on wait on the claw's disk. */
188
+ | {
189
+ op: 'release';
190
+ h: string;
191
+ off: number;
192
+ }
193
+ /** Relay `h` again, from byte `from` (default: the last acknowledged byte). */
194
+ | {
195
+ op: 'attach';
196
+ h: string;
197
+ from?: number;
198
+ }
199
+ /** `h`'s exit was received: its run directory may go. */
200
+ | {
201
+ op: 'forget';
202
+ h: string;
203
+ } | {
204
+ op: 'running';
205
+ req: number;
206
+ }
207
+ /** The coordinator's heartbeat, with how far it has taken each JVM's lines. */
208
+ | {
209
+ op: 'ping';
210
+ acks: Record<string, number>;
211
+ }
212
+ /**
213
+ * The coordinator is restarting (a deploy): do not fence for `ms` (at most `HOLD_MAX_MS`) after
214
+ * the fencing window would have. The next coordinator's relay ends the hold; an unclean
215
+ * coordinator death sends none, and fences at the window as before.
216
+ */
217
+ | {
218
+ op: 'hold';
219
+ ms: number;
220
+ }
221
+ /**
222
+ * Run the draft bot service from installed artifact `sha`, or none (null). Idempotent: the
223
+ * coordinator repeats it whenever the heartbeat shows the agent wanting something else.
224
+ */
225
+ | {
226
+ op: 'draftbot';
227
+ sha: string | null;
228
+ };
229
+ /** The draft bot service the agent supervises, as the heartbeat reports it. */
230
+ export interface DraftbotHealth {
231
+ /** The artifact it was asked to run. */
232
+ sha: string;
233
+ /** `refused`: it cannot run here (not installed, or no room in the slice); `error` says why. */
234
+ state: 'starting' | 'up' | 'down' | 'refused';
235
+ pid: number | null;
236
+ /** Its leaf's `memory.current`, or the process's RSS without cgroups. */
237
+ memoryMb: number | null;
238
+ /** Times it has been started again after it died. */
239
+ restarts: number;
240
+ error: string | null;
241
+ /** When it entered `state`, unix ms. */
242
+ since: number;
243
+ }
244
+ export interface JvmHealth {
245
+ hostId: string;
246
+ pid: number;
247
+ xmxMb: number;
248
+ rssMb: number | null;
249
+ /** From the JVM's own GC log: the heap after the last collection. */
250
+ heapUsedMb: number | null;
251
+ heapMaxMb: number | null;
252
+ /** Share of wall time in GC pauses over the last heartbeat window, 0–1. */
253
+ gcShare: number | null;
254
+ /** The heap after GC is past `RECYCLE_HEAP_SHARE` of `-Xmx`; the coordinator decides. */
255
+ recycleWanted: boolean;
256
+ attached: boolean;
257
+ }
258
+ export interface SliceHealth {
259
+ cgroup: string | null;
260
+ delegated: boolean;
261
+ memoryMaxMb: number | null;
262
+ memoryCurrentMb: number | null;
263
+ /** `memory.events`, every counter. `oom_kill` is the kernel's OOM kills. */
264
+ memoryEvents: Record<string, number>;
265
+ /** `cpu.stat`, every counter. */
266
+ cpuStat: Record<string, number>;
267
+ cpus: number | null;
268
+ }
269
+ export type FromAgent =
270
+ /** The session's first frame. */
271
+ {
272
+ t: 'hello';
273
+ agentPid: number;
274
+ version: string;
275
+ running: string[];
276
+ fenceMs: number;
277
+ } | {
278
+ t: 'hb';
279
+ at: number;
280
+ jvms: JvmHealth[];
281
+ slice: SliceHealth;
282
+ draftbot?: DraftbotHealth | null;
283
+ }
284
+ /** One stdout line of JVM `h`; `off` is the byte offset just past it. */
285
+ | {
286
+ t: 'line';
287
+ h: string;
288
+ off: number;
289
+ line: string;
290
+ } | {
291
+ t: 'exit';
292
+ h: string;
293
+ reason: string;
294
+ } | {
295
+ t: 'running';
296
+ req: number;
297
+ hostIds: string[];
298
+ }
299
+ /** A frame the agent could not act on. */
300
+ | {
301
+ t: 'error';
302
+ h?: string;
303
+ error: string;
304
+ };
package/dist/wire.js ADDED
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The host agent's wire: what the coordinator (this server) and the agent on a
3
+ * hosting claw (`apps/agent`) say to each other, and how every word from the
4
+ * coordinator is signed. Both sides import this one file; it uses node
5
+ * builtins only, because the agent bundles it for node 22.
6
+ *
7
+ * ## Requests
8
+ *
9
+ * Plain HTTP on the agent's port (`CARDTABLE_AGENT_PORT`, 7621 on a claw).
10
+ * Every request carries
11
+ *
12
+ * x-agent-ts unix ms, within `SKEW_MS` of the agent's clock
13
+ * x-agent-body sha256 hex of the body (of the empty string when there is none)
14
+ * x-agent-sig base64 Ed25519 over "<METHOD>\n<path>\n<ts>\n<body sha>"
15
+ *
16
+ * The coordinator holds the private key; the agent build embeds the public
17
+ * half. A signature is accepted once (`ReplayGuard`) and only while its
18
+ * timestamp is fresh, so a captured request can be neither replayed nor saved
19
+ * for later. The body is hashed as it arrives and refused on a mismatch.
20
+ * Loopback is not trusted: CI on the same claw reaches it.
21
+ *
22
+ * ## The relay
23
+ *
24
+ * `GET /relay` with `Upgrade: cardtable-relay`, signed as above, turns the
25
+ * connection into one long-lived stream of newline-delimited JSON frames. The
26
+ * agent answers `101` with `x-agent-nonce`, a fresh random session id. Every
27
+ * coordinator frame is `{seq, m, sig}`: `seq` counts up from 1 in this session
28
+ * and `sig` signs "relay\n<nonce>\n<seq>\n<JSON of m>", so a frame captured
29
+ * from one session is refused in every other, and a frame dropped, replayed or
30
+ * reordered inside one is refused too. A refused frame ends the session.
31
+ * Agent frames are plain JSON (`FromAgent`); the agent holds no key.
32
+ *
33
+ * A newer session replaces the older one: one coordinator at a time.
34
+ */
35
+ import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
36
+ /** The agent's port on a claw (fleet-manager's `CARDTABLE_AGENT_PORT`). */
37
+ export const AGENT_PORT = 7621;
38
+ /** A request's timestamp must be within this of the agent's clock. */
39
+ export const SKEW_MS = 30_000;
40
+ /** The agent heartbeats this often; the coordinator pings back as often. */
41
+ export const HEARTBEAT_MS = 2000;
42
+ /**
43
+ * The fencing window: an agent that has heard nothing from the coordinator for
44
+ * this long kills every JVM it runs, and a coordinator that has heard no
45
+ * heartbeat for this long fails the claw over. Five missed heartbeats, from the
46
+ * 48 h link probe (`docs/planning/forge-hosting-plan.md` §4.1).
47
+ */
48
+ export const FENCE_MS = 10_000;
49
+ /**
50
+ * The longest a coordinator going down may ask an agent to hold its JVMs past the fencing window
51
+ * (`{op:'hold'}`). A deploy's restart re-attaches in seconds; the cap keeps a coordinator that
52
+ * never comes back from holding a claw's matches for long.
53
+ */
54
+ export const HOLD_MAX_MS = 5 * 60_000;
55
+ /** What a JVM costs beyond its heap (H8: RSS 1.24–1.27 GB at `-Xmx1000m`). */
56
+ export const JVM_OVERHEAD_MB = 400;
57
+ /** What the agent itself is allowed in the slice, beside its JVMs. */
58
+ export const AGENT_RESERVE_MB = 100;
59
+ /**
60
+ * The draft bot service's memory cap (its leaf's `memory.max`), and what it reserves in the slice.
61
+ * Measured on a hosting node (2026-11-06): 1.15–1.31 GB RSS answering one pod's 7 seats a call, 1.88 GB
62
+ * after 56-seat calls. 1.5 GB still leaves a 4 GB unit room for one 2 GB-heap JVM; a call too big
63
+ * for it is OOM-killed, the agent restarts it, and the backup answers meanwhile.
64
+ */
65
+ export const DRAFTBOT_MB = 1536;
66
+ /**
67
+ * The agent's fit rule, shared so the coordinator places by the same arithmetic the agent refuses
68
+ * by: the memory the slice must hold for JVMs of these heaps, the agent included, and the draft bot
69
+ * service when the claw runs it.
70
+ */
71
+ export function sliceNeedMb(xmxMbs, draftbot = false) {
72
+ return xmxMbs.reduce((sum, x) => sum + x + JVM_OVERHEAD_MB, AGENT_RESERVE_MB + (draftbot ? DRAFTBOT_MB : 0));
73
+ }
74
+ /** A heap past this share of `-Xmx` after GC is reported as `recycleWanted`. */
75
+ export const RECYCLE_HEAP_SHARE = 0.85;
76
+ export const RELAY_PROTOCOL = 'cardtable-relay';
77
+ export const SHA256 = /^[0-9a-f]{64}$/;
78
+ /** A JVM's host id: also a directory and a cgroup name on the claw. */
79
+ export const HOST_ID = /^[A-Za-z0-9_-]{1,64}$/;
80
+ export const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
81
+ export const EMPTY_SHA = sha256Hex('');
82
+ /* ── Keys ────────────────────────────────────────────────────────────── */
83
+ /**
84
+ * The coordinator's Ed25519 private key, as a PEM or as base64 PKCS#8 DER (one
85
+ * line, which survives an environment variable and a vault item unchanged).
86
+ */
87
+ export function privateKeyFrom(text) {
88
+ const t = text.trim();
89
+ if (t.startsWith('-----BEGIN'))
90
+ return createPrivateKey(t);
91
+ return createPrivateKey({ key: Buffer.from(t, 'base64'), format: 'der', type: 'pkcs8' });
92
+ }
93
+ /** The public half as a PEM, which is what an agent build embeds. */
94
+ export function publicPemOf(key) {
95
+ return createPublicKey(key).export({ type: 'spki', format: 'pem' }).toString();
96
+ }
97
+ const requestText = (method, path, ts, bodySha) => Buffer.from(`${method}\n${path}\n${ts}\n${bodySha}`);
98
+ export function signRequest(key, method, path, bodySha, now = Date.now()) {
99
+ return {
100
+ 'x-agent-ts': String(now),
101
+ 'x-agent-body': bodySha,
102
+ 'x-agent-sig': sign(null, requestText(method, path, now, bodySha), key).toString('base64'),
103
+ };
104
+ }
105
+ /** A malformed signature is a bad one, not an error. */
106
+ function verified(key, text, sig) {
107
+ try {
108
+ return verify(null, text, key, Buffer.from(sig, 'base64'));
109
+ }
110
+ catch {
111
+ return false;
112
+ }
113
+ }
114
+ /** Each accepted signature, kept until it could no longer pass the skew check anyway. */
115
+ export class ReplayGuard {
116
+ seen = new Map();
117
+ now;
118
+ // No parameter property: `deploy.sh` runs this file under node's type stripping.
119
+ constructor(now = Date.now) {
120
+ this.now = now;
121
+ }
122
+ /** True the first time `sig` is offered; false after. */
123
+ first(sig) {
124
+ const now = this.now();
125
+ for (const [s, at] of this.seen)
126
+ if (now - at > 2 * SKEW_MS)
127
+ this.seen.delete(s);
128
+ if (this.seen.has(sig))
129
+ return false;
130
+ this.seen.set(sig, now);
131
+ return true;
132
+ }
133
+ }
134
+ /** Null when the request is the coordinator's, fresh and first; otherwise why not. */
135
+ export function checkRequest(key, guard, req, now = Date.now()) {
136
+ const header = (name) => {
137
+ const v = req.headers[name];
138
+ return Array.isArray(v) ? (v[0] ?? '') : (v ?? '');
139
+ };
140
+ const ts = Number(header('x-agent-ts'));
141
+ const body = header('x-agent-body');
142
+ const sig = header('x-agent-sig');
143
+ if (!Number.isFinite(ts) || ts <= 0 || Math.abs(now - ts) > SKEW_MS)
144
+ return 'stale or missing x-agent-ts';
145
+ if (!SHA256.test(body))
146
+ return 'missing x-agent-body';
147
+ if (sig === '')
148
+ return 'unsigned';
149
+ if (!verified(key, requestText(req.method, req.path, ts, body), sig))
150
+ return 'bad signature';
151
+ if (!guard.first(sig))
152
+ return 'replayed signature';
153
+ return null;
154
+ }
155
+ const frameText = (nonce, seq, body) => Buffer.from(`relay\n${nonce}\n${seq}\n${body}`);
156
+ /** One coordinator frame, as the line that goes on the wire (no newline). */
157
+ export function signFrame(key, nonce, seq, m) {
158
+ const body = JSON.stringify(m);
159
+ return `{"seq":${seq},"sig":"${sign(null, frameText(nonce, seq, body), key).toString('base64')}","m":${body}}`;
160
+ }
161
+ /**
162
+ * The message, when `line` is the next signed frame of session `nonce`;
163
+ * otherwise why not. The signature covers `m` exactly as it was sent: the
164
+ * frame is cut at `"m":`, never re-serialised.
165
+ */
166
+ export function openFrame(key, nonce, expectSeq, line) {
167
+ const at = line.indexOf(',"m":');
168
+ const head = /^\{"seq":(\d+),"sig":"([A-Za-z0-9+/=]+)"$/.exec(line.slice(0, at));
169
+ if (at < 0 || head === null || !line.endsWith('}'))
170
+ return { error: 'malformed frame' };
171
+ const seq = Number(head[1]);
172
+ if (seq !== expectSeq)
173
+ return { error: `frame ${seq}, expected ${expectSeq}` };
174
+ const body = line.slice(at + 5, -1);
175
+ if (!verified(key, frameText(nonce, seq, body), head[2]))
176
+ return { error: 'bad frame signature' };
177
+ try {
178
+ return { m: JSON.parse(body) };
179
+ }
180
+ catch {
181
+ return { error: 'frame body is not JSON' };
182
+ }
183
+ }
184
+ export const JVM_ARTIFACT_KINDS = ['jdk', 'jar', 'res', 'bridge'];
185
+ export const ARTIFACT_KINDS = [...JVM_ARTIFACT_KINDS, 'draftbot'];
186
+ /**
187
+ * The coordinator's draft bot calls, proxied by the agent to the service on its loopback: the body
188
+ * is `{inputs}` and the answer the service's own (`{success, results}`).
189
+ */
190
+ export const DRAFTBOT_PATH = '/draftbot/batchdraft';
191
+ /**
192
+ * `spec.runtime`, named for the callers that read a JVM's shape through a `LaunchSpec` rather than
193
+ * holding a `JvmRuntimeSpec` directly (`jvm.ts`, `agent.ts`). No fallback any more — the flat fields
194
+ * it used to fall back to no longer exist on `LaunchSpec` at all.
195
+ */
196
+ export function runtimeOf(spec) {
197
+ return spec.runtime;
198
+ }
package/package.json CHANGED
@@ -1,6 +1,22 @@
1
1
  {
2
2
  "name": "@hadoku/host-wire",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.6",
4
+ "type": "module",
5
+ "license": "MIT",
6
+ "description": "The signed wire between a match host and the agent on a hosting claw: request signing, the relay's frames, the messages each side sends, artifact hashes and slice sizing. Knows no game. MIT; imports only node builtins, because the agent bundles it for node 22.",
7
+ "exports": {
8
+ ".": {
9
+ "types": "./dist/wire.d.ts",
10
+ "import": "./dist/wire.js"
11
+ }
12
+ },
13
+ "files": [
14
+ "dist",
15
+ "LICENSE"
16
+ ],
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "https://github.com/WolffM/hadoku-cardtable.git",
20
+ "directory": "packages/host-wire"
21
+ }
22
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.