@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/internal/backend-contracts/mlsDevGroup.d.ts

@@ -0,0 +1,321 @@
+import { type MlsDevTextProtocol, type MlsDevInteractionBinding, type MlsDevItem, type MlsDevTextPayload, type MlsDevApplicationEnvelope, type MlsDevApplicationPreconditions } from './mlsDevApplication.js';
+import { type MlsDevGroupFeedApplicationEntry } from './mlsDevGroupFeed.js';
+import { type MlsDevFeedReceiptProof } from './mlsDevFeedReceipt.js';
+import { type MlsDevEnrollmentDevice } from './mlsDevEnrollment.js';
+import { type MlsDevKeyPackageClaimReceipt } from './mlsDevKeyPackages.js';
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+export declare const MLS_DEV_GROUP_ROSTER_MAX = 32;
+export declare const MLS_DEV_GROUP_TLS_MAX_BYTES: number;
+export declare const MLS_DEV_GROUP_CONTROL_MAX_BYTES: number;
+export declare const MLS_DEV_GROUP_WRAPPED_MAX_BYTES: number;
+export declare const MLS_DEV_GROUP_PREPARATION_MAX_BYTES: number;
+export declare const MLS_DEV_GROUP_QUERY_MAX_BYTES: number;
+export declare const MLS_DEV_GROUP_QUERY_MAX_CONTROLS = 4;
+export interface MlsDevGroupCreateConversation {
+    readonly name: string;
+    readonly memberIds: readonly string[];
+    readonly mlsDev: {
+        readonly version: 1;
+        readonly conversationId: string;
+        readonly credential: string;
+        readonly protocol?: MlsDevTextProtocol;
+    };
+}
+export interface MlsDevGroupHead {
+    readonly sequence: number;
+    readonly epoch: number;
+    readonly hash: string;
+}
+export interface MlsDevGroupMarker {
+    readonly version: 1;
+    readonly groupId: string;
+    readonly head: MlsDevGroupHead;
+}
+export interface MlsDevGroupRosterEntry {
+    readonly device: MlsDevEnrollmentDevice;
+    readonly admissionId: string;
+}
+export interface MlsDevGroupPreconditions {
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+    readonly targetAdmissionId: string | null;
+}
+export interface MlsDevGroupUnsignedControl {
+    readonly version: 1;
+    readonly environmentId: MlsEnvironmentId;
+    readonly kind: 'create' | 'add' | 'remove';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly senderCredential: string;
+    readonly expectedHead: MlsDevGroupHead | null;
+    readonly epoch: number;
+    readonly preconditions: MlsDevGroupPreconditions;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly groupInfo: string | null;
+    readonly commit: string | null;
+    readonly welcome: string | null;
+    readonly keyPackageClaim: MlsDevKeyPackageClaimReceipt | null;
+    readonly removedDeviceId: string | null;
+}
+/** The device signs the closed public control plus the existing outer endpoint
+ * operation ID. Neither the signature nor an issuer credential grants membership. */
+export interface MlsDevGroupControl extends MlsDevGroupUnsignedControl {
+    readonly proof: string;
+}
+export interface MlsDevGroupAcceptedControl {
+    readonly version: 1;
+    readonly authorization: 'group_control_only';
+    readonly operationId: string;
+    readonly control: MlsDevGroupControl;
+    readonly head: MlsDevGroupHead;
+    readonly acceptedAtMs: number;
+    readonly membershipRevision: number;
+}
+/** Which current members' devices a room still needs to admit (mls-rooms-by-default.md §2.4), asked by an admitted device. */
+export interface MlsDevGroupAdmissionsQuery {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly credential: string;
+}
+export interface MlsDevGroupAdmissionCandidate {
+    readonly principal: {
+        readonly type: 'human' | 'ai_agent';
+        readonly id: string;
+    };
+    readonly deviceId: string;
+    /** The member's admission, the `targetAdmissionId` a claim for this device names. */
+    readonly targetAdmissionId: string;
+}
+export interface MlsDevGroupAdmissionsResult {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly membershipRevision: number;
+    /** Registered, eligible devices of current members that are not in the group and have a KeyPackage available. */
+    readonly candidates: readonly MlsDevGroupAdmissionCandidate[];
+    /** Current members with no device in the group (whether or not one is a candidate): the room's send hold (D2). */
+    readonly waitingPrincipalIds: readonly string[];
+}
+export declare const MLS_DEV_GROUP_ADMISSION_MAX_CANDIDATES = 64;
+export interface MlsDevGroupQuery {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly credential: string;
+    readonly afterSequence: number;
+    readonly limit: number;
+}
+export interface MlsDevGroupQueryResult {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly marker: MlsDevGroupMarker | null;
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly controls: readonly MlsDevGroupAcceptedControl[];
+    readonly nextSequence: number;
+    readonly hasMore: boolean;
+    /** True exposes only the caller's bounded removal history, never later rows. */
+    readonly terminal: boolean;
+}
+export interface MlsDevGroupContext {
+    readonly version: 1;
+    readonly environmentId: MlsEnvironmentId;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly deviceId: string;
+    readonly installationId: string;
+    /** Local protected-state revision, distinct from server sequence and MLS epoch. */
+    readonly revision: number;
+    readonly protocol?: MlsDevTextProtocol;
+}
+export type MlsDevGroupCommand = {
+    readonly op: 'encrypt_text';
+    readonly operationId: string;
+    readonly messageId: string;
+    readonly credential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevApplicationPreconditions;
+    readonly text: string;
+    /** v3 rooms only (mls-payload-v3.md §2); native refuses either in a v1 or v2 room. */
+    readonly replyTo?: MlsDevTextPayload['replyTo'];
+    readonly mentions?: MlsDevTextPayload['mentions'];
+} | {
+    /** v3 rooms only (mls-payload-v3.md §2): native carries the item as an opaque object this contract validates. */
+    readonly op: 'encrypt_item';
+    readonly operationId: string;
+    readonly messageId: string;
+    readonly credential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevApplicationPreconditions;
+    readonly item: MlsDevItem;
+} | {
+    readonly op: 'process_application';
+    readonly entry: MlsDevGroupFeedApplicationEntry;
+} | {
+    /** v2 only (encrypted-interactions.md §2.3). `body` is the payload's `interaction` object; native adds a secret
+     * request's one-time `secretKey`, and with `seal` seals the answer text into `answer.sealed` for the requester. */
+    readonly op: 'encrypt_interaction';
+    readonly operationId: string;
+    readonly messageId: string;
+    readonly credential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevApplicationPreconditions;
+    readonly interaction: MlsDevInteractionBinding;
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly seal: {
+        readonly text: string;
+        readonly publicKey: string;
+        readonly requesterDeviceId: string;
+    } | null;
+} | {
+    /** The requester opens a sealed answer once; native removes the request's key from the state it returns (§2.5). */
+    readonly op: 'open_secret_answer';
+    readonly requestId: string;
+    readonly responderId: string;
+    readonly responderDeviceId: string;
+    readonly sealed: {
+        readonly enc: string;
+        readonly ciphertext: string;
+    };
+} | {
+    readonly op: 'create';
+    readonly operationId: string;
+    readonly credential: string;
+    readonly preconditions: MlsDevGroupPreconditions;
+} | {
+    readonly op: 'add';
+    readonly operationId: string;
+    readonly credential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevGroupPreconditions;
+    readonly keyPackageClaim: MlsDevKeyPackageClaimReceipt;
+} | {
+    readonly op: 'remove';
+    readonly operationId: string;
+    readonly credential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevGroupPreconditions;
+    readonly removedDeviceId: string;
+} | {
+    readonly op: 'finalize';
+    readonly accepted: MlsDevGroupAcceptedControl;
+} | {
+    readonly op: 'discard';
+    readonly operationId: string;
+    readonly control: MlsDevGroupControl;
+} | {
+    readonly op: 'join';
+    readonly credential: string;
+    readonly accepted: MlsDevGroupAcceptedControl;
+    /** Canon's signed acceptance time for the control at `feedOrdinal` (mls-signed-acceptance.md). */
+    readonly receiptProof: MlsDevFeedReceiptProof;
+    readonly feedOrdinal: number;
+    readonly keyPackageId: string;
+} | {
+    readonly op: 'process';
+    readonly credential: string;
+    readonly accepted: MlsDevGroupAcceptedControl;
+    readonly receiptProof: MlsDevFeedReceiptProof;
+    readonly feedOrdinal: number;
+};
+export type MlsDevGroupPayload = {
+    readonly kind: 'application';
+    readonly envelope: MlsDevApplicationEnvelope;
+    /** `encrypt_item` only: the exact authored item plaintext, the endpoint's own copy. */
+    readonly payload?: string;
+} | {
+    /** A received item: its exact plaintext JSON, which the endpoint parses (`parseMlsDevItemPayload`). */
+    readonly kind: 'item';
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly payload: string;
+    readonly feedOrdinal: number;
+} | {
+    readonly kind: 'text';
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly text: string;
+    readonly replyTo?: MlsDevTextPayload['replyTo'];
+    readonly mentions?: MlsDevTextPayload['mentions'];
+    readonly feedOrdinal: number;
+} | {
+    /** `payload` is the exact authored plaintext JSON: a secret request's public key, or only a sealed answer. */
+    readonly kind: 'interaction_application';
+    readonly envelope: MlsDevApplicationEnvelope;
+    readonly payload: string;
+} | {
+    readonly kind: 'interaction';
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly payload: string;
+    readonly feedOrdinal: number;
+} | {
+    /** v2 only: content that failed native checks after an authenticated receive. Consumed, logged, never applied. */
+    readonly kind: 'invalid';
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly feedOrdinal: number;
+} | {
+    readonly kind: 'secret';
+    readonly requestId: string;
+    readonly text: string;
+} | {
+    readonly kind: 'discarded';
+    readonly operationId: string;
+    readonly head: MlsDevGroupHead | null;
+} | {
+    readonly kind: 'control';
+    readonly control: MlsDevGroupControl;
+} | {
+    readonly kind: 'applied';
+    readonly head: MlsDevGroupHead;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly removed: boolean;
+    readonly consumedKeyPackageId: string | null;
+};
+export interface MlsDevGroupPreparation {
+    readonly wrappedState: string;
+    readonly payload: MlsDevGroupPayload;
+}
+export declare class MlsDevGroupValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_GROUP";
+    constructor();
+}
+export declare function parseMlsDevGroupCreateConversation(value: unknown): MlsDevGroupCreateConversation;
+export declare function parseMlsDevGroupHead(value: unknown): MlsDevGroupHead;
+export declare function parseMlsDevGroupMarker(value: unknown): MlsDevGroupMarker;
+export declare function parseMlsDevGroupRoster(value: unknown): readonly MlsDevGroupRosterEntry[];
+/** Hold, then close (owner ruling 2026-10-16; mls-dev-groups.md): how long an erased member's devices wait for a commit. */
+export declare const MLS_DEV_ROOM_REMOVAL_DEADLINE_MS: number;
+export interface MlsDevRoomRemovalEntry {
+    readonly principalId: string;
+    /** The erased principal's devices still in the MLS roster; any other admitted device may commit their removal. */
+    readonly deviceIds: readonly string[];
+    readonly deadlineAtMs: number;
+}
+/** `conversations/{id}.mlsRemoval`: `pending` holds every send; `closing` and `closed` refuse every later send and roster
+ * change. `closing` still lists the erased principals whose Canon membership the scheduler has yet to remove. */
+export interface MlsDevRoomRemoval {
+    readonly version: 1;
+    readonly status: 'pending' | 'closing' | 'closed';
+    readonly pending: readonly MlsDevRoomRemovalEntry[];
+    readonly closedAtMs: number | null;
+}
+export declare function parseMlsDevRoomRemoval(value: unknown): MlsDevRoomRemoval;
+export declare function parseMlsDevGroupPreconditions(value: unknown): MlsDevGroupPreconditions;
+export declare function parseMlsDevGroupUnsignedControl(value: unknown): MlsDevGroupUnsignedControl;
+export declare function parseMlsDevGroupControl(value: unknown): MlsDevGroupControl;
+export declare function parseMlsDevGroupAcceptedControl(value: unknown): MlsDevGroupAcceptedControl;
+export declare function parseMlsDevGroupAdmissionsQuery(value: unknown): MlsDevGroupAdmissionsQuery;
+export declare function parseMlsDevGroupAdmissionsResult(value: unknown): MlsDevGroupAdmissionsResult;
+export declare function parseMlsDevGroupQuery(value: unknown): MlsDevGroupQuery;
+export declare function parseMlsDevGroupQueryResult(value: unknown): MlsDevGroupQueryResult;
+export declare function parseMlsDevGroupContext(value: unknown): MlsDevGroupContext;
+export declare function parseMlsDevGroupCommand(value: unknown): MlsDevGroupCommand;
+export declare function parseMlsDevGroupPreparation(value: unknown): MlsDevGroupPreparation;
+export declare function encodeMlsDevGroupControlProof(value: unknown, operationId: string): Uint8Array;
+/** Hash these exact bytes with SHA-256 for the accepted control head. */
+export declare function encodeMlsDevGroupHead(value: unknown, operationId: string): Uint8Array;

package/dist/internal/backend-contracts/mlsDevGroupFeed.d.ts

@@ -0,0 +1,51 @@
+import { type MlsDevGroupAcceptedControl, type MlsDevGroupMarker, type MlsDevGroupRosterEntry } from './mlsDevGroup.js';
+import { type MlsDevTextProtocol, type MlsDevApplicationEnvelope, type MlsDevApplicationReceipt } from './mlsDevApplication.js';
+import { type MlsDevFeedReceiptProof } from './mlsDevFeedReceipt.js';
+export declare const MLS_DEV_GROUP_FEED_MAX_ENTRIES = 4;
+export declare const MLS_DEV_GROUP_FEED_MAX_BYTES: number;
+export interface MlsDevGroupFeedControlEntry {
+    readonly version: 1;
+    readonly ordinal: number;
+    readonly kind: 'control';
+    readonly accepted: MlsDevGroupAcceptedControl;
+    /** Canon's signature over the time it accepted this entry (mls-signed-acceptance.md). */
+    readonly receiptProof?: MlsDevFeedReceiptProof;
+}
+export interface MlsDevGroupFeedApplicationEntry {
+    readonly version: 1;
+    readonly ordinal: number;
+    readonly kind: 'application';
+    readonly receipt: MlsDevApplicationReceipt;
+    readonly envelope: MlsDevApplicationEnvelope;
+    readonly receiptProof?: MlsDevFeedReceiptProof;
+}
+export type MlsDevGroupFeedEntry = MlsDevGroupFeedControlEntry | MlsDevGroupFeedApplicationEntry;
+export interface MlsDevGroupFeedQuery {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly credential: string;
+    readonly afterOrdinal: number;
+    readonly limit: number;
+}
+export interface MlsDevGroupFeedResult {
+    readonly version: 1;
+    readonly protocol: MlsDevTextProtocol;
+    readonly conversationId: string;
+    readonly marker: MlsDevGroupMarker | null;
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly minimumOrdinal: number | null;
+    readonly latestOrdinal: number;
+    readonly nextOrdinal: number;
+    readonly entries: readonly MlsDevGroupFeedEntry[];
+    readonly hasMore: boolean;
+    readonly terminal: boolean;
+}
+export declare class MlsDevGroupFeedValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_GROUP_FEED";
+    constructor();
+}
+export declare function parseMlsDevGroupFeedEntry(value: unknown): MlsDevGroupFeedEntry;
+export declare function parseMlsDevGroupFeedQuery(value: unknown): MlsDevGroupFeedQuery;
+export declare function parseMlsDevGroupFeedResult(value: unknown): MlsDevGroupFeedResult;

package/dist/internal/backend-contracts/mlsDevInteraction.d.ts

@@ -0,0 +1,159 @@
+import { type MlsDevInteractionBinding, type MlsDevInteractionKind, type MlsDevItemPayload, type MlsDevTextPayload } from './mlsDevApplication.js';
+import { type MlsDevGroupHead } from './mlsDevGroup.js';
+/**
+ * Encrypted approvals and questions in `canon.mls.dev-text.v2` rooms (docs/design/encrypted-interactions.md §2.3–§2.4).
+ * The MLS plaintext is a closed union on `kind`; every variant carries the text payload's shared ids. These parsers run
+ * in the sender's endpoint before encryption and in every recipient after decryption. Native custody treats an
+ * interaction body as canonical JSON and checks only the shared ids, kind and size.
+ */
+export declare const MLS_DEV_INTERACTION_LIMITS: Readonly<{
+    title: 200;
+    details: 8000;
+    options: 10;
+    optionLabel: 120;
+    text: 4000;
+}>;
+/** RFC 9180 base mode, DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-128-GCM: MLS suite 1's primitives. */
+export declare const MLS_DEV_SECRET_ANSWER_SUITE: "x25519-hkdf-sha256-aes128gcm";
+/** UTF-8 of at most 4,000 code points (4 bytes each) plus the AES-GCM tag. */
+export declare const MLS_DEV_SECRET_ANSWER_MAX_BYTES: number;
+export declare const MLS_DEV_INTERACTION_WITHDRAW_REASONS: readonly ["stopped", "turn_ended", "expired", "restart"];
+export type MlsDevInteractionWithdrawReason = typeof MLS_DEV_INTERACTION_WITHDRAW_REASONS[number];
+export interface MlsDevInteractionOption {
+    readonly id: string;
+    readonly label: string;
+}
+export interface MlsDevInteractionRequestBody {
+    readonly requestId: string;
+    readonly kind: MlsDevInteractionKind;
+    readonly title: string;
+    readonly details?: string;
+    readonly options?: readonly MlsDevInteractionOption[];
+    readonly multiple?: boolean;
+    readonly risk?: 'normal' | 'destructive';
+    readonly allowSession?: boolean;
+    readonly scopeKey?: string;
+    readonly responderIds: readonly [string];
+    readonly expiresAtMs: number;
+    /** A secret request's one-time HPKE recipient key, generated and held by the requesting device's custody (§2.5). */
+    readonly secretKey?: {
+        readonly kem: 'x25519';
+        readonly publicKey: string;
+    };
+}
+export type MlsDevInteractionAnswer = {
+    readonly decision: 'allow' | 'deny';
+    readonly scope: 'once' | 'session';
+} | {
+    readonly choices: readonly string[];
+} | {
+    readonly text: string;
+} | {
+    readonly sealed: {
+        readonly enc: string;
+        readonly ciphertext: string;
+    };
+}
+/** The responder's Cancel/Skip on a question or secret card (review of #1081). */
+ | {
+    readonly cancelled: true;
+};
+export interface MlsDevInteractionResponseBody {
+    readonly requestId: string;
+    readonly agentId: string;
+    readonly answer: MlsDevInteractionAnswer;
+}
+export interface MlsDevInteractionWithdrawBody {
+    readonly requestId: string;
+    readonly reason: MlsDevInteractionWithdrawReason;
+}
+interface MlsDevApplicationPayloadIds {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+}
+export type MlsDevInteractionPayload = (MlsDevApplicationPayloadIds & {
+    readonly kind: 'interaction.request';
+    readonly interaction: MlsDevInteractionRequestBody;
+}) | (MlsDevApplicationPayloadIds & {
+    readonly kind: 'interaction.response';
+    readonly interaction: MlsDevInteractionResponseBody;
+}) | (MlsDevApplicationPayloadIds & {
+    readonly kind: 'interaction.withdraw';
+    readonly interaction: MlsDevInteractionWithdrawBody;
+});
+export type MlsDevApplicationPayload = MlsDevTextPayload | MlsDevItemPayload | MlsDevInteractionPayload;
+export type MlsDevInteractionPayloadKind = MlsDevInteractionPayload['kind'];
+export declare const MLS_DEV_INTERACTION_PAYLOAD_KINDS: readonly ["interaction.request", "interaction.response", "interaction.withdraw"];
+/** The server's metadata-only record (§2.4): no title, options, decision, scope or answer. */
+export interface MlsDevInteractionRecord {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly agentId: string;
+    readonly requesterDeviceId: string;
+    readonly requestId: string;
+    readonly kind: MlsDevInteractionKind;
+    readonly responderIds: readonly [string];
+    readonly expiresAtMs: number;
+    readonly status: 'pending' | 'answered' | 'withdrawn';
+    readonly binding: {
+        readonly groupId: string;
+        readonly head: MlsDevGroupHead;
+        readonly membershipRevision: number;
+        readonly requestMessageId: string;
+        readonly requestOrdinal: number;
+    };
+    readonly answer?: {
+        readonly responderId: string;
+        readonly responderDeviceId: string;
+        readonly messageId: string;
+        readonly ordinal: number;
+        readonly acceptedAtMs: number;
+    };
+    readonly withdrawal?: {
+        readonly messageId: string;
+        readonly ordinal: number;
+        readonly acceptedAtMs: number;
+    };
+    readonly createdAtMs: number;
+}
+export interface MlsDevInteractionsQuery {
+    readonly version: 1;
+    readonly conversationId?: string;
+}
+/** The caller's answerable pending requests, for badges and web's content-free waiting notice. */
+export interface MlsDevInteractionsResult {
+    readonly version: 1;
+    readonly interactions: readonly {
+        readonly conversationId: string;
+        readonly agentId: string;
+        readonly requestId: string;
+        readonly kind: MlsDevInteractionKind;
+        readonly expiresAtMs: number;
+    }[];
+}
+export declare const MLS_DEV_INTERACTIONS_QUERY_MAX = 50;
+export declare class MlsDevInteractionValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_INTERACTION";
+    constructor();
+}
+export declare function parseMlsDevInteractionRequestBody(value: unknown): MlsDevInteractionRequestBody;
+export declare function parseMlsDevInteractionAnswer(value: unknown): MlsDevInteractionAnswer;
+export declare function parseMlsDevInteractionResponseBody(value: unknown): MlsDevInteractionResponseBody;
+export declare function parseMlsDevInteractionWithdrawBody(value: unknown): MlsDevInteractionWithdrawBody;
+/** The closed v2 plaintext union. A v1 room accepts only `kind: 'text'` (`parseMlsDevTextPayload`). */
+export declare function parseMlsDevApplicationPayload(value: unknown): MlsDevApplicationPayload;
+/** Receipt-time check (`applyApplication`): the encrypted payload repeats exactly what its public binding announced. */
+export declare function assertMlsDevInteractionPayloadBinding(payload: MlsDevApplicationPayload, binding: MlsDevInteractionBinding | undefined): void;
+/**
+ * Whether an answer has the shape its request allows. A session-scoped decision needs a request that offered a session
+ * rule (`allowSession`; a destructive action never does, §3); the runner also counts one only from the agent's owner.
+ */
+export declare function isMlsDevInteractionAnswerAllowed(request: MlsDevInteractionRequestBody, answer: MlsDevInteractionAnswer): boolean;
+export declare function parseMlsDevInteractionRecord(value: unknown): MlsDevInteractionRecord;
+export declare function parseMlsDevInteractionsQuery(value: unknown): MlsDevInteractionsQuery;
+export declare function parseMlsDevInteractionsResult(value: unknown): MlsDevInteractionsResult;
+export {};

package/dist/internal/backend-contracts/mlsDevKeyPackage.d.ts

@@ -0,0 +1,42 @@
+export declare const MLS_DEV_KEY_PACKAGE_COMMAND_MAX_BYTES = 16384;
+export declare const MLS_DEV_KEY_PACKAGE_WIRE_MAX_BYTES = 16384;
+export declare const MLS_DEV_KEY_PACKAGE_WRAPPED_STATE_MAX_BYTES: number;
+export declare const MLS_DEV_KEY_PACKAGE_PREPARATION_MAX_BYTES: number;
+/** Typed local preparation only; neither this command nor its output grants
+ * publication, room membership, or current device authority. */
+export interface MlsDevKeyPackageCommand {
+    readonly version: 1;
+    readonly op: 'key_package';
+    readonly keyPackageId: string;
+    readonly credential: string;
+}
+export interface MlsDevKeyPackagePayload {
+    readonly version: 1;
+    readonly keyPackageId: string;
+    readonly deviceId: string;
+    readonly credentialId: string;
+    readonly credentialGeneration: number;
+    readonly ciphersuite: 1;
+    readonly signaturePublicKey: string;
+    /** Canonical base64url TLS MLSMessage carrying one KeyPackage. */
+    readonly keyPackage: string;
+    /** MLS RefHash, not a hash of the enclosing MLSMessage. */
+    readonly keyPackageRef: string;
+    /** The encoded MLS lifetime expressed as a half-open interval in milliseconds. */
+    readonly notBeforeMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MlsDevKeyPackagePreparation {
+    readonly wrappedState: string;
+    readonly payload: MlsDevKeyPackagePayload;
+}
+export declare class MlsDevKeyPackageValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_KEY_PACKAGE";
+    constructor();
+}
+export declare function parseMlsDevKeyPackageId(value: unknown): string;
+export declare function parseMlsDevKeyPackageCommand(value: unknown): MlsDevKeyPackageCommand;
+export declare function parseMlsDevKeyPackagePayload(value: unknown): MlsDevKeyPackagePayload;
+/** Structural validation. Only the native boundary can authenticate ciphertext
+ * or inspect the MLS leaf/signature; callers independently verify issuer trust. */
+export declare function parseMlsDevKeyPackagePreparation(value: unknown): MlsDevKeyPackagePreparation;

package/dist/internal/backend-contracts/mlsDevKeyPackages.d.ts

@@ -0,0 +1,55 @@
+export declare const MLS_DEV_KEY_PACKAGES_MAX_BYTES = 32768;
+export declare const MLS_DEV_KEY_PACKAGE_TLS_MAX_BYTES = 16384;
+export interface MlsDevKeyPackagePublishRequest {
+    readonly version: 1;
+    readonly requestId: string;
+    readonly keyPackage: string;
+}
+export interface MlsDevKeyPackagePublicationReceipt {
+    readonly version: 1;
+    readonly authorization: 'key_package_publication_only';
+    readonly requestId: string;
+    readonly keyPackageRef: string;
+    readonly deviceId: string;
+    readonly publishedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MlsDevKeyPackageClaimPreconditions {
+    readonly conversationId: string;
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+    readonly targetAdmissionId: string;
+}
+export interface MlsDevKeyPackageClaimRequest {
+    readonly version: 1;
+    readonly requestId: string;
+    readonly claimantCredential: string;
+    readonly recipientDeviceId: string;
+    readonly preconditions: MlsDevKeyPackageClaimPreconditions;
+}
+/** A bounded, authenticated delivery receipt. It grants neither membership nor
+ * permission to accept the peer: the receiving MLS implementation must validate
+ * the package again when preparing Add. */
+export interface MlsDevKeyPackageClaimReceipt {
+    readonly version: 1;
+    readonly authorization: 'key_package_claim_only';
+    readonly requestId: string;
+    readonly preconditions: MlsDevKeyPackageClaimPreconditions;
+    readonly claimantDeviceId: string;
+    readonly recipientDeviceId: string;
+    readonly keyPackageRef: string;
+    readonly keyPackage: string;
+    readonly claimedAtMs: number;
+}
+export declare class MlsDevKeyPackagesValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_KEY_PACKAGES";
+    constructor();
+}
+/** Structural encoding validation only; the server's OpenMLS validator parses
+ * and authenticates the actual TLS message before publication. */
+export declare function parseMlsDevKeyPackageWire(value: unknown): string;
+export declare function parseMlsDevKeyPackageClaimPreconditions(value: unknown): MlsDevKeyPackageClaimPreconditions;
+export declare function parseMlsDevKeyPackagePublish(value: unknown): MlsDevKeyPackagePublishRequest;
+export declare function parseMlsDevKeyPackagePublicationReceipt(value: unknown): MlsDevKeyPackagePublicationReceipt;
+export declare function parseMlsDevKeyPackageClaim(value: unknown): MlsDevKeyPackageClaimRequest;
+export declare function parseMlsDevKeyPackageClaimReceipt(value: unknown): MlsDevKeyPackageClaimReceipt;

package/dist/internal/backend-contracts/mlsEnvironment.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Each environment's MLS identity: the values signed into its credentials, group controls and application AAD. A
+ * production device, credential or group can never verify as Dev (or the reverse) because these differ. Dev's values
+ * are today's literals, so Dev bytes are unchanged. A declared profile only defines the wire; whether an environment
+ * runs MLS is decided by its deployment (Functions gates, configuration, native builds), never here.
+ */
+export declare const MLS_ENVIRONMENT_PROFILES: Readonly<{
+    readonly 'canon-dev-v1': Readonly<{
+        issuer: "canon-mls-dev-v1";
+        credentialType: "canon-mls-dev-credential+jws";
+        issuerKeyPath: "projects/canonmail-dev/locations/europe-west1/keyRings/canon-mls/cryptoKeys/device-issuer";
+        receiptKeyPath: "projects/canonmail-dev/locations/europe-west1/keyRings/canon-mls/cryptoKeys/feed-receipt";
+    }>;
+    readonly 'canon-prod-v1': Readonly<{
+        issuer: "canon-mls-prod-v1";
+        credentialType: "canon-mls-prod-credential+jws";
+        issuerKeyPath: "projects/canonmail-prod/locations/europe-west1/keyRings/canon-mls/cryptoKeys/device-issuer";
+        receiptKeyPath: "projects/canonmail-prod/locations/europe-west1/keyRings/canon-mls/cryptoKeys/feed-receipt";
+    }>;
+}>;
+export type MlsEnvironmentId = keyof typeof MLS_ENVIRONMENT_PROFILES;
+export type MlsEnvironmentProfile = (typeof MLS_ENVIRONMENT_PROFILES)[MlsEnvironmentId];
+export type MlsIssuerId = MlsEnvironmentProfile['issuer'];
+/**
+ * Exact match only: no trimming or case folding, so an alias never reaches signed bytes. Throws the shared internal
+ * parser error, which each public boundary replaces with its own.
+ */
+export declare function requireMlsEnvironmentId(value: unknown): MlsEnvironmentId;
+/** The same exact match as a predicate, for callers that refuse with their own error. */
+export declare function isMlsEnvironmentId(value: unknown): value is MlsEnvironmentId;
+export declare function mlsEnvironmentProfile(environmentId: MlsEnvironmentId): MlsEnvironmentProfile;
+/** The environment whose issuer key a KMS key-version path names, or undefined for any other path. */
+export declare function mlsEnvironmentOfIssuerKeyVersion(value: string): MlsEnvironmentId | undefined;
+/** The environment whose feed-receipt key (mls-signed-acceptance.md) a KMS key-version path names, or undefined. */
+export declare function mlsEnvironmentOfReceiptKeyVersion(value: string): MlsEnvironmentId | undefined;