@cortexkit/subc-client 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/subc-client",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "TypeScript client for the subc daemon. Wire-compatible (byte-for-byte) with the Rust subc-transport handshake and subc-protocol envelope.",
   "type": "module",
   "exports": {

package/src/client.ts

@@ -38,6 +38,8 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const BODY_READ_TIMEOUT_MS = 30_000;
 const EMPTY_BODY = new Uint8Array(0);
 const DEFAULT_MANAGED_TARGET_KIND: ManagedRouteKind = "management_surface";
+export const SUBC_MODULE_ID_ENV = "SUBC_MODULE_ID";
+export const SUBC_LAUNCH_NONCE_ENV = "SUBC_LAUNCH_NONCE";
 
 export interface BindIdentity {
   project_root: string;
@@ -52,6 +54,16 @@ export type RouteTarget =
 
 export type ManagedRouteKind = "management_surface" | "tool_provider";
 
+export interface ConsumerIdentity {
+  module_id: string;
+  launch_nonce: string;
+}
+
+export interface RouteOpenOptions {
+  /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
+  consumerIdentity?: ConsumerIdentity | null;
+}
+
 export interface CatalogEntry {
   module_id: string;
   roles: unknown[];
@@ -70,6 +82,8 @@ export interface ManagedCallOptions extends RequestOptions {
   identity?: BindIdentity;
   /** Defaults to management_surface, matching the store/host management APIs. */
   targetKind?: ManagedRouteKind;
+  /** Optional override for the consumer identity; by default the SUBC_MODULE_ID and SUBC_LAUNCH_NONCE environment variables are used when both are non-empty. Set null to send route.open without consumer_identity. */
+  consumerIdentity?: ConsumerIdentity | null;
 }
 
 export interface SubscribeOptions {
@@ -83,6 +97,8 @@ export interface CloseRouteOptions {
    * Defaults to false: close immediately, aborting everything in flight.
    */
   drain?: boolean;
+  /** Consumer identity to use when looking up the route to close; only needed for routes opened with a non-default consumer identity. */
+  consumerIdentity?: ConsumerIdentity | null;
 }
 
 /**
@@ -199,6 +215,7 @@ interface CachedRoute {
   moduleId: string;
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>;
   identity: BindIdentity;
+  consumerIdentity?: ConsumerIdentity;
   channel: number | null;
   generation: number;
   opening: Promise<number> | null;
@@ -252,8 +269,14 @@ export class SubcClient {
   }
 
   /** Open a route to a provider (channel-0 route.open); returns the route channel. */
-  async routeOpen(target: RouteTarget, identity: BindIdentity): Promise<number> {
-    const body = this.encode({ op: "route.open", target, identity });
+  async routeOpen(target: RouteTarget, identity: BindIdentity, opts: RouteOpenOptions = {}): Promise<number> {
+    const consumerIdentity = routeOpenConsumerIdentity(opts);
+    const body = this.encode({
+      op: "route.open",
+      target,
+      identity,
+      ...(consumerIdentity ? { consumer_identity: consumerIdentity } : {}),
+    });
     const reply = await this.controlRpc(body);
     const parsed = this.parseJson(reply) as { op: string; route_channel?: number };
     if (typeof parsed.route_channel !== "number") {
@@ -380,7 +403,7 @@ export class SubcClient {
     identity: BindIdentity,
     opts: CloseRouteOptions = {},
   ): Promise<void> {
-    const key = routeCacheKey(target, identity);
+    const key = routeCacheKey(target, identity, routeOpenConsumerIdentity(opts));
     const cached = this.routes.get(key);
     if (!cached) return; // never opened / already closed — idempotent no-op.
     // Generation guard: an in-flight openCachedRoute holds this same object and
@@ -498,7 +521,7 @@ export class SubcClient {
         timer: null,
       };
       pending.timer = setTimeout(() => {
-        this.rejectPending(key, pending, new SubcError(`request on channel ${channel} timed out after ${ms}ms`));
+        this.rejectPending(key, pending, new SubcError(this.timeoutMessage(channel, corr, ms)));
       }, ms);
       this.pending.set(key, pending);
       this.sock.write(encodeFrame(frame), Date.now() + ms).catch((err) => {
@@ -563,7 +586,7 @@ export class SubcClient {
         classifyFailure,
       };
       pending.timer = setTimeout(() => {
-        this.rejectPending(key, pending, new SubcError(`request on channel ${channel} timed out after ${ms}ms`));
+        this.rejectPending(key, pending, new SubcError(this.timeoutMessage(channel, corr, ms)));
       }, ms);
       this.pending.set(key, pending);
 
@@ -590,7 +613,8 @@ export class SubcClient {
       RouteTarget,
       { kind: ManagedRouteKind }
     >;
-    const key = routeCacheKey(target, identity);
+    const consumerIdentity = routeOpenConsumerIdentity(opts);
+    const key = routeCacheKey(target, identity, consumerIdentity);
     let cached = this.routes.get(key);
     if (!cached) {
       cached = {
@@ -598,6 +622,7 @@ export class SubcClient {
         moduleId,
         target,
         identity,
+        consumerIdentity,
         channel: null,
         generation: 0,
         opening: null,
@@ -630,7 +655,9 @@ export class SubcClient {
       }
 
       try {
-        const channel = await this.routeOpen(cached.target, cached.identity);
+        const channel = await this.routeOpen(cached.target, cached.identity, {
+          consumerIdentity: cached.consumerIdentity ?? null,
+        });
         // Generation guard: a closeRoute may have flipped the tombstone WHILE this
         // route.open was in flight. If so, close wins — do NOT install the channel
         // into the (already-removed) cache entry; GOODBYE the channel we just opened
@@ -725,7 +752,14 @@ export class SubcClient {
     }
     for (const cached of this.routes.values()) {
       if (cached.closed) continue; // closed concurrently with reconnect — don't reopen.
-      const channel = await this.routeOpen(cached.target, cached.identity);
+      // Thread the route's consumer identity through the reopen, exactly as the
+      // lazy per-call path (openCachedRoute) does. Dropping it here would make a
+      // route reopened after a reconnect send route.open with no consumer_identity,
+      // so the daemon would re-stamp it with a different (weaker) principal than the
+      // one it was originally bound under — a silent post-reconnect trust downgrade.
+      const channel = await this.routeOpen(cached.target, cached.identity, {
+        consumerIdentity: cached.consumerIdentity ?? null,
+      });
       // A closeRoute may have raced this reopen (flipping the tombstone during the
       // route.open await). If so, GOODBYE the channel instead of installing it, so the
       // closed route isn't silently re-established on the new connection.
@@ -738,6 +772,16 @@ export class SubcClient {
     }
   }
 
+  // A request timeout carries the local socket port and (channel, corr) so a
+  // packet capture can pinpoint the exact on-wire exchange — the decisive evidence
+  // for whether a "timed out" reply was actually delivered to this socket (a
+  // client-local demux problem) or never sent (a daemon/module problem).
+  private timeoutMessage(channel: number, corr: bigint, ms: number): string {
+    const port = this.sock.localPort();
+    const where = port === null ? "channel" : `local_port=${port} channel`;
+    return `request on ${where} ${channel} corr ${corr} timed out after ${ms}ms`;
+  }
+
   private routeClosedDuringOpen(): SubcCallError {
     return new SubcCallError("not_sent", "route was closed before route.open completed", "route_closed");
   }
@@ -885,8 +929,23 @@ function normalizeConnectOptions(opts: ConnectOptions): NormalizedConnectOptions
   };
 }
 
-function routeCacheKey(target: Extract<RouteTarget, { kind: ManagedRouteKind }>, identity: BindIdentity): string {
-  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}`;
+function routeCacheKey(
+  target: Extract<RouteTarget, { kind: ManagedRouteKind }>,
+  identity: BindIdentity,
+  consumerIdentity?: ConsumerIdentity,
+): string {
+  const consumerPart = consumerIdentity
+    ? `${consumerIdentity.module_id}\0${consumerIdentity.launch_nonce}`
+    : "";
+  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}`;
+}
+
+function routeOpenConsumerIdentity(opts: RouteOpenOptions = {}): ConsumerIdentity | undefined {
+  if (opts.consumerIdentity !== undefined) return opts.consumerIdentity ?? undefined;
+  const moduleId = process.env[SUBC_MODULE_ID_ENV];
+  const launchNonce = process.env[SUBC_LAUNCH_NONCE_ENV];
+  if (!moduleId || !launchNonce) return undefined;
+  return { module_id: moduleId, launch_nonce: launchNonce };
 }
 
 function errorCode(err: unknown): string | undefined {

package/src/index.ts

@@ -3,11 +3,15 @@ export {
   SubcError,
   SubcCallError,
   DEFAULT_RECONNECT_BACKOFF,
+  SUBC_MODULE_ID_ENV,
+  SUBC_LAUNCH_NONCE_ENV,
   isConsumerReconnectTransient,
   connectionFileExists,
   type BindIdentity,
   type RouteTarget,
   type ManagedRouteKind,
+  type ConsumerIdentity,
+  type RouteOpenOptions,
   type CatalogEntry,
   type RequestOptions,
   type ManagedCallOptions,
@@ -57,6 +61,7 @@ export {
   jsonProviderHandler,
   type ProviderRequestContext,
   type BindDecision,
+  type Principal,
   type BindingsInput,
   type CircuitBreakerInput,
   type Concurrency,

package/src/provider.ts

@@ -202,10 +202,16 @@ export type ProviderHandler = (
   ctx: ProviderRequestContext,
 ) => Promise<Uint8Array | void> | Uint8Array | void;
 
+export type Principal =
+  | { kind: "reserved"; module_id: string }
+  | { kind: "direct" }
+  | { kind: "unverified" };
+
 export interface RouteBindRequest {
   route_channel: number;
   target: RouteTarget;
   identity: BindIdentity;
+  principal?: Principal;
 }
 
 export type BindDecision =
@@ -533,6 +539,7 @@ export class SubcProvider {
       route_channel: numberField(request.route_channel, "route_channel"),
       target: request.target as RouteTarget,
       identity: request.identity as BindIdentity,
+      principal: request.principal as Principal | undefined,
     };
 
     const decision = await this.opts.onBind?.(bindRequest);

package/src/socket.ts

@@ -64,6 +64,15 @@ export class SubcSocket {
     sock.on("close", () => fail(new SocketClosedError("subc connection closed")));
   }
 
+  /**
+   * The OS-assigned local TCP port of this connection, or null if not yet
+   * connected/closed. Used to correlate a client-side timeout with a specific
+   * socket in a packet capture when diagnosing reply-delivery issues.
+   */
+  localPort(): number | null {
+    return this.sock.localPort ?? null;
+  }
+
   static connect(host: string, port: number, deadlineMs: number): Promise<SubcSocket> {
     return new Promise((resolve, reject) => {
       const sock = net.connect({ host, port });