@moondeck/station 0.0.1 → 1.0.0

package/lib/token-broker-ssm.ts

@@ -0,0 +1,525 @@
+/**
+ * Parameter Store adapter for the broker core (ADR-135) — the storage the
+ * broker Lambda runs against. Reads the ADR-134 engine-account parameters
+ * under `<prefix>/orgs` and `<prefix>/hosts`, hands each to the core as a
+ * credential, and writes refreshed material + the `refresh` block back with
+ * `Overwrite`. Only the Lambda imports this module: it depends on the AWS
+ * SDK the Lambda runtime provides, which the host package does not ship.
+ */
+
+import {
+  GetParameterCommand,
+  GetParameterHistoryCommand,
+  GetParametersByPathCommand,
+  ListTagsForResourceCommand,
+  PutParameterCommand,
+  SSMClient,
+} from "@aws-sdk/client-ssm";
+
+import {
+  BROKER_PARAMETER_ROOT,
+  idPathSegment,
+  legacyAdoptedRoot,
+  legacyEngineParameterRoot,
+} from "../src/cloud-credentials";
+import type { BrokerCredential, BrokerStorage } from "./token-broker";
+import type { AdoptionStore } from "./token-broker-adopt";
+import type { RevisionStore, StoredParameter } from "./token-broker-revision";
+import { refreshMetaFrom, type CredentialFiles, type RefreshMeta } from "./token-lanes/types";
+
+export interface SsmBrokerStorageOptions {
+  prefix: string;
+  kmsKeyId: string;
+  client?: SSMClient;
+  region?: string;
+}
+
+interface StoredValue {
+  raw: Record<string, unknown>;
+  version: number | undefined;
+}
+
+/** `<prefix>/orgs/<o>/engines/<kind>/<id>` and the corresponding host path. */
+export function engineParameterHeader(
+  name: string,
+  prefix: string,
+): { kind: string; id: string; scope: string } | null {
+  if (!name.startsWith(`${prefix}/`)) return null;
+  const parts = name.slice(prefix.length + 1).split("/");
+  if (parts.length !== 5 || parts[2] !== "engines") return null;
+  const [owner, ownerId, , kind, id] = parts as [string, string, string, string, string];
+  if (owner === "orgs") return { kind, id, scope: `org:${ownerId}` };
+  if (owner === "hosts") return { kind, id, scope: "host" };
+  return null;
+}
+
+export class SsmBrokerStorage implements BrokerStorage {
+  private readonly client: SSMClient;
+  private readonly values = new Map<string, StoredValue>();
+
+  constructor(private readonly opts: SsmBrokerStorageOptions) {
+    this.client = opts.client ?? new SSMClient(opts.region ? { region: opts.region } : {});
+  }
+
+  async list(): Promise<BrokerCredential[]> {
+    // ADR-154, owner answer 3: an adopted account has one refresher, the
+    // cloud's scheduler, never this scan. Markers that cannot be listed stop
+    // the run rather than risk a second refresher.
+    const adopted = await adoptedLegacyNames(this.client, this.opts.prefix);
+    const out: BrokerCredential[] = [];
+    for (const path of [`${this.opts.prefix}/orgs`, `${this.opts.prefix}/hosts`]) {
+      let nextToken: string | undefined;
+      do {
+        const page = await this.client.send(
+          new GetParametersByPathCommand({
+            Path: path,
+            Recursive: true,
+            WithDecryption: true,
+            NextToken: nextToken,
+          }),
+        );
+        for (const p of page.Parameters ?? []) {
+          if (!p.Name || typeof p.Value !== "string") continue;
+          if (adopted.has(p.Name)) continue;
+          const header = engineParameterHeader(p.Name, this.opts.prefix);
+          if (!header) continue;
+          let raw: unknown;
+          try {
+            raw = JSON.parse(p.Value);
+          } catch {
+            continue;
+          }
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+          const value = raw as Record<string, unknown>;
+          if (value.v !== 1 || value.authKind !== "config-dir") continue;
+          const files = value.files;
+          if (!files || typeof files !== "object" || Array.isArray(files)) continue;
+          const materials: CredentialFiles = {};
+          for (const [k, v] of Object.entries(files as Record<string, unknown>)) {
+            if (typeof v === "string") materials[k] = v;
+          }
+          this.values.set(p.Name, { raw: value, version: p.Version });
+          out.push({
+            name: p.Name,
+            header: { kind: header.kind, authKind: "config-dir", id: header.id, scope: header.scope },
+            files: materials,
+            refresh: refreshMetaFrom(value.refresh),
+          });
+        }
+        nextToken = page.NextToken;
+      } while (nextToken);
+    }
+    return out;
+  }
+
+  async save(
+    credential: BrokerCredential,
+    files: CredentialFiles | null,
+    refresh: RefreshMeta,
+  ): Promise<void> {
+    const stored = this.values.get(credential.name);
+    const raw = stored?.raw ?? { v: 1 };
+    const next = { ...raw, refresh, ...(files ? { files } : {}) };
+    await this.client.send(
+      new PutParameterCommand({
+        Name: credential.name,
+        Value: JSON.stringify(next),
+        Type: "SecureString",
+        KeyId: this.opts.kmsKeyId,
+        Tier: "Advanced",
+        Overwrite: true,
+      }),
+    );
+    this.values.set(credential.name, { raw: next, version: undefined });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mutual exclusion between runs. Reserved concurrency 1 is the first line
+// (deploy-aws.sh sets it when the account's limit allows); this lock is the
+// one that always holds. A lock is one parameter that is never deleted: AWS
+// asks for 30 seconds between deleting a parameter and creating one of the
+// same name (DeleteParameter), and adoptions take the scan lock one after
+// another. Free, it holds RELEASED_LOCK; held, its holder's
+// `<time>:<nonce>`. A holder that died keeps it at most LOCK_STALE_MS; a
+// later run takes it over.
+// ---------------------------------------------------------------------------
+
+export const LOCK_STALE_MS = 5 * 60_000;
+/** A holder frees the lock only this far inside the stale window: past it,
+ *  a run that found the lock stale may hold it now. The broker's 120-second
+ *  Lambda timeout (deploy-aws.sh) keeps every holder well inside. */
+const LOCK_RELEASE_MARGIN_MS = 60_000;
+/** A free lock: time zero, which every reader takes for stale (the build
+ *  before this one too, which deleted the parameter instead). */
+export const RELEASED_LOCK = "0:released";
+
+interface LockToken {
+  heldAt: number;
+  /** The SSM version this claimant had to create. Null for the previous
+   *  build's `<time>:<nonce>` tokens and recovery fences, which stay
+   *  conservatively held until released or stale. */
+  expectedVersion: number | null;
+}
+
+function lockToken(value: string | undefined): LockToken | null {
+  if (typeof value !== "string") return null;
+  const parts = value.split(":");
+  const [heldAtText, expectedText] = parts;
+  const heldAt = Number(heldAtText);
+  if (!Number.isSafeInteger(heldAt) || heldAt <= 0) return null;
+  const expectedVersion = Number(expectedText);
+  return {
+    heldAt,
+    expectedVersion:
+      parts.length === 3 && Number.isSafeInteger(expectedVersion) && expectedVersion > 0
+        ? expectedVersion
+        : null,
+  };
+}
+
+/** A contender can land after the elected holder has already released. Its
+ * token is not a lock (its returned SSM version missed the version it named),
+ * but it may also have overwritten a newer holder that is still working.
+ * Replay every intervening version: an elected token opens a hold, RELEASED
+ * closes it, and a losing token changes neither. Only a complete chain ending
+ * with no open hold proves that the current false token is free. */
+async function holderBeforeFalseToken(
+  client: SSMClient,
+  name: string,
+  expectedVersion: number,
+  currentVersion: number,
+): Promise<LockToken | null | undefined> {
+  let nextToken: string | undefined;
+  const history = new Map<number, string>();
+  try {
+    do {
+      const page = await client.send(
+        new GetParameterHistoryCommand({
+          Name: name,
+          WithDecryption: false,
+          MaxResults: 50,
+          NextToken: nextToken,
+        }),
+      );
+      for (const item of page.Parameters ?? []) {
+        if (
+          item.Version !== undefined &&
+          item.Version >= expectedVersion &&
+          item.Version < currentVersion &&
+          item.Value !== undefined
+        ) {
+          history.set(item.Version, item.Value);
+        }
+      }
+      nextToken = page.NextToken;
+    } while (nextToken);
+  } catch {
+    // Missing IAM or a transient history read fails closed. The false token
+    // becomes stale normally; it must never be mistaken for a free live lock.
+  }
+  let holder: LockToken | null = null;
+  for (let version = expectedVersion; version < currentVersion; version += 1) {
+    const value = history.get(version);
+    // A missing/expired history entry cannot prove the holder is gone.
+    if (value === undefined) return undefined;
+    if (value === RELEASED_LOCK) {
+      holder = null;
+      continue;
+    }
+    const claim = lockToken(value);
+    // The previous build's two-field token won its own election; for a new
+    // token, only the exact SSM version it named did. Losing writes do not
+    // erase an already-open hold.
+    if (claim && (claim.expectedVersion === null || claim.expectedVersion === version)) {
+      holder = claim;
+    }
+  }
+  return holder;
+}
+
+function lockWriteConflict(error: unknown): boolean {
+  const name = (error as { name?: string }).name;
+  return name === "ParameterAlreadyExists" || name === "TooManyUpdates";
+}
+
+/** History can age out (SSM retains 100 versions) or be temporarily
+ * unavailable. Replace an unprovable false token with a fresh fence and admit
+ * nobody for one stale window. Any hidden holder predates this write and is
+ * therefore stale when the fence is; a normal holder release may free it
+ * sooner. This is deliberately not an elected holder and never returns a
+ * release callback. */
+async function installRecoveryFence(
+  client: SSMClient,
+  name: string,
+  now: () => number,
+): Promise<void> {
+  const token = `${now()}:recovery:${Math.random().toString(36).slice(2)}`;
+  try {
+    await client.send(
+      new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: true }),
+    );
+  } catch (error) {
+    if (!lockWriteConflict(error)) throw error;
+  }
+}
+
+export function brokerLockName(prefix: string): string {
+  return `${prefix}/locks/token-broker`;
+}
+
+export interface BrokerLockOptions {
+  client: SSMClient;
+  prefix: string;
+  now?: () => number;
+  staleMs?: number;
+}
+
+/** Try to take the lock. Returns a release function, or null when another
+ *  run holds a fresh one. */
+export async function acquireBrokerLock(opts: BrokerLockOptions): Promise<(() => Promise<void>) | null> {
+  return acquireParameterLock({ ...opts, name: brokerLockName(opts.prefix) });
+}
+
+/** The same lock, at any parameter name. */
+export async function acquireParameterLock(opts: {
+  client: SSMClient;
+  name: string;
+  now?: () => number;
+  staleMs?: number;
+}): Promise<(() => Promise<void>) | null> {
+  const name = opts.name;
+  const now = opts.now ?? Date.now;
+  const staleMs = opts.staleMs ?? LOCK_STALE_MS;
+  let current: { Parameter?: { Value?: string; Version?: number } } | null;
+  try {
+    current = await opts.client.send(new GetParameterCommand({ Name: name }));
+  } catch (err) {
+    if ((err as { name?: string }).name !== "ParameterNotFound") throw err;
+    current = null;
+  }
+  if (current !== null) {
+    const claim = lockToken(current.Parameter?.Value);
+    const currentVersion = current.Parameter?.Version;
+    if (claim) {
+      const isElected =
+        claim.expectedVersion === null ||
+        currentVersion === undefined ||
+        claim.expectedVersion === currentVersion;
+      if (isElected) {
+        if (now() - claim.heldAt < staleMs) return null;
+      } else {
+        // Versions only rise. A token naming a future version is malformed,
+        // not evidence that a previous holder released. Fence recovery rather
+        // than leaving the malformed lineage wedged forever.
+        if (claim.expectedVersion! > currentVersion) {
+          await installRecoveryFence(opts.client, name, now);
+          return null;
+        }
+        // Replay a mismatched token even when that token's own timestamp is
+        // stale: it may have landed late over a much newer, live holder.
+        const holder = await holderBeforeFalseToken(
+          opts.client,
+          name,
+          claim.expectedVersion!,
+          currentVersion,
+        );
+        if (holder === undefined) {
+          await installRecoveryFence(opts.client, name, now);
+          return null;
+        }
+        if (holder !== null && now() - holder.heldAt < staleMs) {
+          return null;
+        }
+      }
+    }
+  }
+  // Timed at the write, so a run that lost the election below leaves a token
+  // no older than ours.
+  const takenAt = now();
+  const read = current?.Parameter?.Version;
+  const expectedVersion = current === null ? 1 : read === undefined ? null : read + 1;
+  if (expectedVersion === null) return null;
+  const token = `${takenAt}:${expectedVersion}:${Math.random().toString(36).slice(2)}`;
+  if (current === null) {
+    // Never taken (or deleted by the build before this one): created once.
+    try {
+      await opts.client.send(new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: false }));
+    } catch (err) {
+      if (lockWriteConflict(err)) return null;
+      throw err;
+    }
+  } else {
+    /**
+     * SSM has no conditional overwrite, but it numbers every write: ours is
+     * the lock only if it is the very next version after the one we read
+     * free or stale. Of runs that read the same version, exactly one gets
+     * the next; the others may leave their tokens in the value after it, but
+     * a token is only written over a lock read free or stale, so none of
+     * them holds it meanwhile.
+     */
+    let written: { Version?: number };
+    try {
+      written = await opts.client.send(
+        new PutParameterCommand({ Name: name, Value: token, Type: "String", Overwrite: true }),
+      );
+    } catch (error) {
+      if (lockWriteConflict(error)) return null;
+      throw error;
+    }
+    if (written.Version !== expectedVersion) return null;
+  }
+  return async () => {
+    // Inside the hold no other run can hold the lock, whatever token a run
+    // that lost the election left in the value: free it. Late in it, a run
+    // that found it stale may hold it already; leave it, stale anyway.
+    if (now() - takenAt >= Math.max(0, staleMs - LOCK_RELEASE_MARGIN_MS)) return;
+    try {
+      await opts.client.send(
+        new PutParameterCommand({ Name: name, Value: RELEASED_LOCK, Type: "String", Overwrite: true }),
+      );
+    } catch {
+      /* the stale window covers a failed release */
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154 §7: one named revision, for the exact-name entry point
+// ---------------------------------------------------------------------------
+
+/** One credential's lock: one invoke at a time per credential, whichever
+ *  revision it names, since an invoke the cloud gave up on may still run. */
+export function revisionLockName(credentialId: string): string {
+  return `${BROKER_PARAMETER_ROOT}/locks/${idPathSegment(credentialId)}`;
+}
+
+export class SsmRevisionStore implements RevisionStore {
+  constructor(
+    private readonly opts: { client: SSMClient; kmsKeyId: string; now?: () => number },
+  ) {}
+
+  async get(name: string): Promise<StoredParameter | null> {
+    try {
+      const out = await this.opts.client.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+      const parameter = out.Parameter;
+      if (parameter?.Value === undefined || parameter.Version === undefined) return null;
+      return { value: parameter.Value, version: parameter.Version };
+    } catch (err) {
+      if ((err as { name?: string }).name === "ParameterNotFound") return null;
+      throw err;
+    }
+  }
+
+  async overwrite(name: string, value: string): Promise<number> {
+    const out = await this.opts.client.send(
+      new PutParameterCommand({
+        Name: name,
+        Value: value,
+        Type: "SecureString",
+        KeyId: this.opts.kmsKeyId,
+        Overwrite: true,
+      }),
+    );
+    if (out.Version === undefined) throw new Error("PutParameter returned no version");
+    return out.Version;
+  }
+
+  lock(credentialId: string): Promise<(() => Promise<void>) | null> {
+    return acquireParameterLock({
+      client: this.opts.client,
+      name: revisionLockName(credentialId),
+      now: this.opts.now,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ADR-154, owner answer 3: adoption of today's workspace AI accounts
+// ---------------------------------------------------------------------------
+
+async function parametersUnder(
+  client: SSMClient,
+  path: string,
+  decrypt: boolean,
+): Promise<Array<{ name: string; value: string }>> {
+  const out: Array<{ name: string; value: string }> = [];
+  let nextToken: string | undefined;
+  do {
+    const page = await client.send(
+      new GetParametersByPathCommand({ Path: path, Recursive: true, WithDecryption: decrypt, NextToken: nextToken }),
+    );
+    for (const p of page.Parameters ?? []) {
+      if (p.Name && typeof p.Value === "string") out.push({ name: p.Name, value: p.Value });
+    }
+    nextToken = page.NextToken;
+  } while (nextToken);
+  return out;
+}
+
+/** The legacy parameter names (under `prefix`) an adoption marker names. */
+export async function adoptedLegacyNames(client: SSMClient, prefix: string): Promise<Set<string>> {
+  const names = new Set<string>();
+  const adoptedRoot = legacyAdoptedRoot(prefix);
+  for (const marker of await parametersUnder(client, `${adoptedRoot}/orgs`, false)) {
+    names.add(`${prefix}${marker.name.slice(adoptedRoot.length)}`);
+  }
+  return names;
+}
+
+export class SsmAdoptionStore extends SsmRevisionStore implements AdoptionStore {
+  constructor(
+    private readonly adoption: { client: SSMClient; kmsKeyId: string; prefix: string; now?: () => number },
+  ) {
+    super(adoption);
+  }
+
+  get legacyPrefix(): string {
+    return this.adoption.prefix;
+  }
+
+  async create(name: string, value: string, tags: Record<string, string>): Promise<"created" | "matched"> {
+    const entries = Object.entries(tags);
+    const marker = name.startsWith(`${legacyAdoptedRoot(this.adoption.prefix)}/`);
+    try {
+      await this.adoption.client.send(
+        new PutParameterCommand({
+          Name: name,
+          Value: value,
+          // A marker names ids only; every part is a secret.
+          Type: marker ? "String" : "SecureString",
+          ...(marker ? {} : { KeyId: this.adoption.kmsKeyId }),
+          Tier: marker ? "Standard" : "Advanced",
+          Overwrite: false,
+          Tags: entries.map(([Key, Value]) => ({ Key, Value })),
+        }),
+      );
+      return "created";
+    } catch (error) {
+      if ((error as { name?: string }).name !== "ParameterAlreadyExists") throw error;
+    }
+    // Exists: this create's retry only when its identity tags all match.
+    const listed = await this.adoption.client.send(
+      new ListTagsForResourceCommand({ ResourceType: "Parameter", ResourceId: name }),
+    );
+    const observed = new Map((listed.TagList ?? []).map((tag) => [tag.Key, tag.Value]));
+    for (const [key, expected] of entries) {
+      const actual = observed.get(key);
+      if (actual === undefined) throw new Error(`${name} exists and its tags are not visible yet`);
+      if (actual !== expected) throw new Error(`${name} exists as another credential's`);
+    }
+    return "matched";
+  }
+
+  listLegacy(): Promise<Array<{ name: string; value: string }>> {
+    return parametersUnder(this.adoption.client, legacyEngineParameterRoot(this.adoption.prefix), true);
+  }
+
+  listMarkers(): Promise<Array<{ name: string; value: string }>> {
+    return parametersUnder(this.adoption.client, `${legacyAdoptedRoot(this.adoption.prefix)}/orgs`, false);
+  }
+
+  scanLock(): Promise<(() => Promise<void>) | null> {
+    return acquireBrokerLock({ client: this.adoption.client, prefix: this.adoption.prefix, now: this.adoption.now });
+  }
+}