@byok-sdk/protocol 0.29.0 → 0.30.0

package/dist/sealed-payload.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Sealed payload v1 on the hosted wire (#654 design §8.1, §8.3, §8.6).
+ *
+ * Each sealed message type (`task.complete_sealed`, …) is its plaintext type
+ * without the fields one data category moves into the ciphertext, plus a
+ * sealed member. The type, not a field, is gated, so a decoder that does not
+ * know `sealed-payload-v1` refuses the whole message. The Host reads only the
+ * sealed member's outer fields. It checks the shape here:
+ * version, suite, encodings, a legal padded length, and exactly one of inline
+ * `ciphertext` and `ciphertextRef`. Inline is the only legal form up to
+ * {@link SEALED_INLINE_MAX_PADDED_LENGTH}; above it, the ciphertext is a blob.
+ * So one content has one legal wire form, and two submissions compare by
+ * their outer fields only.
+ *
+ * `@byok-sdk/core/sealed-payload` seals and opens the bytes. Protocol does
+ * not depend on core, so this module repeats the header rules and the padded
+ * length function; a cross-package test keeps the two equal.
+ */
+import { z } from 'zod';
+export { SEALED_SPLIT_TABLE, isSealedMessageType } from './sealed-split-table';
+export type { SealedDigestRule, SealedMessageType, SealedSplitEntry } from './sealed-split-table';
+export declare const SEALED_PAYLOAD_VERSION = 1;
+/** The only suite v1 admits. A new suite is a new constant and a new capability, never a parser branch. */
+export declare const SEALED_PAYLOAD_SUITE = "byok-sealed-v1.hkdf-sha256.aes-256-gcm";
+/** C1–C4 in canonical order. A task lists its sealing categories in this order. */
+export declare const SEALED_PAYLOAD_CATEGORIES: readonly ['task-input', 'agent-message', 'task-output', 'memory-projection'];
+export type SealedPayloadCategory = (typeof SEALED_PAYLOAD_CATEGORIES)[number];
+/**
+ * The categories a v1 task may seal (D17): task input and task output. Agent
+ * messages, memory projections, input preparation and drafts come later.
+ */
+export declare const SEALED_PAYLOAD_V1_CATEGORIES: readonly ['task-input', 'task-output'];
+export type SealedPayloadV1Category = (typeof SEALED_PAYLOAD_V1_CATEGORIES)[number];
+/**
+ * Closed `task.decline` codes of a receiver that refuses sealed task input
+ * (§8.3). They are plaintext: a device without the scope key cannot seal a
+ * reason. A device sends them only to a server that advertised
+ * `sealed-payload-v1`.
+ */
+export declare const SEALED_DECLINE_CODES: readonly ['sealed_key_unavailable', 'sealed_open_failed', 'sealed_content_mac_mismatch', 'sealing_policy_mismatch'];
+export type SealedDeclineCode = (typeof SEALED_DECLINE_CODES)[number];
+/**
+ * The closed plaintext codes of a task whose output is sealed (#654 12d).
+ * It lists each plaintext output type that has a plaintext form on such a
+ * task, with the codes that each field moved or dropped by its sealed type
+ * may hold. Such a field that is not listed here must be absent. An output
+ * type with a sealed form that is not listed has no plaintext form. An
+ * interrupted task reports `daemon_interrupted`; a device that cannot seal
+ * reports `sealed_key_unavailable`. The Host check, the daemon and the member
+ * display read this one list, and compare by exact match.
+ */
+export declare const SEALED_TASK_PLAIN_CODES: Readonly<{
+    readonly 'task.fail': {
+        readonly reason: readonly ["daemon_interrupted", "sealed_key_unavailable"];
+    };
+    readonly 'task.decline': {
+        readonly reason: readonly ["sealed_key_unavailable", "sealed_open_failed", "sealed_content_mac_mismatch", "sealing_policy_mismatch"];
+    };
+    readonly 'task.cancelled': {
+        readonly reason: readonly [];
+    };
+}>;
+/**
+ * True when `payload` is a legal plaintext `type` message of a task whose
+ * output is sealed: each field that a `task-output` sealed type of `type`
+ * moves or drops is absent or holds one of {@link SEALED_TASK_PLAIN_CODES}.
+ * A type that has a sealed output form and is not listed there is never
+ * legal. A plaintext decline also names its code as `code`. A type with no
+ * sealed output form is always legal.
+ */
+export declare function isSealedTaskPlainOutput(type: string, payload: object): boolean;
+/** Padded frames above this length travel as a ciphertext blob (§8.6). */
+export declare const SEALED_INLINE_MAX_PADDED_LENGTH: number;
+/** Plaintext limit of every v1 category, in UTF-8 bytes of canonical JSON (D8). */
+export declare const SEALED_PAYLOAD_MAX_CONTENT_LENGTH: number;
+/**
+ * The one legal padded length of a frame of `frameLength` bytes
+ * (`4 + contentLength`): the next multiple of 256 up to 16 KiB, Padmé above.
+ */
+export declare function sealedPayloadPaddedLength(frameLength: number): number;
+/** The largest padded length a v1 content may have. */
+export declare const SEALED_PAYLOAD_MAX_PADDED_LENGTH: number;
+/**
+ * The byte length of canonical unpadded base64url, or `undefined`. Canonical
+ * means no padding, no impossible length, and zero unused bits in the last
+ * character, so one byte string has exactly one encoding.
+ */
+export declare function sealedBase64UrlByteLength(value: string): number | undefined;
+/** A sealed member of any v1 category. */
+export declare const SealedPayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    suite: z.ZodLiteral<"byok-sealed-v1.hkdf-sha256.aes-256-gcm">;
+    category: z.ZodEnum<{
+        "task-input": "task-input";
+        "task-output": "task-output";
+    }>;
+    scope: z.ZodObject<{
+        id: z.ZodString;
+        epoch: z.ZodNumber;
+        keyId: z.ZodString;
+    }, z.core.$strict>;
+    chainHead: z.ZodObject<{
+        seq: z.ZodNumber;
+        hash: z.ZodString;
+    }, z.core.$strict>;
+    sender: z.ZodString;
+    salt: z.ZodString;
+    nonce: z.ZodString;
+    paddedLength: z.ZodNumber;
+    contentMac: z.ZodString;
+    ciphertext: z.ZodOptional<z.ZodString>;
+    ciphertextRef: z.ZodOptional<z.ZodObject<{
+        blobId: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        contentType: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SealedPayload = z.infer<typeof SealedPayloadSchema>;
+/** The sealed member of a task-input message (offers, steer). */
+export declare const SealedTaskInputSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    suite: z.ZodLiteral<"byok-sealed-v1.hkdf-sha256.aes-256-gcm">;
+    category: z.ZodLiteral<"task-input">;
+    scope: z.ZodObject<{
+        id: z.ZodString;
+        epoch: z.ZodNumber;
+        keyId: z.ZodString;
+    }, z.core.$strict>;
+    chainHead: z.ZodObject<{
+        seq: z.ZodNumber;
+        hash: z.ZodString;
+    }, z.core.$strict>;
+    sender: z.ZodString;
+    salt: z.ZodString;
+    nonce: z.ZodString;
+    paddedLength: z.ZodNumber;
+    contentMac: z.ZodString;
+    ciphertext: z.ZodOptional<z.ZodString>;
+    ciphertextRef: z.ZodOptional<z.ZodObject<{
+        blobId: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        contentType: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The sealed member of a task-output message. */
+export declare const SealedTaskOutputSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    suite: z.ZodLiteral<"byok-sealed-v1.hkdf-sha256.aes-256-gcm">;
+    category: z.ZodLiteral<"task-output">;
+    scope: z.ZodObject<{
+        id: z.ZodString;
+        epoch: z.ZodNumber;
+        keyId: z.ZodString;
+    }, z.core.$strict>;
+    chainHead: z.ZodObject<{
+        seq: z.ZodNumber;
+        hash: z.ZodString;
+    }, z.core.$strict>;
+    sender: z.ZodString;
+    salt: z.ZodString;
+    nonce: z.ZodString;
+    paddedLength: z.ZodNumber;
+    contentMac: z.ZodString;
+    ciphertext: z.ZodOptional<z.ZodString>;
+    ciphertextRef: z.ZodOptional<z.ZodObject<{
+        blobId: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        contentType: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * A task's frozen sealing policy (§6.2). The offer carries it in plaintext.
+ * `epoch` is the epoch of the offer's task-input content, and the lowest epoch
+ * the task accepts.
+ */
+export declare const TaskSealingSchema: z.ZodObject<{
+    scopeId: z.ZodString;
+    epoch: z.ZodNumber;
+    categories: z.ZodArray<z.ZodEnum<{
+        "task-input": "task-input";
+        "task-output": "task-output";
+    }>>;
+}, z.core.$strict>;
+export type TaskSealing = z.infer<typeof TaskSealingSchema>;
+/**
+ * The routine template of a sealed execution (design §6.3). The offer's
+ * `sealed` member is then the template, family `routine.template`, which the
+ * member sealed once for every occurrence. The device rebuilds its binding
+ * from these fields: identity `{ routineId, definitionVersion }`, no device,
+ * the offer's `agentRef` and `sealing.categories`, and `notAfter`. They travel
+ * in plaintext because the AAD binds them. `definitionVersion` is an integer,
+ * because the binding tells `4` and `"4"` apart. The device, not the Host,
+ * checks `notAfter` against its clock.
+ */
+export declare const RoutineRefSchema: z.ZodObject<{
+    routineId: z.ZodString;
+    definitionVersion: z.ZodNumber;
+    notAfter: z.ZodString;
+}, z.core.$strict>;
+/**
+ * The rule of a sealed offer, for `superRefine`: `sealed` is present exactly
+ * when the task's `sealing` includes `task-input`, and then `instruction` is
+ * absent and `sealed.scope` is the task's scope at the task's epoch. When the
+ * task seals only its output, `instruction` is plaintext and required. A
+ * `routineRef` names a routine template, which is sealed task input, so it
+ * needs a task that seals `task-input`.
+ *
+ * Whether a task's later messages must be sealed is the Host's and the
+ * device's check: they know the task's `sealing`, this payload does not.
+ */
+export declare function sealedOfferRule(payload: {
+    readonly instruction?: unknown;
+    readonly sealing: TaskSealing;
+    readonly sealed?: SealedPayload;
+    readonly routineRef?: unknown;
+}, ctx: z.RefinementCtx): void;

package/dist/sealed-split-table.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The split table of sealed payload v1 (#654 design §8.1, §9.3): for each
+ * sealed message type, its plaintext type, its data category, its identity
+ * fields, the fields that move into the ciphertext, the fields it drops, and
+ * the rule of each digest field (D16).
+ *
+ * Plain data with no runtime imports, so `wire-additions.ts` can derive the
+ * sealed gates from it and stay free of zod.
+ */
+import type { MessageType } from './messages';
+import type { SealedPayloadV1Category } from './sealed-payload';
+/**
+ * How a sealed message type treats one digest field of its plaintext type
+ * (D16, design §9.3).
+ *
+ * - `ciphertext-sha256`: the SHA-256 of the sealed bytes, for a Host that
+ *   checks the bytes it stores (a ciphertext blob).
+ * - `keyed-mac`: a keyed MAC under the scope's MAC key; the Host forwards it.
+ * - `sealed`: the field moves into the ciphertext with its parent.
+ * - `plain`: a digest that no sealed content derives, kept in plaintext.
+ * - `forbidden`: the sealed type does not carry it in v1.
+ */
+export type SealedDigestRule = 'ciphertext-sha256' | 'keyed-mac' | 'sealed' | 'plain' | 'forbidden';
+/** One sealed message type in the split table. */
+export interface SealedSplitEntry {
+    /**
+     * The plaintext message type this type seals. The AAD and the content MAC
+     * bind it as the family, not the sealed wire type.
+     */
+    readonly plainType: MessageType;
+    readonly category: SealedPayloadV1Category;
+    /**
+     * Payload fields that, after the envelope `task_id`, name this write in the
+     * AAD and the content MAC (§8.2, §9.1). The sealed type requires them.
+     */
+    readonly identity: readonly string[];
+    /**
+     * Top-level fields of the plaintext type that move into the ciphertext.
+     * The sealed type does not have them; the receiver merges the opened
+     * object back and validates the plaintext type.
+     */
+    readonly moved: readonly string[];
+    /** Top-level fields of the plaintext type that the sealed type drops in v1. */
+    readonly forbidden: readonly string[];
+    /**
+     * Every path of the plaintext type whose name contains `digest`, `hash` or
+     * `revision` (case-insensitive), with its rule. A schema test keeps this
+     * complete.
+     */
+    readonly digests: {
+        readonly [path: string]: SealedDigestRule;
+    };
+    /**
+     * UTF-8 byte limits of moved fields that replace the plaintext type's limit
+     * of that field after the merge (decision 12b). The category limit still
+     * bounds the whole opened content.
+     */
+    readonly limits?: {
+        readonly [field: string]: number;
+    };
+}
+/**
+ * The split table (design §8.3): each sealed message type, the plaintext type
+ * it seals, its category, identity, moved and forbidden fields, and the rule
+ * of each digest field. It is the one authority; the schemas, the Host's
+ * comparison projection and the receiver's merge read it.
+ *
+ * A sealed offer also carries the task's `sealing`. When the categories
+ * include `task-input`, `instruction` is sealed; otherwise it stays plaintext
+ * and only the task output is sealed.
+ *
+ * Blob bytes have no sealing rule yet, so a sealed type carries no plaintext
+ * blob reference: `artifactRefs` and the artifact `blobRef` are dropped until
+ * that rule exists. A sealed artifact is inline content, so its `inline`
+ * takes up to 2 MiB instead of the plaintext 64 KB (decision 12b).
+ */
+export declare const SEALED_SPLIT_TABLE: Readonly<{
+    readonly 'task.offer_sealed': SealedSplitEntry;
+    readonly 'task.offer_with_toolsets_sealed': SealedSplitEntry;
+    readonly 'task.offer_for_agent_sealed': SealedSplitEntry;
+    readonly 'task.offer_for_agent_with_egress_sealed': SealedSplitEntry;
+    readonly 'task.offer_for_agent_with_egress_fresh_sealed': SealedSplitEntry;
+    readonly 'task.steer_sealed': {
+        readonly plainType: 'task.steer';
+        readonly category: 'task-input';
+        readonly identity: readonly ["steerId"];
+        readonly moved: readonly ["text"];
+        readonly forbidden: readonly [];
+        readonly digests: {};
+    };
+    readonly 'task.complete_sealed': {
+        readonly plainType: 'task.complete';
+        readonly category: 'task-output';
+        readonly identity: readonly [];
+        readonly moved: readonly ["summary", "finalMessage", "document"];
+        readonly forbidden: readonly ["artifactRefs", "preparedObservation"];
+        readonly digests: {
+            readonly 'agentRef.profileRevision': 'plain';
+            readonly 'agentHomeProjection.profileRevision': 'plain';
+            readonly 'agentHomeProjection.projectionHash': 'plain';
+            readonly 'artifactRefs[].contentHash': 'forbidden';
+            readonly 'preparedObservation.requestDigest': 'forbidden';
+        };
+    };
+    readonly 'task.fail_sealed': {
+        readonly plainType: 'task.fail';
+        readonly category: 'task-output';
+        readonly identity: readonly [];
+        readonly moved: readonly ["reason"];
+        readonly forbidden: readonly ["preparedObservation"];
+        readonly digests: {
+            readonly 'agentRef.profileRevision': 'plain';
+            readonly 'agentHomeProjection.profileRevision': 'plain';
+            readonly 'agentHomeProjection.projectionHash': 'plain';
+            readonly 'preparedObservation.requestDigest': 'forbidden';
+        };
+    };
+    readonly 'task.decline_sealed': {
+        readonly plainType: 'task.decline';
+        readonly category: 'task-output';
+        readonly identity: readonly [];
+        readonly moved: readonly ["reason"];
+        readonly forbidden: readonly [];
+        readonly digests: {
+            readonly 'agentRef.profileRevision': 'plain';
+        };
+    };
+    readonly 'task.cancelled_sealed': {
+        readonly plainType: 'task.cancelled';
+        readonly category: 'task-output';
+        readonly identity: readonly [];
+        readonly moved: readonly ["reason"];
+        readonly forbidden: readonly [];
+        readonly digests: {
+            readonly 'agentRef.profileRevision': 'plain';
+            readonly 'agentHomeProjection.profileRevision': 'plain';
+            readonly 'agentHomeProjection.projectionHash': 'plain';
+        };
+    };
+    readonly 'task.progress_sealed': {
+        readonly plainType: 'task.progress';
+        readonly category: 'task-output';
+        readonly identity: readonly ["seq"];
+        readonly moved: readonly ["events"];
+        readonly forbidden: readonly [];
+        readonly digests: {
+            readonly 'events[].spill.blob.contentHash': 'sealed';
+        };
+    };
+    readonly 'task.artifact_sealed': {
+        readonly plainType: 'task.artifact';
+        readonly category: 'task-output';
+        readonly identity: readonly ["artifactId"];
+        readonly moved: readonly ["inline"];
+        readonly forbidden: readonly ["blobRef"];
+        readonly digests: {
+            readonly 'blobRef.contentHash': 'forbidden';
+        };
+        readonly limits: {
+            readonly inline: number;
+        };
+    };
+    readonly 'task.await_approval_sealed': {
+        readonly plainType: 'task.await_approval';
+        readonly category: 'task-output';
+        readonly identity: readonly ["approvalId"];
+        readonly moved: readonly ["summary"];
+        readonly forbidden: readonly [];
+        readonly digests: {};
+    };
+}>;
+export type SealedMessageType = keyof typeof SEALED_SPLIT_TABLE;
+export declare function isSealedMessageType(type: string): type is SealedMessageType;

package/dist/version.d.ts

@@ -100,5 +100,5 @@ export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
  * cannot accidentally execute the instruction without the required tools.
  */
 export declare const CUSTOM_HARNESS_CAPABILITY: 'custom-harness';
-export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "agent-home-readers", "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1", "agent-memory-selection", 'agent-message-draft'];
+export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "agent-home-readers", "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1", "agent-memory-selection", "agent-memory-read-if-admitted", 'agent-message-draft', "sealed-payload-v1"];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/dist/wire-additions.d.ts

@@ -26,8 +26,8 @@
  *
  * Senders derive their admission flags from {@link requiredReceiverCapabilities}
  * and nowhere else, so a gate cannot exist in one place and be missing in
- * another. This module imports no runtime code (types only) so it stays free
- * of zod.
+ * another. This module imports no runtime code except the plain-data split
+ * table, so it stays free of zod.
  */
 import type { MessageType } from './messages';
 import type { CapabilityFlag } from './version';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/protocol",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "BYOK SDK wire protocol: envelope schema, message types, and codec helpers",
   "type": "module",
   "license": "MIT",