@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,17 @@
+export type TransferReceiptDecision = 'result' | 'pending' | 'uncertain' | 'rejected' | 'invalid';
+export interface TransferReceiptIdentity {
+    protocol: string;
+    operationId: string;
+    installationId: string;
+    action: string;
+}
+/** A transport failure is local attention, never a remote delivery outcome. */
+export declare function classifyTransferHttpFailure(status: number): 'retry' | 'attention';
+/** A successful mutation with failed restricted-result hydration is still
+ * unresolved locally. Never translate an operation rejection into a delivery outcome. */
+export declare function classifyTransferReceipt(value: unknown, expected: TransferReceiptIdentity): TransferReceiptDecision;
+/** Shared native recovery policy. Random is injected so all implementations run
+ * the same fixture corpus; a longer server retry hint is never truncated. */
+export declare function transferRetryDelay(attempt: number, random: number, retryAfterMs?: number): number;
+/** Expiry bounds automatic work, not the ability to reconcile an unknown result. */
+export declare function mayAttemptMediaTransfer(nowMs: number, createdAtMs: number, expiresAtMs?: number | null): boolean;

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

@@ -0,0 +1,21 @@
+/** A server-written membership transition stored in the ordinary chat history. */
+export interface MembershipChangeMetadata extends Record<string, unknown> {
+    type: 'membership_change';
+    action: 'added' | 'removed' | 'left';
+    actorId: string | null;
+    actorName: string | null;
+    memberId: string | null;
+    memberName: string;
+    membershipRevision: number;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+/** Recognize the reserved marker even when the remaining metadata is malformed. */
+export declare function isMembershipChangeMessage(message: {
+    metadata?: unknown;
+}): boolean;
+/** Membership revisions own these document IDs; user messages cannot claim them. */
+export declare function isMembershipChangeMessageId(messageId: unknown): boolean;
+export declare function readMembershipChangeMetadata(metadata: unknown): MembershipChangeMetadata | null;
+/** Uses stored names so the notice remains readable after a profile leaves the roster. */
+export declare function formatMembershipChangeNotice(metadata: MembershipChangeMetadata, currentUserId?: string): string;

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

@@ -0,0 +1,86 @@
+import { MediaAttachment } from './media.js';
+import { type MlsDevMessageReference } from './mlsDevApplication.js';
+export type SerializedSenderType = 'human' | 'ai_agent';
+/** Canonical agent client identifiers shared by Canon services and clients. */
+export declare const AGENT_CLIENT_TYPES: readonly ["claude-code", "codex", "hermes", "generic"];
+export type SerializedAgentClientType = typeof AGENT_CLIENT_TYPES[number];
+export type SerializedContentType = 'text' | 'image' | 'audio' | 'video' | 'file' | 'contact_card' | 'interaction';
+export interface ForwardedFrom {
+    sourceConversationId: string;
+    messageId: string;
+}
+export type SerializedReactions = Record<string, string[]>;
+export interface SerializedContactCard {
+    userId: string;
+    canonContactId?: string;
+    displayName: string;
+    avatarUrl: string | null;
+    userType: SerializedSenderType;
+    clientType?: SerializedAgentClientType;
+    about?: string;
+    isActive?: boolean;
+    ownerId?: string;
+    ownerName?: string;
+    lifecycleState?: string;
+}
+export interface SerializedMessage {
+    /** Public encrypted-message hint; content is read only from the authenticated MLS feed. */
+    mls?: MlsDevMessageReference;
+    id: string;
+    senderId: string;
+    senderName?: string;
+    senderType: SerializedSenderType;
+    isOwner: boolean;
+    contentType: SerializedContentType;
+    text: string | null;
+    attachments: MediaAttachment[];
+    mentions: string[];
+    replyTo: string | null;
+    replyToPosition: number | null;
+    forwarded?: boolean;
+    forwardedFrom?: ForwardedFrom;
+    status: 'sent' | 'read';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+    contactCard?: SerializedContactCard;
+    /** Durable canon.card.v1 runtime card content, passed through opaquely. */
+    runtimeCard?: Record<string, unknown>;
+    /**
+     * Plaintext, server-authorized interaction envelope for `contentType:
+     * 'interaction'` messages (card / input / approval / plan / contact). The
+     * authorization contract (`response`) and preview live here; the opaque
+     * request payload rides in `body`.
+     */
+    interaction?: SerializedInteraction;
+    /** Opaque interaction payload (JSON string or ciphertext); never parsed here. */
+    body?: string;
+    reactions?: SerializedReactions;
+}
+export type SerializedInteractionKind = 'contact' | 'approval' | 'input' | 'plan' | 'card';
+export interface SerializedInteraction {
+    kind: SerializedInteractionKind;
+    requestId: string;
+    interactive: boolean;
+    responseUserId?: string;
+    expiresAt?: string;
+    schemaVersion?: string;
+    preview?: {
+        title?: string;
+        blockKinds?: string[];
+    };
+    response?: {
+        actionIds?: string[];
+        actionFields?: Record<string, unknown>;
+        questions?: Array<{
+            id: string;
+            sensitive?: boolean;
+        }>;
+    };
+}
+export interface SerializeMessageInput {
+    id: string;
+    data: Record<string, unknown>;
+    senderName?: string;
+    isOwner: boolean;
+}
+export declare function serializeStoredMessage(input: SerializeMessageInput): SerializedMessage;

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

@@ -0,0 +1,6 @@
+/** Maximum UTF-8 payload size for a human-authored message. */
+export declare const HUMAN_MESSAGE_TEXT_MAX_BYTES: number;
+/** Returns the encoded UTF-8 size used by the message API. */
+export declare function messageTextUtf8ByteLength(value: string): number;
+/** Whether human-authored message text fits the API's UTF-8 byte budget. */
+export declare function isHumanMessageTextWithinLimit(value: string): boolean;

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

@@ -0,0 +1,161 @@
+import { type MlsDevGroupHead } from './mlsDevGroup.js';
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+export declare const MLS_DEV_TEXT_PROTOCOL: "canon.mls.dev-text.v1";
+/** Text plus encrypted interactions (docs/design/encrypted-interactions.md §2.1). Fresh rooms only, immutable from birth. */
+export declare const MLS_DEV_TEXT_PROTOCOL_V2: "canon.mls.dev-text.v2";
+/** v2 plus a text's reply and mentions inside the ciphertext (docs/design/mls-payload-v3.md §2). What Canon births. */
+export declare const MLS_DEV_TEXT_PROTOCOL_V3: "canon.mls.dev-text.v3";
+export declare const MLS_DEV_TEXT_PROTOCOLS: readonly ["canon.mls.dev-text.v1", "canon.mls.dev-text.v2", "canon.mls.dev-text.v3"];
+export type MlsDevTextProtocol = typeof MLS_DEV_TEXT_PROTOCOLS[number];
+export declare function isMlsDevTextProtocol(value: unknown): value is MlsDevTextProtocol;
+/** Whether a room carries encrypted cards: v2, and v3, which is v2 with richer text. */
+export declare function mlsDevProtocolCarriesCards(value: unknown): boolean;
+export declare const MLS_DEV_REPLY_QUOTE_MAX_CHARACTERS = 1024;
+export declare const MLS_DEV_MENTIONS_MAX = 32;
+/** Shared with Functions' runtime request ids (`RUNTIME_ID_PATTERN`): the runner's `ask-<sha256>` fits. */
+export declare const MLS_DEV_INTERACTION_ID_PATTERN: RegExp;
+export declare const MLS_DEV_INTERACTION_KINDS: readonly ["approval", "question", "secret"];
+export type MlsDevInteractionKind = typeof MLS_DEV_INTERACTION_KINDS[number];
+export declare const MLS_DEV_APPLICATION_TLS_MAX_BYTES: number;
+export declare const MLS_DEV_APPLICATION_MAX_BYTES: number;
+export declare const MLS_DEV_TEXT_MAX_BYTES: number;
+export interface MlsDevApplicationPreconditions {
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+}
+/** Public, device-signed and MLS-authenticated interaction routing (§2.2). Only a v2 room accepts it. The requester is
+ * the authenticated sender principal; titles, options, answers, decisions and scope stay in the encrypted payload. */
+export type MlsDevInteractionBinding = {
+    readonly role: 'request';
+    readonly requestId: string;
+    readonly kind: MlsDevInteractionKind;
+    readonly responderIds: readonly [string];
+    readonly expiresAtMs: number;
+} | {
+    readonly role: 'response';
+    readonly requestId: string;
+    readonly agentId: string;
+} | {
+    readonly role: 'withdraw';
+    readonly requestId: string;
+};
+export interface MlsDevApplicationBinding {
+    readonly version: 1;
+    readonly environmentId: MlsEnvironmentId;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly senderCredential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevApplicationPreconditions;
+    /** Absent for text. Framed after `preconditions` into the proof, envelope hash and MLS AAD. */
+    readonly interaction?: MlsDevInteractionBinding;
+}
+export interface MlsDevApplicationUnsignedEnvelope extends MlsDevApplicationBinding {
+    readonly ciphertext: string;
+}
+export interface MlsDevApplicationEnvelope extends MlsDevApplicationUnsignedEnvelope {
+    readonly proof: string;
+}
+export interface MlsDevApplicationReceipt {
+    readonly version: 1;
+    readonly authorization: 'encrypted_text_only';
+    readonly operationId: string;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly feedOrdinal: number;
+    readonly head: MlsDevGroupHead;
+    readonly acceptedAtMs: number;
+    readonly envelopeHash: string;
+}
+export interface MlsDevTextPayload {
+    readonly version: 1;
+    readonly kind: 'text';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly text: string;
+    /** v3 only: the message replied to, with an excerpt a device admitted after it can still show. */
+    readonly replyTo?: {
+        readonly messageId: string;
+        readonly quote: string;
+    };
+    /** v3 only: the accounts the text mentions, 1 to 32, each once. */
+    readonly mentions?: readonly string[];
+}
+/** The media kinds an encrypted item carries (payload v3 §2). Contact cards and artifacts are not items yet. */
+export declare const MLS_DEV_ITEM_TYPES: readonly ["image", "video", "audio", "file"];
+/**
+ * An item's reference inside the ciphertext. Its bytes stay in Canon's media pipeline and are not end-to-end
+ * encrypted; `url` is the upload's bearer download URL, which only the room's members receive this way. The file
+ * name and caption reach Canon only here, encrypted.
+ */
+export interface MlsDevItem {
+    readonly type: typeof MLS_DEV_ITEM_TYPES[number];
+    readonly uploadId: string;
+    readonly url: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+    readonly fileName?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly durationMs?: number;
+    readonly thumbnailUrl?: string;
+    readonly caption?: string;
+    /** As a v3 text's: the message replied to, with its excerpt, and the accounts mentioned. They ride inside the item,
+     * which native carries opaquely. */
+    readonly replyTo?: MlsDevTextPayload['replyTo'];
+    readonly mentions?: readonly string[];
+}
+export interface MlsDevItemPayload {
+    readonly version: 1;
+    readonly kind: 'item';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly item: MlsDevItem;
+}
+/** Public projection only. Plaintext is produced locally after authenticated MLS receive. */
+export interface MlsDevMessageReference {
+    readonly version: 1;
+    readonly protocol: MlsDevTextProtocol;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly feedOrdinal: number;
+    readonly head: MlsDevGroupHead;
+    readonly envelopeHash: string;
+    /** The public binding's role only, so triggers can withhold previews, pushes and unread counts from answers. */
+    readonly interaction?: {
+        readonly role: MlsDevInteractionBinding['role'];
+    };
+}
+export declare class MlsDevApplicationValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_APPLICATION";
+    constructor();
+}
+/** An encrypted message's ID: an endpoint ID that is not a membership notice's (`membership-<revision>`). */
+export declare function isMlsDevMessageId(value: unknown): value is string;
+/** Parses the closed public interaction binding (§2.2); the field order here is the framed order. */
+export declare function parseMlsDevInteractionBinding(value: unknown): MlsDevInteractionBinding;
+export declare function parseMlsDevApplicationWire(value: unknown): string;
+export declare function parseMlsDevApplicationPreconditions(value: unknown): MlsDevApplicationPreconditions;
+export declare function parseMlsDevApplicationBinding(value: unknown): MlsDevApplicationBinding;
+export declare function parseMlsDevApplicationUnsignedEnvelope(value: unknown): MlsDevApplicationUnsignedEnvelope;
+export declare function parseMlsDevApplicationEnvelope(value: unknown): MlsDevApplicationEnvelope;
+export declare function parseMlsDevApplicationReceipt(value: unknown): MlsDevApplicationReceipt;
+export declare function parseMlsDevTextPayload(value: unknown): MlsDevTextPayload;
+/** An encrypted item (payload v3 §2): its reference and caption, as the ciphertext carries them. */
+export declare function parseMlsDevItemPayload(value: unknown): MlsDevItemPayload;
+export declare function parseMlsDevMessageReference(value: unknown): MlsDevMessageReference;
+/** `domain`, then the operation ID and the JSON value, each behind its 4-byte big-endian length: the bytes Canon's MLS
+ * proofs sign. */
+export declare function frameMlsDevStatement(domain: string, value: unknown, operationId: string): Uint8Array;
+export declare function encodeMlsDevApplicationProof(value: unknown, operationId: string): Uint8Array;
+export declare function encodeMlsDevApplicationEnvelopeHash(value: unknown, operationId: string): Uint8Array;
+export declare function encodeMlsDevApplicationAad(value: unknown, operationId: string): Uint8Array;

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

@@ -0,0 +1,78 @@
+import { type MlsDevEnrollmentDevice } from './mlsDevEnrollment.js';
+import { type MlsEnvironmentId, type MlsIssuerId } from './mlsEnvironment.js';
+export declare const MLS_DEV_CREDENTIAL_TTL_MS = 86400000;
+export declare const MLS_DEV_CREDENTIAL_CHALLENGE_TTL_MS = 300000;
+export declare const MLS_DEV_CREDENTIAL_MAX_BYTES = 8192;
+export interface MlsDevCredentialClaims {
+    readonly version: 1;
+    readonly credentialId: string;
+    /** The device's environment's issuer (`MLS_ENVIRONMENT_PROFILES`). */
+    readonly issuer: MlsIssuerId;
+    readonly device: MlsDevEnrollmentDevice;
+    readonly generation: number;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MlsDevCredentialUnsigned {
+    readonly keyVersion: string;
+    readonly claims: MlsDevCredentialClaims;
+}
+export interface MlsDevCredentialChallenge {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly nonce: string;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+    readonly credential: MlsDevCredentialUnsigned;
+}
+export interface MlsDevCredentialBeginRequest {
+    readonly version: 1;
+    readonly deviceId: string;
+    readonly expectedCredentialGeneration: number;
+}
+export interface MlsDevCredentialCompleteRequest {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly proof: string;
+}
+export interface MlsDevCredentialReceipt {
+    readonly version: 1;
+    readonly authorization: 'device_credential_only';
+    readonly credential: string;
+}
+export interface MlsDevCredentialRevokeRequest {
+    readonly version: 1;
+    readonly deviceId: string;
+}
+export interface MlsDevCredentialRevocationReceipt {
+    readonly version: 1;
+    readonly authorization: 'device_revocation_only';
+    readonly deviceId: string;
+    readonly revokedAtMs: number;
+}
+export declare class MlsDevCredentialValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_CREDENTIAL";
+    constructor();
+}
+/** A version of an environment's issuer key: of `environmentId`'s when given, else of any declared environment's. */
+export declare function parseMlsDevIssuerKeyVersion(value: unknown, environmentId?: MlsEnvironmentId): string;
+export declare function parseMlsDevCredentialClaims(value: unknown): MlsDevCredentialClaims;
+export declare function parseMlsDevCredentialUnsigned(value: unknown): MlsDevCredentialUnsigned;
+export declare function parseMlsDevCredentialChallenge(value: unknown): MlsDevCredentialChallenge;
+export declare function parseMlsDevCredentialBegin(value: unknown): MlsDevCredentialBeginRequest;
+export declare function parseMlsDevCredentialComplete(value: unknown): MlsDevCredentialCompleteRequest;
+export declare function parseMlsDevCredentialRevoke(value: unknown): MlsDevCredentialRevokeRequest;
+export declare function parseMlsDevCredentialRevocationReceipt(value: unknown): MlsDevCredentialRevocationReceipt;
+export declare function createMlsDevCredentialSigningInput(value: MlsDevCredentialUnsigned): string;
+export declare function parseMlsDevCredentialSigningInput(value: unknown): MlsDevCredentialUnsigned;
+export declare function encodeMlsDevCredentialToken(unsigned: MlsDevCredentialUnsigned, signature: string): string;
+/** Structure only. Does not verify the signature, clock, revocation or authority. */
+export declare function parseMlsDevCredentialToken(value: unknown): Readonly<{
+    unsigned: MlsDevCredentialUnsigned;
+    signature: string;
+    signingInput: string;
+}>;
+/** Receipt parsing validates credential structure only, never its authority. */
+export declare function parseMlsDevCredentialReceipt(value: unknown): MlsDevCredentialReceipt;
+/** Device Ed25519 signs these domain-separated bytes directly, without prehash. */
+export declare function encodeMlsDevCredentialProof(value: MlsDevCredentialChallenge): Uint8Array;

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

@@ -0,0 +1,45 @@
+import { type MlsDevEnrollmentDevice } from './mlsDevEnrollment.js';
+/** Observations synchronize an intact device journal; they grant no authority. */
+export declare const MLS_DEV_CREDENTIAL_RECONCILIATION_CHALLENGE_TTL_MS = 300000;
+export declare const MLS_DEV_CREDENTIAL_RECONCILIATION_MAX_BYTES = 8192;
+export interface MlsDevCredentialReconciliationBeginRequest {
+    readonly version: 1;
+    readonly deviceId: string;
+    readonly requestId: string;
+    readonly expectedCredentialGeneration: number;
+}
+export interface MlsDevCredentialReconciliationChallenge {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly requestId: string;
+    readonly nonce: string;
+    readonly device: MlsDevEnrollmentDevice;
+    readonly expectedCredentialGeneration: number;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MlsDevCredentialReconciliationCompleteRequest {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly proof: string;
+}
+export interface MlsDevCredentialReconciliationReceipt {
+    readonly version: 1;
+    readonly authorization: 'credential_generation_observation_only';
+    readonly challenge: MlsDevCredentialReconciliationChallenge;
+    readonly observedCredentialGeneration: number;
+    readonly observedAtMs: number;
+}
+export declare class MlsDevCredentialReconciliationValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_CREDENTIAL_RECONCILIATION";
+    constructor();
+}
+export declare function parseMlsDevCredentialReconciliationBegin(value: unknown): MlsDevCredentialReconciliationBeginRequest;
+export declare function parseMlsDevCredentialReconciliationChallenge(value: unknown): MlsDevCredentialReconciliationChallenge;
+export declare function parseMlsDevCredentialReconciliationComplete(value: unknown): MlsDevCredentialReconciliationCompleteRequest;
+/** Structure only. The caller must authenticate the server response separately.
+ * Neither this receipt nor its generation establishes credential/current status. */
+export declare function parseMlsDevCredentialReconciliationReceipt(value: unknown): MlsDevCredentialReconciliationReceipt;
+/** Fixed Ed25519, no prehash: domain || u32be(JSON byte length) || closed JSON.
+ * Signers reconstruct the canonical challenge; no caller-supplied bytes enter. */
+export declare function encodeMlsDevCredentialReconciliationProof(value: MlsDevCredentialReconciliationChallenge): Uint8Array;

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

@@ -0,0 +1,52 @@
+import { type MlsDevEnrollmentChallenge, type MlsDevEnrollmentPrincipal, type MlsDevEnrollmentResult } from './mlsDevEnrollment.js';
+import { type MlsDevCredentialChallenge } from './mlsDevCredential.js';
+import { type MlsDevCredentialReconciliationChallenge } from './mlsDevCredentialReconciliation.js';
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+/** Synthetic Dev native bridge contracts; never an issuer or membership grant. */
+export declare const MLS_DEV_DEVICE_CONTEXT_MAX_BYTES = 2048;
+export declare const MLS_DEV_DEVICE_COMMAND_MAX_BYTES = 16384;
+export declare const MLS_DEV_DEVICE_WRAPPED_STATE_MAX_BYTES = 6144;
+export interface MlsDevDeviceBinding {
+    readonly version: 1;
+    readonly environmentId: MlsEnvironmentId;
+    readonly principal: MlsDevEnrollmentPrincipal;
+    readonly installationId: string;
+}
+export interface MlsDevDeviceContext extends MlsDevDeviceBinding {
+    /** Current committed revision. The native result is wrapped at revision + 1. */
+    readonly revision: number;
+}
+export type MlsDevDeviceCommand = {
+    readonly op: 'create';
+} | {
+    readonly op: 'enrollment_proof';
+    readonly challenge: MlsDevEnrollmentChallenge;
+} | {
+    readonly op: 'credential_proof';
+    readonly challenge: MlsDevCredentialChallenge;
+    readonly registrationResult: MlsDevEnrollmentResult;
+    readonly expectedCredentialGeneration: number;
+} | {
+    readonly op: 'credential_reconciliation_proof';
+    readonly challenge: MlsDevCredentialReconciliationChallenge;
+    readonly expectedCredentialGeneration: number;
+};
+export interface MlsDevDevicePayload {
+    readonly signaturePublicKey: string;
+    /** Present only for proof commands; no raw key or private state crosses JS. */
+    readonly proof?: string;
+}
+export interface MlsDevDevicePreparation {
+    readonly wrappedState: string;
+    readonly payload: MlsDevDevicePayload;
+}
+export declare class MlsDevDeviceCustodyValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_DEVICE_CUSTODY";
+    constructor();
+}
+export declare function parseMlsDevDeviceBinding(value: unknown): MlsDevDeviceBinding;
+export declare function parseMlsDevDeviceContext(value: unknown): MlsDevDeviceContext;
+/** The host supplies time and private state; neither is accepted from JavaScript. */
+export declare function parseMlsDevDeviceCommand(value: unknown): MlsDevDeviceCommand;
+/** Structural validation only: the native host authenticates wrapped state. */
+export declare function parseMlsDevDevicePreparation(value: unknown, op: MlsDevDeviceCommand['op']): MlsDevDevicePreparation;

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

@@ -0,0 +1,75 @@
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+/** Dev device-key registration only. These records are not MLS issuer credentials. */
+export declare const MLS_DEV_ENROLLMENT_CHALLENGE_TTL_MS = 300000;
+export declare const MLS_DEV_ENROLLMENT_MAX_BYTES = 4096;
+export type MlsDevEnrollmentPrincipal = {
+    readonly type: 'human';
+    readonly id: string;
+} | {
+    readonly type: 'ai_agent';
+    readonly id: string;
+    readonly ownershipVersion: number;
+};
+export interface MlsDevEnrollmentBeginRequest {
+    readonly version: 1;
+    readonly installationId: string;
+    readonly signaturePublicKey: string;
+}
+export interface MlsDevEnrollmentCompleteRequest {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly proof: string;
+}
+export interface MlsDevEnrollmentChallenge {
+    readonly version: 1;
+    readonly challengeId: string;
+    readonly deviceId: string;
+    readonly environmentId: MlsEnvironmentId;
+    readonly principal: MlsDevEnrollmentPrincipal;
+    readonly installationId: string;
+    readonly ciphersuite: 1;
+    readonly signatureScheme: 'ed25519';
+    readonly signaturePublicKey: string;
+    readonly nonce: string;
+    readonly issuedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MlsDevEnrollmentDevice {
+    readonly version: 1;
+    readonly deviceId: string;
+    readonly environmentId: MlsEnvironmentId;
+    readonly principal: MlsDevEnrollmentPrincipal;
+    readonly installationId: string;
+    readonly ciphersuite: 1;
+    readonly signatureScheme: 'ed25519';
+    readonly signaturePublicKey: string;
+    readonly registeredAtMs: number;
+}
+export interface MlsDevEnrollmentResult {
+    readonly version: 1;
+    readonly authorization: 'registration_only';
+    readonly device: MlsDevEnrollmentDevice;
+}
+export declare class MlsDevEnrollmentValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_ENROLLMENT";
+    constructor();
+}
+/** Shared exact identity parsing for the separate protected Dev signing boundary. */
+export declare function parseMlsDevEnrollmentPrincipal(value: unknown): MlsDevEnrollmentPrincipal;
+export declare function parseMlsDevInstallationId(value: unknown): string;
+export declare function parseMlsDevEnrollmentBegin(value: unknown): MlsDevEnrollmentBeginRequest;
+export declare function parseMlsDevEnrollmentComplete(value: unknown): MlsDevEnrollmentCompleteRequest;
+export declare function parseMlsDevEnrollmentChallenge(value: unknown): MlsDevEnrollmentChallenge;
+export declare function parseMlsDevEnrollmentResult(value: unknown): MlsDevEnrollmentResult;
+/** Canonical unpadded base64url; uses no Node-only or browser-only APIs. */
+export declare function encodeCanonicalMlsBase64Url(bytes: Uint8Array): string;
+export declare function decodeCanonicalMlsBase64Url(value: unknown, expectedBytes: number): Uint8Array;
+/**
+ * Ed25519 signs these bytes directly (no extra prehash). Version 1 uses the
+ * domain below, u16 version, LP environment, u8 principal tag (human 0/agent 1),
+ * LP principal id, agent-only u64 ownership version, LP installation id, raw
+ * UUID device/challenge ids, u16 suite, raw key/nonce, u64 issued/expiry times.
+ * LP is u32 byte length followed by UTF-8; all integers are big endian.
+ * The signature scheme is fixed by the validated version/suite, not negotiated.
+ */
+export declare function encodeMlsDevEnrollmentProof(value: MlsDevEnrollmentChallenge): Uint8Array;

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

@@ -0,0 +1,43 @@
+import type { MlsDevGroupFeedEntry } from './mlsDevGroupFeed.js';
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+/**
+ * Signed acceptance times (docs/design/mls-signed-acceptance.md): when Canon accepts an MLS feed entry it signs the
+ * time, with the environment's feed-receipt key, so a device judges the entry's sender at that time instead of by its
+ * own clock. The proof travels beside the entry; the receipt and the accepted control themselves are unchanged.
+ */
+export declare const MLS_DEV_FEED_RECEIPT_DOMAIN = "canon.mls.feed-receipt.v1\0";
+/** What Canon signs for one accepted entry, in this field order. `entryHash` binds the exact accepted bytes: an
+ * application's `envelopeHash`, or an accepted control's `head.hash`. */
+export interface MlsDevFeedReceiptStatement {
+    readonly environmentId: MlsEnvironmentId;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly feedOrdinal: number;
+    readonly kind: 'application' | 'control';
+    readonly entryHash: string;
+    readonly acceptedAtMs: number;
+}
+export interface MlsDevFeedReceiptProof {
+    /** A version of the environment's feed-receipt key. */
+    readonly keyVersion: string;
+    /** Ed25519 over `encodeMlsDevFeedReceipt`, canonical base64url. */
+    readonly signature: string;
+}
+export declare class MlsDevFeedReceiptValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_FEED_RECEIPT";
+    constructor();
+}
+export declare function parseMlsDevReceiptKeyVersion(value: unknown, environmentId?: MlsEnvironmentId): string;
+export declare function parseMlsDevFeedReceiptProof(value: unknown): MlsDevFeedReceiptProof;
+/** The statement for an accepted feed entry, in the environment that accepted it. */
+export declare function mlsDevFeedReceiptStatement(entry: MlsDevGroupFeedEntry, environmentId: MlsEnvironmentId): {
+    statement: MlsDevFeedReceiptStatement;
+    operationId: string;
+};
+/** The exact bytes the feed-receipt key signs: the statement framed under its domain and the entry's operation. */
+export declare function encodeMlsDevFeedReceipt(statement: MlsDevFeedReceiptStatement, operationId: string): Uint8Array;
+/** Native refuses, for now, an entry Canon accepted more than 10 minutes ahead of this device's clock: a retryable
+ * pause, never a room failure (mls-signed-acceptance.md §2.9). */
+export declare const MLS_DEV_GROUP_RECEIPT_CLOCK_SKEW = "MLS_DEV_GROUP_RECEIPT_CLOCK_SKEW";
+/** Whether a native or custody response is exactly that pause (the portable helper adds `version: 1`). */
+export declare function isMlsDevReceiptClockSkew(value: unknown): boolean;