@byollm/protocol 0.1.0-alpha.93 → 0.1.0-alpha.94

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.93`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.94`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/protocol@alpha`.
 >

package/dist/index.d.ts

@@ -3195,4 +3195,70 @@ interface ConsoleOrder {
 }
 declare function consoleOrder(from: "browser" | "box"): ConsoleOrder;
 
-export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, CONSOLE_FRAME_VERSION, CONSOLE_MAX_DATA_BYTES, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, ConsoleBye, ConsoleFrame, ConsoleHello, type ConsoleOrder, type ConsoleOrderFault, type ConsoleOrderResult, ConsoleResize, ConsoleStdin, ConsoleStdout, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, type FloorRefusal, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, REFUSAL_TEXT, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, type StopReason, StopReasonSchema, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, UPDATE_OFFER_SINCE, UPGRADE_COMMAND, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkDaemonFloor, checkProtocolVersion, classifyCost, compareVersions, consoleEnvelope, consoleOrder, cryptoReady, declaredVersion, describeBytes, effectiveOfferScope, envelopeBytes, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mayOfferUpdate, mentionsWireField, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, tooLargeMessage, updateOfferFor, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession, withoutComments };
+/**
+ * The envelope's FORMAT, with no primitives and no platform — B018c step 3.
+ *
+ * ## Why this file exists
+ *
+ * The browser is one of the two ends a console stream is encrypted between,
+ * and it cannot run `envelope.ts`: the sealing is WASM and portable, but the
+ * inner signature goes through `node:crypto`'s Ed25519. So the browser needs
+ * its own primitives.
+ *
+ * What it must NOT have is its own *format*. Two implementations of "which
+ * bytes get signed" is the defect class this codebase spends most of its
+ * checks on, and here the two copies would diverge silently — a mismatched
+ * signature is indistinguishable from an attack, so the first symptom would
+ * be a console that refuses to open and a log line saying `bad-signature`.
+ *
+ * Everything here is therefore pure: no `node:` imports, no `Buffer`, no
+ * `btoa`. `envelope-is-portable.test.ts` asserts that mechanically, because
+ * "somebody will import Buffer for convenience one day" is a prediction, and
+ * this project's rule is that a prediction ships with the test that catches it.
+ *
+ * ## Why base64url is written out by hand
+ *
+ * `Buffer` is Node's and `btoa` takes a binary string, so neither is both
+ * portable and pleasant. Twenty lines of table lookup is: it agrees with
+ * `Buffer` on every byte value, which the test proves rather than assumes.
+ */
+/** Unpadded base64url, the encoding every key and signature on this wire uses. */
+declare function toBase64Url(bytes: Uint8Array): string;
+/** The inverse. Returns undefined rather than throwing — this parses input. */
+declare function fromBase64Url(text: string): Uint8Array | undefined;
+/** Domain tag for the bytes an envelope's signature covers. */
+declare const ENVELOPE_BODY_VERSION = "byollm/v1/envelope";
+/** What an envelope's signature is over — the fields, in this order. */
+interface EnvelopeBodyContext {
+    readonly jobId: string;
+    readonly senderKeyId: string;
+    readonly recipientKeyId: string;
+    readonly deadlineAt: number;
+    readonly direction: string;
+}
+/**
+ * The exact bytes an envelope's signature covers.
+ *
+ * **Field order is part of the format**, because `JSON.stringify` emits keys
+ * in insertion order and the verifier hashes bytes, not meaning. Reordering
+ * these lines is a wire change that no type would catch and every signature
+ * would fail — which is why they are written out rather than spread from an
+ * object somebody could reshape.
+ */
+declare function envelopeSignedBody(context: EnvelopeBodyContext, plaintext: string): Uint8Array;
+/** The signed body and its signature, as they travel inside the sealed box. */
+declare function encodeEnvelopeInner(body: Uint8Array, signature: string): string;
+interface EnvelopeInner {
+    readonly body: Uint8Array;
+    readonly signature: string;
+}
+/**
+ * Read the inner object back.
+ *
+ * Returns undefined for anything malformed rather than throwing, because
+ * every byte reaching this has come out of a decryption and is therefore
+ * input — `malformed` is one of the outcomes `open()` already distinguishes.
+ */
+declare function decodeEnvelopeInner(text: string): EnvelopeInner | undefined;
+
+export { ABOUT, ABOUT_SHORT, ABOUT_SHORT_LEDE, ABOUT_SHORT_TAIL, AUDIENCES, Audience, BACKENDS, BACKEND_CLASSES, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, CONSOLE_FRAME_VERSION, CONSOLE_MAX_DATA_BYTES, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, ConsoleBye, ConsoleFrame, ConsoleHello, type ConsoleOrder, type ConsoleOrderFault, type ConsoleOrderResult, ConsoleResize, ConsoleStdin, ConsoleStdout, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_BODY_VERSION, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeBodyContext, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, type EnvelopeInner, FetchRequest, FetchResponse, type FloorRefusal, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_ENVELOPE_BYTES, MAX_PURPOSES, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, REFUSAL_TEXT, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASSES, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, type StopReason, StopReasonSchema, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, UPDATE_OFFER_SINCE, UPGRADE_COMMAND, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkDaemonFloor, checkProtocolVersion, classifyCost, compareVersions, consoleEnvelope, consoleOrder, cryptoReady, declaredVersion, decodeEnvelopeInner, describeBytes, effectiveOfferScope, encodeEnvelopeInner, envelopeBytes, envelopeSignedBody, fingerprint, fromBase64Url, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mayOfferUpdate, mentionsWireField, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, toBase64Url, tooLargeMessage, updateOfferFor, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession, withoutComments };

package/dist/index.js

@@ -1163,6 +1163,85 @@ var ClaimedStub = JobStub.extend({
 import { createPrivateKey as createPrivateKey2, createPublicKey as createPublicKey2 } from "crypto";
 import sodium from "libsodium-wrappers";
 import { z as z8 } from "zod";
+
+// src/envelope-format.ts
+var ALPHABET2 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var CHARS = ALPHABET2.split("");
+var VALUES = /* @__PURE__ */ (() => {
+  const table = new Uint8Array(128).fill(255);
+  for (let at = 0; at < ALPHABET2.length; at += 1) {
+    table[ALPHABET2.charCodeAt(at)] = at;
+  }
+  return table;
+})();
+function toBase64Url(bytes) {
+  let out = "";
+  for (let at = 0; at < bytes.length; at += 3) {
+    const a = bytes[at] ?? 0;
+    const b = bytes[at + 1];
+    const c = bytes[at + 2];
+    const word = a << 16 | (b ?? 0) << 8 | (c ?? 0);
+    out += CHARS[word >> 18 & 63] ?? "";
+    out += CHARS[word >> 12 & 63] ?? "";
+    if (b !== void 0) out += CHARS[word >> 6 & 63] ?? "";
+    if (c !== void 0) out += CHARS[word & 63] ?? "";
+  }
+  return out;
+}
+function fromBase64Url(text) {
+  const length = text.length;
+  if (length % 4 === 1) return void 0;
+  const bytes = new Uint8Array(Math.floor(length * 3 / 4));
+  let written = 0;
+  let word = 0;
+  let bits = 0;
+  for (let at = 0; at < length; at += 1) {
+    const code = text.charCodeAt(at);
+    const value = code < 128 ? VALUES[code] : 255;
+    if (value === void 0 || value === 255) return void 0;
+    word = word << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[written] = word >> bits & 255;
+      written += 1;
+    }
+  }
+  return bytes.subarray(0, written);
+}
+var ENVELOPE_BODY_VERSION = "byollm/v1/envelope";
+function envelopeSignedBody(context, plaintext) {
+  return new TextEncoder().encode(
+    JSON.stringify({
+      v: ENVELOPE_BODY_VERSION,
+      jobId: context.jobId,
+      senderKeyId: context.senderKeyId,
+      recipientKeyId: context.recipientKeyId,
+      deadlineAt: context.deadlineAt,
+      direction: context.direction,
+      plaintext
+    })
+  );
+}
+function encodeEnvelopeInner(body, signature) {
+  return JSON.stringify({ body: toBase64Url(body), signature });
+}
+function decodeEnvelopeInner(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed.body !== "string" || typeof parsed.signature !== "string") {
+    return void 0;
+  }
+  const body = fromBase64Url(parsed.body);
+  if (body === void 0) return void 0;
+  return { body, signature: parsed.signature };
+}
+
+// src/envelope.ts
 var readied;
 async function cryptoReady() {
   readied ??= sodium.ready;
@@ -1192,20 +1271,7 @@ var SealedEnvelope = z8.object({
    */
   deadlineAt: z8.number().int().positive()
 }).strict();
-function signedBody(context, plaintext) {
-  return Buffer.from(
-    JSON.stringify({
-      v: "byollm/v1/envelope",
-      jobId: context.jobId,
-      senderKeyId: context.senderKeyId,
-      recipientKeyId: context.recipientKeyId,
-      deadlineAt: context.deadlineAt,
-      direction: context.direction,
-      plaintext
-    }),
-    "utf8"
-  );
-}
+var signedBody = (context, plaintext) => envelopeSignedBody(context, plaintext);
 var rawX25519 = (key, part) => {
   const jwk = key.export({ format: "jwk" });
   const value = part === "x" ? jwk.x : jwk.d;
@@ -1216,7 +1282,7 @@ async function seal(input) {
   await cryptoReady();
   const body = signedBody(input.context, input.plaintext);
   const signature = signWith(input.senderKeys, body);
-  const inner = JSON.stringify({ body: body.toString("base64url"), signature });
+  const inner = encodeEnvelopeInner(body, signature);
   const recipient = new Uint8Array(
     Buffer.from(input.recipientEncryptionPublic, "base64url")
   );
@@ -1255,22 +1321,15 @@ async function open(input) {
   } catch {
     return { ok: false, reason: "unopenable" };
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(inner);
-  } catch {
-    return { ok: false, reason: "malformed" };
-  }
-  if (typeof parsed.body !== "string" || typeof parsed.signature !== "string") {
-    return { ok: false, reason: "malformed" };
-  }
-  const body = Buffer.from(parsed.body, "base64url");
+  const parsed = decodeEnvelopeInner(inner);
+  if (parsed === void 0) return { ok: false, reason: "malformed" };
+  const body = parsed.body;
   if (!verifyWith(input.senderIdentityPublic, body, parsed.signature)) {
     return { ok: false, reason: "bad-signature" };
   }
   let claims;
   try {
-    claims = JSON.parse(body.toString("utf8"));
+    claims = JSON.parse(new TextDecoder().decode(body));
   } catch {
     return { ok: false, reason: "malformed" };
   }
@@ -2809,6 +2868,7 @@ export {
   DeliveredResult,
   ENCRYPTION_KEY_CONTEXT,
   ENDPOINTS,
+  ENVELOPE_BODY_VERSION,
   ENVELOPE_MAX_AGE_MS,
   ERROR_STATUS,
   EnvelopeDirection,
@@ -2896,10 +2956,14 @@ export {
   consoleOrder,
   cryptoReady,
   declaredVersion,
+  decodeEnvelopeInner,
   describeBytes,
   effectiveOfferScope,
+  encodeEnvelopeInner,
   envelopeBytes,
+  envelopeSignedBody,
   fingerprint,
+  fromBase64Url,
   generateKeys,
   grantStatement,
   isBackendId,
@@ -2928,6 +2992,7 @@ export {
   sizeClassCeiling,
   sizeClassOf,
   successionStatement,
+  toBase64Url,
   tooLargeMessage,
   updateOfferFor,
   verifyGrant,