@moondeck/station 0.0.1 → 1.0.0

package/lib/project-env-feature.ts

@@ -0,0 +1,74 @@
+/**
+ * Host-only release switch for ADR-153 project-env bindings.
+ *
+ * Capability advertisement and task admission move together: once a sidecar
+ * advertises the protocol, its task cannot expose a legacy env view before the
+ * replica's first complete reconciliation. Advertisement also waits for the
+ * durable managed-runtime floor, so no acknowledged generation can roll back
+ * to code that serves the old value-only store.
+ */
+import { PROJECT_ENV_BINDINGS_PROTOCOL_FEATURE } from "../src/protocol";
+import { PROJECT_ENV_POLICY_EPOCHS } from "../src/project-env-policy";
+import { MANAGED_RUNTIME_CAPABILITY_VERSION } from "./runtime-archive";
+
+const PROJECT_ENV_BINDINGS_ENABLED = true;
+export const PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY =
+  MANAGED_RUNTIME_CAPABILITY_VERSION;
+
+let capabilityFloorClaim: Promise<void> | null = null;
+let capabilityFloorClaimFailed = false;
+let capabilityReady = false;
+
+/**
+ * Claim the irreversible rollback floor before the first capability frame.
+ * The rejected promise is deliberately retained: one process gets one claim
+ * attempt and stays fail-closed until restart if durable persistence fails.
+ */
+export async function initializeProjectEnvBindingCapability(
+  claimFloor: (minimumCapability: number) => Promise<void>,
+): Promise<boolean> {
+  if (!PROJECT_ENV_BINDINGS_ENABLED) return false;
+  capabilityFloorClaim ??= Promise.resolve()
+    .then(() => claimFloor(PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY))
+    .then(() => {
+      capabilityReady = true;
+    })
+    .catch((error: unknown) => {
+      capabilityFloorClaimFailed = true;
+      throw error;
+    });
+  await capabilityFloorClaim;
+  return true;
+}
+
+/**
+ * Complete the in-process half of the first-upgrade transaction. The managed
+ * runtime calls this synchronously under its operation lock after floor 4 is
+ * durable and before it removes activationPending, so task admission cannot
+ * observe a value-only feature state between those two commits.
+ */
+export function completeProjectEnvBindingCapabilityAfterRuntimeActivation(): void {
+  if (!PROJECT_ENV_BINDINGS_ENABLED || capabilityReady) return;
+  if (capabilityFloorClaim === null || !capabilityFloorClaimFailed) {
+    throw new Error(
+      "project env capability has no failed activation claim to complete",
+    );
+  }
+  capabilityFloorClaim = Promise.resolve();
+  capabilityFloorClaimFailed = false;
+  capabilityReady = true;
+}
+
+/** One nullable bundle makes the feature id and its required policy epochs an
+ * atomic advertisement, and is also TaskUp's release admission switch. */
+export function projectEnvBindingCapability(): {
+  feature: string;
+  policyEpochs: number[];
+} | null {
+  return PROJECT_ENV_BINDINGS_ENABLED && capabilityReady
+    ? {
+        feature: PROJECT_ENV_BINDINGS_PROTOCOL_FEATURE,
+        policyEpochs: [...PROJECT_ENV_POLICY_EPOCHS],
+      }
+    : null;
+}

package/lib/project-env-legacy-tags.ts

@@ -0,0 +1,130 @@
+/**
+ * ADR-154 §9: the sign-in box tags pinned legacy env parameters.
+ *
+ * ADR-153's backfill pinned `<prefix>/projects/<projectId>/env/<KEY>` by
+ * version and LastModifiedDate without checking its tags, and a v1 lease
+ * reads `/uai/projects/*` only where the `org` tag is the task's workspace.
+ * The box puts the project's `org` and `project` tags on each parameter the
+ * cloud names and reads them back, with `ssm:AddTagsToResource` and
+ * `ssm:ListTagsForResource`, which its policy already grants on
+ * `/uai/projects/*`. It never reads a value; the cloud checks each pin,
+ * before and after, from its own metadata reads.
+ */
+
+import {
+  isProjectEnvLegacyTagFrame,
+  type ProjectEnvLegacyTagAckFrame,
+  type ProjectEnvLegacyTagFrame,
+  type ProjectEnvLegacyTagOutcome,
+} from "../src/protocol";
+import {
+  CredentialStoreCommandError,
+  configuredCredentialStore,
+  credentialStorePrefix,
+  parameterName,
+  type CredentialStore,
+} from "./credential-store";
+import { PROJECT_ENV_STAGING_TAGS } from "./project-env-staging";
+
+/** A frame starts no key after this; the rest are asked again. With one
+ *  key's two CLI calls after it (30 seconds each at most), the answer still
+ *  reaches the cloud inside its 90-second wait (lib/host-bridge.ts), and a
+ *  managed restart, which waits for drained work, waits that long at most. */
+export const LEGACY_TAG_BUDGET_MS = 20_000;
+
+/** AWS's answers for a parameter that is not there. */
+const MISSING_CODES = new Set(["InvalidResourceId", "ParameterNotFound"]);
+/** AWS will put no more tags on it: nothing a retry changes. */
+const REFUSED_CODES = new Set(["TooManyTagsError"]);
+
+/** The legacy layout's name for one key, as the cloud's
+ *  `projectEnvCloudLegacyParameterName` writes it. */
+export function projectEnvLegacyParameterName(
+  projectId: string,
+  key: string,
+  prefix = credentialStorePrefix(),
+): string {
+  return parameterName(prefix, "projects", projectId, "env", key);
+}
+
+async function tagOne(
+  store: CredentialStore,
+  name: string,
+  tags: Record<string, string>,
+): Promise<ProjectEnvLegacyTagOutcome> {
+  try {
+    await store.tag(name, tags);
+    // Tags are eventually consistent: one not read back yet is a retry, and
+    // tagging again is harmless.
+    const read = await store.listTags(name);
+    return Object.entries(tags).every(([key, value]) => read[key] === value) ? "tagged" : "retry";
+  } catch (error) {
+    const code = error instanceof CredentialStoreCommandError ? error.awsCode : null;
+    if (code !== null && MISSING_CODES.has(code)) return "missing";
+    if (code !== null && REFUSED_CODES.has(code)) return "refused";
+    return "retry";
+  }
+}
+
+export interface ProjectEnvLegacyTagOptions {
+  store?: CredentialStore | null;
+  prefix?: string;
+  now?: () => number;
+  /** When the frame arrived: its budget runs from there. */
+  startedAt?: number;
+  budgetMs?: number;
+  stopping?: () => boolean;
+}
+
+/** Tag each named parameter in turn; one key's failure is its own. Keys
+ *  past the budget, or after the host begins shutting down, are asked again
+ *  without a call. */
+export async function tagProjectEnvLegacyParameters(
+  frame: ProjectEnvLegacyTagFrame,
+  options: ProjectEnvLegacyTagOptions = {},
+): Promise<ProjectEnvLegacyTagAckFrame["results"]> {
+  if (!isProjectEnvLegacyTagFrame(frame)) {
+    throw new Error("invalid legacy environment tag request");
+  }
+  const store = Object.prototype.hasOwnProperty.call(options, "store")
+    ? options.store
+    : configuredCredentialStore();
+  if (!store) return frame.keys.map((key) => ({ key, outcome: "retry" }));
+  const prefix = options.prefix ?? credentialStorePrefix();
+  const tags = {
+    [PROJECT_ENV_STAGING_TAGS.org]: frame.orgId,
+    [PROJECT_ENV_STAGING_TAGS.project]: frame.projectId,
+  };
+  const now = options.now ?? Date.now;
+  const startedAt = options.startedAt ?? now();
+  const budgetMs = options.budgetMs ?? LEGACY_TAG_BUDGET_MS;
+  const results: ProjectEnvLegacyTagAckFrame["results"] = [];
+  for (const key of frame.keys) {
+    if (now() - startedAt >= budgetMs || options.stopping?.() === true) {
+      results.push({ key, outcome: "retry" });
+      continue;
+    }
+    const name = projectEnvLegacyParameterName(frame.projectId, key, prefix);
+    results.push({ key, outcome: await tagOne(store, name, tags) });
+  }
+  return results;
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+/**
+ * One frame at a time, in arrival order: a frame whose key stalled in a CLI
+ * call (its budget stops it starting more, not the call it is in) cannot
+ * land its tags after a later frame's, which may name another workspace or
+ * have been read back already. A frame that waited out its budget in line
+ * answers at once, each key asked again.
+ */
+export function queueProjectEnvLegacyTag(
+  frame: ProjectEnvLegacyTagFrame,
+  options: ProjectEnvLegacyTagOptions = {},
+): Promise<ProjectEnvLegacyTagAckFrame["results"]> {
+  const startedAt = options.startedAt ?? (options.now ?? Date.now)();
+  const run = queue.then(() => tagProjectEnvLegacyParameters(frame, { ...options, startedAt }));
+  queue = run.catch(() => undefined);
+  return run;
+}

package/lib/project-env-loader.ts

@@ -0,0 +1,242 @@
+/**
+ * ADR-153 project-env resolution and shell-document rendering.
+ *
+ * This module is the one value-bearing seam between the encrypted host store
+ * and a task's authenticated loopback gateway. It keeps one rendered snapshot
+ * in memory and invalidates it synchronously with project-value mutations, so
+ * a rotation or deletion is visible to the next command without a restart.
+ */
+
+import { createHash } from "node:crypto";
+
+import {
+  getDecryptedForProject,
+  isReservedTaskEnvName,
+  projectEnvRevision,
+} from "./host-env";
+import type { TaskEnvView } from "./project-env-task-policy";
+import type { TaskProjectEnvSpec } from "./runtime-state";
+import type {
+  TaskGatewayEnvResolver,
+  TaskGatewayEnvSnapshot,
+} from "./task-gateway-state";
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export interface ResolvedTaskProjectEnv {
+  /** Only currently-delivered names. A deleted name disappears on refresh. */
+  readonly values: Readonly<Record<string, string>>;
+}
+
+/**
+ * Where a task's project values come from (ADR-153 §6, "Reconciling a
+ * runner"): one snapshot's view of the store; nothing at all, while the
+ * store is unreconciled or a read of it failed; or, only for a build whose
+ * store predates records, the stored values as they are. `none` never falls
+ * back to the stored values.
+ */
+export type TaskEnvSource =
+  | { kind: "view"; view: TaskEnvView }
+  | { kind: "none" }
+  | { kind: "stored" };
+
+const STORED: TaskEnvSource = { kind: "stored" };
+
+function compareAscii(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function previewNameAllowed(name: string): boolean {
+  // UAI_EDITOR_THEME is a cloud-owned non-secret task literal consumed once
+  // while seeding the editor. Every other reserved name remains host-owned.
+  return name === "UAI_EDITOR_THEME" || !isReservedTaskEnvName(name);
+}
+
+/**
+ * Resolve lead-project precedence before applying that row's declaration.
+ * With the task's view (ADR-153 §4), that view is the only source of project
+ * values: each delivered key's value as of its decision's head, from one
+ * snapshot of the store, never a separate read of the store here. The view
+ * already applied ownership and policy to the live records, so the names
+ * frozen into the task at launch do not filter it: a key added since reaches
+ * the next command, as a changed one does. With `none`, there are no project
+ * values at all.
+ */
+export function resolveTaskProjectEnv(
+  spec: TaskProjectEnvSpec,
+  source: TaskEnvSource = STORED,
+): ResolvedTaskProjectEnv {
+  const view = source.kind === "view" ? source.view : null;
+  const selected: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  const claimed = new Set<string>();
+  const projects = [...spec.projects].sort(
+    (left, right) =>
+      left.position - right.position ||
+      compareAscii(left.projectId, right.projectId),
+  );
+
+  if (view !== null) {
+    for (const policy of view.policies) {
+      if (policy.kind !== "deliver") continue;
+      const value = Object.hasOwn(view.values, policy.key) ? view.values[policy.key] : undefined;
+      const project = projects.find((candidate) => candidate.projectId === policy.projectId);
+      if (
+        value === undefined ||
+        project === undefined ||
+        !ENV_NAME.test(policy.key) ||
+        isReservedTaskEnvName(policy.key) ||
+        value.includes("\0")
+      ) {
+        continue;
+      }
+      selected[policy.key] = value;
+    }
+  }
+
+  for (const project of source.kind === "stored" ? projects : []) {
+    const stored = getDecryptedForProject(project.projectId);
+    const declared = new Set(project.declaredNames);
+    for (const [name, value] of Object.entries(stored)) {
+      if (
+        claimed.has(name) ||
+        !ENV_NAME.test(name) ||
+        isReservedTaskEnvName(name)
+      ) {
+        continue;
+      }
+      // The first stored row owns this key even when that project's schema
+      // does not declare it. Falling through would pair a later project's
+      // declaration with a different project's value, violating ADR-153's
+      // one-authority-unit rule.
+      claimed.add(name);
+      if (!declared.has(name)) continue;
+      if (typeof value !== "string" || value.includes("\0")) continue;
+      selected[name] = value;
+    }
+  }
+
+  // Preview/theme literals are task-scoped and intentionally win a collision
+  // with project env, matching the pre-loader Compose contract.
+  for (const [name, value] of Object.entries(spec.previewEnv)) {
+    if (
+      ENV_NAME.test(name) &&
+      previewNameAllowed(name) &&
+      !value.includes("\0")
+    ) {
+      selected[name] = value;
+    }
+  }
+  return { values: selected };
+}
+
+/** POSIX single-quote syntax, valid in dash, bash and zsh. */
+export function quoteTaskEnvValue(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Render the complete document validated by env-hook.sh. The digest covers
+ * the value-bearing prefix; its raw hex is repeated only in the terminal
+ * sentinel, while HTTP receives the quoted strong ETag.
+ */
+export function renderTaskProjectEnv(
+  resolved: ResolvedTaskProjectEnv,
+): TaskGatewayEnvSnapshot {
+  const names = Object.keys(resolved.values).sort(compareAscii);
+  let prefix = `# uai-env-v1 keys=${names.join(" ")}\n`;
+  for (const name of names) {
+    prefix += `export ${name}=${quoteTaskEnvValue(resolved.values[name] ?? "")}\n`;
+  }
+  const revision = createHash("sha256").update(prefix, "utf8").digest("hex");
+  return {
+    body: `${prefix}# uai-env-v1 end=${revision}\n`,
+    etag: `"${revision}"`,
+  };
+}
+
+/**
+ * Resolver closure installed on a durable task-gateway generation. The
+ * rendered snapshot stays in memory while every project used by the task has
+ * the same value revision. A set, delete, or credential-store reconcile bumps
+ * that project's revision synchronously, so the next request recomputes and
+ * still observes rotations and removals immediately.
+ *
+ * `uaiEnv` is the runner's own env for the task (the secrets proxy's trust
+ * variables while it runs), read per request: reserved names only, so it
+ * never collides with a project value, and its change re-renders too.
+ *
+ * `proxiedEnv` is the task's proxy-mode keys (ADR-153): each such name is
+ * withheld from the project values, and carries its placeholder only while
+ * the key is usable. Also read per request, and part of the cache key, so a
+ * change of readiness alone (pins in, pins failed) re-renders.
+ */
+export function taskProjectEnvResolver(
+  spec: TaskProjectEnvSpec,
+  uaiEnv: () => Readonly<Record<string, string>> = () => ({}),
+  proxiedEnv: () => {
+    readonly withheld: readonly string[];
+    readonly placeholders: Readonly<Record<string, string>>;
+  } = () => ({ withheld: [], placeholders: {} }),
+  taskSource: () => TaskEnvSource = () => STORED,
+  taskSecrets: () => { revision: string; withheld: readonly string[]; values: Readonly<Record<string, string>> } = () => ({ revision: "", withheld: [], values: {} }),
+): TaskGatewayEnvResolver {
+  const projectIds = [...new Set(spec.projects.map((project) => project.projectId))];
+  let revisions: number[] | undefined;
+  let runnerKey: string | undefined;
+  let snapshot: TaskGatewayEnvSnapshot | undefined;
+
+  return () => {
+    const currentRevisions = projectIds.map(projectEnvRevision);
+    const currentUai = uaiEnv();
+    const currentProxied = proxiedEnv();
+    const currentSource = taskSource();
+    const secrets = taskSecrets();
+    const currentRunnerKey = JSON.stringify([
+      secrets.revision,
+      Object.entries(currentUai).sort(([a], [b]) => compareAscii(a, b)),
+      [...currentProxied.withheld].sort(compareAscii),
+      Object.entries(currentProxied.placeholders).sort(([a], [b]) => compareAscii(a, b)),
+      // The source, and a view's decisions and heads, never its values: a
+      // head that moves re-renders.
+      currentSource.kind === "view" ? [currentSource.kind, currentSource.view.policies] : [currentSource.kind],
+    ]);
+    if (
+      snapshot &&
+      runnerKey === currentRunnerKey &&
+      revisions?.length === currentRevisions.length &&
+      revisions.every((revision, index) => revision === currentRevisions[index])
+    ) {
+      return snapshot;
+    }
+
+    const resolved = resolveTaskProjectEnv(spec, currentSource);
+    const values: Record<string, string> = Object.create(null) as Record<string, string>;
+    Object.assign(values, resolved.values);
+    const withheld = new Set([
+      ...currentProxied.withheld,
+      ...secrets.withheld,
+      ...(currentSource.kind === "view" ? currentSource.view.notDelivered : []),
+    ]);
+    for (const name of withheld) delete values[name];
+    // With no project env at all, no placeholder stands in for one either.
+    const placeholders = currentSource.kind === "none" ? {} : currentProxied.placeholders;
+    for (const [name, placeholder] of Object.entries(placeholders)) {
+      // Only in place of a withheld proxy-mode value, never a new name.
+      if (withheld.has(name) && ENV_NAME.test(name) && !isReservedTaskEnvName(name) && !placeholder.includes("\0")) {
+        values[name] = placeholder;
+      }
+    }
+    Object.assign(values, secrets.values);
+    for (const [name, value] of Object.entries(currentUai)) {
+      // Only reserved names: Uai's own variables, never a project's.
+      if (ENV_NAME.test(name) && isReservedTaskEnvName(name) && !value.includes("\0")) values[name] = value;
+    }
+    snapshot = renderTaskProjectEnv({ values });
+    revisions = currentRevisions;
+    runnerKey = currentRunnerKey;
+    return snapshot;
+  };
+}