@moondeck/station 0.0.1 → 1.0.0

package/lib/internal-connections.ts

@@ -0,0 +1,5 @@
+/** ADR-164: the workspace switch is cloud-only. The host independently
+ * checks the concrete runtime identity; unknown and task machines refuse. */
+export function isOwnedInternalConnectionRuntime(provider: string | null | undefined): boolean {
+  return provider === "docker-compose" || provider === "apple-container";
+}

package/lib/keyed-promise-tail.ts

@@ -0,0 +1,23 @@
+/**
+ * Serialize asynchronous maintenance while coalescing callers for the same
+ * requested configuration. A different key always queues a distinct pass;
+ * this is stronger than a plain in-flight memo, which can let configuration C
+ * accidentally join an older B operation and then be declared reconciled.
+ */
+export class KeyedPromiseTail<T> {
+  private tail: { key: string; promise: Promise<T> } | null = null;
+
+  run(key: string, operation: () => Promise<T>): Promise<T> {
+    if (this.tail?.key === key) return this.tail.promise;
+    const predecessor = this.tail?.promise;
+    let running!: Promise<T>;
+    running = (predecessor
+      ? predecessor.catch(() => undefined)
+      : Promise.resolve()
+    ).then(operation).finally(() => {
+      if (this.tail?.promise === running) this.tail = null;
+    });
+    this.tail = { key, promise: running };
+    return running;
+  }
+}

package/lib/launch-mode.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether this host was launched for development or tests, or is an
+ * installed product. An installed service leaves NODE_ENV unset, so "not
+ * production" is the wrong test; these markers are the positive signals of a
+ * development launch. Telemetry's default DSN (lib/obs) and any development
+ * override of where credentials are sent (lib/github-origin) both read this.
+ */
+
+export type LaunchEnv = {
+  NODE_ENV?: string;
+  UAI_AGENT_FROM_REPO?: string;
+  UAI_LAUNCHED_FROM_REPO?: string;
+};
+
+/** A development or test launch: an explicit dev/test NODE_ENV, or a host
+ *  started from a repository checkout (src/load-env.ts stamps that). */
+export function isDevelopmentLaunch(env: LaunchEnv = process.env): boolean {
+  return (
+    env.NODE_ENV === "development" ||
+    env.NODE_ENV === "test" ||
+    env.UAI_AGENT_FROM_REPO === "1" ||
+    env.UAI_AGENT_FROM_REPO === "true" ||
+    env.UAI_LAUNCHED_FROM_REPO === "1"
+  );
+}

package/lib/lease.ts

@@ -0,0 +1,239 @@
+/**
+ * ADR-133 task leases — the sidecar's AWS credentials.
+ *
+ * A task machine holds no long-lived AWS credential. At connect (and ten
+ * minutes before every expiry) the sidecar sends `lease.request` over the
+ * bridge; the cloud checks that this host row is the machine of a running
+ * task, assumes the `uai-task-machine` role with session tags for the task's
+ * workspace and owner, and answers `lease.grant` with the STS session. The
+ * session is held here in memory and handed to exactly two consumers:
+ *
+ *  - the credential store's `aws` CLI calls (Parameter Store reads for engine
+ *    accounts, GitHub tokens, MCP secrets, project env) through `leaseAwsEnv()`;
+ *  - Mountpoint for Amazon S3 (shared files) through a `credential_process`
+ *    that prints the current session — so a refreshed lease reaches a mount
+ *    that is already up without remounting.
+ *
+ * Revocation is the next refresh being denied: `onDenied` fires and the
+ * sidecar exits, and the cloud's sweep terminates the machine. A lease is
+ * bound to one task and one machine; nothing here can ask for another's.
+ */
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { TaskLease } from "../src/protocol";
+
+/** Re-request this long before the session expires. */
+export const LEASE_REFRESH_LEAD_MS = 10 * 60_000;
+/** A denied or unanswered request is retried this often until it lands. */
+export const LEASE_RETRY_MS = 30_000;
+/** The cloud must answer within this window or the request is retried. */
+export const LEASE_REQUEST_TIMEOUT_MS = 20_000;
+
+/** Where the `credential_process` command reads the live session. Root-only:
+ * the agents run as `node` and never see it. */
+export const LEASE_CREDENTIALS_FILE = "/run/uai/lease-credentials.json";
+/** The AWS config Mountpoint is pointed at (`AWS_CONFIG_FILE`). */
+export const LEASE_AWS_CONFIG_FILE = "/run/uai/aws-config";
+/**
+ * The `credential_process` line: `cat` of the JSON, run by the AWS CLI and
+ * by Mountpoint's CRT profile provider through `/bin/sh -c`. NOT a script
+ * under /run — Debian mounts /run `noexec`, so a helper there fails with
+ * EACCES even for root and both clients fall through to the instance
+ * profile, which has no S3 rights (live 2026-09-10, hostless smoke 6: every
+ * mount answered "assumed-role/uai-task-machine-instance … is not
+ * authorized to perform: s3:ListBucket").
+ */
+export const LEASE_CREDENTIAL_PROCESS = `/bin/cat ${LEASE_CREDENTIALS_FILE}`;
+
+export interface LeaseSender {
+  (frame: { kind: "lease.request"; opId: string; taskId: string }): boolean;
+}
+
+export interface LeaseManagerOptions {
+  taskId: string;
+  send: LeaseSender;
+  /** First grant — the store reconciles and the S3 mount wait for this. */
+  onFirstGrant?: (lease: TaskLease) => void;
+  /** Every grant, including refreshes. */
+  onGrant?: (lease: TaskLease) => void;
+  /** The cloud refused: the task is no longer ours. */
+  onDenied?: (error: string) => void;
+  /** Test seam: skip the /run/uai files. */
+  writeFiles?: boolean;
+  now?: () => number;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+}
+
+let current: TaskLease | null = null;
+
+/** The AWS environment for a child process that should act under the lease
+ * (the credential store's CLI runner). Empty when no lease is held — the
+ * caller then runs with whatever the process has, which on a task machine
+ * is nothing. */
+export function leaseAwsEnv(): Record<string, string> {
+  if (!current) return {};
+  return {
+    AWS_ACCESS_KEY_ID: current.accessKeyId,
+    AWS_SECRET_ACCESS_KEY: current.secretAccessKey,
+    AWS_SESSION_TOKEN: current.sessionToken,
+    AWS_REGION: current.region,
+    AWS_DEFAULT_REGION: current.region,
+  };
+}
+
+export function currentLease(): TaskLease | null {
+  return current;
+}
+
+/** Test seam. */
+export function setCurrentLeaseForTesting(lease: TaskLease | null): void {
+  current = lease;
+}
+
+/** The JSON shape the AWS SDK credential_process contract expects. */
+export function credentialProcessOutput(lease: TaskLease): string {
+  return JSON.stringify({
+    Version: 1,
+    AccessKeyId: lease.accessKeyId,
+    SecretAccessKey: lease.secretAccessKey,
+    SessionToken: lease.sessionToken,
+    Expiration: new Date(lease.expiresAt).toISOString(),
+  });
+}
+
+/** The AWS config file content for a lease: default profile, region, and
+ * the `credential_process` that serves the live session. Exported for the
+ * test that pins it. */
+export function leaseAwsConfig(lease: Pick<TaskLease, "region">): string {
+  return `[default]\nregion = ${lease.region}\ncredential_process = ${LEASE_CREDENTIAL_PROCESS}\n`;
+}
+
+/** The org and user a current, unexpired lease was issued for — the credential store paths a
+ * sidecar may list (`/uai/orgs/<org>`, `/uai/users/<user>`; the task-machine
+ * policy grants nothing above them). Null on an owned host or before the
+ * first grant; `orgId` is null for a lease with no org scope. Absent from
+ * the lease when the cloud predates the field. */
+export function leaseScope(
+  now: number = Date.now(),
+): { orgId: string | null; userId: string } | null {
+  if (
+    !current ||
+    current.expiresAt <= now ||
+    typeof current.userId !== "string"
+  ) {
+    return null;
+  }
+  return { orgId: current.orgId ?? null, userId: current.userId };
+}
+
+function writeLeaseFiles(lease: TaskLease): void {
+  mkdirSync(dirname(LEASE_CREDENTIALS_FILE), { recursive: true, mode: 0o700 });
+  writeFileSync(LEASE_CREDENTIALS_FILE, credentialProcessOutput(lease), { mode: 0o600 });
+  chmodSync(LEASE_CREDENTIALS_FILE, 0o600);
+  writeFileSync(LEASE_AWS_CONFIG_FILE, leaseAwsConfig(lease), { mode: 0o600 });
+  chmodSync(LEASE_AWS_CONFIG_FILE, 0o600);
+}
+
+export class LeaseManager {
+  readonly #opts: Required<Pick<LeaseManagerOptions, "now" | "setTimer" | "clearTimer">> &
+    LeaseManagerOptions;
+  #pending: { opId: string; timer: ReturnType<typeof setTimeout> } | null = null;
+  #refresh: ReturnType<typeof setTimeout> | null = null;
+  #granted = false;
+  #stopped = false;
+  #sequence = 0;
+
+  constructor(opts: LeaseManagerOptions) {
+    this.#opts = {
+      ...opts,
+      now: opts.now ?? Date.now,
+      setTimer: opts.setTimer ?? setTimeout,
+      clearTimer: opts.clearTimer ?? clearTimeout,
+    };
+  }
+
+  /** Ask now. Idempotent while a request is in flight. */
+  request(): void {
+    if (this.#stopped || this.#pending) return;
+    const opId = `lease-${this.#opts.taskId}-${++this.#sequence}-${this.#opts.now()}`;
+    const sent = this.#opts.send({ kind: "lease.request", opId, taskId: this.#opts.taskId });
+    const timer = this.#opts.setTimer(() => {
+      // Unanswered (the socket dropped, the cloud was mid-deploy): try again.
+      this.#pending = null;
+      this.#armRetry();
+    }, LEASE_REQUEST_TIMEOUT_MS);
+    timer.unref?.();
+    this.#pending = { opId, timer };
+    if (!sent) {
+      // Nothing on the wire; retry once the socket is back.
+      this.#opts.clearTimer(timer);
+      this.#pending = null;
+      this.#armRetry();
+    }
+  }
+
+  /** Bridge dispatch hands every `lease.*` frame here. */
+  handle(frame: { kind: "lease.grant"; opId: string; lease: TaskLease } | { kind: "lease.deny"; opId: string; error: string }): void {
+    if (!this.#pending || this.#pending.opId !== frame.opId) return;
+    this.#opts.clearTimer(this.#pending.timer);
+    this.#pending = null;
+    if (frame.kind === "lease.deny") {
+      current = null;
+      this.#opts.onDenied?.(frame.error);
+      return;
+    }
+    current = frame.lease;
+    if (this.#opts.writeFiles !== false) {
+      try {
+        writeLeaseFiles(frame.lease);
+      } catch (error) {
+        console.warn(
+          `[lease] could not write the credential_process files: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    const first = !this.#granted;
+    this.#granted = true;
+    this.#armRefresh(frame.lease);
+    if (first) this.#opts.onFirstGrant?.(frame.lease);
+    this.#opts.onGrant?.(frame.lease);
+  }
+
+  /** The socket reconnected: whatever was pending is void; ask again. */
+  reconnected(): void {
+    if (this.#pending) {
+      this.#opts.clearTimer(this.#pending.timer);
+      this.#pending = null;
+    }
+    this.request();
+  }
+
+  stop(): void {
+    this.#stopped = true;
+    if (this.#pending) this.#opts.clearTimer(this.#pending.timer);
+    if (this.#refresh) this.#opts.clearTimer(this.#refresh);
+    this.#pending = null;
+    this.#refresh = null;
+  }
+
+  #armRefresh(lease: TaskLease): void {
+    if (this.#refresh) this.#opts.clearTimer(this.#refresh);
+    const delay = Math.max(1_000, lease.expiresAt - LEASE_REFRESH_LEAD_MS - this.#opts.now());
+    this.#refresh = this.#opts.setTimer(() => {
+      this.#refresh = null;
+      this.request();
+    }, delay);
+    this.#refresh.unref?.();
+  }
+
+  #armRetry(): void {
+    if (this.#stopped || this.#refresh) return;
+    this.#refresh = this.#opts.setTimer(() => {
+      this.#refresh = null;
+      this.request();
+    }, LEASE_RETRY_MS);
+    this.#refresh.unref?.();
+  }
+}