@cortexkit/subc-client 0.21.2 → 0.22.2

package/src/launch-nonce.ts

@@ -9,14 +9,15 @@
  * {@link launchNonce} reads that descriptor once, closes it, and caches the
  * value for the life of the process. While modules move over, the daemon also
  * keeps setting the environment copy (`SUBC_LAUNCH_NONCE`), which
- * {@link launchNonce} reads when no descriptor is named. Windows has no
- * descriptor handoff, so there only the environment copy is read.
+ * {@link launchNonce} reads when no descriptor is named. Windows uses a
+ * PID-authenticated named pipe; call {@link launchNonceAsync} to initialize it.
  *
  * This mirrors the Rust accessor in `subc-os` (`subc_os::launch_nonce`): the
  * same checks in the same order, the same error names and messages.
  */
 
 import { closeSync, fstatSync, readSync, type BigIntStats } from "node:fs";
+import { connect, type Socket } from "node:net";
 
 /** The environment copy of the nonce, kept only while modules move to the descriptor. */
 export const SUBC_LAUNCH_NONCE_ENV = "SUBC_LAUNCH_NONCE";
@@ -30,11 +31,20 @@ export const SUBC_LAUNCH_NONCE_ENV = "SUBC_LAUNCH_NONCE";
  */
 export const SUBC_LAUNCH_NONCE_FD_ENV = "SUBC_LAUNCH_NONCE_FD";
 
+/** The one-time Windows pipe name. Its name is not a secret. */
+export const SUBC_LAUNCH_NONCE_PIPE_ENV = "SUBC_LAUNCH_NONCE_PIPE";
+
+/** When the daemon sets this variable to `env`, a failed pipe read may use
+ * `SUBC_LAUNCH_NONCE` instead. The daemon keeps that copy until every module
+ * reads its secret from the pipe, so older modules can still register.
+ */
+export const SUBC_LAUNCH_NONCE_PIPE_FALLBACK_ENV = "SUBC_LAUNCH_NONCE_PIPE_FALLBACK";
+
 /** The descriptor number the daemon gives the pipe's read end in the module. */
 export const LAUNCH_NONCE_FD = 3;
 
 /** Where a process got its launch nonce from, as modules report it in provenance. */
-export type LaunchNonceSource = "fd" | "env";
+export type LaunchNonceSource = "fd" | "pipe" | "env";
 
 /** The nonce this process was launched with, and where it came from. */
 export interface LaunchNonce {
@@ -46,7 +56,9 @@ export interface LaunchNonce {
  * Why the descriptor named by `SUBC_LAUNCH_NONCE_FD` gave no nonce. The names
  * are the Rust `LaunchNonceError` variants.
  *
- * None of these falls back to the environment copy. A named descriptor that
+ * These errors never fall back unless the Windows daemon explicitly sets
+ * `SUBC_LAUNCH_NONCE_PIPE_FALLBACK=env` while offering a nonempty environment copy.
+ * A named descriptor that
  * cannot be read means the handoff went wrong, or that this process inherited
  * the variable from a module without inheriting the pipe; reading the
  * environment instead would hide the first and defeat the second.
@@ -65,7 +77,12 @@ export type LaunchNonceErrorKind =
   /** Reading the named pipe failed. */
   | "Unreadable"
   /** The named pipe held bytes that are not UTF-8. */
-  | "NotUtf8";
+  | "NotUtf8"
+  | "PipeNeedsAsync"
+  | "PipeNotOpen"
+  | "PipeEmpty"
+  | "PipeUnreadable"
+  | "PipeNotUtf8";
 
 export interface LaunchNonceErrorDetails {
   /** The descriptor number, for every kind except `Malformed`. */
@@ -134,6 +151,10 @@ export function isLaunchNonceError(error: unknown): error is LaunchNonceError {
  *   names is taken only if it is a pipe with the named inode and holds bytes;
  *   it is then read to end of file and closed. Anything else throws and leaves
  *   the descriptor as it was, and never falls back to the environment.
+ * - Windows pipe reads use the async accessor. An uninitialized sync pipe
+ *   reader throws `PipeNeedsAsync`, except when the daemon explicitly permits
+ *   fallback with `SUBC_LAUNCH_NONCE_PIPE_FALLBACK=env`; then a sync reader
+ *   caches the environment copy.
  * - Otherwise the value of `SUBC_LAUNCH_NONCE` is used.
  *
  * It never changes `process.env`. Removing either variable would break any
@@ -164,6 +185,33 @@ export function launchNonceOrUndefined(): LaunchNonce | undefined {
   return result.ok ? result.nonce ?? undefined : undefined;
 }
 
+/** Initialize the Windows pipe, or use the synchronous Unix/environment reader.
+ * Concurrent callers share one in-flight read and its cached result. After this
+ * completes, synchronous accessors return that same result. With the daemon's
+ * explicit `SUBC_LAUNCH_NONCE_PIPE_FALLBACK=env` permission, failed or incomplete
+ * pipe reads cache `SUBC_LAUNCH_NONCE` and its `env` source. Without that variable
+ * set to `env`, a failed pipe read remains an error even if the copy exists.
+ * Node's public pipe API cannot ask Windows to let the server inspect the
+ * client's identity without also allowing it to impersonate the client's token.
+ */
+export async function launchNonceAsync(): Promise<LaunchNonce | undefined> {
+  const cell = processCell();
+  return unwrap(await (cell.resultAsync?.() ?? cell.result()));
+}
+
+/** Return the cached nonce asynchronously, or `undefined` if its read failed.
+ * The SDK uses this when building `route.open`: without a nonce it omits
+ * `consumer_identity` instead of presenting an unread or invalid credential.
+ */
+export async function launchNonceOrUndefinedAsync(): Promise<LaunchNonce | undefined> {
+  try {
+    return await launchNonceAsync();
+  } catch (error) {
+    if (isLaunchNonceError(error)) return undefined;
+    throw error;
+  }
+}
+
 type CachedResult =
   | { readonly ok: true; readonly nonce: LaunchNonce | null }
   | { readonly ok: false; readonly error: LaunchNonceError };
@@ -174,6 +222,7 @@ type CachedResult =
  */
 interface SharedLaunchNonceCell {
   result(): CachedResult;
+  resultAsync?(): Promise<CachedResult>;
 }
 
 /**
@@ -219,27 +268,68 @@ export type LaunchNonceStat = (fd: number) => Pick<BigIntStats, "isFIFO" | "ino"
  */
 export class LaunchNonceCell implements SharedLaunchNonceCell {
   private cached: CachedResult | undefined;
+  private pending: Promise<CachedResult> | undefined;
   /** How many times this cell has taken a descriptor. At most one. */
   descriptorReads = 0;
   private readonly lookup: (key: string) => string | undefined;
   private readonly platform: NodeJS.Platform;
   private readonly stat: LaunchNonceStat;
+  private readonly pipeReader: (name: string) => Promise<LaunchNonce>;
 
   constructor(
     lookup: (key: string) => string | undefined,
     platform: NodeJS.Platform = process.platform,
     stat: LaunchNonceStat = (fd) => fstatSync(fd, { bigint: true }),
+    pipeReader: (name: string) => Promise<LaunchNonce> = readLaunchNoncePipe,
   ) {
     this.lookup = lookup;
     this.platform = platform;
     this.stat = stat;
+    this.pipeReader = pipeReader;
   }
 
   result(): CachedResult {
+    if (this.cached === undefined && this.platform === "win32" && this.lookup(SUBC_LAUNCH_NONCE_PIPE_ENV) !== undefined) {
+      const fallback = this.permittedPipeFallback();
+      if (fallback === undefined) {
+        throw new LaunchNonceError("PipeNeedsAsync", "call launchNonceAsync() before the synchronous reader when SUBC_LAUNCH_NONCE_PIPE is set");
+      }
+      // Legacy synchronous readers cannot use net.connect. Only the daemon's
+      // explicit fallback permission lets them retain environment startup while
+      // environment-only modules migrate to async pipe reads.
+      this.cached = { ok: true, nonce: fallback };
+    }
     if (this.cached === undefined) this.cached = this.read();
     return this.cached;
   }
 
+  async resultAsync(): Promise<CachedResult> {
+    if (this.cached !== undefined) return this.cached;
+    if (this.pending !== undefined) return this.pending;
+    const named = this.platform === "win32" ? this.lookup(SUBC_LAUNCH_NONCE_PIPE_ENV) : undefined;
+    if (named === undefined) return this.result();
+    const fallback = this.permittedPipeFallback();
+    this.pending = this.pipeReader(named).then(
+      (nonce): CachedResult => ({ ok: true, nonce: fallback !== undefined && nonce.value !== fallback.value ? fallback : nonce }),
+      (error: unknown): CachedResult => {
+        if (fallback !== undefined) return { ok: true, nonce: fallback };
+        if (!isLaunchNonceError(error)) throw error;
+        return { ok: false, error };
+      },
+    ).then((result) => { this.cached ??= result; return this.cached; });
+    return this.pending;
+  }
+
+  private permittedPipeFallback(): LaunchNonce | undefined {
+    if (this.lookup(SUBC_LAUNCH_NONCE_PIPE_FALLBACK_ENV) !== "env") return undefined;
+    const value = this.lookup(SUBC_LAUNCH_NONCE_ENV);
+    return value ? makeLaunchNonce(value, "env") : undefined;
+  }
+
+  async getAsync(): Promise<LaunchNonce | undefined> {
+    return unwrap(await this.resultAsync());
+  }
+
   /** The cached value, reading it first if no caller has yet; throws a refusal. */
   get(): LaunchNonce | undefined {
     return unwrap(this.result());
@@ -445,3 +535,75 @@ function closeQuietly(fd: number): void {
     // Nothing useful can be done if closing the consumed pipe fails.
   }
 }
+
+/** Read a one-time pipe to EOF. The injected connector and budgets let unit
+ * tests exercise busy retry and timeouts without requiring a Windows host.
+ */
+export async function readLaunchNoncePipe(
+  name: string,
+  connector: (name: string) => Socket = (path) => connect(path),
+  openWindowMs = 500,
+  readWindowMs = 2000,
+): Promise<LaunchNonce> {
+  const deadline = Date.now() + openWindowMs;
+  for (;;) {
+    try {
+      const bytes = await pipeAttempt(name, connector, Math.max(1, deadline - Date.now()), readWindowMs);
+      if (bytes.length === 0) throw new LaunchNonceError("PipeEmpty", "the launch nonce named pipe is empty");
+      let value: string;
+      try {
+        value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch {
+        throw new LaunchNonceError("PipeNotUtf8", "the launch nonce named pipe held bytes that are not UTF-8");
+      }
+      return makeLaunchNonce(value, "pipe");
+    } catch (error) {
+      if (isLaunchNonceError(error)) throw error;
+      const busy = (error as NodeJS.ErrnoException)?.code === "EBUSY" || errnoOf(error) === 231;
+      if (!busy || Date.now() >= deadline) {
+        throw new LaunchNonceError("PipeNotOpen", "SUBC_LAUNCH_NONCE_PIPE names a pipe that could not be opened", { errno: errnoOf(error) });
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(10, Math.max(1, deadline - Date.now()))));
+    }
+  }
+}
+
+function pipeAttempt(
+  name: string,
+  connector: (name: string) => Socket,
+  openWindowMs: number,
+  readWindowMs: number,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    let socket: Socket;
+    try { socket = connector(name); } catch (error) { reject(error); return; }
+    let connected = false;
+    let settled = false;
+    let size = 0;
+    const chunks: Buffer[] = [];
+    let timer = setTimeout(() => finish(new LaunchNonceError("PipeNotOpen", "launch nonce pipe open timed out")), openWindowMs);
+    function finish(error?: unknown): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error !== undefined) reject(error);
+      else resolve(Buffer.concat(chunks));
+    }
+    socket.once("connect", () => {
+      connected = true;
+      clearTimeout(timer);
+      timer = setTimeout(() => finish(new LaunchNonceError("PipeUnreadable", "launch nonce pipe read timed out")), readWindowMs);
+    });
+    socket.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > 4096) { finish(new LaunchNonceError("PipeUnreadable", "launch nonce pipe exceeded its byte limit")); return; }
+      chunks.push(Buffer.from(chunk));
+    });
+    socket.once("end", () => finish());
+    socket.once("error", (error) => finish(connected ? new LaunchNonceError("PipeUnreadable", "could not read the launch nonce from the named pipe", { errno: errnoOf(error) }) : error));
+    socket.once("close", () => {
+      if (!settled) finish(new LaunchNonceError("PipeUnreadable", "launch nonce pipe closed before EOF"));
+    });
+  });
+}

package/src/provider.ts

@@ -27,7 +27,8 @@ import {
 } from "./envelope.js";
 import {
   isLaunchNonceError,
-  launchNonce as processLaunchNonce,
+  launchNonceAsync as processLaunchNonce,
+  launchNonceOrUndefinedAsync,
   launchNonceOrUndefined,
   type LaunchNonceError,
   type LaunchNonceSource,
@@ -680,7 +681,7 @@ export class SubcProvider {
       );
     }
 
-    const normalized = normalizeProviderConnectOptions(opts);
+    const normalized = await normalizeProviderConnectOptions(opts);
     const opened = await SubcProvider.openConnection(normalized);
     return new SubcProvider(opened.sock, opened.conn, normalized, opened.ack);
   }
@@ -1466,7 +1467,7 @@ function nonEmpty(value: string | undefined): string | undefined {
   return value && value.length > 0 ? value : undefined;
 }
 
-function normalizeProviderConnectOptions(opts: SubcProviderConnectOptions): NormalizedSubcProviderConnectOptions {
+async function normalizeProviderConnectOptions(opts: SubcProviderConnectOptions): Promise<NormalizedSubcProviderConnectOptions> {
   // The environment is read once here. The daemon injects both variables when it
   // spawns a module; together they mark the process as supervised, and the nonce
   // is also what HELLO echoes for a reserved module_id.
@@ -1478,13 +1479,13 @@ function normalizeProviderConnectOptions(opts: SubcProviderConnectOptions): Norm
   let processNonce: string | undefined;
   if (opts.launchNonce === undefined) {
     try {
-      processNonce = processLaunchNonce()?.value;
+      processNonce = (await processLaunchNonce())?.value;
     } catch (error) {
       if (isLaunchNonceError(error)) throw launchNonceUnavailable(error);
       throw error;
     }
   } else {
-    processNonce = launchNonceOrUndefined()?.value;
+    processNonce = (await launchNonceOrUndefinedAsync())?.value;
   }
   const envLaunchNonce = nonEmpty(processNonce);
   const supervised = envModuleId !== undefined && envLaunchNonce !== undefined;