@continuonai/rcan-ts 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # rcan-ts
 
-Official TypeScript SDK for the **RCAN v1.5** Robot Communication and Addressing Network protocol.
+Official TypeScript SDK for the **RCAN v1.6** Robot Communication and Addressing Network protocol.
 
 [![npm version](https://badge.fury.io/js/%40continuonai%2Frcan-ts.svg)](https://www.npmjs.com/package/@continuonai/rcan-ts)
 [![CI](https://github.com/continuonai/rcan-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/continuonai/rcan-ts/actions)

package/dist/browser.d.mts

@@ -121,6 +121,12 @@ interface RCANMessageData {
     proximityMeters?: number;
     /** v1.5: GAP-15 observer */
     readOnly?: boolean;
+    /** v1.6: GAP-14 level of assurance */
+    loa?: number;
+    /** v1.6: GAP-17 transport encoding hint */
+    transportEncoding?: string;
+    /** v1.6: GAP-18 multi-modal media chunks */
+    mediaChunks?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 }
 declare class RCANMessageError extends Error {
@@ -147,6 +153,12 @@ declare class RCANMessage {
     readonly presenceVerified: boolean | undefined;
     readonly proximityMeters: number | undefined;
     readonly readOnly: boolean | undefined;
+    /** v1.6: GAP-14 level of assurance */
+    readonly loa: number | undefined;
+    /** v1.6: GAP-17 transport encoding hint */
+    readonly transportEncoding: string | undefined;
+    /** v1.6: GAP-18 multi-modal media chunks */
+    readonly mediaChunks: Array<Record<string, unknown>> | undefined;
     constructor(data: RCANMessageData);
     /** Whether this message has a signature block */
     get isSigned(): boolean;
@@ -714,7 +726,9 @@ declare function makeTransparencyMessage(ruri: string, disclosure: string, deleg
  * §3.5 — Protocol Version Compatibility
  */
 /** The RCAN spec version this SDK implements. */
-declare const SPEC_VERSION = "1.5";
+declare const SPEC_VERSION = "1.6";
+/** The SDK release version. */
+declare const SDK_VERSION = "0.6.0";
 /**
  * Validate version compatibility.
  *
@@ -1176,15 +1190,246 @@ interface AuditExportRequest {
 }
 
 /**
- * rcan-ts — Official TypeScript SDK for RCAN v1.5
+ * RCAN Identity & Level of Assurance (LoA) — GAP-14.
+ *
+ * Provides JWT-based LoA extraction and per-scope policy enforcement.
+ * Backward compatible: DEFAULT_LOA_POLICY requires only ANONYMOUS (LoA 1).
+ */
+declare enum LevelOfAssurance {
+    ANONYMOUS = 1,
+    EMAIL_VERIFIED = 2,
+    HARDWARE_TOKEN = 3
+}
+interface LoaPolicy {
+    minLoaDiscover: LevelOfAssurance;
+    minLoaStatus: LevelOfAssurance;
+    minLoaChat: LevelOfAssurance;
+    minLoaControl: LevelOfAssurance;
+    minLoaSafety: LevelOfAssurance;
+}
+/** Backward-compatible policy — every scope accepts anonymous callers. */
+declare const DEFAULT_LOA_POLICY: LoaPolicy;
+/** Production-hardened policy — control needs e-mail, safety needs hardware token. */
+declare const PRODUCTION_LOA_POLICY: LoaPolicy;
+/**
+ * Decode a JWT (header.payload.sig) and return the `loa` claim.
+ * Defaults to ANONYMOUS when the claim is absent or the token is malformed.
+ */
+declare function extractLoaFromJwt(token: string): LevelOfAssurance;
+/**
+ * Check whether `loa` satisfies the minimum required for `scope`.
+ *
+ * @param loa    - Caller's assurance level
+ * @param scope  - One of discover | status | chat | control | safety
+ * @param policy - Defaults to DEFAULT_LOA_POLICY (backward compatible)
+ */
+declare function validateLoaForScope(loa: LevelOfAssurance, scope: string, policy?: LoaPolicy): {
+    valid: boolean;
+    reason: string;
+};
+
+/**
+ * RCAN Federation — cross-registry trust and sync (GAP-16).
+ *
+ * Provides:
+ *  - Registry tier model (root / authoritative / community)
+ *  - TrustAnchorCache with 24-hour TTL and DNS-TXT discovery
+ *  - JWT verification against a trusted registry
+ *  - Cross-registry command validation (LoA ≥ 2 required; ESTOP always allowed)
+ */
+
+declare enum RegistryTier {
+    ROOT = "root",
+    AUTHORITATIVE = "authoritative",
+    COMMUNITY = "community"
+}
+declare enum FederationSyncType {
+    CONSENT = "consent",
+    REVOCATION = "revocation",
+    KEY = "key"
+}
+interface RegistryIdentity {
+    registryUrl: string;
+    tier: RegistryTier;
+    publicKeyPem: string;
+    domain: string;
+    verifiedAt?: string;
+}
+interface FederationSyncPayload {
+    sourceRegistry: string;
+    targetRegistry: string;
+    syncType: FederationSyncType;
+    payload: Record<string, unknown>;
+    signature: string;
+}
+/**
+ * In-memory cache of trusted registry identities.
+ *
+ * Entries expire after 24 hours. Discovery via DNS TXT records
+ * (_rcan-registry.<domain>) is supported in Node.js environments.
+ */
+declare class TrustAnchorCache {
+    private readonly store;
+    /** Store or refresh a registry identity. */
+    set(identity: RegistryIdentity): void;
+    /**
+     * Look up a registry URL.
+     * Returns undefined when absent or when the TTL has expired.
+     */
+    lookup(url: string): RegistryIdentity | undefined;
+    /**
+     * Discover a registry via DNS TXT record `_rcan-registry.<domain>`.
+     *
+     * The TXT record is expected to contain a JSON object with the
+     * RegistryIdentity fields. Returns the identity and caches it.
+     *
+     * Node.js only — returns undefined in environments without `dns.promises`.
+     */
+    discoverViaDns(domain: string): Promise<RegistryIdentity | undefined>;
+    /**
+     * Verify a JWT was issued by the registry at `url`.
+     *
+     * Validates the `iss` claim and checks the registry is in the trust cache.
+     * Full cryptographic signature verification requires the registry's public
+     * key material — callers should perform additional checks using `publicKeyPem`
+     * from the returned identity.
+     */
+    verifyRegistryJwt(token: string, url: string): Promise<RegistryIdentity>;
+}
+/**
+ * Build a FEDERATION_SYNC message (MessageType 12).
+ */
+declare function makeFederationSync(source: string, target: string, syncType: FederationSyncType, payload: FederationSyncPayload): RCANMessage;
+/**
+ * Validate a cross-registry command against the local trust anchor cache.
+ *
+ * Rules:
+ *  - ESTOP (SAFETY type 6 or cmd=estop) always returns valid (P66 invariant).
+ *  - All other cross-registry commands require LoA ≥ 2 (EMAIL_VERIFIED).
+ *  - If the message originates from `localRegistry` it is not cross-registry.
+ */
+declare function validateCrossRegistryCommand(msg: RCANMessage, localRegistry: string, trustCache: TrustAnchorCache): Promise<{
+    valid: boolean;
+    reason: string;
+}>;
+
+/**
+ * RCAN Constrained-Transport Encodings — GAP-17.
+ *
+ * Provides compact JSON, 32-byte minimal (ESTOP-only), BLE frame fragmentation,
+ * and a transport-selection helper. No external runtime dependencies.
+ */
+
+declare class TransportError extends Error {
+    constructor(message: string);
+}
+declare enum TransportEncoding {
+    HTTP = "http",
+    COMPACT = "compact",
+    MINIMAL = "minimal",
+    BLE = "ble"
+}
+/** Serialize a RCANMessage to compact JSON bytes. */
+declare function encodeCompact(message: RCANMessage): Uint8Array;
+/** Deserialize compact JSON bytes to a RCANMessage. */
+declare function decodeCompact(data: Uint8Array): RCANMessage;
+/**
+ * Encode a SAFETY (type 6) message to a 32-byte minimal frame.
+ *
+ * Layout: [2B type][8B from_hash][8B to_hash][4B unix32][8B sig_truncated][2B checksum]
+ *
+ * - Only SAFETY (type 6) messages are accepted; throws `TransportError` for others.
+ * - Runtime assertion: output MUST be exactly 32 bytes.
+ */
+declare function encodeMinimal(message: RCANMessage): Promise<Uint8Array>;
+/**
+ * Decode a 32-byte minimal frame to a partial RCANMessage.
+ */
+declare function decodeMinimal(data: Uint8Array): Partial<RCANMessage>;
+/**
+ * Fragment a RCANMessage into BLE advertisement frames.
+ * Compact JSON encoding is used for the payload; each chunk is ≤ `mtu` bytes.
+ */
+declare function encodeBleFrames(message: RCANMessage, mtu?: number): Uint8Array[];
+/**
+ * Reassemble BLE frames (in order) into a RCANMessage.
+ */
+declare function decodeBleFrames(frames: Uint8Array[]): RCANMessage;
+/**
+ * Select the most appropriate transport encoding from an availability list.
+ *
+ * Priority:
+ *  - SAFETY (type 6) messages: prefer MINIMAL → BLE → COMPACT → HTTP
+ *  - All others: prefer HTTP → COMPACT → BLE
+ */
+declare function selectTransport(available: TransportEncoding[], message: RCANMessage): TransportEncoding;
+
+/**
+ * RCAN Multi-modal Data — GAP-18.
+ *
+ * Provides inline and by-reference media attachment for RCANMessage,
+ * streaming chunk helpers, and training-data message construction.
+ * SHA-256 is computed via the Web Crypto API (built-in Node 18+).
+ */
+
+declare enum MediaEncoding {
+    BASE64 = "base64",
+    REF = "ref"
+}
+interface MediaChunk {
+    chunkId: string;
+    mimeType: string;
+    encoding: MediaEncoding;
+    hashSha256: string;
+    dataB64?: string;
+    refUrl?: string;
+    sizeBytes: number;
+}
+interface StreamChunk {
+    streamId: string;
+    chunkIndex: number;
+    isFinal: boolean;
+    chunk: MediaChunk;
+}
+/**
+ * Attach inline (base64-encoded) media to a message.
+ * SHA-256 is computed via Web Crypto API.
+ */
+declare function addMediaInline(message: RCANMessage, data: Uint8Array, mimeType: string): Promise<RCANMessage>;
+/**
+ * Attach a media reference (URL + pre-computed hash) to a message.
+ */
+declare function addMediaRef(message: RCANMessage, refUrl: string, mimeType: string, hashSha256: string, sizeBytes: number): RCANMessage;
+/**
+ * Validate media chunks on a message.
+ * Checks that inline chunks have dataB64 and ref chunks have refUrl.
+ */
+declare function validateMediaChunks(message: RCANMessage): Promise<{
+    valid: boolean;
+    reason: string;
+}>;
+/**
+ * Build a TRAINING_DATA message (MessageType 10) with multiple media attachments.
+ */
+declare function makeTrainingDataMessage(media: Array<{
+    data: Uint8Array;
+    mimeType: string;
+}>): Promise<RCANMessage>;
+/**
+ * Build a streaming chunk message wrapping a single media item.
+ */
+declare function makeStreamChunk(streamId: string, data: Uint8Array, mimeType: string, chunkIndex: number, isFinal: boolean): Promise<RCANMessage>;
+
+/**
+ * rcan-ts — Official TypeScript SDK for RCAN v1.6
  * Robot Communication and Accountability Network
  *
  * @see https://rcan.dev
  * @see https://github.com/continuonai/rcan-ts
  */
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.6.0";
 /** @deprecated Use SPEC_VERSION from ./version instead */
-declare const RCAN_VERSION = "1.5";
+declare const RCAN_VERSION = "1.6";
 
-export { type ApprovalStatus, AuditChain, AuditError, type AuditExportRequest, type CachedKey, type ChainVerifyResult, ClockDriftError, type ClockSyncStatus, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, ConfidenceGate, type ConsentRequestParams, type ConsentResponseParams, type ConsentType, DataCategory, type DelegationHop, FaultCode, type FaultReportParams, type FaultSeverity, GateError, HiTLGate, type JWKEntry, type JWKSDocument, KeyStore, type ListResult, MessageType, NodeClient, type OfflineCommandResult, OfflineModeManager, type OfflineState, type PendingApproval, QoSAckTimeoutError, QoSLevel, QoSManager, type QoSResult, type QoSSendOptions, RCANAddressError, type RCANAgentConfig, type RCANConfig, RCANConfigAuthorizationError, RCANDelegationChainError, RCANError, RCANGateError, RCANMessage, type RCANMessageData, type RCANMessageEnvelope, RCANMessageError, type RCANMetadata, RCANNodeError, RCANNodeNotFoundError, RCANNodeSyncError, RCANNodeTrustError, RCANRegistryError, type RCANRegistryNode, RCANReplayAttackError, type RCANResolveResult, RCANSignatureError, RCANValidationError, RCANVersionIncompatibleError, RCAN_VERSION, type RegistrationResult, RegistryClient, ReplayCache, type ReplayCheckResult, type ReplayableMessage, RevocationCache, type RevocationStatus, type RevocationStatusValue, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, SAFETY_MESSAGE_TYPE, SPEC_VERSION, type SafetyEvent, type SafetyMessage, type SenderType, type SignatureBlock, type TrainingConsentRequestParams, type TransparencyMessage, VERSION, type ValidationResult, addDelegationHop, assertClockSynced, checkClockSync, checkRevocation, fetchCanonicalSchema, isSafetyMessage, makeCloudRelayMessage, makeConfigUpdate, makeConsentDeny, makeConsentGrant, makeConsentRequest, makeEstopMessage, makeEstopWithQoS, makeFaultReport, makeKeyRotationMessage, makeResumeMessage, makeRevocationBroadcast, makeStopMessage, makeTrainingConsentDeny, makeTrainingConsentGrant, makeTrainingConsentRequest, makeTransparencyMessage, validateConfig, validateConfigAgainstSchema, validateConfigUpdate, validateConsentMessage, validateDelegationChain, validateMessage, validateNodeAgainstSchema, validateReplay, validateSafetyMessage, validateTrainingDataMessage, validateURI, validateVersionCompat };
+export { type ApprovalStatus, AuditChain, AuditError, type AuditExportRequest, type CachedKey, type ChainVerifyResult, ClockDriftError, type ClockSyncStatus, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, ConfidenceGate, type ConsentRequestParams, type ConsentResponseParams, type ConsentType, DEFAULT_LOA_POLICY, DataCategory, type DelegationHop, FaultCode, type FaultReportParams, type FaultSeverity, type FederationSyncPayload, FederationSyncType, GateError, HiTLGate, type JWKEntry, type JWKSDocument, KeyStore, LevelOfAssurance, type ListResult, type LoaPolicy, type MediaChunk, MediaEncoding, MessageType, NodeClient, type OfflineCommandResult, OfflineModeManager, type OfflineState, PRODUCTION_LOA_POLICY, type PendingApproval, QoSAckTimeoutError, QoSLevel, QoSManager, type QoSResult, type QoSSendOptions, RCANAddressError, type RCANAgentConfig, type RCANConfig, RCANConfigAuthorizationError, RCANDelegationChainError, RCANError, RCANGateError, RCANMessage, type RCANMessageData, type RCANMessageEnvelope, RCANMessageError, type RCANMetadata, RCANNodeError, RCANNodeNotFoundError, RCANNodeSyncError, RCANNodeTrustError, RCANRegistryError, type RCANRegistryNode, RCANReplayAttackError, type RCANResolveResult, RCANSignatureError, RCANValidationError, RCANVersionIncompatibleError, RCAN_VERSION, type RegistrationResult, RegistryClient, type RegistryIdentity, RegistryTier, ReplayCache, type ReplayCheckResult, type ReplayableMessage, RevocationCache, type RevocationStatus, type RevocationStatusValue, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, SAFETY_MESSAGE_TYPE, SDK_VERSION, SPEC_VERSION, type SafetyEvent, type SafetyMessage, type SenderType, type SignatureBlock, type StreamChunk, type TrainingConsentRequestParams, type TransparencyMessage, TransportEncoding, TransportError, TrustAnchorCache, VERSION, type ValidationResult, addDelegationHop, addMediaInline, addMediaRef, assertClockSynced, checkClockSync, checkRevocation, decodeBleFrames, decodeCompact, decodeMinimal, encodeBleFrames, encodeCompact, encodeMinimal, extractLoaFromJwt, fetchCanonicalSchema, isSafetyMessage, makeCloudRelayMessage, makeConfigUpdate, makeConsentDeny, makeConsentGrant, makeConsentRequest, makeEstopMessage, makeEstopWithQoS, makeFaultReport, makeFederationSync, makeKeyRotationMessage, makeResumeMessage, makeRevocationBroadcast, makeStopMessage, makeStreamChunk, makeTrainingConsentDeny, makeTrainingConsentGrant, makeTrainingConsentRequest, makeTrainingDataMessage, makeTransparencyMessage, selectTransport, validateConfig, validateConfigAgainstSchema, validateConfigUpdate, validateConsentMessage, validateCrossRegistryCommand, validateDelegationChain, validateLoaForScope, validateMediaChunks, validateMessage, validateNodeAgainstSchema, validateReplay, validateSafetyMessage, validateTrainingDataMessage, validateURI, validateVersionCompat };