feat(edge): support connection tokens when starting an edge and add token encode/decode utilities

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/remoteingress',
-  version: '3.0.4',
+  version: '3.1.0',
   description: 'Edge ingress tunnel for DcRouter - accepts incoming TCP connections at network edge and tunnels them to DcRouter SmartProxy preserving client IP via PROXY protocol v1.'
 }

ts/classes.remoteingressedge.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import { EventEmitter } from 'events';
+import { decodeConnectionToken } from './classes.token.js';
 
 // Command map for the edge side of remoteingress-bin
 type TEdgeCommands = {
@@ -13,8 +14,6 @@ type TEdgeCommands = {
       hubPort: number;
       edgeId: string;
       secret: string;
-      listenPorts: number[];
-      stunIntervalSecs?: number;
     };
     result: { started: boolean };
   };
@@ -39,8 +38,6 @@ export interface IEdgeConfig {
   hubPort?: number;
   edgeId: string;
   secret: string;
-  listenPorts: number[];
-  stunIntervalSecs?: number;
 }
 
 export class RemoteIngressEdge extends EventEmitter {
@@ -86,20 +83,33 @@ export class RemoteIngressEdge extends EventEmitter {
 
   /**
    * Start the edge — spawns the Rust binary and connects to the hub.
+   * Accepts either a connection token or an explicit IEdgeConfig.
    */
-  public async start(config: IEdgeConfig): Promise<void> {
+  public async start(config: { token: string } | IEdgeConfig): Promise<void> {
+    let edgeConfig: IEdgeConfig;
+
+    if ('token' in config) {
+      const decoded = decodeConnectionToken(config.token);
+      edgeConfig = {
+        hubHost: decoded.hubHost,
+        hubPort: decoded.hubPort,
+        edgeId: decoded.edgeId,
+        secret: decoded.secret,
+      };
+    } else {
+      edgeConfig = config;
+    }
+
     const spawned = await this.bridge.spawn();
     if (!spawned) {
       throw new Error('Failed to spawn remoteingress-bin');
     }
 
     await this.bridge.sendCommand('startEdge', {
-      hubHost: config.hubHost,
-      hubPort: config.hubPort ?? 8443,
-      edgeId: config.edgeId,
-      secret: config.secret,
-      listenPorts: config.listenPorts,
-      stunIntervalSecs: config.stunIntervalSecs,
+      hubHost: edgeConfig.hubHost,
+      hubPort: edgeConfig.hubPort ?? 8443,
+      edgeId: edgeConfig.edgeId,
+      secret: edgeConfig.secret,
     });
 
     this.started = true;

ts/classes.token.ts

@@ -0,0 +1,66 @@
+/**
+ * Connection token utilities for RemoteIngress edge connections.
+ * A token is a base64url-encoded compact JSON object carrying hub connection details.
+ */
+
+export interface IConnectionTokenData {
+  hubHost: string;
+  hubPort: number;
+  edgeId: string;
+  secret: string;
+}
+
+/**
+ * Encode connection data into a single opaque token string (base64url).
+ */
+export function encodeConnectionToken(data: IConnectionTokenData): string {
+  const compact = JSON.stringify({
+    h: data.hubHost,
+    p: data.hubPort,
+    e: data.edgeId,
+    s: data.secret,
+  });
+  // base64url: standard base64 with + → -, / → _, trailing = stripped
+  return Buffer.from(compact, 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Decode a connection token back into its constituent fields.
+ * Throws on malformed or incomplete tokens.
+ */
+export function decodeConnectionToken(token: string): IConnectionTokenData {
+  let parsed: { h?: unknown; p?: unknown; e?: unknown; s?: unknown };
+  try {
+    // Restore standard base64 from base64url
+    let base64 = token.replace(/-/g, '+').replace(/_/g, '/');
+    // Re-add padding
+    const remainder = base64.length % 4;
+    if (remainder === 2) base64 += '==';
+    else if (remainder === 3) base64 += '=';
+
+    const json = Buffer.from(base64, 'base64').toString('utf-8');
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error('Invalid connection token');
+  }
+
+  if (
+    typeof parsed.h !== 'string' ||
+    typeof parsed.p !== 'number' ||
+    typeof parsed.e !== 'string' ||
+    typeof parsed.s !== 'string'
+  ) {
+    throw new Error('Invalid connection token: missing required fields');
+  }
+
+  return {
+    hubHost: parsed.h,
+    hubPort: parsed.p,
+    edgeId: parsed.e,
+    secret: parsed.s,
+  };
+}

ts/index.ts

@@ -1,2 +1,3 @@
 export * from './classes.remoteingresshub.js';
 export * from './classes.remoteingressedge.js';
+export * from './classes.token.js';