@continuonai/rcan-ts 0.8.0 → 1.2.0

package/dist/index.d.mts

@@ -86,12 +86,18 @@ declare enum MessageType {
     CONTRIBUTE_RESULT = 34,
     CONTRIBUTE_CANCEL = 35,
     TRAINING_DATA = 36,
-    /** @deprecated Use FLEET_COMMAND (23) */
-    FEDERATION_SYNC = 23,
-    /** @deprecated Use FAULT_REPORT (26) */
-    ALERT = 26,
-    /** @deprecated Use TRANSPARENCY (16) */
-    AUDIT = 16
+    COMPETITION_ENTER = 37,
+    COMPETITION_SCORE = 38,
+    SEASON_STANDING = 39,
+    PERSONAL_RESEARCH_RESULT = 40,
+    /** authority → robot: EU AI Act Art. 16(j) audit data request */
+    AUTHORITY_ACCESS = 41,
+    /** robot → authority: audit data response */
+    AUTHORITY_RESPONSE = 42,
+    /** robot → RRF: publish signed firmware manifest */
+    FIRMWARE_ATTESTATION = 43,
+    /** robot → RRF: publish updated CycloneDX SBOM */
+    SBOM_UPDATE = 44
 }
 /** §8.5 — Sender Type and Service Identity */
 type SenderType = "robot" | "human" | "cloud_function" | "system";
@@ -108,6 +114,12 @@ interface SignatureBlock {
     kid: string;
     sig: string;
 }
+/** v2.2: Post-quantum (ML-DSA-65) signature block */
+interface PQSignatureBlock {
+    alg: "ml-dsa-65";
+    kid: string;
+    sig: string;
+}
 interface RCANMessageData {
     rcan?: string;
     /** v1.5: explicit protocol version field (defaults to SPEC_VERSION) */
@@ -142,6 +154,12 @@ interface RCANMessageData {
     transportEncoding?: string;
     /** v1.6: GAP-18 multi-modal media chunks */
     mediaChunks?: Array<Record<string, unknown>>;
+    /** v2.1: SHA-256 of sender's firmware manifest (envelope field 13). Required at L2+. */
+    firmwareHash?: string;
+    /** v2.1: URI to sender's SBOM attestation endpoint (envelope field 14). Required at L2+. */
+    attestationRef?: string;
+    /** v2.2: ML-DSA-65 post-quantum signature block (field 16, FIPS 204). Hybrid mode alongside Ed25519. */
+    pqSig?: PQSignatureBlock | undefined;
     [key: string]: unknown;
 }
 declare class RCANMessageError extends Error {
@@ -174,6 +192,12 @@ declare class RCANMessage {
     readonly transportEncoding: string | undefined;
     /** v1.6: GAP-18 multi-modal media chunks */
     readonly mediaChunks: Array<Record<string, unknown>> | undefined;
+    /** v2.1: SHA-256 of sender's firmware manifest */
+    readonly firmwareHash: string | undefined;
+    /** v2.1: URI to sender's SBOM attestation endpoint */
+    readonly attestationRef: string | undefined;
+    /** v2.2: ML-DSA-65 post-quantum signature (field 16, FIPS 204). Hybrid alongside Ed25519. */
+    readonly pqSig: PQSignatureBlock | undefined;
     constructor(data: RCANMessageData);
     /** Whether this message has a signature block */
     get isSigned(): boolean;
@@ -741,14 +765,13 @@ 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.9.0";
+declare const SPEC_VERSION = "2.2.0";
 /** The SDK release version. */
-declare const SDK_VERSION = "0.8.0";
+declare const SDK_VERSION = "1.2.0";
 /**
  * Validate version compatibility.
  *
- * A receiver MUST accept messages from senders with the same MAJOR version
- * and lower-or-equal MINOR version. MAJOR mismatch → incompatible.
+ * MAJOR must match. Lower-or-equal MINOR is acceptable.
  *
  * @param incomingVersion - The rcanVersion from the incoming message
  * @param localVersion    - The local SPEC_VERSION (defaults to SPEC_VERSION)
@@ -1012,7 +1035,7 @@ interface RevocationStatus {
 /**
  * RevocationCache — TTL-based cache for revocation status records.
  */
-declare class RevocationCache {
+declare class RevocationCache$1 {
     private readonly _cache;
     /** Get a cached status if still fresh */
     get(rrn: string, nowMs?: number): RevocationStatus | undefined;
@@ -1031,7 +1054,7 @@ declare class RevocationCache {
  * @param registryUrl - Base URL of the registry (e.g. "https://registry.rcan.dev")
  * @param cache       - Optional RevocationCache to use (creates ephemeral one if not provided)
  */
-declare function checkRevocation(rrn: string, registryUrl: string, cache?: RevocationCache): Promise<RevocationStatus>;
+declare function checkRevocation(rrn: string, registryUrl: string, cache?: RevocationCache$1): Promise<RevocationStatus>;
 /**
  * Build a ROBOT_REVOCATION broadcast message.
  *
@@ -1205,43 +1228,94 @@ interface AuditExportRequest {
 }
 
 /**
- * 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
+ * rcan/identity — RCAN v2.1 Role-Based Access Control and Identity.
+ *
+ * Defines the seven-level role hierarchy (§2), JWT claim parsing, scope
+ * validation, and identity record types.
+ *
+ * Roles (v2.1):
+ *   GUEST        (JWT 1)   — read-only, anonymous
+ *   OPERATOR     (JWT 2)   — operational control
+ *   CONTRIBUTOR  (JWT 2.5) — idle compute donation scope
+ *   ADMIN        (JWT 3)   — configuration, user management
+ *   M2M_PEER     (JWT 4)   — robot-to-robot; issued by ADMIN
+ *   CREATOR      (JWT 5)   — full hardware/software control
+ *   M2M_TRUSTED  (JWT 6)   — fleet orchestration; RRF-issued only
+ *
+ * Spec: §2 — Role-Based Access Control
+ */
+/** RCAN v2.1 role hierarchy. Use ROLE_JWT_LEVEL to map to JWT level values. */
+declare enum Role {
+    GUEST = 1,
+    OPERATOR = 2,
+    CONTRIBUTOR = 3,// JWT level 2.5
+    ADMIN = 4,// JWT level 3
+    M2M_PEER = 5,// JWT level 4
+    CREATOR = 6,// JWT level 5
+    M2M_TRUSTED = 7
+}
+/** @deprecated Use Role instead. Kept for v1.x backward compatibility. */
+declare const LevelOfAssurance: typeof Role;
+type LevelOfAssurance = Role;
+/** Maps Role enum value to JWT rcan_role level (fractional for CONTRIBUTOR). */
+declare const ROLE_JWT_LEVEL: Record<Role, number>;
+/** Return the Role for a JWT rcan_role numeric level, or undefined. */
+declare function roleFromJwtLevel(level: number): Role | undefined;
+declare const SCOPE_MIN_ROLE: Record<string, Role>;
+interface IdentityRecord {
+    /** Subject identifier (UUID, RRN, or orchestrator id). */
+    sub: string;
+    /** RCAN v2.1 Role. */
+    role: Role;
+    /** JWT-level value for this role. */
+    jwtLevel: number;
+    /** Registry that issued this identity. */
+    registryUrl?: string;
+    /** Granted scopes. */
+    scopes: string[];
+    /** UTC ISO-8601 timestamp of most recent verification. */
+    verifiedAt?: string;
+    /** For M2M_PEER tokens — the authorized peer's RRN. */
+    peerRrn?: string;
+    /** For M2M_TRUSTED tokens — explicit fleet allowlist. */
+    fleetRrns?: string[];
 }
 interface LoaPolicy {
-    minLoaDiscover: LevelOfAssurance;
-    minLoaStatus: LevelOfAssurance;
-    minLoaChat: LevelOfAssurance;
-    minLoaControl: LevelOfAssurance;
-    minLoaSafety: LevelOfAssurance;
+    minRoleForDiscover: Role;
+    minRoleForStatus: Role;
+    minRoleForChat: Role;
+    minRoleForControl: Role;
+    minRoleForSafety: Role;
 }
-/** Backward-compatible policy — every scope accepts anonymous callers. */
+/** Backward-compatible default policy — every scope accepts GUEST callers. */
 declare const DEFAULT_LOA_POLICY: LoaPolicy;
-/** Production-hardened policy — control needs e-mail, safety needs hardware token. */
+/** Production-hardened policy — control needs OPERATOR, safety needs CREATOR. */
 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.
+ * Parse an RCAN v2.1 JWT and return the Role.
+ *
+ * Reads `rcan_role` (v2.1) with fallback to `loa` (v1.x).
+ * Defaults to GUEST on parse failure.
  */
-declare function extractLoaFromJwt(token: string): LevelOfAssurance;
+declare function extractRoleFromJwt(token: string): Role;
+/** @deprecated Use extractRoleFromJwt. Kept for v1.x backward compatibility. */
+declare function extractLoaFromJwt(token: string): Role;
 /**
- * Check whether `loa` satisfies the minimum required for `scope`.
+ * Parse an RCAN v2.1 JWT and return a full IdentityRecord.
  *
- * @param loa    - Caller's assurance level
- * @param scope  - One of discover | status | chat | control | safety
- * @param policy - Defaults to DEFAULT_LOA_POLICY (backward compatible)
+ * Does NOT verify the JWT signature.
  */
-declare function validateLoaForScope(loa: LevelOfAssurance, scope: string, policy?: LoaPolicy): {
-    valid: boolean;
+declare function extractIdentityFromJwt(token: string): IdentityRecord;
+interface ScopeValidationResult {
+    ok: boolean;
     reason: string;
-};
+}
+/**
+ * Check whether `role` meets the minimum requirement for `scope`.
+ */
+declare function validateRoleForScope(role: Role, scope: string): ScopeValidationResult;
+/** @deprecated Use validateRoleForScope. */
+declare function validateLoaForScope(role: Role, scope: string): ScopeValidationResult;
 
 /**
  * RCAN Federation — cross-registry trust and sync (GAP-16).
@@ -1496,6 +1570,375 @@ declare function validateContributeScope(scopeLevel: number, action?: "request"
  */
 declare function isPreemptedBy(scopeLevel: number): boolean;
 
+/**
+ * rcan/competition — Competition protocol messages and scope.
+ *
+ * Implements the competition scope and message types for RCAN v1.10+.
+ * Robots can enter competitions, publish scores, receive season standings,
+ * and log private personal research results.
+ *
+ * Spec: §3 MessageTypes 37–40
+ */
+
+/** Competition scope level — chat-level scope (observation, not control). */
+declare const COMPETITION_SCOPE_LEVEL = 2;
+type CompetitionFormat = "sprint" | "endurance" | "precision" | "efficiency";
+type CompetitionBadge = "gold" | "silver" | "bronze" | "participant";
+type RunType = "personal" | "community";
+interface StandingEntry {
+    rank: number;
+    rrn: string;
+    score: number;
+    badge: CompetitionBadge;
+}
+interface ResearchMetrics {
+    success_rate: number;
+    p66_rate: number;
+    token_efficiency: number;
+    latency_score: number;
+    [key: string]: number;
+}
+interface CompetitionEnter {
+    type: typeof MessageType.COMPETITION_ENTER;
+    competition_id: string;
+    competition_format: CompetitionFormat;
+    hardware_tier: string;
+    model_id: string;
+    robot_rrn: string;
+    entered_at: number;
+}
+interface CompetitionScore {
+    type: typeof MessageType.COMPETITION_SCORE;
+    competition_id: string;
+    candidate_id: string;
+    score: number;
+    hardware_tier: string;
+    verified: boolean;
+    submitted_at: number;
+}
+interface SeasonStanding {
+    type: typeof MessageType.SEASON_STANDING;
+    season_id: string;
+    class_id: string;
+    standings: StandingEntry[];
+    days_remaining: number;
+    broadcast_at: number;
+}
+interface PersonalResearchResult {
+    type: typeof MessageType.PERSONAL_RESEARCH_RESULT;
+    run_id: string;
+    run_type: RunType;
+    candidate_id: string;
+    score: number;
+    hardware_tier: string;
+    model_id: string;
+    owner_uid: string;
+    metrics: ResearchMetrics;
+    submitted_to_community: boolean;
+    created_at: number;
+}
+declare function makeCompetitionEnter(params?: Partial<Omit<CompetitionEnter, "type">>): CompetitionEnter;
+declare function makeCompetitionScore(params?: Partial<Omit<CompetitionScore, "type">>): CompetitionScore;
+declare function makeSeasonStanding(params?: Partial<Omit<SeasonStanding, "type">>): SeasonStanding;
+declare function makePersonalResearchResult(params?: Partial<Omit<PersonalResearchResult, "type">>): PersonalResearchResult;
+/**
+ * Check if the given scope level permits competition operations.
+ * Competition messages require scope >= 2.0 (chat level).
+ */
+declare function validateCompetitionScope(scopeLevel: number): boolean;
+
+/**
+ * rcan/firmware — RCAN v2.1 Firmware Manifest types and helpers.
+ *
+ * Every RCAN v2.1 robot MUST publish a signed firmware manifest at:
+ *   {ruri}/.well-known/rcan-firmware-manifest.json
+ *
+ * The manifest is Ed25519-signed by the manufacturer's key registered in the RRF.
+ * The envelope field `firmwareHash` (field 13) carries a SHA-256 of the manifest.
+ *
+ * Spec: §11 — Firmware Manifests
+ */
+/** Well-known endpoint path for firmware manifests. */
+declare const FIRMWARE_MANIFEST_PATH = "/.well-known/rcan-firmware-manifest.json";
+/** A single component entry in the firmware manifest. */
+interface FirmwareComponent {
+    /** Component name, e.g. "brain-runtime" */
+    name: string;
+    /** Semantic version string */
+    version: string;
+    /** SHA-256 hash prefixed with "sha256:" */
+    hash: string;
+}
+/** RCAN v2.1 firmware manifest. */
+interface FirmwareManifest {
+    /** Robot Registration Number */
+    rrn: string;
+    /** Semver or CalVer version string */
+    firmwareVersion: string;
+    /** SHA-256 of the full firmware bundle, prefixed "sha256:" */
+    buildHash: string;
+    /** Per-component records */
+    components: FirmwareComponent[];
+    /** UTC ISO-8601 timestamp when the manifest was signed */
+    signedAt: string;
+    /** Ed25519 signature over canonical JSON (base64url), empty if unsigned */
+    signature?: string;
+}
+/**
+ * Serialized (wire) format of a firmware manifest.
+ * Uses snake_case keys to match the JSON spec.
+ */
+interface FirmwareManifestWire {
+    rrn: string;
+    firmware_version: string;
+    build_hash: string;
+    components: FirmwareComponent[];
+    signed_at: string;
+    signature?: string;
+}
+/** Convert a camelCase FirmwareManifest to the wire (snake_case) format. */
+declare function manifestToWire(m: FirmwareManifest): FirmwareManifestWire;
+/** Parse a wire-format manifest into the typed FirmwareManifest. */
+declare function manifestFromWire(w: FirmwareManifestWire): FirmwareManifest;
+/**
+ * Return the canonical JSON bytes of a manifest (no signature field, sorted keys).
+ * This is the byte string that the Ed25519 signature covers.
+ */
+declare function canonicalManifestJson(m: FirmwareManifest): string;
+/** Thrown when firmware manifest signature verification fails. */
+declare class FirmwareIntegrityError extends Error {
+    constructor(message: string);
+}
+/** Validate a manifest structure and return a list of errors. */
+declare function validateManifest(m: FirmwareManifest): string[];
+
+/**
+ * rcan/authority — RCAN v2.1 Authority Access Protocol (EU AI Act §16(j)).
+ *
+ * Defines payload types for AUTHORITY_ACCESS (41) and AUTHORITY_RESPONSE (42)
+ * message types, and helpers for building/validating authority requests.
+ *
+ * The authority access protocol enables regulatory bodies to request audit data
+ * from robots under EU AI Act Article 16(j) and similar frameworks.
+ *
+ * Spec: §13 (Authority Access) — EU AI Act Art. 16 mapping
+ */
+/** Allowed audit data categories that an authority may request. */
+type AuthorityDataCategory = "audit_chain" | "transparency_records" | "sbom" | "firmware_manifest";
+/** Payload for AUTHORITY_ACCESS (41) — sent by a regulatory authority to a robot. */
+interface AuthorityAccessPayload {
+    /** Unique request identifier (correlated in the response). */
+    requestId: string;
+    /** Authority identifier, e.g. "EU-AI-ACT-NCA-DE" */
+    authorityId: string;
+    /** Audit data categories requested. */
+    requestedData: AuthorityDataCategory[];
+    /** Human-readable justification for the request. */
+    justification: string;
+    /** Unix timestamp — request must be responded to before this time. */
+    expiresAt: number;
+}
+/** Provided audit data in an AUTHORITY_RESPONSE. */
+interface AuthorityResponseData {
+    auditChain?: unknown[];
+    transparencyRecords?: unknown[];
+    sbomUrl?: string;
+    firmwareManifestUrl?: string;
+}
+/** Payload for AUTHORITY_RESPONSE (42) — sent by the robot in reply. */
+interface AuthorityResponsePayload {
+    /** Correlates with the AUTHORITY_ACCESS requestId. */
+    requestId: string;
+    /** Robot Registration Number of the responding robot. */
+    rrn: string;
+    /** Unix timestamp when the data was packaged. */
+    providedAt: number;
+    /** Provided audit data. */
+    data: AuthorityResponseData;
+}
+/** Convert AuthorityAccessPayload to/from snake_case wire format. */
+interface AuthorityAccessPayloadWire {
+    request_id: string;
+    authority_id: string;
+    requested_data: AuthorityDataCategory[];
+    justification: string;
+    expires_at: number;
+}
+declare function authorityAccessToWire(p: AuthorityAccessPayload): AuthorityAccessPayloadWire;
+declare function authorityAccessFromWire(w: AuthorityAccessPayloadWire): AuthorityAccessPayload;
+/**
+ * Validate an authority access payload.
+ * Returns an array of error strings (empty = valid).
+ */
+declare function validateAuthorityAccess(p: AuthorityAccessPayload): string[];
+/** Return true if an AUTHORITY_ACCESS request is still within its deadline. */
+declare function isAuthorityRequestValid(p: AuthorityAccessPayload): boolean;
+declare const AUTHORITY_ERROR_CODES: {
+    readonly NOT_RECOGNIZED: "AUTHORITY_NOT_RECOGNIZED";
+    readonly REQUEST_EXPIRED: "AUTHORITY_REQUEST_EXPIRED";
+    readonly INVALID_TOKEN: "AUTHORITY_INVALID_TOKEN";
+    readonly RATE_LIMITED: "AUTHORITY_RATE_LIMITED";
+};
+
+declare const RRF_REVOCATION_URL = "https://api.rrf.rcan.dev/v2/revocations";
+declare const M2M_TRUSTED_ISSUER = "rrf.rcan.dev";
+/** Revocation cache TTL in milliseconds (≤ 60 s per spec). */
+declare const RRF_REVOCATION_CACHE_TTL_MS = 55000;
+/** Parsed claims from an M2M_PEER JWT. */
+interface M2MPeerClaims {
+    /** Subject RRN of the peer robot. */
+    sub: string;
+    /** The robot this peer is authorized to command. */
+    peerRrn: string;
+    /** Authorized scopes. */
+    scopes: string[];
+    /** Unix expiry timestamp. */
+    exp: number;
+    /** Issuing principal (ADMIN or CREATOR RRN). */
+    iss: string;
+}
+/** Parsed claims from an M2M_TRUSTED JWT (RRF-issued). */
+interface M2MTrustedClaims {
+    /** Orchestrator identifier (not a robot RRN). */
+    sub: string;
+    /** Explicit allowlist of robots this token may command. */
+    fleetRrns: string[];
+    /** Must include "fleet.trusted". */
+    scopes: string[];
+    /** Unix expiry timestamp (max 24 h from issuance). */
+    exp: number;
+    /** Must be "rrf.rcan.dev". */
+    iss: string;
+    /** RRF Ed25519 signature over claims (base64url). */
+    rrfSig: string;
+}
+/** Thrown when M2M token verification fails. */
+declare class M2MAuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse an M2M_PEER JWT without signature verification.
+ * Validates expiry and required claims.
+ */
+declare function parseM2mPeerToken(token: string): M2MPeerClaims;
+/**
+ * Parse an M2M_TRUSTED JWT claims WITHOUT signature verification.
+ *
+ * Checks issuer, scope, and expiry. Does not contact RRF.
+ * For full verification use `verifyM2mTrustedTokenClaims`.
+ */
+declare function parseM2mTrustedToken(token: string): M2MTrustedClaims;
+/**
+ * Verify M2M_TRUSTED token claims and check that it authorizes `targetRrn`.
+ *
+ * This method validates claims structure only (no RRF network call).
+ * In production, also check the RRF revocation list with `RRFRevocationCache`.
+ */
+declare function verifyM2mTrustedTokenClaims(token: string, targetRrn: string): M2MTrustedClaims;
+interface RevocationCache {
+    revokedOrchestrators: Set<string>;
+    revokedJtis: Set<string>;
+    fetchedAt: number;
+}
+/**
+ * Fetch the RRF revocation list and cache it.
+ *
+ * Uses `fetch()` (available in Node 18+ and all modern browsers).
+ * TTL: 55 s (spec max: 60 s).
+ */
+declare function fetchRRFRevocations(url?: string): Promise<RevocationCache>;
+/**
+ * Check whether an M2M_TRUSTED orchestrator sub is revoked.
+ * Fetches the revocation list if the cache is stale.
+ */
+declare function isM2mTrustedRevoked(claims: M2MTrustedClaims, jti?: string): Promise<boolean>;
+/**
+ * Full async M2M_TRUSTED verification: claims check + revocation list.
+ *
+ * Note: Signature verification requires the RRF public key and is typically
+ * done server-side using the rcan-py SDK or castor.auth middleware.
+ */
+declare function verifyM2mTrustedToken(token: string, targetRrn: string, options?: {
+    skipRevocationCheck?: boolean;
+}): Promise<M2MTrustedClaims>;
+
+/**
+ * RCAN v2.2 Post-Quantum Hybrid Signing — ML-DSA-65 (NIST FIPS 204)
+ *
+ * Provides MLDSAKeyPair for post-quantum signing alongside the existing
+ * Ed25519 SignatureBlock.  In hybrid mode a message carries both:
+ *   - `signature`  — Ed25519 SignatureBlock  (backward-compat with v2.1)
+ *   - `pqSig`      — MLDSASignatureBlock     (new in v2.2)
+ *
+ * Key sizes (ML-DSA-65, NIST security level 3):
+ *   Public key:   1952 bytes
+ *   Private key:  4032 bytes
+ *   Signature:    3309 bytes
+ *
+ * Requires: @noble/post-quantum (npm install @noble/post-quantum)
+ *
+ * Spec: https://rcan.dev/spec#section-7-2
+ */
+
+/** @deprecated use PQSignatureBlock */
+type MLDSASignatureBlock = PQSignatureBlock;
+interface MLDSAKeyPairData {
+    /** Public key bytes (1952 bytes) */
+    publicKey: Uint8Array;
+    /** Private key bytes (4032 bytes). Absent for verify-only key pairs. */
+    secretKey?: Uint8Array;
+    /** 8-char hex key ID */
+    keyId: string;
+}
+/**
+ * An ML-DSA-65 (CRYSTALS-Dilithium, NIST FIPS 204) key pair.
+ *
+ * Immutable value object.  Build via {@link MLDSAKeyPair.generate} or
+ * {@link MLDSAKeyPair.fromPublicKey}.
+ */
+declare class MLDSAKeyPair {
+    readonly keyId: string;
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array | undefined;
+    private constructor();
+    /** Generate a new ML-DSA-65 key pair. */
+    static generate(): Promise<MLDSAKeyPair>;
+    /** Build a verify-only key pair from raw public key bytes. */
+    static fromPublicKey(publicKey: Uint8Array): Promise<MLDSAKeyPair>;
+    /** Build a full key pair from saved bytes (public + secret). */
+    static fromKeyMaterial(publicKey: Uint8Array, secretKey: Uint8Array): Promise<MLDSAKeyPair>;
+    get hasPrivateKey(): boolean;
+    /** Sign raw bytes; returns ML-DSA-65 signature (3309 bytes). */
+    signBytes(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Verify an ML-DSA-65 signature.
+     * @returns true if valid
+     * @throws {Error} on invalid signature
+     */
+    verifyBytes(data: Uint8Array, signature: Uint8Array): Promise<void>;
+    toString(): string;
+}
+/**
+ * Add an ML-DSA-65 signature (`pqSig`) to an RCAN message.
+ *
+ * This is the v2.2 hybrid complement to the existing Ed25519 signature.
+ * Call {@link signMessageEd25519} (or the existing signing path) first to set
+ * `signature`, then call this to append `pqSig`.
+ *
+ * @param msg      RCAN message (mutated in place — sets `pqSig`)
+ * @param keypair  ML-DSA-65 key pair with private key
+ * @returns The same message cast to include `pqSig`
+ */
+declare function addPQSignature(msg: RCANMessage, keypair: MLDSAKeyPair): Promise<RCANMessage>;
+/**
+ * Verify the ML-DSA-65 signature (`pqSig`) on an RCAN message.
+ *
+ * @param msg           Message with a `pqSig` field
+ * @param trustedKeys   Trusted ML-DSA public key pairs
+ * @param requirePQ     If true, raise when `pqSig` is absent (for post-2028 hard mode)
+ */
+declare function verifyPQSignature(msg: RCANMessage, trustedKeys: MLDSAKeyPair[], requirePQ?: boolean): Promise<void>;
+
 /**
  * rcan-ts — Official TypeScript SDK for RCAN v1.6
  * Robot Communication and Accountability Network
@@ -1508,4 +1951,4 @@ declare const VERSION = "0.6.0";
 /** @deprecated Use SPEC_VERSION from ./version instead */
 declare const RCAN_VERSION = "1.6";
 
-export { type ApprovalStatus, AuditChain, AuditError, type AuditExportRequest, CONTRIBUTE_SCOPE_LEVEL, type CachedKey, type ChainVerifyResult, ClockDriftError, type ClockSyncStatus, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, type ComputeResource, ConfidenceGate, type ConsentRequestParams, type ConsentResponseParams, type ConsentType, type ContributeCancel, type ContributeRequest, type ContributeResult, 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, type WorkUnitStatus, addDelegationHop, addMediaInline, addMediaRef, assertClockSynced, checkClockSync, checkRevocation, decodeBleFrames, decodeCompact, decodeMinimal, encodeBleFrames, encodeCompact, encodeMinimal, extractLoaFromJwt, fetchCanonicalSchema, isPreemptedBy, isSafetyMessage, makeCloudRelayMessage, makeConfigUpdate, makeConsentDeny, makeConsentGrant, makeConsentRequest, makeContributeCancel, makeContributeRequest, makeContributeResult, makeEstopMessage, makeEstopWithQoS, makeFaultReport, makeFederationSync, makeKeyRotationMessage, makeResumeMessage, makeRevocationBroadcast, makeStopMessage, makeStreamChunk, makeTrainingConsentDeny, makeTrainingConsentGrant, makeTrainingConsentRequest, makeTrainingDataMessage, makeTransparencyMessage, selectTransport, validateConfig, validateConfigAgainstSchema, validateConfigUpdate, validateConsentMessage, validateContributeScope, validateCrossRegistryCommand, validateDelegationChain, validateLoaForScope, validateMediaChunks, validateMessage, validateNodeAgainstSchema, validateReplay, validateSafetyMessage, validateTrainingDataMessage, validateURI, validateVersionCompat };
+export { AUTHORITY_ERROR_CODES, type ApprovalStatus, AuditChain, AuditError, type AuditExportRequest, type AuthorityAccessPayload, type AuthorityAccessPayloadWire, type AuthorityDataCategory, type AuthorityResponseData, type AuthorityResponsePayload, COMPETITION_SCOPE_LEVEL, CONTRIBUTE_SCOPE_LEVEL, type CachedKey, type ChainVerifyResult, ClockDriftError, type ClockSyncStatus, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, type CompetitionBadge, type CompetitionEnter, type CompetitionFormat, type CompetitionScore, type ComputeResource, ConfidenceGate, type ConsentRequestParams, type ConsentResponseParams, type ConsentType, type ContributeCancel, type ContributeRequest, type ContributeResult, DEFAULT_LOA_POLICY, DataCategory, type DelegationHop, FIRMWARE_MANIFEST_PATH, FaultCode, type FaultReportParams, type FaultSeverity, type FederationSyncPayload, FederationSyncType, type FirmwareComponent, FirmwareIntegrityError, type FirmwareManifest, type FirmwareManifestWire, GateError, HiTLGate, type IdentityRecord, type JWKEntry, type JWKSDocument, KeyStore, LevelOfAssurance, type ListResult, type LoaPolicy, M2MAuthError, type M2MPeerClaims, type M2MTrustedClaims, M2M_TRUSTED_ISSUER, MLDSAKeyPair, type MLDSAKeyPairData, type MLDSASignatureBlock, type MediaChunk, MediaEncoding, MessageType, NodeClient, type OfflineCommandResult, OfflineModeManager, type OfflineState, PRODUCTION_LOA_POLICY, type PendingApproval, type PersonalResearchResult, 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, ROLE_JWT_LEVEL, RRF_REVOCATION_CACHE_TTL_MS, RRF_REVOCATION_URL, type RegistrationResult, RegistryClient, type RegistryIdentity, RegistryTier, ReplayCache, type ReplayCheckResult, type ReplayableMessage, type ResearchMetrics, RevocationCache$1 as RevocationCache, type RevocationStatus, type RevocationStatusValue, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, Role, type RunType, SAFETY_MESSAGE_TYPE, SCOPE_MIN_ROLE, SDK_VERSION, SPEC_VERSION, type SafetyEvent, type SafetyMessage, type ScopeValidationResult, type SeasonStanding, type SenderType, type SignatureBlock, type StandingEntry, type StreamChunk, type TrainingConsentRequestParams, type TransparencyMessage, TransportEncoding, TransportError, TrustAnchorCache, VERSION, type ValidationResult, type WorkUnitStatus, addDelegationHop, addMediaInline, addMediaRef, addPQSignature, assertClockSynced, authorityAccessFromWire, authorityAccessToWire, canonicalManifestJson, checkClockSync, checkRevocation, decodeBleFrames, decodeCompact, decodeMinimal, encodeBleFrames, encodeCompact, encodeMinimal, extractIdentityFromJwt, extractLoaFromJwt, extractRoleFromJwt, fetchCanonicalSchema, fetchRRFRevocations, isAuthorityRequestValid, isM2mTrustedRevoked, isPreemptedBy, isSafetyMessage, makeCloudRelayMessage, makeCompetitionEnter, makeCompetitionScore, makeConfigUpdate, makeConsentDeny, makeConsentGrant, makeConsentRequest, makeContributeCancel, makeContributeRequest, makeContributeResult, makeEstopMessage, makeEstopWithQoS, makeFaultReport, makeFederationSync, makeKeyRotationMessage, makePersonalResearchResult, makeResumeMessage, makeRevocationBroadcast, makeSeasonStanding, makeStopMessage, makeStreamChunk, makeTrainingConsentDeny, makeTrainingConsentGrant, makeTrainingConsentRequest, makeTrainingDataMessage, makeTransparencyMessage, manifestFromWire, manifestToWire, parseM2mPeerToken, parseM2mTrustedToken, roleFromJwtLevel, selectTransport, validateAuthorityAccess, validateCompetitionScope, validateConfig, validateConfigAgainstSchema, validateConfigUpdate, validateConsentMessage, validateContributeScope, validateCrossRegistryCommand, validateDelegationChain, validateLoaForScope, validateManifest, validateMediaChunks, validateMessage, validateNodeAgainstSchema, validateReplay, validateRoleForScope, validateSafetyMessage, validateTrainingDataMessage, validateURI, validateVersionCompat, verifyM2mTrustedToken, verifyM2mTrustedTokenClaims, verifyPQSignature };