@moondeck/station 0.0.1 → 1.0.1

package/src/apple-tunnel-route.ts

@@ -0,0 +1,104 @@
+/**
+ * ADR-106 Apple tunnel routing, extracted from main.ts so its two safety
+ * properties are directly testable: the identity proof and the TCP connect
+ * both happen inside the task's lifecycle slot (a concurrent
+ * taskDown/recreate cannot free and reuse the address between proof and
+ * connection), and a readiness-epoch change during the awaited connect
+ * destroys the socket rather than carrying a dead generation's proof out.
+ */
+
+export interface AppleRouteSocket {
+  connect(port: number, host: string): void;
+  once(event: "connect" | "error", listener: () => void): void;
+  destroy(): void;
+}
+
+export interface AppleTunnelRouteDeps {
+  getTask(taskId: string): { statusMirror: string | null } | undefined;
+  reconstruct(task: unknown): Promise<{
+    inspectRoute?: () => Promise<
+      | { kind: "running"; ipv4Address: string }
+      | { kind: "unavailable" }
+      | { kind: "unknown"; detail: string }
+    >;
+  } | null>;
+  runTaskLifecycle<T>(taskId: string, work: () => Promise<T>): Promise<T>;
+  runtimeProblem(): unknown;
+  readinessEpoch(): number;
+  epochIsCurrent(epoch: number): boolean;
+  poison(detail: string): void;
+  createSocket(): AppleRouteSocket;
+  connectTimeoutMs?: number;
+}
+
+export interface AppleTunnelRouteRequest {
+  taskId: string;
+  target: string;
+  containerPort?: number;
+}
+
+export async function resolveAppleTunnelRoute(
+  request: AppleTunnelRouteRequest,
+  deps: AppleTunnelRouteDeps,
+): Promise<{ host: string; port: number; socket: AppleRouteSocket } | null> {
+  const applePort =
+    request.target === "editor" ? 8080 : request.containerPort;
+  if (!applePort) return null;
+  if (deps.getTask(request.taskId)?.statusMirror !== "running") return null;
+  return deps.runTaskLifecycle(request.taskId, async () => {
+    const current = deps.getTask(request.taskId);
+    if (!current || current.statusMirror !== "running") return null;
+    let route:
+      | { kind: "running"; ipv4Address: string }
+      | { kind: "unavailable" }
+      | { kind: "unknown"; detail: string }
+      | null = null;
+    try {
+      const handle = await deps.reconstruct(current);
+      if (handle === null || handle.inspectRoute === undefined) return null;
+      route = await handle.inspectRoute();
+    } catch {
+      return null;
+    }
+    if (route === null) return null;
+    if (route.kind === "unknown") {
+      // The CLI answered with neither presence nor absence — the same signal
+      // class as a Docker daemon that stopped responding mid-tunnel.
+      deps.poison(route.detail);
+      return null;
+    }
+    if (route.kind !== "running") return null;
+    if (deps.runtimeProblem()) return null;
+    const routeEpoch = deps.readinessEpoch();
+    const upstream = deps.createSocket();
+    const connected = await new Promise<boolean>((resolveConnect) => {
+      let settled = false;
+      const settle = (ok: boolean): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(deadline);
+        resolveConnect(ok);
+      };
+      const deadline = setTimeout(() => {
+        upstream.destroy();
+        settle(false);
+      }, deps.connectTimeoutMs ?? 10_000);
+      deadline.unref?.();
+      upstream.once("connect", () => settle(true));
+      upstream.once("error", () => settle(false));
+      upstream.connect(applePort, route.ipv4Address);
+    });
+    if (
+      !connected ||
+      // The awaited connect is a window: a forced recheck can invalidate the
+      // runtime mid-wait, and a proof from a dead generation must not carry
+      // a live socket out of the slot.
+      !deps.epochIsCurrent(routeEpoch) ||
+      deps.runtimeProblem()
+    ) {
+      upstream.destroy();
+      return null;
+    }
+    return { host: route.ipv4Address, port: applePort, socket: upstream };
+  });
+}

package/src/bridge-diagnostics.ts

@@ -0,0 +1,39 @@
+/**
+ * What station.log says about a lost cloud connection, so its cause can be
+ * read off the log. The previous MacBook Air station showed 599 reconnects
+ * over about 18 hours as bare "disconnected; reconnecting in ~1s" lines:
+ * neither who closed the socket nor why was logged, and nothing showed that
+ * the Mac had been asleep (2026-11-03).
+ */
+
+/** The close code and reason in words: who closed it, and why if known. */
+export function describeClose(code: number, reason: string): string {
+  const why = reason.trim();
+  const known: Record<number, string> = {
+    1000: "closed normally",
+    1001: "the cloud went away (restart or deploy)",
+    1006: "the connection dropped without a close frame (network, sleep or a proxy)",
+    1011: "the cloud hit an internal error",
+    1012: "the cloud is restarting",
+    1013: "the cloud asked to try again later",
+    4000: "closed by the cloud or this station",
+    4001: "authentication refused",
+  };
+  const label = known[code] ?? "closed";
+  return `code ${code}, ${label}${why ? `: ${why}` : ""}`;
+}
+
+/** How far past its due time a periodic timer may fire before the gap counts
+ *  as a suspension (system sleep, a stopped process) rather than load. */
+export const SUSPEND_SLACK_MS = 20_000;
+
+/**
+ * The time this process was suspended, when a timer due every `intervalMs`
+ * fires `now - previousTick` later; null when it fired on time. A sleeping
+ * Mac stops every timer; on wake the gap shows, the cloud has long dropped
+ * the silent socket (it closes one silent for 45 s), and a reconnect follows.
+ */
+export function suspendedFor(previousTick: number, now: number, intervalMs: number): number | null {
+  const gap = now - previousTick;
+  return gap > intervalMs + SUSPEND_SLACK_MS ? gap : null;
+}

package/src/capture-wire.ts

@@ -0,0 +1,102 @@
+/** Pure capture contract, independent of leases and custom connections. */
+import { parseLeaseParameterName, parseBrokerParameterName, sameLocation, isIdValue, isTagValue, type CredentialLocation } from "./credential-location";
+import { exactObject, isPositiveInteger, isEpochMs } from "./credential-wire-validation";
+
+/**
+ * What the cloud tells the sign-in box to write for one capture: the
+ * revision's parameters (the box never chooses a name) and the ids it tags
+ * them with. The box checks every field against the others before it writes.
+ */
+export interface CaptureFlowWire {
+  credentialId: string;
+  revision: string;
+  leaseParameter: string;
+  /** Null for a static credential. */
+  brokerParameter: string | null;
+  /** The workspace tag: required except for GitHub and SSH. */
+  orgId: string | null;
+  /** The person, for a personal credential. */
+  userId: string | null;
+}
+
+/** What the box answers once both parts are written: never material. */
+export interface CaptureResultWire {
+  credentialId: string;
+  revision: string;
+  /** The lease-readable parameter's Parameter Store version. */
+  leaseVersion: number;
+  /** The access token's expiry when the box could read it. */
+  expiresAt: number | null;
+}
+
+/**
+ * A capture flow, rebuilt and checked, with the location its parameters name,
+ * or null. The two parameters must name the same credential and revision under
+ * their own roots, and the tags must be the parameter's owner: a workspace
+ * credential's `orgId` is its owner and it has no `userId`; a personal AI
+ * account or MCP connection names both its person and its workspace; GitHub
+ * and SSH name their person alone.
+ */
+export function parseCaptureFlowWire(
+  value: unknown,
+): (CaptureFlowWire & { location: CredentialLocation }) | null {
+  const o = exactObject(value, [
+    "credentialId",
+    "revision",
+    "leaseParameter",
+    "brokerParameter",
+    "orgId",
+    "userId",
+  ]);
+  if (
+    !o ||
+    !isIdValue(o.credentialId) ||
+    !isIdValue(o.revision) ||
+    typeof o.leaseParameter !== "string" ||
+    !(o.brokerParameter === null || typeof o.brokerParameter === "string") ||
+    !(o.orgId === null || (isIdValue(o.orgId) && isTagValue(o.orgId))) ||
+    !(o.userId === null || (isIdValue(o.userId) && isTagValue(o.userId)))
+  ) {
+    return null;
+  }
+  const location = parseLeaseParameterName(o.leaseParameter);
+  if (!location || location.revision !== o.revision) return null;
+  const isPerson = location.class === "github" || location.class === "ssh";
+  if (!isPerson && location.credentialId !== o.credentialId) return null;
+  if (o.brokerParameter !== null) {
+    const broker = parseBrokerParameterName(o.brokerParameter);
+    if (!broker || !sameLocation(broker, location)) return null;
+  }
+  if (isPerson && o.brokerParameter !== null) return null;
+  const ownerOk =
+    location.scope === "org"
+      ? o.orgId === location.ownerId && o.userId === null
+      : o.userId === location.ownerId && (isPerson ? o.orgId === null : o.orgId !== null);
+  if (!ownerOk) return null;
+  return {
+    credentialId: o.credentialId,
+    revision: o.revision,
+    leaseParameter: o.leaseParameter,
+    brokerParameter: o.brokerParameter,
+    orgId: o.orgId,
+    userId: o.userId,
+    location,
+  };
+}
+
+export function parseCaptureResultWire(value: unknown): CaptureResultWire | null {
+  const o = exactObject(value, ["credentialId", "revision", "leaseVersion", "expiresAt"]);
+  return o &&
+    isIdValue(o.credentialId) &&
+    isIdValue(o.revision) &&
+    isPositiveInteger(o.leaseVersion) &&
+    (o.expiresAt === null || isEpochMs(o.expiresAt))
+    ? {
+        credentialId: o.credentialId,
+        revision: o.revision,
+        leaseVersion: o.leaseVersion,
+        expiresAt: o.expiresAt,
+      }
+    : null;
+}
+