@continuonai/rcan-ts 0.1.2 → 0.3.0

package/README.md

@@ -9,6 +9,8 @@ Official TypeScript SDK for the **RCAN v1.2** Robot Communication and Accountabi
 npm install @continuonai/rcan-ts
 ```
 
+> **v0.2.0** — RCAN v1.2 spec compliance including §17 Distributed Registry Node Protocol
+
 ### CDN / Browser (no build step)
 
 ```html
@@ -139,6 +141,89 @@ result.warnings.forEach((w) => console.warn("⚠️", w));
 | `validateURI` | Validate a Robot URI string |
 | `validateMessage` | Validate a RCAN message object |
 | `validateConfig` | L1/L2/L3 conformance check for a robot RCAN config |
+| `NodeClient` | Resolve RRNs from federated registry nodes (§17) |
+| `fetchCanonicalSchema` | Fetch the canonical JSON schema from rcan.dev |
+| `validateConfigAgainstSchema` | Validate a config object against the live JSON schema |
+| `validateNodeAgainstSchema` | Validate a node manifest against the node schema |
+
+---
+
+## Distributed Registry Nodes (§17)
+
+RCAN v1.2 §17 introduces a federated registry network. `NodeClient` resolves RRNs from any node — root or delegated authoritative.
+
+```typescript
+import { NodeClient } from '@continuonai/rcan-ts';
+
+const client = new NodeClient();
+
+// Resolve an RRN across the federation
+const result = await client.resolve('RRN-BD-000000000001');
+console.log(`Resolved by: ${result.resolved_by}`);
+console.log(`Robot: ${result.record.name}`);
+
+// Discover the authoritative node for a namespace
+const node = await client.discover('RRN-BD-000000000001');
+console.log(`Authoritative: ${node.operator} at ${node.api_base}`);
+
+// List all known registry nodes
+const nodes = await client.listNodes();
+nodes.forEach(n => console.log(`${n.operator}: ${n.namespace_prefix}`));
+
+// Verify a node manifest
+const manifest = await client.getNodeManifest('https://registry.example.com');
+const isValid = client.verifyNode(manifest);
+
+// Error handling
+import { RCANNodeNotFoundError, RCANNodeTrustError } from '@continuonai/rcan-ts';
+try {
+  const result = await client.resolve('RRN-UNKNOWN-000000000001');
+} catch (e) {
+  if (e instanceof RCANNodeNotFoundError) {
+    console.log(`Not found: ${e.rrn}`);
+  } else if (e instanceof RCANNodeTrustError) {
+    console.log(`Trust failure: ${e.reason}`);
+  }
+}
+```
+
+### RRN Format
+
+```
+Root namespace:    RRN-000000000001    (12-digit recommended, 8-digit still valid)
+Delegated:        RRN-BD-000000000001  (prefix 2-8 alphanumeric chars)
+Legacy (valid):   RRN-00000001         (8-digit, backward compatible)
+```
+
+## Schema Validation
+
+Validate configs against the canonical JSON schema published at rcan.dev:
+
+```typescript
+import { validateConfigAgainstSchema, validateNodeAgainstSchema } from '@continuonai/rcan-ts';
+
+// Validate a RCAN config against the canonical schema from rcan.dev
+const result = await validateConfigAgainstSchema(myConfig);
+if (!result.valid) {
+  console.error('Config invalid:', result.errors);
+} else if (result.skipped) {
+  console.warn('Schema validation skipped (rcan.dev unreachable)');
+}
+
+// Validate a node manifest
+const nodeResult = await validateNodeAgainstSchema(manifest);
+```
+
+### CDN / Browser Usage
+
+```html
+<script src="https://unpkg.com/@continuonai/rcan-ts/dist/rcan.iife.js"></script>
+<script>
+  const { validateConfig, NodeClient } = window.RCAN;
+  const client = new NodeClient();
+  client.resolve('RRN-000000000001').then(r => console.log(r));
+</script>
+```
 
 ---
 

package/bin/rcan-validate.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { NodeClient, validateConfig, VERSION, SPEC_VERSION } from '../dist/index.js';
+import { readFileSync } from 'fs';
+import { parseArgs } from 'util';
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    version: { type: 'boolean', short: 'v' },
+    file: { type: 'string', short: 'f' },
+  },
+  allowPositionals: true,
+});
+
+if (values.version) {
+  console.log(`rcan-validate (ts) ${VERSION} (RCAN spec ${SPEC_VERSION})`);
+  process.exit(0);
+}
+
+const [subcommand, target] = positionals;
+
+if (subcommand === 'node') {
+  if (!target) {
+    console.error('Usage: rcan-validate node <url>');
+    process.exit(1);
+  }
+
+  const client = new NodeClient();
+  console.log(`Validating node manifest: ${target}`);
+
+  try {
+    const manifest = await client.getNodeManifest(target);
+    const valid = client.verifyNode(manifest);
+
+    const checks = [
+      ['node_type', manifest.node_type, ['root','authoritative','resolver','cache'].includes(manifest.node_type)],
+      ['operator', manifest.operator, !!manifest.operator],
+      ['namespace_prefix', manifest.namespace_prefix, !!manifest.namespace_prefix],
+      ['public_key', manifest.public_key?.substring(0, 20) + '...', manifest.public_key?.startsWith('ed25519:')],
+      ['api_base', manifest.api_base, manifest.api_base?.startsWith('https://')],
+    ];
+
+    for (const [name, value, pass] of checks) {
+      console.log(`  ${pass ? '✓' : '✗'} ${name}: ${value}`);
+    }
+
+    const passed = checks.filter(([,,p]) => p).length;
+    console.log(`\n${valid ? 'PASS' : 'FAIL'} (${passed}/${checks.length} checks)`);
+    process.exit(valid ? 0 : 1);
+  } catch (e) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (subcommand === 'config') {
+  const filePath = target || values.file;
+  if (!filePath) {
+    console.error('Usage: rcan-validate config <file>');
+    process.exit(1);
+  }
+
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const config = JSON.parse(raw);
+    const result = validateConfig(config);
+    if (result.ok) {
+      console.log('✓ Config valid');
+      if (result.warnings?.length) {
+        result.warnings.forEach(w => console.warn(`  ⚠️  ${w}`));
+      }
+      process.exit(0);
+    } else {
+      console.error('✗ Config invalid:');
+      result.issues?.forEach(i => console.error(`  ❌ ${i}`));
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+console.error(`Unknown subcommand: ${subcommand}`);
+console.error('Usage: rcan-validate node <url> | rcan-validate config <file> | rcan-validate --version');
+process.exit(1);

package/dist/browser.d.mts

@@ -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 };