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

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.92`) — 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

@@ -2972,4 +2972,293 @@ declare const MUST_IDS: readonly ("PAIR_ONE_USER" | "PAIR_INTERACTIVE" | "PAIR_C
 /** Every MUST verified a particular way. */
 declare function mustsVerifiedBy(kind: MustVerification): MustId[];
 
-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, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, 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, 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 terminal stream a hosted box's console runs over — byollm_018 §"Console
+ * redesign: brokered E2E replaces SSH-first (RULED, Todd 2026-09-03)".
+ *
+ * The ruling's item 3 is the whole reason this file exists: *"The terminal
+ * stream is E2E encrypted browser↔agent with the sealed-channel pattern jobs
+ * use; the hub routes ciphertext."* So the bytes are carried by
+ * {@link seal}/{@link open} exactly as a job's payload is, and what is defined
+ * here is the thing a sealed envelope does not carry: **what a frame means,
+ * and where it sits in the stream.**
+ *
+ * ## Why an ordering rule is protocol and not an implementation detail
+ *
+ * Sealing makes the hub unable to READ the stream. It does nothing to make
+ * the hub unable to reshape it. A router that holds ciphertext can drop a
+ * frame, deliver two out of order, or send the same frame twice, and every
+ * envelope still opens, still verifies against the pinned identity, and still
+ * looks perfect to the receiver — because each envelope is authenticated on
+ * its own and says nothing about the ones around it.
+ *
+ * On a terminal that is not a theoretical loss of tidiness. A dropped
+ * keystroke is a different command; two frames swapped is a different command;
+ * a replayed frame is a command run twice. The console carries vendor
+ * sign-in flows (byollm_018 item 5), so "a different command" can mean an auth
+ * code going somewhere it was not typed.
+ *
+ * Hence {@link consoleOrder}: a sequence inside the ciphertext, checked by
+ * both ends. Inside, because a counter the hub could see is a counter the hub
+ * could rewrite.
+ *
+ * ## One definition, both ends, and there are three ends
+ *
+ * The browser, the box's agent, and the hub broker all handle these frames,
+ * and the first two must agree byte for byte or the stream silently corrupts.
+ * The hub must NOT be able to agree — it only ever sees the sealed envelope.
+ * This module is the single definition the two real ends share; neither
+ * retypes it.
+ *
+ * ## The pinned box key is the PAIRING key (CCB's call, 09-16)
+ *
+ * The ruling says "box key pinned at first session", and the backlog left one
+ * delta open: whether the identity the owner already approved at pairing can
+ * serve as that pinned key. It can, and it should, for three reasons.
+ *
+ * 1. **The pairing key is the only one a human ever chose.** `PairStartRequest`
+ *    carries the device's {@link PublicIdentity} and says why: *"Pairing is
+ *    where the two parties learn each other's identities, because it is the
+ *    one moment a human is already deciding to trust: the approval click. A
+ *    key exchanged anywhere else would be a key nobody chose."* A fresh
+ *    trust-on-first-use pin at the first console session is precisely a key
+ *    nobody chose — it trusts whoever answers first, which on a brokered
+ *    channel is whoever the broker points at.
+ * 2. **Two pins of one box can disagree, and silently.** A console pin
+ *    separate from the pairing pin is a second record of the same fact, which
+ *    is this project's most-repeated defect. When they diverge, nothing reads
+ *    both, so nothing notices.
+ * 3. **Alarm-on-change comes free from the split already in `keys.ts`.** The
+ *    Ed25519 identity is the pinned half and the X25519 encryption key is
+ *    signed by it, so {@link verifyPublicIdentity} lets the box rotate its
+ *    encryption key without a new ceremony while an IDENTITY change fails to
+ *    verify and alarms — which is what the ruling asks for, and it is already
+ *    written.
+ *
+ * **What this does not claim.** Pinning the pairing key does not make the hub
+ * unable to lie about which key that was; the hub is the one telling the
+ * browser. The ruling is explicit that we build the operator-ACCOUNTABLE
+ * version, not the operator-incapable one, and item 4's session feed is where
+ * that accountability is paid. What the pin buys is that a CHANGE is
+ * detectable, and that the key being pinned is one an owner approved rather
+ * than one a broker supplied.
+ */
+/** Domain tag for the plaintext inside a console envelope. */
+declare const CONSOLE_FRAME_VERSION = "byollm/v1/console";
+/**
+ * The largest `data` payload one frame may carry, before base64.
+ *
+ * Far below {@link MAX_ENVELOPE_BYTES}, and deliberately: an envelope cap
+ * stops a memory attack, while this stops a latency one. A console is
+ * interactive, so a peer that batches a megabyte into one frame has made the
+ * stream unusable without ever exceeding a limit.
+ */
+declare const CONSOLE_MAX_DATA_BYTES: number;
+declare const ConsoleHello: z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"hello">;
+    seq: z.ZodLiteral<1>;
+    browser: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>;
+type ConsoleHello = z.infer<typeof ConsoleHello>;
+/**
+ * Two schemas rather than one with a `kind: z.enum([...])`, because the union
+ * below discriminates on `kind` and a discriminator that is itself a set is
+ * how a union quietly stops discriminating.
+ */
+declare const ConsoleStdin: z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"stdin">;
+    seq: z.ZodNumber;
+    data: z.ZodString;
+}, z.core.$strict>;
+type ConsoleStdin = z.infer<typeof ConsoleStdin>;
+declare const ConsoleStdout: z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"stdout">;
+    seq: z.ZodNumber;
+    data: z.ZodString;
+}, z.core.$strict>;
+type ConsoleStdout = z.infer<typeof ConsoleStdout>;
+declare const ConsoleResize: z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"resize">;
+    seq: z.ZodNumber;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>;
+type ConsoleResize = z.infer<typeof ConsoleResize>;
+declare const ConsoleBye: z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"bye">;
+    seq: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>;
+type ConsoleBye = z.infer<typeof ConsoleBye>;
+declare const ConsoleFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"hello">;
+    seq: z.ZodLiteral<1>;
+    browser: z.ZodObject<{
+        identity: z.ZodString;
+        encryption: z.ZodString;
+        encryptionSig: z.ZodString;
+    }, z.core.$strict>;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"stdin">;
+    seq: z.ZodNumber;
+    data: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"stdout">;
+    seq: z.ZodNumber;
+    data: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"resize">;
+    seq: z.ZodNumber;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    v: z.ZodLiteral<"byollm/v1/console">;
+    kind: z.ZodLiteral<"bye">;
+    seq: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>], "kind">;
+type ConsoleFrame = z.infer<typeof ConsoleFrame>;
+/**
+ * The envelope context for a console frame.
+ *
+ * Exported so that neither end computes it: the session id goes in `jobId`
+ * and the direction is derived, and if the two ends disagreed about either,
+ * every envelope would fail to open with `not-for-us` — a failure that looks
+ * exactly like an attack.
+ */
+declare function consoleEnvelope(input: {
+    sessionId: string;
+    from: "browser" | "box";
+    senderKeyId: string;
+    recipientKeyId: string;
+    deadlineAt: number;
+}): EnvelopeContext;
+/** Why a frame was refused. Each one is a distinct thing a router can do. */
+type ConsoleOrderFault = 
+/** Seq went backwards or repeated — the router sent it twice. */
+"replayed"
+/** Seq skipped — the router dropped what was between. */
+ | "gap"
+/** A `hello` that was not the first frame, or a first frame that was not `hello`. */
+ | "out-of-turn"
+/** A `stdin` from the box, or a `stdout` from the browser. */
+ | "wrong-way"
+/** Anything after `bye`. The stream is over. */
+ | "closed";
+type ConsoleOrderResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly fault: ConsoleOrderFault;
+};
+/**
+ * One direction's ordering rule, which both ends run over what they receive.
+ *
+ * **Strictly +1, not merely increasing.** Increasing would catch replay and
+ * reorder while letting a DROP through silently, and a dropped frame on a
+ * terminal is a truncated command that still runs. There is no benign gap
+ * here to tolerate: the transport underneath is an ordered, reliable stream,
+ * so a gap means something between the ends removed a frame.
+ *
+ * Every fault is fatal to the session by design. A console has no
+ * resynchronisation story that is safe — you cannot ask "what did I miss" of
+ * a party that may be the one who took it.
+ */
+/**
+ * One direction's receiver-side ordering state.
+ *
+ * Named as an interface rather than inferred, so the box's agent and the
+ * browser hold the SAME type — an inferred one would let the two ends drift
+ * apart without a compiler ever objecting.
+ */
+interface ConsoleOrder {
+    /** The last sequence accepted. 0 before anything has been. */
+    readonly seen: number;
+    accept(frame: ConsoleFrame): ConsoleOrderResult;
+}
+declare function consoleOrder(from: "browser" | "box"): ConsoleOrder;
+
+/**
+ * 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

@@ -89,16 +89,16 @@ function verifyPublicIdentity(identity) {
     return false;
   }
 }
-function signWith(keys, data) {
-  return sign(null, data, importPrivate(keys.identityPrivate)).toString(
+function signWith(keys, data2) {
+  return sign(null, data2, importPrivate(keys.identityPrivate)).toString(
     "base64url"
   );
 }
-function verifyWith(identityPublic, data, signature) {
+function verifyWith(identityPublic, data2, signature) {
   try {
     return verify(
       null,
-      data,
+      data2,
       importPublic(identityPublic, "Ed25519"),
       Buffer.from(signature, "base64url")
     );
@@ -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" };
   }
@@ -2663,6 +2722,118 @@ var MUST_IDS = Object.freeze(Object.keys(MUSTS));
 function mustsVerifiedBy(kind) {
   return MUST_IDS.filter((id) => kindsOf(MUSTS[id]).includes(kind));
 }
+
+// src/console.ts
+import { z as z12 } from "zod";
+var CONSOLE_FRAME_VERSION = "byollm/v1/console";
+var CONSOLE_MAX_DATA_BYTES = 64 * 1024;
+var data = z12.string().max(Math.ceil(CONSOLE_MAX_DATA_BYTES * 4 / 3) + 4).describe("base64");
+var cols = z12.number().int().min(1).max(1e4);
+var rows = z12.number().int().min(1).max(1e4);
+var seq = z12.number().int().positive();
+var ConsoleHello = z12.object({
+  v: z12.literal(CONSOLE_FRAME_VERSION),
+  kind: z12.literal("hello"),
+  seq: z12.literal(1),
+  /**
+   * The browser's EPHEMERAL identity for this session, and the reason hello
+   * exists as its own frame.
+   *
+   * A browser has no long-term key — it is a tab, not a machine — so it
+   * generates one per session and the box seals its output to it. That key
+   * has to reach the box without the hub being able to substitute one of its
+   * own, which is the classic broker attack. So it travels SEALED TO THE
+   * BOX'S PINNED IDENTITY like every other frame: the hub cannot read it and
+   * cannot replace it, because replacing it means producing a sealed box
+   * the box's key opens and the browser's key signed.
+   *
+   * The box does not pin this. It cannot — it is new every session, and
+   * nothing authorises it cryptographically. What authorises the browser is
+   * the hub's per-session grant (ruling item 2); what this key does is keep
+   * the hub from READING what it authorised.
+   */
+  browser: PublicIdentity,
+  cols,
+  rows
+}).strict();
+var ConsoleStdin = z12.object({
+  v: z12.literal(CONSOLE_FRAME_VERSION),
+  /** Browser→box only. A `stdin` arriving from the box is `wrong-way`. */
+  kind: z12.literal("stdin"),
+  seq,
+  data
+}).strict();
+var ConsoleStdout = z12.object({
+  v: z12.literal(CONSOLE_FRAME_VERSION),
+  /** Box→browser only. */
+  kind: z12.literal("stdout"),
+  seq,
+  data
+}).strict();
+var ConsoleResize = z12.object({
+  v: z12.literal(CONSOLE_FRAME_VERSION),
+  kind: z12.literal("resize"),
+  seq,
+  cols,
+  rows
+}).strict();
+var ConsoleBye = z12.object({
+  v: z12.literal(CONSOLE_FRAME_VERSION),
+  kind: z12.literal("bye"),
+  seq,
+  /** Shown to the owner in the session feed, so it is a sentence. */
+  reason: z12.string().min(1).max(200)
+}).strict();
+var ConsoleFrame = z12.discriminatedUnion("kind", [
+  ConsoleHello,
+  ConsoleStdin,
+  ConsoleStdout,
+  ConsoleResize,
+  ConsoleBye
+]);
+function consoleEnvelope(input) {
+  return {
+    jobId: input.sessionId,
+    senderKeyId: input.senderKeyId,
+    recipientKeyId: input.recipientKeyId,
+    deadlineAt: input.deadlineAt,
+    direction: input.from === "browser" ? "payload" : "result"
+  };
+}
+function consoleOrder(from) {
+  const maySend = {
+    // The browser drives: it opens, it types, it sets the size, it leaves.
+    browser: ["hello", "stdin", "resize", "bye"],
+    // The box answers, and can end a session. Nothing else.
+    box: ["stdout", "bye"]
+  };
+  const allowed = maySend[from];
+  const opensWithHello = from === "browser";
+  let last = 0;
+  let closed = false;
+  return {
+    /** The last sequence accepted. 0 before anything has been. */
+    get seen() {
+      return last;
+    },
+    accept(frame) {
+      if (closed) return { ok: false, fault: "closed" };
+      if (!allowed.includes(frame.kind)) {
+        return { ok: false, fault: "wrong-way" };
+      }
+      const isFirst = last === 0;
+      const wantsHello = isFirst && opensWithHello;
+      if (wantsHello !== (frame.kind === "hello")) {
+        return { ok: false, fault: "out-of-turn" };
+      }
+      if (frame.seq <= last) return { ok: false, fault: "replayed" };
+      if (frame.seq !== last + 1) return { ok: false, fault: "gap" };
+      last = frame.seq;
+      if (frame.kind === "bye") closed = true;
+      return { ok: true };
+    }
+  };
+}
 export {
   ABOUT,
   ABOUT_SHORT,
@@ -2678,6 +2849,8 @@ export {
   BackendIdSchema,
   CLOCK_ATTRIBUTION_MS,
   CLOCK_SKEW_WARN_MS,
+  CONSOLE_FRAME_VERSION,
+  CONSOLE_MAX_DATA_BYTES,
   Capability,
   CapabilityMatrix,
   ChatMessage,
@@ -2686,9 +2859,16 @@ export {
   ClaimResponse,
   ClaimedJob,
   ClaimedStub,
+  ConsoleBye,
+  ConsoleFrame,
+  ConsoleHello,
+  ConsoleResize,
+  ConsoleStdin,
+  ConsoleStdout,
   DeliveredResult,
   ENCRYPTION_KEY_CONTEXT,
   ENDPOINTS,
+  ENVELOPE_BODY_VERSION,
   ENVELOPE_MAX_AGE_MS,
   ERROR_STATUS,
   EnvelopeDirection,
@@ -2772,12 +2952,18 @@ export {
   checkProtocolVersion,
   classifyCost,
   compareVersions,
+  consoleEnvelope,
+  consoleOrder,
   cryptoReady,
   declaredVersion,
+  decodeEnvelopeInner,
   describeBytes,
   effectiveOfferScope,
+  encodeEnvelopeInner,
   envelopeBytes,
+  envelopeSignedBody,
   fingerprint,
+  fromBase64Url,
   generateKeys,
   grantStatement,
   isBackendId,
@@ -2806,6 +2992,7 @@ export {
   sizeClassCeiling,
   sizeClassOf,
   successionStatement,
+  toBase64Url,
   tooLargeMessage,
   updateOfferFor,
   verifyGrant,