@continuonai/rcan-ts 0.2.0 → 0.3.0

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);
@@ -782,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";
@@ -906,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 = {
@@ -917,11 +1201,16 @@ var RCAN_VERSION = "1.2";
   ConfidenceGate,
   GateError,
   HiTLGate,
+  NodeClient,
   RCANAddressError,
   RCANError,
   RCANGateError,
   RCANMessage,
   RCANMessageError,
+  RCANNodeError,
+  RCANNodeNotFoundError,
+  RCANNodeSyncError,
+  RCANNodeTrustError,
   RCANRegistryError,
   RCANSignatureError,
   RCANValidationError,
@@ -929,9 +1218,13 @@ var RCAN_VERSION = "1.2";
   RegistryClient,
   RobotURI,
   RobotURIError,
+  SPEC_VERSION,
   VERSION,
+  fetchCanonicalSchema,
   validateConfig,
+  validateConfigAgainstSchema,
   validateMessage,
+  validateNodeAgainstSchema,
   validateURI
 });
 //# sourceMappingURL=index.js.map