@continuonai/rcan-ts 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -201,48 +201,101 @@ declare class AuditChain {
 }
 
 /**
- * RCAN Validation — validate messages, configs, and URIs.
+ * rcan-ts types — TypeScript interfaces for RCAN config and message shapes.
  *
- * Each function returns a ValidationResult with ok, issues, warnings, info.
+ * These provide parity with the rcan-py TypedDicts and enable
+ * static type checking with tsc/ts-jest/pyright.
  */
-interface ValidationResult {
-    ok: boolean;
-    issues: string[];
-    warnings: string[];
-    info: string[];
+interface RCANMetadata {
+    manufacturer?: string;
+    model?: string;
+    version?: string;
+    device_id?: string;
+    robot_name?: string;
+    rrn?: string;
+    rcan_uri?: string;
 }
-declare function validateURI(uri: string): ValidationResult;
-declare function validateMessage(data: unknown): ValidationResult;
-interface RCANConfig {
-    rcan_version?: string;
-    metadata?: {
-        manufacturer?: string;
-        model?: string;
-        version?: string;
-        rrn?: string;
-        rcan_uri?: string;
+interface RCANAgentConfig {
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    confidence_gates?: Array<{
+        threshold?: number;
+        [key: string]: unknown;
+    }>;
+    hitl_gates?: Array<Record<string, unknown>>;
+    commitment_chain?: {
+        enabled?: boolean;
+        [key: string]: unknown;
     };
-    agent?: {
-        provider?: string;
-        model?: string;
-        confidence_gates?: Array<{
-            threshold?: number;
-        }>;
-        hitl_gates?: Array<Record<string, unknown>>;
-        commitment_chain?: {
-            enabled?: boolean;
-        };
-        signing?: {
-            enabled?: boolean;
-        };
+    signing?: {
+        enabled?: boolean;
+        [key: string]: unknown;
     };
+}
+interface RCANConfig {
+    rcan_version?: string;
+    metadata?: RCANMetadata;
+    agent?: RCANAgentConfig;
+    channels?: Record<string, unknown>;
     rcan_protocol?: {
         jwt_auth?: {
             enabled?: boolean;
         };
+        [key: string]: unknown;
     };
     [key: string]: unknown;
 }
+interface RCANMessageEnvelope {
+    cmd: string;
+    target: string;
+    rcan_version?: string;
+    confidence?: number;
+    timestamp_ns?: number;
+    params?: Record<string, unknown>;
+    signature?: string;
+    [key: string]: unknown;
+}
+interface RCANRegistryNode {
+    rcan_node_version: string;
+    node_type: "root" | "authoritative" | "resolver" | "cache";
+    operator: string;
+    namespace_prefix: string;
+    public_key: string;
+    api_base: string;
+    registry_ui?: string;
+    spec_version?: string;
+    capabilities?: string[];
+    sync_endpoint?: string;
+    last_sync?: string;
+    ttl_seconds?: number;
+    contact?: string;
+    governance?: string;
+    federation_protocol?: string;
+}
+interface RCANResolveResult {
+    rrn: string;
+    resolved_by: string;
+    namespace: string;
+    record: Record<string, unknown>;
+    cache_status: "HIT" | "MISS" | "STALE";
+    resolved_at: string;
+}
+
+/**
+ * RCAN Validation — validate messages, configs, and URIs.
+ *
+ * Each function returns a ValidationResult with ok, issues, warnings, info.
+ */
+
+interface ValidationResult {
+    ok: boolean;
+    issues: string[];
+    warnings: string[];
+    info: string[];
+}
+declare function validateURI(uri: string): ValidationResult;
+declare function validateMessage(data: unknown): ValidationResult;
 declare function validateConfig(config: RCANConfig): ValidationResult;
 
 /**
@@ -270,6 +323,22 @@ declare class RCANSignatureError extends RCANError {
 declare class RCANRegistryError extends RCANError {
     constructor(message: string);
 }
+declare class RCANNodeError extends RCANError {
+    readonly nodeUrl?: string | undefined;
+    constructor(message: string, nodeUrl?: string | undefined);
+}
+declare class RCANNodeNotFoundError extends RCANNodeError {
+    readonly rrn: string;
+    constructor(rrn: string, nodeUrl?: string);
+}
+declare class RCANNodeSyncError extends RCANNodeError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, nodeUrl?: string, cause?: Error | undefined);
+}
+declare class RCANNodeTrustError extends RCANNodeError {
+    readonly reason: "invalid_signature" | "expired_cert" | "unknown_issuer" | "missing_pubkey";
+    constructor(reason: RCANNodeTrustError["reason"], nodeUrl?: string);
+}
 
 /**
  * rcan-ts — RegistryClient
@@ -339,6 +408,68 @@ declare class RegistryClient {
     }): Promise<Robot[]>;
 }
 
+/**
+ * rcan-ts — NodeClient
+ * Federation-aware node discovery and RRN resolution.
+ *
+ * Zero runtime dependencies — uses globalThis.fetch (Node 18+, browsers, CF Workers).
+ *
+ * @see https://rcan.dev/spec#section-federation
+ */
+
+declare class NodeClient {
+    private readonly rootUrl;
+    private readonly timeoutMs;
+    constructor(rootUrl?: string, timeoutMs?: number);
+    private _fetch;
+    /**
+     * Fetch /.well-known/rcan-node.json from any node URL.
+     * Throws RCANNodeTrustError if the manifest is malformed.
+     * Throws RCANNodeSyncError on network failure.
+     */
+    getNodeManifest(nodeUrl: string): Promise<RCANRegistryNode>;
+    /**
+     * Get list of known registry nodes from root /api/v1/nodes.
+     * Optionally filter by namespace prefix (e.g. "BD").
+     */
+    listNodes(prefix?: string): Promise<RCANRegistryNode[]>;
+    /**
+     * Find the authoritative node for an RRN.
+     * - Delegated RRN (RRN-BD-00000001): GET /api/v1/nodes?prefix=BD, return first match.
+     * - Root RRN (RRN-00000042): return root node manifest.
+     * - Unknown format: throws RCANNodeNotFoundError.
+     */
+    discover(rrn: string): Promise<RCANRegistryNode>;
+    /**
+     * Resolve an RRN across the federation.
+     * First tries {rootUrl}/api/v1/resolve/{rrn}.
+     * On 404, discovers the authoritative node and tries {node.api_base}/robots/{rrn}.
+     */
+    resolve(rrn: string): Promise<RCANResolveResult>;
+    /**
+     * Verify a node manifest is well-formed.
+     * Checks required fields, ed25519: public_key prefix, valid node_type, https:// api_base.
+     */
+    verifyNode(manifest: unknown): manifest is RCANRegistryNode;
+}
+
+declare function fetchCanonicalSchema(schemaName: string): Promise<object | null>;
+/**
+ * Validate a config object against the canonical rcan-config schema from rcan.dev.
+ * Returns { valid: true } or { valid: false, errors: string[] }.
+ * Gracefully returns { valid: true, skipped: true } if schema unreachable.
+ */
+declare function validateConfigAgainstSchema(config: unknown): Promise<{
+    valid: boolean;
+    errors?: string[];
+    skipped?: boolean;
+}>;
+declare function validateNodeAgainstSchema(manifest: unknown): Promise<{
+    valid: boolean;
+    errors?: string[];
+    skipped?: boolean;
+}>;
+
 /**
  * rcan-ts — Official TypeScript SDK for RCAN v1.2
  * Robot Communication and Accountability Network
@@ -347,7 +478,9 @@ declare class RegistryClient {
  * @see https://github.com/continuonai/rcan-ts
  */
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.3.0";
+declare const SPEC_VERSION = "1.2";
+/** @deprecated Use SPEC_VERSION instead */
 declare const RCAN_VERSION = "1.2";
 
-export { type ApprovalStatus, AuditChain, AuditError, type ChainVerifyResult, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, ConfidenceGate, GateError, HiTLGate, type ListResult, type PendingApproval, RCANAddressError, type RCANConfig, RCANError, RCANGateError, RCANMessage, type RCANMessageData, RCANMessageError, RCANRegistryError, RCANSignatureError, RCANValidationError, RCAN_VERSION, type RegistrationResult, RegistryClient, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, type SignatureBlock, VERSION, type ValidationResult, validateConfig, validateMessage, validateURI };
+export { type ApprovalStatus, AuditChain, AuditError, type ChainVerifyResult, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, ConfidenceGate, GateError, HiTLGate, type ListResult, NodeClient, type PendingApproval, RCANAddressError, type RCANAgentConfig, type RCANConfig, RCANError, RCANGateError, RCANMessage, type RCANMessageData, type RCANMessageEnvelope, RCANMessageError, type RCANMetadata, RCANNodeError, RCANNodeNotFoundError, RCANNodeSyncError, RCANNodeTrustError, RCANRegistryError, type RCANRegistryNode, type RCANResolveResult, RCANSignatureError, RCANValidationError, RCAN_VERSION, type RegistrationResult, RegistryClient, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, SPEC_VERSION, type SignatureBlock, VERSION, type ValidationResult, fetchCanonicalSchema, validateConfig, validateConfigAgainstSchema, validateMessage, validateNodeAgainstSchema, validateURI };

package/dist/index.js

@@ -26,11 +26,16 @@ __export(index_exports, {
   ConfidenceGate: () => ConfidenceGate,
   GateError: () => GateError,
   HiTLGate: () => HiTLGate,
+  NodeClient: () => NodeClient,
   RCANAddressError: () => RCANAddressError,
   RCANError: () => RCANError,
   RCANGateError: () => RCANGateError,
   RCANMessage: () => RCANMessage,
   RCANMessageError: () => RCANMessageError,
+  RCANNodeError: () => RCANNodeError,
+  RCANNodeNotFoundError: () => RCANNodeNotFoundError,
+  RCANNodeSyncError: () => RCANNodeSyncError,
+  RCANNodeTrustError: () => RCANNodeTrustError,
   RCANRegistryError: () => RCANRegistryError,
   RCANSignatureError: () => RCANSignatureError,
   RCANValidationError: () => RCANValidationError,
@@ -38,9 +43,13 @@ __export(index_exports, {
   RegistryClient: () => RegistryClient,
   RobotURI: () => RobotURI,
   RobotURIError: () => RobotURIError,
+  SPEC_VERSION: () => SPEC_VERSION,
   VERSION: () => VERSION,
+  fetchCanonicalSchema: () => fetchCanonicalSchema,
   validateConfig: () => validateConfig,
+  validateConfigAgainstSchema: () => validateConfigAgainstSchema,
   validateMessage: () => validateMessage,
+  validateNodeAgainstSchema: () => validateNodeAgainstSchema,
   validateURI: () => validateURI
 });
 module.exports = __toCommonJS(index_exports);
@@ -693,9 +702,22 @@ function validateConfig(config) {
   const meta = config.metadata ?? {};
   const agent = config.agent ?? {};
   const rcanProto = config.rcan_protocol ?? {};
+  for (const key of ["rcan_version", "metadata", "agent"]) {
+    if (!(key in config) || config[key] === void 0 || config[key] === null) {
+      fail(result, `Missing required key: '${key}'`);
+    }
+  }
+  const rv = config.rcan_version;
+  if (rv) {
+    if (!/^\d+\.\d+$/.test(rv)) {
+      fail(result, `rcan_version '${rv}' must match pattern N.N (e.g. '1.2')`);
+    }
+  }
   if (!meta.manufacturer) fail(result, "L1: metadata.manufacturer is required (\xA72)");
   if (!meta.model) fail(result, "L1: metadata.model is required (\xA72)");
-  if (!config.rcan_version) warn(result, "L1: rcan_version not declared (recommended)");
+  if (!meta.device_id && !meta.robot_name) {
+    fail(result, "L1: metadata.device_id (or robot_name) is required (\xA72)");
+  }
   if (!rcanProto.jwt_auth?.enabled) {
     warn(result, "L2: jwt_auth not enabled (required for L2 conformance, \xA78)");
   }
@@ -769,6 +791,39 @@ var RCANRegistryError = class extends RCANError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var RCANNodeError = class _RCANNodeError extends RCANError {
+  constructor(message, nodeUrl) {
+    super(message);
+    this.nodeUrl = nodeUrl;
+    this.name = "RCANNodeError";
+    Object.setPrototypeOf(this, _RCANNodeError.prototype);
+  }
+};
+var RCANNodeNotFoundError = class _RCANNodeNotFoundError extends RCANNodeError {
+  constructor(rrn, nodeUrl) {
+    super(`RRN not found in federation: ${rrn}`, nodeUrl);
+    this.rrn = rrn;
+    this.name = "RCANNodeNotFoundError";
+    Object.setPrototypeOf(this, _RCANNodeNotFoundError.prototype);
+  }
+};
+var RCANNodeSyncError = class _RCANNodeSyncError extends RCANNodeError {
+  constructor(message, nodeUrl, cause) {
+    super(message, nodeUrl);
+    this.cause = cause;
+    this.name = "RCANNodeSyncError";
+    Object.setPrototypeOf(this, _RCANNodeSyncError.prototype);
+  }
+};
+var RCANNodeTrustError = class _RCANNodeTrustError extends RCANNodeError {
+  reason;
+  constructor(reason, nodeUrl) {
+    super(`Node trust verification failed: ${reason}`, nodeUrl);
+    this.name = "RCANNodeTrustError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, _RCANNodeTrustError.prototype);
+  }
+};
 
 // src/registry.ts
 var DEFAULT_BASE_URL = "https://rcan-spec.pages.dev";
@@ -893,8 +948,250 @@ var RegistryClient = class {
   }
 };
 
+// src/node.ts
+var ROOT_NODE_URL = "https://rcan.dev";
+var NODE_MANIFEST_PATH = "/.well-known/rcan-node.json";
+var VALID_NODE_TYPES = /* @__PURE__ */ new Set([
+  "root",
+  "authoritative",
+  "resolver",
+  "cache"
+]);
+function parseRRNNamespace(rrn) {
+  const delegated = rrn.match(/^RRN-([A-Z0-9]{2,8})-(\d{8,16})$/);
+  if (delegated) return { type: "delegated", prefix: delegated[1], serial: delegated[2] };
+  const root = rrn.match(/^RRN-(\d{8,16})$/);
+  if (root) return { type: "root", serial: root[1] };
+  return null;
+}
+var NodeClient = class {
+  rootUrl;
+  timeoutMs;
+  constructor(rootUrl = ROOT_NODE_URL, timeoutMs = 1e4) {
+    this.rootUrl = rootUrl.replace(/\/$/, "");
+    this.timeoutMs = timeoutMs;
+  }
+  // ── Private helpers ─────────────────────────────────────────────────────────
+  async _fetch(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await globalThis.fetch(url, { signal: controller.signal });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new RCANNodeSyncError(`Request timed out: ${url}`, url, err);
+      }
+      throw new RCANNodeSyncError(
+        `Network error fetching ${url}: ${err.message}`,
+        url,
+        err instanceof Error ? err : void 0
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ── Public API ───────────────────────────────────────────────────────────────
+  /**
+   * Fetch /.well-known/rcan-node.json from any node URL.
+   * Throws RCANNodeTrustError if the manifest is malformed.
+   * Throws RCANNodeSyncError on network failure.
+   */
+  async getNodeManifest(nodeUrl) {
+    const url = `${nodeUrl.replace(/\/$/, "")}${NODE_MANIFEST_PATH}`;
+    const resp = await this._fetch(url);
+    if (!resp.ok) {
+      if (resp.status === 404) {
+        throw new RCANNodeNotFoundError(url, nodeUrl);
+      }
+      throw new RCANNodeSyncError(
+        `Failed to fetch node manifest from ${nodeUrl}: HTTP ${resp.status}`,
+        nodeUrl
+      );
+    }
+    let data;
+    try {
+      data = await resp.json();
+    } catch (err) {
+      throw new RCANNodeSyncError(
+        `Invalid JSON in node manifest from ${nodeUrl}`,
+        nodeUrl,
+        err instanceof Error ? err : void 0
+      );
+    }
+    if (!this.verifyNode(data)) {
+      throw new RCANNodeTrustError("missing_pubkey", nodeUrl);
+    }
+    return data;
+  }
+  /**
+   * Get list of known registry nodes from root /api/v1/nodes.
+   * Optionally filter by namespace prefix (e.g. "BD").
+   */
+  async listNodes(prefix) {
+    const qs = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+    const url = `${this.rootUrl}/api/v1/nodes${qs}`;
+    const resp = await this._fetch(url);
+    if (!resp.ok) {
+      throw new RCANNodeSyncError(
+        `Failed to list nodes from ${url}: HTTP ${resp.status}`,
+        url
+      );
+    }
+    let data;
+    try {
+      data = await resp.json();
+    } catch (err) {
+      throw new RCANNodeSyncError(
+        `Invalid JSON in nodes list from ${url}`,
+        url,
+        err instanceof Error ? err : void 0
+      );
+    }
+    if (Array.isArray(data)) return data;
+    if (data && typeof data === "object" && "nodes" in data) {
+      return data.nodes;
+    }
+    return [];
+  }
+  /**
+   * Find the authoritative node for an RRN.
+   * - Delegated RRN (RRN-BD-00000001): GET /api/v1/nodes?prefix=BD, return first match.
+   * - Root RRN (RRN-00000042): return root node manifest.
+   * - Unknown format: throws RCANNodeNotFoundError.
+   */
+  async discover(rrn) {
+    const parsed = parseRRNNamespace(rrn);
+    if (!parsed) {
+      throw new RCANNodeNotFoundError(rrn, this.rootUrl);
+    }
+    if (parsed.type === "root") {
+      return this.getNodeManifest(this.rootUrl);
+    }
+    const nodes = await this.listNodes(parsed.prefix);
+    if (nodes.length === 0) {
+      throw new RCANNodeNotFoundError(rrn, this.rootUrl);
+    }
+    return nodes[0];
+  }
+  /**
+   * Resolve an RRN across the federation.
+   * First tries {rootUrl}/api/v1/resolve/{rrn}.
+   * On 404, discovers the authoritative node and tries {node.api_base}/robots/{rrn}.
+   */
+  async resolve(rrn) {
+    const primaryUrl = `${this.rootUrl}/api/v1/resolve/${encodeURIComponent(rrn)}`;
+    let resp;
+    try {
+      resp = await this._fetch(primaryUrl);
+    } catch (err) {
+      throw err;
+    }
+    if (resp.ok) {
+      try {
+        return await resp.json();
+      } catch (err) {
+        throw new RCANNodeSyncError(
+          `Invalid JSON in resolve response for ${rrn}`,
+          this.rootUrl,
+          err instanceof Error ? err : void 0
+        );
+      }
+    }
+    if (resp.status !== 404) {
+      throw new RCANNodeSyncError(
+        `Unexpected HTTP ${resp.status} resolving ${rrn}`,
+        this.rootUrl
+      );
+    }
+    const node = await this.discover(rrn);
+    const fallbackUrl = `${node.api_base.replace(/\/$/, "")}/robots/${encodeURIComponent(rrn)}`;
+    const fallbackResp = await this._fetch(fallbackUrl);
+    if (!fallbackResp.ok) {
+      if (fallbackResp.status === 404) {
+        throw new RCANNodeNotFoundError(rrn, node.api_base);
+      }
+      throw new RCANNodeSyncError(
+        `HTTP ${fallbackResp.status} from authoritative node for ${rrn}`,
+        node.api_base
+      );
+    }
+    try {
+      return await fallbackResp.json();
+    } catch (err) {
+      throw new RCANNodeSyncError(
+        `Invalid JSON in fallback resolve response for ${rrn}`,
+        node.api_base,
+        err instanceof Error ? err : void 0
+      );
+    }
+  }
+  /**
+   * Verify a node manifest is well-formed.
+   * Checks required fields, ed25519: public_key prefix, valid node_type, https:// api_base.
+   */
+  verifyNode(manifest) {
+    if (!manifest || typeof manifest !== "object") return false;
+    const m = manifest;
+    if (typeof m.rcan_node_version !== "string" || !m.rcan_node_version) return false;
+    if (typeof m.node_type !== "string" || !VALID_NODE_TYPES.has(m.node_type)) return false;
+    if (typeof m.operator !== "string" || !m.operator) return false;
+    if (typeof m.namespace_prefix !== "string" || !m.namespace_prefix) return false;
+    if (typeof m.public_key !== "string" || !m.public_key.startsWith("ed25519:")) return false;
+    if (typeof m.api_base !== "string" || !m.api_base.startsWith("https://")) return false;
+    return true;
+  }
+};
+
+// src/schema.ts
+var SCHEMA_BASE = "https://rcan.dev/schemas";
+var schemaCache = /* @__PURE__ */ new Map();
+async function fetchCanonicalSchema(schemaName) {
+  if (schemaCache.has(schemaName)) return schemaCache.get(schemaName);
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5e3);
+    const res = await fetch(`${SCHEMA_BASE}/${schemaName}`, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const schema = await res.json();
+    schemaCache.set(schemaName, schema);
+    return schema;
+  } catch {
+    return null;
+  }
+}
+async function validateConfigAgainstSchema(config) {
+  const schema = await fetchCanonicalSchema("rcan-config.schema.json");
+  if (!schema) return { valid: true, skipped: true };
+  const errors = [];
+  if (typeof config !== "object" || config === null) {
+    return { valid: false, errors: ["Config must be an object"] };
+  }
+  const cfg = config;
+  const required = schema.required ?? [];
+  for (const key of required) {
+    if (!(key in cfg)) errors.push(`Missing required field: ${key}`);
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}
+async function validateNodeAgainstSchema(manifest) {
+  const schema = await fetchCanonicalSchema("rcan-node.schema.json");
+  if (!schema) return { valid: true, skipped: true };
+  const errors = [];
+  if (typeof manifest !== "object" || manifest === null) {
+    return { valid: false, errors: ["Manifest must be an object"] };
+  }
+  const m = manifest;
+  const required = schema.required ?? [];
+  for (const key of required) {
+    if (!(key in m)) errors.push(`Missing required field: ${key}`);
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}
+
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
+var SPEC_VERSION = "1.2";
 var RCAN_VERSION = "1.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -904,11 +1201,16 @@ var RCAN_VERSION = "1.2";
   ConfidenceGate,
   GateError,
   HiTLGate,
+  NodeClient,
   RCANAddressError,
   RCANError,
   RCANGateError,
   RCANMessage,
   RCANMessageError,
+  RCANNodeError,
+  RCANNodeNotFoundError,
+  RCANNodeSyncError,
+  RCANNodeTrustError,
   RCANRegistryError,
   RCANSignatureError,
   RCANValidationError,
@@ -916,9 +1218,13 @@ var RCAN_VERSION = "1.2";
   RegistryClient,
   RobotURI,
   RobotURIError,
+  SPEC_VERSION,
   VERSION,
+  fetchCanonicalSchema,
   validateConfig,
+  validateConfigAgainstSchema,
   validateMessage,
+  validateNodeAgainstSchema,
   validateURI
 });
 //# sourceMappingURL=index.js.map