@canonmsg/agent-sdk 11.2.0 → 12.0.0

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

@@ -0,0 +1,75 @@
+import { type MlsDevEnrollmentDevice } from './mlsDevEnrollment.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;
+    readonly issuer: 'canon-mls-dev-v1';
+    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();
+}
+export declare function parseMlsDevIssuerKeyVersion(value: unknown): 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,51 @@
+import { type MlsDevEnrollmentChallenge, type MlsDevEnrollmentPrincipal, type MlsDevEnrollmentResult } from './mlsDevEnrollment.js';
+import { type MlsDevCredentialChallenge } from './mlsDevCredential.js';
+import { type MlsDevCredentialReconciliationChallenge } from './mlsDevCredentialReconciliation.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: 'canon-dev-v1';
+    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,74 @@
+/** 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: 'canon-dev-v1';
+    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: 'canon-dev-v1';
+    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/mlsDevGroup.d.ts

@@ -0,0 +1,197 @@
+import { MLS_DEV_TEXT_PROTOCOL, type MlsDevApplicationEnvelope, type MlsDevApplicationPreconditions } from './mlsDevApplication.js';
+import { type MlsDevGroupFeedApplicationEntry } from './mlsDevGroupFeed.js';
+import { type MlsDevEnrollmentDevice } from './mlsDevEnrollment.js';
+import { type MlsDevKeyPackageClaimReceipt } from './mlsDevKeyPackages.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?: typeof MLS_DEV_TEXT_PROTOCOL;
+    };
+}
+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: 'canon-dev-v1';
+    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;
+}
+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: 'canon-dev-v1';
+    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?: typeof MLS_DEV_TEXT_PROTOCOL;
+}
+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;
+} | {
+    readonly op: 'process_application';
+    readonly entry: MlsDevGroupFeedApplicationEntry;
+} | {
+    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;
+    readonly keyPackageId: string;
+} | {
+    readonly op: 'process';
+    readonly credential: string;
+    readonly accepted: MlsDevGroupAcceptedControl;
+};
+export type MlsDevGroupPayload = {
+    readonly kind: 'application';
+    readonly envelope: MlsDevApplicationEnvelope;
+} | {
+    readonly kind: 'text';
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly text: string;
+    readonly feedOrdinal: number;
+} | {
+    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[];
+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 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,47 @@
+import { type MlsDevGroupAcceptedControl, type MlsDevGroupMarker, type MlsDevGroupRosterEntry } from './mlsDevGroup.js';
+import { MLS_DEV_TEXT_PROTOCOL, type MlsDevApplicationEnvelope, type MlsDevApplicationReceipt } from './mlsDevApplication.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;
+}
+export interface MlsDevGroupFeedApplicationEntry {
+    readonly version: 1;
+    readonly ordinal: number;
+    readonly kind: 'application';
+    readonly receipt: MlsDevApplicationReceipt;
+    readonly envelope: MlsDevApplicationEnvelope;
+}
+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: typeof MLS_DEV_TEXT_PROTOCOL;
+    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/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/moderation.d.ts

@@ -0,0 +1,7 @@
+export type ModerationStatus = 'active' | 'ejected';
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+export declare function readModerationStatus(data: unknown): ModerationStatus;

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

@@ -0,0 +1,63 @@
+/** Existing server content readers. Classification is not encryption: these
+ * processors intentionally inspect plaintext in the current JSON release.
+ * Their input boundary must be redesigned before enabling encrypted rooms. */
+export declare const PLAINTEXT_PROCESSORS: {
+    readonly preview: {
+        readonly current: "Read message/display text to derive conversation and notification previews.";
+        readonly beforeMls: "Derive on authorized endpoints; clear/reconcile deleted-message previews there.";
+    };
+    readonly push: {
+        readonly current: "Send visible titles and message previews to FCM/APNs.";
+        readonly beforeMls: "Use generic wake notifications or endpoint-decrypted notification extensions.";
+    };
+    readonly topic: {
+        readonly current: "Derive the initial topic from message text.";
+        readonly beforeMls: "Derive on an authorized endpoint and publish as encrypted conversation content.";
+    };
+    readonly forward: {
+        readonly current: "Read source content and copy plaintext attachments into the target room.";
+        readonly beforeMls: "Decrypt and re-encrypt on an authorized endpoint; keep server target admission checks.";
+    };
+    readonly message_validation: {
+        readonly current: "Inspect text, attachment descriptors and rich content before storing messages.";
+        readonly beforeMls: "Validate decrypted content on endpoints; retain bounded ciphertext/envelope checks on the server.";
+    };
+    readonly interaction_validation: {
+        readonly current: "Validate card/input/approval/plan render contracts and submitted responses.";
+        readonly beforeMls: "Validate content on authorized requesting/responding endpoints; retain public admission and lifecycle checks.";
+    };
+    readonly image_generation: {
+        readonly current: "Send prompts/source image bytes to Vertex and persist generated output.";
+        readonly beforeMls: "Require explicit provider disclosure and an authorized endpoint/processing participant; no silent server decryption.";
+    };
+    readonly media_assembly: {
+        readonly current: "Decode prepared JSON and combine ordered accepted blob descriptors into canonical publication.";
+        readonly beforeMls: "Pass an immutable encrypted envelope without interpreting or rewriting it; private blob metadata stays inside the payload.";
+    };
+    readonly streaming: {
+        readonly current: "Validate and publish plaintext live text, chunks and provisional content.";
+        readonly beforeMls: "Encrypt and validate streaming content on authorized endpoints with explicit ordering and key-epoch boundaries.";
+    };
+    readonly video_processing: {
+        readonly current: "Download plaintext video, normalize it and create a poster.";
+        readonly beforeMls: "Process on an endpoint or an explicitly authorized processing participant before encrypted upload.";
+    };
+    readonly owner_observation: {
+        readonly current: "Allow authenticated owners to inspect managed agent conversations without room membership.";
+        readonly beforeMls: "Explicitly enroll authorized owner keyholders or retire content observation; ownership alone supplies no decryption keys.";
+    };
+    readonly moderation_evidence: {
+        readonly current: "Accept user-selected plaintext message evidence for moderation.";
+        readonly beforeMls: "Design explicit selective disclosure/authenticity (including franking policy); never infer access to room keys.";
+    };
+};
+export type PlaintextProcessorName = keyof typeof PLAINTEXT_PROCESSORS;
+export interface PlaintextProcessorInput<T> {
+    encoding: 'json';
+    value: T;
+}
+/** The callback is the actual content processor, not a telemetry hook. Keeping
+ * the codec explicit ensures an opaque body cannot accidentally be processed by
+ * the JSON path. This is not authorization; callers still enforce their domain
+ * policy and every enabled transport currently requires JSON. */
+export declare function runPlaintextProcessor<T, R>(name: PlaintextProcessorName, input: PlaintextProcessorInput<T>, process: (value: T) => R): R;