@byollm/protocol 0.1.0-alpha.4 → 0.1.0-alpha.40
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 +87 -2
- package/dist/index.d.ts +358 -26
- package/dist/index.js +692 -115
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
import { z as z2 } from "zod";
|
|
3
3
|
|
|
4
4
|
// src/backends.ts
|
|
5
|
+
import { isIP } from "net";
|
|
5
6
|
import { z } from "zod";
|
|
6
7
|
var BackendClass = z.enum(["http", "process"]);
|
|
7
8
|
var BackendCost = z.enum(["free", "metered", "subscription"]);
|
|
@@ -177,13 +178,16 @@ function backendDescriptor(id) {
|
|
|
177
178
|
function isLocalHost(hostname) {
|
|
178
179
|
const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
|
|
179
180
|
if (host === "localhost" || host.endsWith(".localhost")) return true;
|
|
180
|
-
|
|
181
|
+
const version = isIP(host);
|
|
182
|
+
if (version === 0) return false;
|
|
183
|
+
if (version === 6) {
|
|
184
|
+
if (host === "::1") return true;
|
|
185
|
+
return /^f[cd]/.test(host);
|
|
186
|
+
}
|
|
181
187
|
if (host.startsWith("127.")) return true;
|
|
182
188
|
if (host.startsWith("10.")) return true;
|
|
183
189
|
if (host.startsWith("192.168.")) return true;
|
|
184
|
-
|
|
185
|
-
if (/^f[cd]/.test(host)) return true;
|
|
186
|
-
return false;
|
|
190
|
+
return /^172\.(1[6-9]|2\d|3[01])\./.test(host);
|
|
187
191
|
}
|
|
188
192
|
function resolveCost(id, baseUrl) {
|
|
189
193
|
const declared = BACKENDS[id].cost;
|
|
@@ -290,11 +294,21 @@ var ChatMessage = z3.object({
|
|
|
290
294
|
var GeneratePayload = z3.object({
|
|
291
295
|
prompt: z3.string().min(1).max(PAYLOAD_LIMITS.maxTextChars),
|
|
292
296
|
system: z3.string().max(PAYLOAD_LIMITS.maxTextChars).optional()
|
|
293
|
-
}).strict()
|
|
297
|
+
}).strict().refine(
|
|
298
|
+
(payload) => payload.prompt.length + (payload.system?.length ?? 0) <= PAYLOAD_LIMITS.maxTotalChars,
|
|
299
|
+
{
|
|
300
|
+
message: `payload exceeds ${String(PAYLOAD_LIMITS.maxTotalChars)} characters`
|
|
301
|
+
}
|
|
302
|
+
);
|
|
294
303
|
var ChatPayload = z3.object({
|
|
295
304
|
messages: z3.array(ChatMessage).min(1).max(PAYLOAD_LIMITS.maxMessages),
|
|
296
305
|
system: z3.string().max(PAYLOAD_LIMITS.maxTextChars).optional()
|
|
297
|
-
}).strict()
|
|
306
|
+
}).strict().refine(
|
|
307
|
+
(payload) => payload.messages.reduce((sum, m) => sum + m.content.length, 0) + (payload.system?.length ?? 0) <= PAYLOAD_LIMITS.maxTotalChars,
|
|
308
|
+
{
|
|
309
|
+
message: `payload exceeds ${String(PAYLOAD_LIMITS.maxTotalChars)} characters`
|
|
310
|
+
}
|
|
311
|
+
);
|
|
298
312
|
var JobKind = z3.enum(["llm.generate", "llm.chat"]);
|
|
299
313
|
var JOB_KINDS = Object.freeze(JobKind.options);
|
|
300
314
|
var KindedPayload = z3.discriminatedUnion("kind", [
|
|
@@ -378,8 +392,19 @@ var ClaimedJob = z4.object({
|
|
|
378
392
|
audience: Audience,
|
|
379
393
|
/** The app's id for the user who enqueued it. */
|
|
380
394
|
owner: z4.string().min(1),
|
|
381
|
-
/**
|
|
382
|
-
|
|
395
|
+
/**
|
|
396
|
+
* Which site's job — V1-3.
|
|
397
|
+
*
|
|
398
|
+
* The stub has always carried it; the opened job did not, so everything
|
|
399
|
+
* downstream of the payload — the ingress line above all — recorded a job
|
|
400
|
+
* id that belongs to a site without saying which. Two sites can choose
|
|
401
|
+
* the same id, and the meter is the product.
|
|
402
|
+
*
|
|
403
|
+
* Optional so a caller assembling a job by hand is not forced to invent
|
|
404
|
+
* one, and so this reads as what it is: a fact about where the work came
|
|
405
|
+
* from, not a second copy of the routing key.
|
|
406
|
+
*/
|
|
407
|
+
site: z4.string().min(1).optional(),
|
|
383
408
|
lease: Lease
|
|
384
409
|
}).strict();
|
|
385
410
|
var ResultProvenance = z4.object({
|
|
@@ -409,6 +434,13 @@ function provenanceFor(input) {
|
|
|
409
434
|
untrusted: input.audience !== "self"
|
|
410
435
|
};
|
|
411
436
|
}
|
|
437
|
+
var RunMetadata = z4.object({
|
|
438
|
+
/** Which model actually served it. */
|
|
439
|
+
model: z4.string().min(1),
|
|
440
|
+
backendClass: BackendClass,
|
|
441
|
+
/** Wall-clock milliseconds the backend call took. */
|
|
442
|
+
durationMs: z4.number().int().nonnegative()
|
|
443
|
+
}).strict();
|
|
412
444
|
var JobResultOk = z4.object({
|
|
413
445
|
outcome: z4.literal("ok"),
|
|
414
446
|
text: z4.string(),
|
|
@@ -430,6 +462,7 @@ var JobOutcome = z4.discriminatedUnion("outcome", [
|
|
|
430
462
|
JobResultError,
|
|
431
463
|
JobResultCanceled
|
|
432
464
|
]);
|
|
465
|
+
var SealedOutcome = z4.object({ outcome: JobOutcome, ran: RunMetadata }).strict();
|
|
433
466
|
var DeliveredResult = z4.object({
|
|
434
467
|
jobId: z4.string().min(1),
|
|
435
468
|
state: JobState,
|
|
@@ -456,8 +489,51 @@ var JobStub = z4.object({
|
|
|
456
489
|
kind: JobKind,
|
|
457
490
|
/** The app's id for the user who enqueued it. */
|
|
458
491
|
owner: z4.string().min(1),
|
|
492
|
+
/**
|
|
493
|
+
* Which site this job belongs to — byollm_009 Amendment A §A.3.
|
|
494
|
+
*
|
|
495
|
+
* **The site's identity key id**, not an id somebody assigned it. §6 has
|
|
496
|
+
* listed `site` since this spec was frozen; the schema never carried it,
|
|
497
|
+
* which is the drift the amendment closes.
|
|
498
|
+
*
|
|
499
|
+
* A key id rather than an opaque handle for one reason above the others:
|
|
500
|
+
* it makes the stub *self-describing* instead of a pointer into somebody
|
|
501
|
+
* else's table. A daemon holds this key id already, from pinning, so it
|
|
502
|
+
* can check `stub.site` against the payload envelope's `senderKeyId`
|
|
503
|
+
* without a lookup and without trusting the party that routed it. An
|
|
504
|
+
* opaque id can only be believed.
|
|
505
|
+
*
|
|
506
|
+
* It also avoids inventing a second namespace for a thing that has a
|
|
507
|
+
* canonical one — the shape of finding 41 (two owner namespaces compared
|
|
508
|
+
* for equality) and of finding fourteen before it.
|
|
509
|
+
*
|
|
510
|
+
* Rotation is a designed transition rather than a cost: a site publishes a
|
|
511
|
+
* new identity signed by the outgoing one, both are valid through an
|
|
512
|
+
* overlap window, and a daemon re-keys its own map by verifying that
|
|
513
|
+
* signature against the key it already pinned (§A.3.1).
|
|
514
|
+
*/
|
|
515
|
+
site: z4.string().min(1),
|
|
459
516
|
audience: Audience,
|
|
460
|
-
audienceAllow
|
|
517
|
+
// `audienceAllow` is **not** here, and its absence is the enforcement —
|
|
518
|
+
// cloud_008 §0.2.
|
|
519
|
+
//
|
|
520
|
+
// It was a list of the people who may run a job, travelling to every
|
|
521
|
+
// routing party on every `named` job. byollm_001 Rev 1 §B settled who
|
|
522
|
+
// decides that long before this schema existed: *the daemon's own list
|
|
523
|
+
// decides, not the server's*, and `allowlist.predicateFor(origin)` is the
|
|
524
|
+
// enforcement in both lanes. So this was a second answer to a question the
|
|
525
|
+
// daemon already owned — able only to agree, in which case it was
|
|
526
|
+
// redundant, or to disagree, in which case nothing said which wins.
|
|
527
|
+
//
|
|
528
|
+
// The rule it leaves behind, which decides the next field too: **a class
|
|
529
|
+
// the router acts on may travel; membership never does.** `audience` stays
|
|
530
|
+
// for exactly that reason — the relay narrows on it. A roster does not
|
|
531
|
+
// travel, so `ROSTER_NOT_DISCLOSED` holds here by absence, which is the
|
|
532
|
+
// strongest way for a MUST to hold.
|
|
533
|
+
//
|
|
534
|
+
// The site keeps its own copy on `JobRecord` and still filters candidates
|
|
535
|
+
// with it before offering. That is server-internal, where the party
|
|
536
|
+
// holding the list authored it.
|
|
461
537
|
sizeClass: SizeClass,
|
|
462
538
|
/** Reserved for byollm_006. False until streaming exists. */
|
|
463
539
|
streaming: z4.boolean(),
|
|
@@ -748,6 +824,21 @@ function signRequest(keys, input) {
|
|
|
748
824
|
signature: signWith(keys, canonicalRequest(input))
|
|
749
825
|
};
|
|
750
826
|
}
|
|
827
|
+
function signSiteRequest(keys, input) {
|
|
828
|
+
return signRequest(keys, {
|
|
829
|
+
endpoint: siteEndpoint(input.endpoint),
|
|
830
|
+
runnerId: input.siteId,
|
|
831
|
+
issuedAt: input.issuedAt,
|
|
832
|
+
body: input.body
|
|
833
|
+
});
|
|
834
|
+
}
|
|
835
|
+
function verifySiteRequest(input) {
|
|
836
|
+
return verifyRequest({
|
|
837
|
+
...input,
|
|
838
|
+
endpoint: siteEndpoint(input.endpoint)
|
|
839
|
+
});
|
|
840
|
+
}
|
|
841
|
+
var siteEndpoint = (endpoint) => `site/${endpoint}`;
|
|
751
842
|
function verifyRequest(input) {
|
|
752
843
|
const skew = input.maxSkewMs ?? MAX_CLOCK_SKEW_MS;
|
|
753
844
|
if (Math.abs(input.now - input.signature.issuedAt) > skew) return "stale";
|
|
@@ -764,7 +855,69 @@ function verifyRequest(input) {
|
|
|
764
855
|
return ok ? null : "bad-signature";
|
|
765
856
|
}
|
|
766
857
|
|
|
858
|
+
// src/succession.ts
|
|
859
|
+
import { z as z8 } from "zod";
|
|
860
|
+
var SUCCESSION_CONTEXT = "byollm/v1/site-succession";
|
|
861
|
+
var RETIREMENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
|
|
862
|
+
var MAX_SUCCESSION_CHAIN = 64;
|
|
863
|
+
var Succession = z8.object({
|
|
864
|
+
/**
|
|
865
|
+
* The predecessor's public identity — K1, in full.
|
|
866
|
+
*
|
|
867
|
+
* The whole identity rather than the key id, because a daemon meeting a
|
|
868
|
+
* chain it has not seen before has to *verify* each link, and a key id is
|
|
869
|
+
* a fingerprint: enough to compare, never enough to check a signature.
|
|
870
|
+
*/
|
|
871
|
+
identity: PublicIdentity,
|
|
872
|
+
/** K1's signature over the statement naming K1 and its successor. */
|
|
873
|
+
signature: z8.string().min(1)
|
|
874
|
+
}).strict();
|
|
875
|
+
function successionStatement(fromKeyId, toKeyId) {
|
|
876
|
+
return Buffer.from(`${SUCCESSION_CONTEXT}:${fromKeyId}:${toKeyId}`);
|
|
877
|
+
}
|
|
878
|
+
function signSuccession(previous, next) {
|
|
879
|
+
return {
|
|
880
|
+
identity: {
|
|
881
|
+
identity: previous.identityPublic,
|
|
882
|
+
encryption: previous.encryptionPublic,
|
|
883
|
+
encryptionSig: previous.encryptionSig
|
|
884
|
+
},
|
|
885
|
+
signature: signWith(
|
|
886
|
+
previous,
|
|
887
|
+
successionStatement(keyId(previous.identityPublic), keyId(next.identity))
|
|
888
|
+
)
|
|
889
|
+
};
|
|
890
|
+
}
|
|
891
|
+
function verifyLink(link, toKeyId) {
|
|
892
|
+
if (!verifyPublicIdentity(link.identity)) return false;
|
|
893
|
+
return verifyWith(
|
|
894
|
+
link.identity.identity,
|
|
895
|
+
successionStatement(keyId(link.identity.identity), toKeyId),
|
|
896
|
+
link.signature
|
|
897
|
+
);
|
|
898
|
+
}
|
|
899
|
+
function walkSuccession(input) {
|
|
900
|
+
const { current, chain, approved } = input;
|
|
901
|
+
if (chain.length === 0) return { path: [current], failure: "no-chain" };
|
|
902
|
+
if (chain.length > MAX_SUCCESSION_CHAIN)
|
|
903
|
+
return { path: [current], failure: "too-long" };
|
|
904
|
+
const steps = [...chain].reverse();
|
|
905
|
+
const path = [current];
|
|
906
|
+
let succeeding = current;
|
|
907
|
+
for (const link of steps) {
|
|
908
|
+
if (!verifyLink(link, succeeding)) return { path, failure: "broken-link" };
|
|
909
|
+
const previous = keyId(link.identity.identity);
|
|
910
|
+
path.unshift(previous);
|
|
911
|
+
if (approved(previous)) return { path, from: previous };
|
|
912
|
+
succeeding = previous;
|
|
913
|
+
}
|
|
914
|
+
return { path, failure: "unknown-origin" };
|
|
915
|
+
}
|
|
916
|
+
|
|
767
917
|
// src/musts.ts
|
|
918
|
+
function kindsOf(must2) {
|
|
919
|
+
return typeof must2.verifiedBy === "string" ? [must2.verifiedBy] : must2.verifiedBy;
|
|
920
|
+
}
|
|
768
921
|
var must = (m) => Object.freeze(m);
|
|
769
922
|
var MUSTS = Object.freeze({
|
|
770
923
|
// ---- Pairing and identity -------------------------------------------
|
|
@@ -797,6 +950,48 @@ var MUSTS = Object.freeze({
|
|
|
797
950
|
verifiedBy: "conformance",
|
|
798
951
|
source: "byollm_009 \xA74"
|
|
799
952
|
}),
|
|
953
|
+
SITE_KEY_BY_STUB: must({
|
|
954
|
+
id: "SITE_KEY_BY_STUB",
|
|
955
|
+
statement: "A daemon MUST verify a job's payload against the pinned key of the site the stub names, and MUST refuse a job naming a site it has not pinned. It MUST NOT fall back to another pinned key, and MUST refuse an envelope whose declared sender disagrees with the stub's site.",
|
|
956
|
+
enforcedBy: "daemon",
|
|
957
|
+
// Adversarial, and the reason is the finding that produced it: the
|
|
958
|
+
// honest paths pass with every site check deleted, because `open`
|
|
959
|
+
// refuses a signature from the wrong key anyway. What distinguishes an
|
|
960
|
+
// enforced rule from a coincidence here is a hostile pairing of stub and
|
|
961
|
+
// envelope, which no conformance client would ever send.
|
|
962
|
+
verifiedBy: "adversarial",
|
|
963
|
+
source: "byollm_009 \xA7A.3"
|
|
964
|
+
}),
|
|
965
|
+
SITES_LOCALLY_APPROVED: must({
|
|
966
|
+
id: "SITES_LOCALLY_APPROVED",
|
|
967
|
+
statement: "A daemon MUST NOT run work for a site it has not approved on the machine itself. An upstream may propose a site set; a site the daemon has never approved MUST be offered to its owner and served nothing until they approve it. A key that has changed for an already-approved id MUST be refused for the life of the pairing, including after that id has left the set and returned. A **verified succession** is not a changed key: a new key id carrying a signature, by a key this daemon has already approved, over a statement naming both key ids MUST be accepted without a new local approval \u2014 provided the control plane projects the same successor \u2014 and MUST be announced rather than applied silently.",
|
|
968
|
+
enforcedBy: "daemon",
|
|
969
|
+
// Two kinds, and the second is the one that matters — V1-1.
|
|
970
|
+
//
|
|
971
|
+
// `construction`: the daemon cannot serve a site that is not in its
|
|
972
|
+
// pinned map, and admission refuses before a payload is fetched, so the
|
|
973
|
+
// ordinary path cannot reach a site nobody approved.
|
|
974
|
+
//
|
|
975
|
+
// `adversarial`: the property that survives is about a *sequence* —
|
|
976
|
+
// remove the id, re-offer it under a different key — which no honest
|
|
977
|
+
// upstream sends and which the fence above does not see. That was the
|
|
978
|
+
// bypass: the pin was deleted with the id, so the comparison had nothing
|
|
979
|
+
// to compare against and the substitution arrived as a stranger.
|
|
980
|
+
// **Not `conformance`, and that is a live gap rather than a judgement.**
|
|
981
|
+
// Amendment C's succession clause is a rule about two implementations
|
|
982
|
+
// agreeing, which is what a conformance check is for — but rotating a
|
|
983
|
+
// site's key is not something `ConformanceTarget` can express, and adding
|
|
984
|
+
// an optional hook that most targets omit would produce a check reporting
|
|
985
|
+
// success for a reason unrelated to the property it claims. That is this
|
|
986
|
+
// project's most-repeated bug, and it is not worth reintroducing for a
|
|
987
|
+
// stronger-sounding word in a table. The rotation path is verified by
|
|
988
|
+
// `site-rotation.test.ts` (both directions, against the shipped runner)
|
|
989
|
+
// and `relay/test/rotation.test.ts` (both planes, against the reference
|
|
990
|
+
// relay); the missing piece is a second *independent* implementation to
|
|
991
|
+
// check them against, and there is not one yet.
|
|
992
|
+
verifiedBy: ["construction", "adversarial"],
|
|
993
|
+
source: "byollm_009 \xA7B.2, Amendment C"
|
|
994
|
+
}),
|
|
800
995
|
KEYS_EXCHANGED_AT_CONSENT: must({
|
|
801
996
|
id: "KEYS_EXCHANGED_AT_CONSENT",
|
|
802
997
|
statement: "Pairing MUST exchange both parties' public identities; each side MUST verify that the encryption key is signed by the identity presenting it, and MUST pin the identity. Keys MUST NOT be delivered before approval.",
|
|
@@ -984,12 +1179,12 @@ var MUSTS = Object.freeze({
|
|
|
984
1179
|
verifiedBy: "conformance",
|
|
985
1180
|
source: "byollm_001 \xA7Endpoints.4"
|
|
986
1181
|
}),
|
|
987
|
-
|
|
988
|
-
id: "
|
|
989
|
-
statement: "A result
|
|
1182
|
+
PROVENANCE_NAMES_DEVICE: must({
|
|
1183
|
+
id: "PROVENANCE_NAMES_DEVICE",
|
|
1184
|
+
statement: "A result MUST carry the claiming device's key id and its relationship to the requester, to the delivery seam, so an app never treats volunteer output as first-party. The key id MUST be the device the upstream granted the lease to, and a result whose signature does not verify against that device MUST be refused rather than recorded.",
|
|
990
1185
|
enforcedBy: "server",
|
|
991
1186
|
verifiedBy: "conformance",
|
|
992
|
-
source: "
|
|
1187
|
+
source: "byollm_009 \xA711"
|
|
993
1188
|
}),
|
|
994
1189
|
// ---- The trust surface -------------------------------------------------
|
|
995
1190
|
INGRESS_LOGGED_BEFORE_EXECUTION: must({
|
|
@@ -1041,26 +1236,117 @@ var MUSTS = Object.freeze({
|
|
|
1041
1236
|
enforcedBy: "daemon",
|
|
1042
1237
|
verifiedBy: "adversarial",
|
|
1043
1238
|
source: "byollm_004 \xA74"
|
|
1239
|
+
}),
|
|
1240
|
+
REVOCATION_IMMEDIATE: must({
|
|
1241
|
+
id: "REVOCATION_IMMEDIATE",
|
|
1242
|
+
statement: "Revocation MUST take effect at the upstream at once \u2014 a revoked runner MUST NOT be granted further work from the moment the record changes \u2014 and MUST reach the daemon by its next heartbeat.",
|
|
1243
|
+
// Both, and stated as one sentence with two obligations rather than
|
|
1244
|
+
// folded into REVOCATION_HONORED. That one binds the *daemon*: a revoked
|
|
1245
|
+
// daemon stops claiming and abandons in-flight work. This binds the
|
|
1246
|
+
// *upstream*. byollm_009 §5 is explicit that the pair is the point — "a
|
|
1247
|
+
// revocation enforced at one end survives a compromise of that end" — and
|
|
1248
|
+
// one entry covering both would make a compromised daemon look compliant.
|
|
1249
|
+
enforcedBy: "both",
|
|
1250
|
+
verifiedBy: "conformance",
|
|
1251
|
+
source: "byollm_009 \xA711"
|
|
1252
|
+
}),
|
|
1253
|
+
CONSENT_BEFORE_ROUTE: must({
|
|
1254
|
+
id: "CONSENT_BEFORE_ROUTE",
|
|
1255
|
+
statement: "An upstream MUST NOT route a job to a device without a record binding that user, that site and that scope. There MUST be no discovery path by which a device receives work it was never granted.",
|
|
1256
|
+
enforcedBy: "server",
|
|
1257
|
+
verifiedBy: "conformance",
|
|
1258
|
+
source: "byollm_009 \xA711"
|
|
1259
|
+
}),
|
|
1260
|
+
ROSTER_NOT_DISCLOSED: must({
|
|
1261
|
+
id: "ROSTER_NOT_DISCLOSED",
|
|
1262
|
+
statement: "A site MUST NOT learn the membership of a group whose compute it uses, and MUST NOT publish membership to a routing party. No wire message may carry a list of who may run a job.",
|
|
1263
|
+
// Checkable since cloud_008 §0.2 took `audienceAllow` off the stub: the
|
|
1264
|
+
// property now holds by *absence*, and absence is exactly what a strict
|
|
1265
|
+
// schema and a serialised stub can be asked about. Before that it was a
|
|
1266
|
+
// sentence — and one this project cited in code comments, tests and two
|
|
1267
|
+
// specs as though it were enforced data, which is why it is worth
|
|
1268
|
+
// stating precisely rather than generously.
|
|
1269
|
+
enforcedBy: "both",
|
|
1270
|
+
verifiedBy: "conformance",
|
|
1271
|
+
source: "byollm_009 \xA711"
|
|
1272
|
+
}),
|
|
1273
|
+
EFFECTIVE_OFFER_ONLY: must({
|
|
1274
|
+
id: "EFFECTIVE_OFFER_ONLY",
|
|
1275
|
+
statement: "A daemon MUST declare effective offers only. An upstream MUST NOT receive raw config, allowlists, or capacity the owner has not shared, and MUST act on the declared offer rather than on what was asked for.",
|
|
1276
|
+
enforcedBy: "both",
|
|
1277
|
+
verifiedBy: "conformance",
|
|
1278
|
+
source: "byollm_009 \xA711"
|
|
1279
|
+
}),
|
|
1280
|
+
FALLBACK_LABELED: must({
|
|
1281
|
+
id: "FALLBACK_LABELED",
|
|
1282
|
+
statement: "Work served by anything other than the user's own compute MUST be labelled as such wherever it is reported, and MUST NOT be silently substituted.",
|
|
1283
|
+
// `construction` today, and deliberately not `conformance`. Nothing on
|
|
1284
|
+
// the wire yet distinguishes a fallback from any other community job —
|
|
1285
|
+
// the ledger that would give it a surface is unbuilt — so a check would
|
|
1286
|
+
// have to assert something it cannot observe. Promoted the day that
|
|
1287
|
+
// surface exists. Marking it `conformance` now would put "verified"
|
|
1288
|
+
// beside a property no third party can see, which is the one thing the
|
|
1289
|
+
// kinds exist to prevent.
|
|
1290
|
+
enforcedBy: "both",
|
|
1291
|
+
verifiedBy: "construction",
|
|
1292
|
+
source: "byollm_009 \xA711"
|
|
1293
|
+
}),
|
|
1294
|
+
RELAY_BLIND: must({
|
|
1295
|
+
id: "RELAY_BLIND",
|
|
1296
|
+
statement: "A relay MUST NOT hold any key capable of decrypting a payload, a result, or a delta frame.",
|
|
1297
|
+
// Operator: a third party can read the relay's types and see there is
|
|
1298
|
+
// nowhere to put such a key, but the kit certifies a *server* and cannot
|
|
1299
|
+
// reach inside somebody's deployment to prove what it holds.
|
|
1300
|
+
enforcedBy: "server",
|
|
1301
|
+
verifiedBy: "operator",
|
|
1302
|
+
source: "byollm_009 \xA711"
|
|
1303
|
+
}),
|
|
1304
|
+
SHARED_COMPUTE_DISCLOSED: must({
|
|
1305
|
+
id: "SHARED_COMPUTE_DISCLOSED",
|
|
1306
|
+
statement: "Before a user's work first runs on compute they do not own, they MUST be told in plain language that the machine's owner can see it.",
|
|
1307
|
+
// Operator, and cloud_008 §0.3 is why the classification now comes with a
|
|
1308
|
+
// standing answer rather than a standing question. The screen is not
|
|
1309
|
+
// wire-observable, but the *string the server composes* is, and it is
|
|
1310
|
+
// now unit-tested with the two false sentences forbidden by name. The
|
|
1311
|
+
// kind stays `operator` because a third-party site can still render
|
|
1312
|
+
// whatever it likes; what changed is that the part inside our own
|
|
1313
|
+
// boundary stopped depending on somebody remembering to audit it.
|
|
1314
|
+
enforcedBy: "server",
|
|
1315
|
+
verifiedBy: "operator",
|
|
1316
|
+
source: "byollm_009 \xA711"
|
|
1044
1317
|
})
|
|
1045
1318
|
});
|
|
1319
|
+
var RETIRED_MUSTS = Object.freeze({
|
|
1320
|
+
RESULT_PROVENANCE: {
|
|
1321
|
+
supersededBy: "PROVENANCE_NAMES_DEVICE",
|
|
1322
|
+
note: "Strengthened, not renamed: attribution is now by proof of possession \u2014 the result's signature must verify against the device the upstream granted the lease to \u2014 rather than by a provenance label travelling beside it. byollm_009 \xA711 states the stronger form."
|
|
1323
|
+
}
|
|
1324
|
+
});
|
|
1046
1325
|
var MUST_IDS = Object.freeze(Object.keys(MUSTS));
|
|
1047
1326
|
function mustsVerifiedBy(kind) {
|
|
1048
|
-
return MUST_IDS.filter((id) => MUSTS[id].
|
|
1327
|
+
return MUST_IDS.filter((id) => kindsOf(MUSTS[id]).includes(kind));
|
|
1049
1328
|
}
|
|
1050
1329
|
|
|
1051
1330
|
// src/wire.ts
|
|
1052
|
-
import { z as
|
|
1331
|
+
import { z as z9 } from "zod";
|
|
1053
1332
|
var PROTOCOL_VERSION = "0";
|
|
1054
1333
|
var SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([
|
|
1055
1334
|
PROTOCOL_VERSION
|
|
1056
1335
|
]);
|
|
1057
1336
|
var MIN_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0] ?? PROTOCOL_VERSION;
|
|
1337
|
+
function declaredVersion(input) {
|
|
1338
|
+
const { body, query } = input;
|
|
1339
|
+
if (typeof body === "object" && body !== null && Object.hasOwn(body, "protocolVersion")) {
|
|
1340
|
+
return body.protocolVersion;
|
|
1341
|
+
}
|
|
1342
|
+
return query?.get("protocolVersion") ?? void 0;
|
|
1343
|
+
}
|
|
1058
1344
|
function checkProtocolVersion(body) {
|
|
1059
1345
|
const declared = typeof body === "object" && body !== null && Object.hasOwn(body, "protocolVersion") ? body.protocolVersion : void 0;
|
|
1060
1346
|
if (typeof declared !== "string" || declared.length === 0) {
|
|
1061
1347
|
return {
|
|
1062
1348
|
error: "unsupported-protocol-version",
|
|
1063
|
-
message:
|
|
1349
|
+
message: `this request declared no protocol version. Upgrade the daemon: \`${UPGRADE_COMMAND}\`.`,
|
|
1064
1350
|
supported: SUPPORTED_PROTOCOL_VERSIONS,
|
|
1065
1351
|
minimum: MIN_PROTOCOL_VERSION
|
|
1066
1352
|
};
|
|
@@ -1068,13 +1354,14 @@ function checkProtocolVersion(body) {
|
|
|
1068
1354
|
if (!SUPPORTED_PROTOCOL_VERSIONS.includes(declared)) {
|
|
1069
1355
|
return {
|
|
1070
1356
|
error: "unsupported-protocol-version",
|
|
1071
|
-
message: `this server speaks protocol ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")} and the daemon asked for ${declared}. ` + (declared < MIN_PROTOCOL_VERSION ?
|
|
1357
|
+
message: `this server speaks protocol ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")} and the daemon asked for ${declared}. ` + (declared < MIN_PROTOCOL_VERSION ? `Upgrade the daemon: \`${UPGRADE_COMMAND}\`.` : "This daemon is newer than the server; the server needs upgrading."),
|
|
1072
1358
|
supported: SUPPORTED_PROTOCOL_VERSIONS,
|
|
1073
1359
|
minimum: MIN_PROTOCOL_VERSION
|
|
1074
1360
|
};
|
|
1075
1361
|
}
|
|
1076
1362
|
return null;
|
|
1077
1363
|
}
|
|
1364
|
+
var UPGRADE_COMMAND = "npm i -g byollm@latest";
|
|
1078
1365
|
var PROTOCOL_PREFIX = "/byollm";
|
|
1079
1366
|
var ENDPOINTS = Object.freeze([
|
|
1080
1367
|
"pair",
|
|
@@ -1084,22 +1371,22 @@ var ENDPOINTS = Object.freeze([
|
|
|
1084
1371
|
"result",
|
|
1085
1372
|
"release"
|
|
1086
1373
|
]);
|
|
1087
|
-
var Capability =
|
|
1374
|
+
var Capability = z9.object({
|
|
1088
1375
|
kind: JobKind,
|
|
1089
1376
|
backendId: BackendIdSchema,
|
|
1090
1377
|
backendClass: BackendClass,
|
|
1091
|
-
model:
|
|
1378
|
+
model: z9.string().min(1),
|
|
1092
1379
|
offerScope: OfferScope
|
|
1093
1380
|
}).strict();
|
|
1094
|
-
var CapabilityMatrix =
|
|
1095
|
-
var PairStartRequest =
|
|
1096
|
-
protocolVersion:
|
|
1097
|
-
action:
|
|
1098
|
-
daemon:
|
|
1099
|
-
version:
|
|
1381
|
+
var CapabilityMatrix = z9.array(Capability);
|
|
1382
|
+
var PairStartRequest = z9.object({
|
|
1383
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1384
|
+
action: z9.literal("start"),
|
|
1385
|
+
daemon: z9.object({
|
|
1386
|
+
version: z9.string().min(1),
|
|
1100
1387
|
/** Shown in the app's runner list so a user can tell their machines apart. */
|
|
1101
|
-
label:
|
|
1102
|
-
platform:
|
|
1388
|
+
label: z9.string().min(1).max(120),
|
|
1389
|
+
platform: z9.enum(["darwin", "linux", "win32"])
|
|
1103
1390
|
}),
|
|
1104
1391
|
/**
|
|
1105
1392
|
* This machine's public keys (byollm_009 §5).
|
|
@@ -1111,70 +1398,96 @@ var PairStartRequest = z8.object({
|
|
|
1111
1398
|
device: PublicIdentity,
|
|
1112
1399
|
capabilities: CapabilityMatrix
|
|
1113
1400
|
}).strict();
|
|
1114
|
-
var PairStartResponse =
|
|
1401
|
+
var PairStartResponse = z9.object({
|
|
1115
1402
|
/** Secret the daemon polls with. Never shown to the user. */
|
|
1116
|
-
deviceCode:
|
|
1403
|
+
deviceCode: z9.string().min(20),
|
|
1117
1404
|
/** Short code the user reads and confirms in the browser. */
|
|
1118
|
-
userCode:
|
|
1405
|
+
userCode: z9.string().min(4).max(16),
|
|
1119
1406
|
/** Where the user approves. Must be on the server's own origin. */
|
|
1120
|
-
verificationUrl:
|
|
1407
|
+
verificationUrl: z9.url(),
|
|
1121
1408
|
/** Epoch ms after which the code is dead ({@link MUSTS.PAIR_CODE_EXPIRES}). */
|
|
1122
|
-
expiresAt:
|
|
1409
|
+
expiresAt: z9.number().int().positive(),
|
|
1123
1410
|
/** How often the daemon may poll. */
|
|
1124
|
-
pollIntervalMs:
|
|
1411
|
+
pollIntervalMs: z9.number().int().min(500).max(6e4)
|
|
1125
1412
|
}).strict();
|
|
1126
|
-
var PairPollRequest =
|
|
1127
|
-
protocolVersion:
|
|
1128
|
-
action:
|
|
1129
|
-
deviceCode:
|
|
1413
|
+
var PairPollRequest = z9.object({
|
|
1414
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1415
|
+
action: z9.literal("poll"),
|
|
1416
|
+
deviceCode: z9.string().min(20)
|
|
1130
1417
|
}).strict();
|
|
1131
|
-
var PairPollResponse =
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
status:
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1418
|
+
var PairPollResponse = z9.discriminatedUnion("status", [
|
|
1419
|
+
z9.object({ status: z9.literal("pending") }).strict(),
|
|
1420
|
+
z9.object({ status: z9.literal("denied") }).strict(),
|
|
1421
|
+
z9.object({ status: z9.literal("expired") }).strict(),
|
|
1422
|
+
z9.object({
|
|
1423
|
+
status: z9.literal("approved"),
|
|
1424
|
+
// `runnerToken` is gone — cloud_008 §2.4, finding 37.
|
|
1425
|
+
//
|
|
1426
|
+
// It was minted here, hashed into `RunnerRecord.tokenHash`, written to
|
|
1427
|
+
// the daemon's pairings file, and then **never sent, never looked up
|
|
1428
|
+
// and never compared**. `getRunnerByTokenHash` existed on both stores
|
|
1429
|
+
// and was called by nothing but a test asserting it returns null.
|
|
1430
|
+
//
|
|
1431
|
+
// Not merely dead wire, which is what `audienceAllow` and
|
|
1432
|
+
// `HeartbeatResponse.leases` were. This was a *secret*: minted,
|
|
1433
|
+
// transmitted, and written to two disks at rest, for nothing. A
|
|
1434
|
+
// credential with no purpose is a liability rather than clutter,
|
|
1435
|
+
// because the only thing it can ever do is leak.
|
|
1436
|
+
//
|
|
1437
|
+
// `REQUESTS_SIGNED_NOT_BEARER` was already the rule and was already
|
|
1438
|
+
// enforced — every authenticated call is signed by the device's pinned
|
|
1439
|
+
// identity key. This removes the thing the MUST is named after.
|
|
1440
|
+
runnerId: z9.string().min(1),
|
|
1140
1441
|
/** The app's id for the approving user — this daemon's owner forever. */
|
|
1141
|
-
owner:
|
|
1442
|
+
owner: z9.string().min(1),
|
|
1142
1443
|
/** Display name for the trust UI, if the app offers one. */
|
|
1143
|
-
ownerLabel:
|
|
1444
|
+
ownerLabel: z9.string().optional(),
|
|
1144
1445
|
/**
|
|
1145
|
-
* The
|
|
1446
|
+
* The sites this pairing covers, for the daemon to pin (byollm_009 §5),
|
|
1447
|
+
* keyed by each site's identity key id — cloud_009 §5.
|
|
1146
1448
|
*
|
|
1147
|
-
* Returned only on approval
|
|
1449
|
+
* Returned only on approval: a pending or denied poll learns nothing,
|
|
1148
1450
|
* so an unapproved code cannot be used to enumerate a site's keys.
|
|
1451
|
+
*
|
|
1452
|
+
* **One pairing per upstream, not one per site.** A user who connects a
|
|
1453
|
+
* site on a web dashboard has no reason to go back to a laptop and run
|
|
1454
|
+
* a command, so which sites a pairing covers is a projection of consent
|
|
1455
|
+
* — refreshed on the heartbeat — rather than something frozen at
|
|
1456
|
+
* pairing. A direct site answers with exactly one entry, which is the
|
|
1457
|
+
* same shape and not a special case.
|
|
1458
|
+
*
|
|
1459
|
+
* Keyed by the id `stub.site` carries (Amendment A §A.3), so the
|
|
1460
|
+
* runner's lookup is a map read rather than a join across two
|
|
1461
|
+
* namespaces.
|
|
1149
1462
|
*/
|
|
1150
|
-
|
|
1463
|
+
sites: z9.record(z9.string().min(1), PublicIdentity)
|
|
1151
1464
|
}).strict()
|
|
1152
1465
|
]);
|
|
1153
|
-
var PairRequest =
|
|
1466
|
+
var PairRequest = z9.discriminatedUnion("action", [
|
|
1154
1467
|
PairStartRequest,
|
|
1155
1468
|
PairPollRequest
|
|
1156
1469
|
]);
|
|
1157
|
-
var ClaimRequest =
|
|
1158
|
-
protocolVersion:
|
|
1159
|
-
runnerId:
|
|
1470
|
+
var ClaimRequest = z9.object({
|
|
1471
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1472
|
+
runnerId: z9.string().min(1),
|
|
1160
1473
|
/** Re-sent on every claim so a server never matches against a stale matrix. */
|
|
1161
1474
|
capabilities: CapabilityMatrix,
|
|
1162
1475
|
/** Upper bound on jobs to return; the server may return fewer. */
|
|
1163
|
-
max:
|
|
1476
|
+
max: z9.number().int().min(1).max(64)
|
|
1164
1477
|
}).strict();
|
|
1165
|
-
var ClaimResponse =
|
|
1478
|
+
var ClaimResponse = z9.object({
|
|
1166
1479
|
/**
|
|
1167
1480
|
* Stubs, not jobs. The payload arrives from `fetch`, sealed to whichever
|
|
1168
1481
|
* device claimed — see {@link JobStub} for the exhaustive metadata list.
|
|
1169
1482
|
*/
|
|
1170
|
-
jobs:
|
|
1483
|
+
jobs: z9.array(ClaimedStub),
|
|
1171
1484
|
/** Lease duration granted, so the daemon knows its renewal deadline. */
|
|
1172
|
-
leaseMs:
|
|
1485
|
+
leaseMs: z9.number().int().positive()
|
|
1173
1486
|
}).strict();
|
|
1174
|
-
var HeartbeatRequest =
|
|
1175
|
-
protocolVersion:
|
|
1176
|
-
runnerId:
|
|
1177
|
-
daemonVersion:
|
|
1487
|
+
var HeartbeatRequest = z9.object({
|
|
1488
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1489
|
+
runnerId: z9.string().min(1),
|
|
1490
|
+
daemonVersion: z9.string().min(1),
|
|
1178
1491
|
capabilities: CapabilityMatrix,
|
|
1179
1492
|
/**
|
|
1180
1493
|
* Leases this daemon believes it holds; the server renews exactly these.
|
|
@@ -1182,40 +1495,154 @@ var HeartbeatRequest = z8.object({
|
|
|
1182
1495
|
* Lease ids rather than job ids, so a replayed heartbeat cannot renew a
|
|
1183
1496
|
* grant the runner no longer holds — see {@link Lease.id}.
|
|
1184
1497
|
*/
|
|
1185
|
-
activeLeases:
|
|
1186
|
-
|
|
1498
|
+
activeLeases: z9.array(
|
|
1499
|
+
z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
|
|
1187
1500
|
),
|
|
1188
1501
|
/** True while the owner has the daemon paused; the server stops offering work. */
|
|
1189
|
-
paused:
|
|
1502
|
+
paused: z9.boolean()
|
|
1190
1503
|
}).strict();
|
|
1191
|
-
var HeartbeatResponse =
|
|
1192
|
-
/**
|
|
1193
|
-
|
|
1504
|
+
var HeartbeatResponse = z9.object({
|
|
1505
|
+
/**
|
|
1506
|
+
* The sites this daemon may serve, right now — cloud_008 finding 59.
|
|
1507
|
+
*
|
|
1508
|
+
* Revocation used to be a boolean, and it was device-wide: the daemon
|
|
1509
|
+
* plane refused every call when the (owner, hub-site) consent was gone,
|
|
1510
|
+
* heartbeat answered `revoked: true` with `lost: all`, and the daemon
|
|
1511
|
+
* dropped its whole pairing by origin. Under a hub that is one site's
|
|
1512
|
+
* revocation ending a machine's relationship with every other site it
|
|
1513
|
+
* served — the amplification finding 48 warned about, arriving through
|
|
1514
|
+
* the one field nobody thought of as tenancy.
|
|
1515
|
+
*
|
|
1516
|
+
* So the answer is the set. A site that leaves it is revoked *for that
|
|
1517
|
+
* site*: the daemon drops that pin and keeps the rest. An empty set is
|
|
1518
|
+
* what "revoked" used to mean, and the daemon can see that for itself
|
|
1519
|
+
* rather than being told a second time — two fields for one fact is how
|
|
1520
|
+
* they drift.
|
|
1521
|
+
*/
|
|
1522
|
+
sites: z9.record(z9.string().min(1), PublicIdentity),
|
|
1523
|
+
/**
|
|
1524
|
+
* How a site's current key traces back to one this daemon already holds —
|
|
1525
|
+
* byollm_009 Amendment C.
|
|
1526
|
+
*
|
|
1527
|
+
* Keyed by the same id as `sites`, and **additive on purpose**: `sites`
|
|
1528
|
+
* remains the one statement of which key is current, and this says only
|
|
1529
|
+
* how that key got there. Two fields for one fact is how they drift; this
|
|
1530
|
+
* is two facts, and the second is evidence about the first.
|
|
1531
|
+
*
|
|
1532
|
+
* Optional because a site that has never rotated has no chain, which is
|
|
1533
|
+
* every site today. A daemon that receives one for an id it already holds
|
|
1534
|
+
* ignores it: the pin it has is the pin it approved.
|
|
1535
|
+
*
|
|
1536
|
+
* §12 carries what this adds to the metadata surface — a site's rotation
|
|
1537
|
+
* history is public by construction, because a daemon that cannot read it
|
|
1538
|
+
* cannot verify it.
|
|
1539
|
+
*/
|
|
1540
|
+
successions: z9.record(
|
|
1541
|
+
z9.string().min(1),
|
|
1542
|
+
z9.object({
|
|
1543
|
+
/** Oldest last, as the projection carries it. */
|
|
1544
|
+
succeeds: z9.array(Succession).max(MAX_SUCCESSION_CHAIN),
|
|
1545
|
+
/**
|
|
1546
|
+
* Until when the superseded key may still sign work — epoch ms.
|
|
1547
|
+
*
|
|
1548
|
+
* The daemon holds its own clock against this, for the reason it
|
|
1549
|
+
* holds its own allowlist: a projection that could extend the
|
|
1550
|
+
* window indefinitely would be a two-key site forever, decided by
|
|
1551
|
+
* the party this design does not trust.
|
|
1552
|
+
*/
|
|
1553
|
+
retiringUntil: z9.number().int().positive().optional()
|
|
1554
|
+
}).strict()
|
|
1555
|
+
).optional(),
|
|
1194
1556
|
/**
|
|
1195
1557
|
* Per-job cancel (byollm_001 Rev 1 §C). The daemon aborts these jobs'
|
|
1196
1558
|
* in-flight backend calls and reports them `canceled`.
|
|
1559
|
+
*
|
|
1560
|
+
* **The grant, not the id** — V1-3. Job ids are chosen per site, so two
|
|
1561
|
+
* sites may pick the same one, and a bare id told a daemon holding both
|
|
1562
|
+
* to abort whichever it happened to have filed under that name. The lease
|
|
1563
|
+
* is the unique grant and the daemon already keys its work by it; this is
|
|
1564
|
+
* the same shape `activeLeases` sends in the other direction.
|
|
1197
1565
|
*/
|
|
1198
|
-
cancel:
|
|
1199
|
-
|
|
1200
|
-
leases: z8.array(
|
|
1201
|
-
z8.object({
|
|
1202
|
-
jobId: z8.string().min(1),
|
|
1203
|
-
expiresAt: z8.number().int().positive()
|
|
1204
|
-
}).strict()
|
|
1566
|
+
cancel: z9.array(
|
|
1567
|
+
z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
|
|
1205
1568
|
),
|
|
1569
|
+
// `leases` is deliberately absent — cloud_008 §1.4b, finding 16.
|
|
1570
|
+
//
|
|
1571
|
+
// It carried "these leases were renewed, and here is the new expiry", and
|
|
1572
|
+
// **no daemon ever read it.** A mutation returning an empty list while
|
|
1573
|
+
// renewing correctly survived every test, which is what made it visible.
|
|
1574
|
+
//
|
|
1575
|
+
// It is neither a class nor membership, so Amendment A's rule does not
|
|
1576
|
+
// decide it — the older test does: nothing reads it, so it is dead wire.
|
|
1577
|
+
// §6's exhaustiveness is a commitment about what an upstream can see, and
|
|
1578
|
+
// it applies to every message rather than only to the stub.
|
|
1579
|
+
//
|
|
1580
|
+
// `lost` is the actionable signal and always was: a daemon stops work on
|
|
1581
|
+
// a lease it no longer holds. "Renewed" was the same question answered a
|
|
1582
|
+
// second time, and a second answer can only agree or contradict.
|
|
1583
|
+
//
|
|
1584
|
+
// Renewal itself is untouched — the upstream still extends the grants a
|
|
1585
|
+
// heartbeat names, which is what §0.6 fixed. What ended is telling the
|
|
1586
|
+
// daemon about it in a field it ignored. If an upstream ever needs to
|
|
1587
|
+
// push lease decisions, that is a new field with a reader, added on
|
|
1588
|
+
// purpose.
|
|
1206
1589
|
/**
|
|
1207
1590
|
* Jobs the daemon thinks it holds but the server has reassigned or
|
|
1208
1591
|
* expired. The daemon must stop work on these and not report results.
|
|
1592
|
+
*
|
|
1593
|
+
* Named by grant rather than by id, for V1-3's reason: a bare id is
|
|
1594
|
+
* ambiguous across sites, and "the lease you no longer hold" is exactly
|
|
1595
|
+
* what this field means anyway.
|
|
1209
1596
|
*/
|
|
1210
|
-
lost:
|
|
1597
|
+
lost: z9.array(
|
|
1598
|
+
z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) }).strict()
|
|
1599
|
+
),
|
|
1211
1600
|
/** Server clock, so a daemon with a skewed clock still honors leases. */
|
|
1212
|
-
serverTime:
|
|
1601
|
+
serverTime: z9.number().int().positive(),
|
|
1602
|
+
/**
|
|
1603
|
+
* Sites whose disclosure the user must read again before work moves —
|
|
1604
|
+
* cloud_008 finding 48, named rather than counted.
|
|
1605
|
+
*
|
|
1606
|
+
* A **subset of `sites`**, deliberately: a paused site keeps its pin, so
|
|
1607
|
+
* re-consenting never costs a re-pair. The daemon can say which site is
|
|
1608
|
+
* waiting and the user can go and read it, which is the difference
|
|
1609
|
+
* between a machine that is quietly idle and one that says why.
|
|
1610
|
+
*
|
|
1611
|
+
* Not `revoked`, which is a human ending a relationship, and not
|
|
1612
|
+
* `paused`, which on the request side already means "this daemon's
|
|
1613
|
+
* operator stopped it" — one word with two subjects on two halves of one
|
|
1614
|
+
* exchange is a confusion nobody untangles from a log.
|
|
1615
|
+
*/
|
|
1616
|
+
awaitingConsent: z9.array(z9.string().min(1))
|
|
1213
1617
|
}).strict();
|
|
1214
|
-
var ResultDisposition =
|
|
1215
|
-
var ResultRequest =
|
|
1216
|
-
protocolVersion:
|
|
1217
|
-
runnerId:
|
|
1218
|
-
jobId:
|
|
1618
|
+
var ResultDisposition = z9.enum(["ok", "error", "canceled"]);
|
|
1619
|
+
var ResultRequest = z9.object({
|
|
1620
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1621
|
+
runnerId: z9.string().min(1),
|
|
1622
|
+
jobId: z9.string().min(1),
|
|
1623
|
+
/**
|
|
1624
|
+
* The grant this result was produced under — cloud_008 §1.4a.
|
|
1625
|
+
*
|
|
1626
|
+
* `fetch` has always named its lease, with the reasoning written beside
|
|
1627
|
+
* it: a request that names only the job would be answerable for whatever
|
|
1628
|
+
* lease exists when it arrives. **The operation that writes the result did
|
|
1629
|
+
* not**, on either plane, and checked only the runner id — which survives
|
|
1630
|
+
* a claim-release-reclaim cycle, so a device whose grant had been swept
|
|
1631
|
+
* and reissued could still land a result for a job it no longer held.
|
|
1632
|
+
*
|
|
1633
|
+
* Found by tracing a mutation that survived in §0.6: the lease lapsed, the
|
|
1634
|
+
* sweep requeued, the daemon re-claimed under a new grant, and the
|
|
1635
|
+
* original run finished and posted anyway. The relay marked the job done
|
|
1636
|
+
* with a result the site cannot open — it verifies the envelope against
|
|
1637
|
+
* the *current* holder's device, so the crypto contains the substitution —
|
|
1638
|
+
* and then refused the real holder's result as a replay. A lost job, in
|
|
1639
|
+
* silence.
|
|
1640
|
+
*
|
|
1641
|
+
* `LEASE_HONORED` is a statement about a lease *instance*. That was
|
|
1642
|
+
* learned once already, when a replayed release yanked a later grant, and
|
|
1643
|
+
* it applies here for the same reason.
|
|
1644
|
+
*/
|
|
1645
|
+
leaseId: z9.string().min(1),
|
|
1219
1646
|
/**
|
|
1220
1647
|
* The outcome, sealed to the site and signed by the device.
|
|
1221
1648
|
*
|
|
@@ -1231,26 +1658,48 @@ var ResultRequest = z8.object({
|
|
|
1231
1658
|
* fact: believing it unverified would let a daemon mark a job `ok` while
|
|
1232
1659
|
* sealing an error, and only the app would ever find out.
|
|
1233
1660
|
*/
|
|
1234
|
-
disposition: ResultDisposition
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1661
|
+
disposition: ResultDisposition
|
|
1662
|
+
// `model`, `backendClass` and `durationMs` are **inside the envelope** —
|
|
1663
|
+
// cloud_008 §2.5. See {@link RunMetadata}.
|
|
1664
|
+
//
|
|
1665
|
+
// They were here, in the clear, and that was two problems wearing one
|
|
1666
|
+
// coat. On the direct plane the site recorded unauthenticated fields
|
|
1667
|
+
// beside an authenticated answer: a daemon could seal one result and
|
|
1668
|
+
// declare a different model, and only the unsigned half would reach the
|
|
1669
|
+
// app. Through a relay they reached a third party that acts on none of
|
|
1670
|
+
// them — `model` in particular being the sort of detail Amendment A's
|
|
1671
|
+
// rule keeps off the wire.
|
|
1672
|
+
//
|
|
1673
|
+
// `disposition` stays, and the difference is the test: a relay *routes*
|
|
1674
|
+
// on it, so it is a class a routing party consumes. Nobody between the
|
|
1675
|
+
// two ends consumes these.
|
|
1240
1676
|
}).strict();
|
|
1241
|
-
var ResultResponse =
|
|
1677
|
+
var ResultResponse = z9.object({
|
|
1678
|
+
/**
|
|
1679
|
+
* False when this submission wrote nothing — the daemon should discard,
|
|
1680
|
+
* not retry ({@link MUSTS.RESULT_IDEMPOTENT}).
|
|
1681
|
+
*/
|
|
1682
|
+
accepted: z9.boolean(),
|
|
1242
1683
|
/**
|
|
1243
|
-
*
|
|
1244
|
-
*
|
|
1245
|
-
*
|
|
1684
|
+
* True when this device had already recorded this job's result.
|
|
1685
|
+
*
|
|
1686
|
+
* The difference between "already recorded" and "you no longer hold this"
|
|
1687
|
+
* — cloud_008 §3.6. A daemon whose acknowledgment was lost is in the first
|
|
1688
|
+
* case and needs to hear it: its answer is safely on disk. Reporting a
|
|
1689
|
+
* stale lease instead invents a worry about a result that is already
|
|
1690
|
+
* stored, and sends its owner looking for a routing problem.
|
|
1691
|
+
*
|
|
1692
|
+
* Set only for the device that finished the job. A different device gets
|
|
1693
|
+
* the same refusal it would get for a job that is *not* terminal, so a job
|
|
1694
|
+
* id cannot be used as a terminality probe.
|
|
1246
1695
|
*/
|
|
1247
|
-
|
|
1696
|
+
duplicate: z9.boolean().optional(),
|
|
1248
1697
|
/** The job's state after this submission. */
|
|
1249
|
-
state:
|
|
1698
|
+
state: z9.string().min(1)
|
|
1250
1699
|
}).strict();
|
|
1251
|
-
var ReleaseRequest =
|
|
1252
|
-
protocolVersion:
|
|
1253
|
-
runnerId:
|
|
1700
|
+
var ReleaseRequest = z9.object({
|
|
1701
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1702
|
+
runnerId: z9.string().min(1),
|
|
1254
1703
|
/**
|
|
1255
1704
|
* Which leases to release — the grant, not just the job.
|
|
1256
1705
|
*
|
|
@@ -1258,8 +1707,8 @@ var ReleaseRequest = z8.object({
|
|
|
1258
1707
|
* moment it arrives, which for a replayed request is not the lease the
|
|
1259
1708
|
* daemon meant. See {@link Lease.id}.
|
|
1260
1709
|
*/
|
|
1261
|
-
leases:
|
|
1262
|
-
|
|
1710
|
+
leases: z9.array(
|
|
1711
|
+
z9.object({ jobId: z9.string().min(1), leaseId: z9.string().min(1) })
|
|
1263
1712
|
),
|
|
1264
1713
|
/**
|
|
1265
1714
|
* Why, so the app's runner list can say something true.
|
|
@@ -1270,39 +1719,152 @@ var ReleaseRequest = z8.object({
|
|
|
1270
1719
|
* stop offering that job to that runner, or the pair would spin between
|
|
1271
1720
|
* claim and release forever.
|
|
1272
1721
|
*/
|
|
1273
|
-
reason:
|
|
1722
|
+
reason: z9.enum(["shutdown", "pause", "revoked", "backend-down", "refused"])
|
|
1274
1723
|
}).strict();
|
|
1275
|
-
var ReleaseResponse =
|
|
1276
|
-
released:
|
|
1724
|
+
var ReleaseResponse = z9.object({
|
|
1725
|
+
released: z9.array(z9.string().min(1))
|
|
1277
1726
|
}).strict();
|
|
1278
|
-
var WireErrorCode =
|
|
1727
|
+
var WireErrorCode = z9.enum([
|
|
1279
1728
|
"bad-request",
|
|
1280
1729
|
"unsupported-protocol-version",
|
|
1730
|
+
// "We do not know who you are." Exactly 401, and only that — cloud_008
|
|
1731
|
+
// §1.4d.
|
|
1281
1732
|
"unauthorized",
|
|
1733
|
+
/**
|
|
1734
|
+
* "We know exactly who you are, and the answer is no." Exactly 403.
|
|
1735
|
+
*
|
|
1736
|
+
* Five refusals across both planes served 403 with `unauthorized`, whose
|
|
1737
|
+
* table entry is 401: a revoked device, a site claiming another site's
|
|
1738
|
+
* stub, a job you do not hold, a device belonging to another owner, a
|
|
1739
|
+
* relay that does not route for you. Every one of them is an *identified*
|
|
1740
|
+
* caller being refused.
|
|
1741
|
+
*
|
|
1742
|
+
* Collapsing the two loses a distinction that matters everywhere it is
|
|
1743
|
+
* read: a revoked daemon would look like an unsigned one in every log and
|
|
1744
|
+
* every client branch, and "check your keys" is the wrong advice for both
|
|
1745
|
+
* of them in opposite directions.
|
|
1746
|
+
*/
|
|
1747
|
+
"forbidden",
|
|
1282
1748
|
"revoked",
|
|
1283
1749
|
"not-found",
|
|
1750
|
+
// Claimed, but the site has not sealed the payload yet — cloud_008 §1.4.
|
|
1751
|
+
//
|
|
1752
|
+
// A daemon must retry rather than abandon: the job is legitimately still
|
|
1753
|
+
// its own until the lease or the awaiting-payload clock says otherwise.
|
|
1754
|
+
// That is why it cannot be `not-found` or `server-error`, and why it was
|
|
1755
|
+
// the protocol gap that produced a bare 409 in the first place.
|
|
1756
|
+
"not-ready",
|
|
1757
|
+
/**
|
|
1758
|
+
* The job is over, and this call is about a job — V1-6, and the code the
|
|
1759
|
+
* site plane has been serving without one (V1-13).
|
|
1760
|
+
*
|
|
1761
|
+
* Distinct from `not-found`, which says "no such job", and from
|
|
1762
|
+
* `not-ready`, which says "not yet, keep asking". This one says "yes, and
|
|
1763
|
+
* it finished" — so a daemon must stop rather than retry, and a replayed
|
|
1764
|
+
* request must not be able to reopen it.
|
|
1765
|
+
*/
|
|
1766
|
+
"too-late",
|
|
1767
|
+
// The caller's clock is too far from ours to judge a signature's freshness.
|
|
1768
|
+
//
|
|
1769
|
+
// Split out from `unauthorized` because the remedy is completely different
|
|
1770
|
+
// and only the server can tell them apart: a bad signature means the key is
|
|
1771
|
+
// wrong, this means the machine's time is wrong. A daemon reporting it as a
|
|
1772
|
+
// generic rejection sends its owner looking at their network.
|
|
1773
|
+
"clock-skew",
|
|
1284
1774
|
"rate-limited",
|
|
1285
1775
|
"server-error"
|
|
1286
1776
|
]);
|
|
1287
|
-
var WireError =
|
|
1777
|
+
var WireError = z9.object({
|
|
1288
1778
|
error: WireErrorCode,
|
|
1289
|
-
message:
|
|
1779
|
+
message: z9.string().min(1),
|
|
1780
|
+
/**
|
|
1781
|
+
* What this server speaks, on `unsupported-protocol-version` — §B.4.
|
|
1782
|
+
*
|
|
1783
|
+
* The refusal has carried these since the version handshake existed and
|
|
1784
|
+
* the enumeration did not model them, so the one error that exists to be
|
|
1785
|
+
* *acted on* was the one that failed to parse as a wire error. Found by
|
|
1786
|
+
* the relay's own suite the day the relay started sending it: a refusal
|
|
1787
|
+
* outside the enumerated shape is a refusal a client cannot branch on,
|
|
1788
|
+
* which is the whole reason §1.4 enumerates them.
|
|
1789
|
+
*
|
|
1790
|
+
* Modelled the way `clock-skew`'s two fields already are — code-specific
|
|
1791
|
+
* extras, refused on any other code by the refinement below.
|
|
1792
|
+
*/
|
|
1793
|
+
supported: z9.array(z9.string().min(1)).optional(),
|
|
1794
|
+
minimum: z9.string().min(1).optional(),
|
|
1290
1795
|
/** Seconds; mirrors Retry-After for `rate-limited` and `server-error`. */
|
|
1291
|
-
retryAfter:
|
|
1292
|
-
|
|
1796
|
+
retryAfter: z9.number().int().nonnegative().optional(),
|
|
1797
|
+
/**
|
|
1798
|
+
* The server's clock, and the window it allows. `clock-skew` only.
|
|
1799
|
+
*
|
|
1800
|
+
* So the far side can say *how far off* rather than *that something is
|
|
1801
|
+
* wrong* — the difference between "adjust your clock by four minutes" and
|
|
1802
|
+
* "something is wrong with your connection". Not a disclosure: the
|
|
1803
|
+
* heartbeat response returns the same value, and so does every `Date`
|
|
1804
|
+
* header.
|
|
1805
|
+
*/
|
|
1806
|
+
serverTime: z9.number().int().positive().optional(),
|
|
1807
|
+
maxSkewMs: z9.number().int().positive().optional()
|
|
1808
|
+
}).strict().superRefine((error, ctx) => {
|
|
1809
|
+
const skew = error.error === "clock-skew";
|
|
1810
|
+
const carried = error.serverTime !== void 0 || error.maxSkewMs !== void 0;
|
|
1811
|
+
if (skew && !carried) {
|
|
1812
|
+
ctx.addIssue({
|
|
1813
|
+
code: "custom",
|
|
1814
|
+
message: "clock-skew must carry serverTime and maxSkewMs"
|
|
1815
|
+
});
|
|
1816
|
+
}
|
|
1817
|
+
if (!skew && carried) {
|
|
1818
|
+
ctx.addIssue({
|
|
1819
|
+
code: "custom",
|
|
1820
|
+
message: `${error.error} must not carry serverTime or maxSkewMs`
|
|
1821
|
+
});
|
|
1822
|
+
}
|
|
1823
|
+
const version = error.error === "unsupported-protocol-version";
|
|
1824
|
+
const versionFields = error.supported !== void 0 || error.minimum !== void 0;
|
|
1825
|
+
if (version && !versionFields) {
|
|
1826
|
+
ctx.addIssue({
|
|
1827
|
+
code: "custom",
|
|
1828
|
+
message: "unsupported-protocol-version must carry supported and minimum"
|
|
1829
|
+
});
|
|
1830
|
+
}
|
|
1831
|
+
if (!version && versionFields) {
|
|
1832
|
+
ctx.addIssue({
|
|
1833
|
+
code: "custom",
|
|
1834
|
+
message: `${error.error} must not carry supported or minimum`
|
|
1835
|
+
});
|
|
1836
|
+
}
|
|
1837
|
+
});
|
|
1293
1838
|
var ERROR_STATUS = Object.freeze({
|
|
1294
1839
|
"bad-request": 400,
|
|
1295
1840
|
"unsupported-protocol-version": 400,
|
|
1296
1841
|
unauthorized: 401,
|
|
1842
|
+
forbidden: 403,
|
|
1297
1843
|
revoked: 403,
|
|
1298
1844
|
"not-found": 404,
|
|
1845
|
+
// 409, not 404: the job exists and is yours, it is simply not ready.
|
|
1846
|
+
"not-ready": 409,
|
|
1847
|
+
// The same 409 as `not-ready` and the opposite instruction: that one says
|
|
1848
|
+
// keep asking, this one says stop. The status is the class of the
|
|
1849
|
+
// problem — a request that does not fit the resource's state — and the
|
|
1850
|
+
// code is what a caller acts on.
|
|
1851
|
+
"too-late": 409,
|
|
1852
|
+
// 401 alongside `unauthorized`, because that is what it is — the
|
|
1853
|
+
// signature could not be judged. The code is what carries the remedy.
|
|
1854
|
+
"clock-skew": 401,
|
|
1299
1855
|
"rate-limited": 429,
|
|
1300
1856
|
"server-error": 500
|
|
1301
1857
|
});
|
|
1302
|
-
var FetchRequest =
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1858
|
+
var FetchRequest = z9.object({
|
|
1859
|
+
// `literal`, like every other request — V1-17. This one said
|
|
1860
|
+
// `string().min(1)`, so a daemon speaking a version this server does not
|
|
1861
|
+
// know got past the handshake on the one endpoint that hands over a
|
|
1862
|
+
// sealed payload. The version check exists so that a mismatch is a named
|
|
1863
|
+
// refusal rather than a schema failure three fields later; here it was
|
|
1864
|
+
// neither.
|
|
1865
|
+
protocolVersion: z9.literal(PROTOCOL_VERSION),
|
|
1866
|
+
runnerId: z9.string().min(1),
|
|
1867
|
+
jobId: z9.string().min(1),
|
|
1306
1868
|
/**
|
|
1307
1869
|
* The grant this daemon holds.
|
|
1308
1870
|
*
|
|
@@ -1310,9 +1872,9 @@ var FetchRequest = z8.object({
|
|
|
1310
1872
|
* only the job would be answerable for whatever lease exists when it
|
|
1311
1873
|
* arrives ({@link Lease.id}).
|
|
1312
1874
|
*/
|
|
1313
|
-
leaseId:
|
|
1875
|
+
leaseId: z9.string().min(1)
|
|
1314
1876
|
}).strict();
|
|
1315
|
-
var FetchResponse =
|
|
1877
|
+
var FetchResponse = z9.object({
|
|
1316
1878
|
/**
|
|
1317
1879
|
* The work, sealed to the device that claimed it — byollm_009 §6.
|
|
1318
1880
|
*
|
|
@@ -1340,6 +1902,7 @@ export {
|
|
|
1340
1902
|
ClaimedJob,
|
|
1341
1903
|
ClaimedStub,
|
|
1342
1904
|
DeliveredResult,
|
|
1905
|
+
ENCRYPTION_KEY_CONTEXT,
|
|
1343
1906
|
ENDPOINTS,
|
|
1344
1907
|
ENVELOPE_MAX_AGE_MS,
|
|
1345
1908
|
ERROR_STATUS,
|
|
@@ -1361,6 +1924,7 @@ export {
|
|
|
1361
1924
|
KindedPayload,
|
|
1362
1925
|
Lease,
|
|
1363
1926
|
MAX_CLOCK_SKEW_MS,
|
|
1927
|
+
MAX_SUCCESSION_CHAIN,
|
|
1364
1928
|
MIN_PROTOCOL_VERSION,
|
|
1365
1929
|
MUSTS,
|
|
1366
1930
|
MUST_IDS,
|
|
@@ -1377,6 +1941,7 @@ export {
|
|
|
1377
1941
|
PairStartResponse,
|
|
1378
1942
|
PublicIdentity,
|
|
1379
1943
|
REFUSAL_MESSAGES,
|
|
1944
|
+
RETIREMENT_WINDOW_MS,
|
|
1380
1945
|
ReleaseRequest,
|
|
1381
1946
|
ReleaseResponse,
|
|
1382
1947
|
RequestSignature,
|
|
@@ -1384,11 +1949,15 @@ export {
|
|
|
1384
1949
|
ResultProvenance,
|
|
1385
1950
|
ResultRequest,
|
|
1386
1951
|
ResultResponse,
|
|
1952
|
+
RunMetadata,
|
|
1387
1953
|
SIZE_CLASS_LIMITS,
|
|
1954
|
+
SUCCESSION_CONTEXT,
|
|
1388
1955
|
SUPPORTED_PROTOCOL_VERSIONS,
|
|
1389
1956
|
SealedEnvelope,
|
|
1957
|
+
SealedOutcome,
|
|
1390
1958
|
SizeClass,
|
|
1391
1959
|
StoredKeys,
|
|
1960
|
+
Succession,
|
|
1392
1961
|
TERMINAL_STATES,
|
|
1393
1962
|
WireError,
|
|
1394
1963
|
WireErrorCode,
|
|
@@ -1397,6 +1966,7 @@ export {
|
|
|
1397
1966
|
canonicalRequest,
|
|
1398
1967
|
checkProtocolVersion,
|
|
1399
1968
|
cryptoReady,
|
|
1969
|
+
declaredVersion,
|
|
1400
1970
|
effectiveOfferScope,
|
|
1401
1971
|
fingerprint,
|
|
1402
1972
|
generateKeys,
|
|
@@ -1405,6 +1975,7 @@ export {
|
|
|
1405
1975
|
isLocalHost,
|
|
1406
1976
|
isTerminal,
|
|
1407
1977
|
keyId,
|
|
1978
|
+
kindsOf,
|
|
1408
1979
|
matchAudience,
|
|
1409
1980
|
mustsVerifiedBy,
|
|
1410
1981
|
open,
|
|
@@ -1414,11 +1985,17 @@ export {
|
|
|
1414
1985
|
resolveCost,
|
|
1415
1986
|
seal,
|
|
1416
1987
|
signRequest,
|
|
1988
|
+
signSiteRequest,
|
|
1989
|
+
signSuccession,
|
|
1417
1990
|
signWith,
|
|
1418
1991
|
sizeClassCeiling,
|
|
1419
1992
|
sizeClassOf,
|
|
1993
|
+
successionStatement,
|
|
1994
|
+
verifyLink,
|
|
1420
1995
|
verifyPublicIdentity,
|
|
1421
1996
|
verifyRequest,
|
|
1422
|
-
|
|
1997
|
+
verifySiteRequest,
|
|
1998
|
+
verifyWith,
|
|
1999
|
+
walkSuccession
|
|
1423
2000
|
};
|
|
1424
2001
|
//# sourceMappingURL=index.js.map
|