@deployfoundation/foundation-deploy 0.1.0

package/src/deploy/license.ts

@@ -0,0 +1,272 @@
+/**
+ * The license check a deploy runs before it deploys (migration step 15).
+ *
+ * An instance carries an annual key in its own `instance.yaml`
+ * (`license.key`). Before `cdk deploy`, `foundation-deploy` asks the Foundry 41
+ * endpoint whether that key is good for this instance and this version. The
+ * request carries the key, the instance id and the version — nothing else. No
+ * telemetry rides along, and there is no second call anywhere in the tool.
+ *
+ * The rules that matter are the failure modes, because a license check sits in
+ * front of every customer's deploy:
+ *
+ *   - **No key configured** — skipped, loudly. Keys are not yet issued and no
+ *     endpoint is live; a check that blocked deploys today would block them
+ *     for nothing.
+ *   - **A definite "no"** — refused. An invalid, expired or revoked key stops
+ *     the deploy; that is what the check is for.
+ *   - **Anything else** (timeout, 5xx, DNS, a rate limit) — retried, then a
+ *     30-DAY GRACE against the last verification this instance cached in its
+ *     own Secrets Manager. Foundry 41's availability must never be a customer's
+ *     outage; a deploy is allowed to proceed for a month on the last good
+ *     answer, saying so each time.
+ *
+ * The cache lives at `<prefix>/license/last-verified` in the INSTANCE's
+ * account: the customer can read it, and Foundry 41 keeps no record of the
+ * deploy beyond answering the question.
+ */
+
+/** Where the check is sent unless the environment says otherwise. */
+export const DEFAULT_LICENSE_ENDPOINT = "https://license.foundry41.com/v1/verify";
+
+export const LICENSE_ENDPOINT_ENV = "FOUNDATION_LICENSE_ENDPOINT";
+
+/** How long a cached verification keeps a customer deploying while the endpoint is down. */
+export const GRACE_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** What this instance cached the last time the endpoint said yes. */
+export interface LastVerified {
+  /** ISO 8601, when the endpoint last answered "valid". */
+  verifiedAt: string;
+  /** The version that was deployed then; informational. */
+  version?: string;
+  /** The license's own expiry, when the endpoint reports one. */
+  expiresAt?: string;
+}
+
+/** Read and write the last-good verification. Secrets Manager in a real deploy. */
+export interface LicenseCache {
+  read(): Promise<LastVerified | undefined>;
+  write(value: LastVerified): Promise<void>;
+}
+
+export interface VerifyLicenseOptions {
+  /** The deployment asking; sent as `instanceId`. */
+  instanceId: string;
+  /** The Foundation version being deployed; sent as `version`. */
+  version: string;
+  endpoint?: string;
+  cache?: LicenseCache;
+  fetchImpl?: typeof fetch;
+  /** Attempts before falling back to the grace period. */
+  attempts?: number;
+  /** Overridable for tests; the default backs off 1s, 2s, 4s. */
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+  /** Per-attempt timeout. */
+  timeoutMs?: number;
+}
+
+export type LicenseOutcome =
+  /** The endpoint said yes. */
+  | "verified"
+  /** The endpoint could not be reached; a recent cached yes is standing in. */
+  | "grace"
+  /** No key is configured. */
+  | "skipped";
+
+export interface LicenseResult {
+  outcome: LicenseOutcome;
+  /** One line for the deploy log. */
+  message: string;
+  expiresAt?: string;
+}
+
+/** The endpoint's answer. Anything else is treated as "could not reach it". */
+interface LicenseResponse {
+  status: "valid" | "invalid";
+  expiresAt?: string;
+  message?: string;
+}
+
+/** Where to send the check: an explicit endpoint, the environment, then the default. */
+export function licenseEndpoint(
+  explicit?: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return explicit ?? env[LICENSE_ENDPOINT_ENV] ?? DEFAULT_LICENSE_ENDPOINT;
+}
+
+/**
+ * Check one license key. Resolves with what happened; throws only when the
+ * deploy must not proceed — a definite rejection, or an unreachable endpoint
+ * with no cached verification inside the grace period.
+ */
+export async function verifyLicense(
+  key: string | undefined,
+  options: VerifyLicenseOptions,
+): Promise<LicenseResult> {
+  if (key === undefined || key === "")
+    return {
+      outcome: "skipped",
+      message:
+        "no license.key in the instance file — skipping the Foundry 41 license check. Set license.key once your key is issued.",
+    };
+
+  const endpoint = licenseEndpoint(options.endpoint);
+  const now = options.now ?? (() => new Date());
+  const attempts = options.attempts ?? 3;
+  const sleep = options.sleep ?? ((ms: number) => new Promise((done) => setTimeout(done, ms)));
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  let lastFailure = "";
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    let response: Response;
+    try {
+      response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        // Exactly three fields. Adding a fourth here is a product decision,
+        // not a convenience.
+        body: JSON.stringify({
+          key,
+          instanceId: options.instanceId,
+          version: options.version,
+        }),
+        signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+      });
+    } catch (error) {
+      lastFailure = error instanceof Error ? error.message : String(error);
+      if (attempt < attempts) await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+
+    // A definite "no" is the endpoint doing its job; do not retry it and do
+    // not fall back to a cached yes.
+    if (response.status === 402 || response.status === 403)
+      throw new Error(
+        `license refused for instance ${options.instanceId}: ${await failureText(response)}`,
+      );
+
+    if (!response.ok) {
+      lastFailure = `HTTP ${response.status}`;
+      if (attempt < attempts) await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+
+    let body: LicenseResponse;
+    try {
+      body = (await response.json()) as LicenseResponse;
+    } catch (error) {
+      lastFailure = `unreadable response: ${error instanceof Error ? error.message : String(error)}`;
+      if (attempt < attempts) await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+
+    if (body.status === "invalid")
+      throw new Error(
+        `license refused for instance ${options.instanceId}: ${body.message ?? "the key is not valid for this instance"}`,
+      );
+    if (body.status !== "valid") {
+      lastFailure = `unexpected status "${String(body.status)}"`;
+      if (attempt < attempts) await sleep(2 ** (attempt - 1) * 1000);
+      continue;
+    }
+
+    const verifiedAt = now().toISOString();
+    await cacheQuietly(options.cache, {
+      verifiedAt,
+      version: options.version,
+      ...(body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }),
+    });
+    return {
+      outcome: "verified",
+      message: `license verified for ${options.instanceId}${body.expiresAt === undefined ? "" : ` (expires ${body.expiresAt})`}`,
+      ...(body.expiresAt === undefined ? {} : { expiresAt: body.expiresAt }),
+    };
+  }
+
+  return grace(lastFailure, options, now());
+}
+
+/**
+ * The endpoint could not be reached. Stand on the last verification this
+ * instance cached, if it is recent enough.
+ */
+async function grace(
+  failure: string,
+  options: VerifyLicenseOptions,
+  now: Date,
+): Promise<LicenseResult> {
+  const cached = await readQuietly(options.cache);
+  if (cached === undefined)
+    throw new Error(
+      `the Foundation license endpoint could not be reached (${failure}) and this instance has no cached verification to fall back on. Retry, or set ${LICENSE_ENDPOINT_ENV} if you use a private endpoint.`,
+    );
+  const verifiedAt = Date.parse(cached.verifiedAt);
+  if (Number.isNaN(verifiedAt))
+    throw new Error(
+      `the Foundation license endpoint could not be reached (${failure}) and the cached verification is unreadable (verifiedAt: ${cached.verifiedAt})`,
+    );
+  const ageDays = (now.getTime() - verifiedAt) / DAY_MS;
+  if (ageDays > GRACE_DAYS)
+    throw new Error(
+      `the Foundation license endpoint could not be reached (${failure}) and the last verification is ${Math.floor(ageDays)} days old, past the ${GRACE_DAYS}-day grace period`,
+    );
+  const remaining = Math.max(0, Math.ceil(GRACE_DAYS - ageDays));
+  return {
+    outcome: "grace",
+    message: `the Foundation license endpoint could not be reached (${failure}); continuing on the verification cached ${Math.floor(ageDays)} days ago — ${remaining} days of grace left`,
+    ...(cached.expiresAt === undefined ? {} : { expiresAt: cached.expiresAt }),
+  };
+}
+
+/** The cache is a convenience, never a reason to fail a deploy that was allowed. */
+async function cacheQuietly(cache: LicenseCache | undefined, value: LastVerified): Promise<void> {
+  if (cache === undefined) return;
+  try {
+    await cache.write(value);
+  } catch (error) {
+    console.warn(
+      `  could not cache the license verification: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function readQuietly(cache: LicenseCache | undefined): Promise<LastVerified | undefined> {
+  if (cache === undefined) return undefined;
+  try {
+    return await cache.read();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What a dry run does instead: name the check, contact nobody.
+ *
+ * A `--dry-run` has no credentials and should reach no third party — least of
+ * all one that would record a deploy that is not happening.
+ */
+export async function plannedLicenseCheck(
+  key: string | undefined,
+  options: VerifyLicenseOptions,
+): Promise<LicenseResult> {
+  return {
+    outcome: "skipped",
+    message:
+      key === undefined || key === ""
+        ? "no license.key in the instance file — nothing to verify"
+        : `dry run — would verify ${options.instanceId} (${options.version}) against ${licenseEndpoint(options.endpoint)}`,
+  };
+}
+
+async function failureText(response: Response): Promise<string> {
+  try {
+    const body = (await response.json()) as { message?: string };
+    return body.message ?? `HTTP ${response.status}`;
+  } catch {
+    return `HTTP ${response.status}`;
+  }
+}

package/src/deploy/paths.ts

@@ -0,0 +1,65 @@
+/**
+ * Where this package's own files are, and where the CDK app lives.
+ *
+ * Deliberately separate from the instance's paths: everything here belongs to
+ * Foundation (the CDK app, the agent image's Dockerfile, the product skills the
+ * release ships), and everything about the deployment comes from the instance
+ * file the caller named. The two must never be confused — that confusion is
+ * exactly what `packages/infra` exists to remove.
+ *
+ * The package root is FOUND rather than counted out in `..`s, because this
+ * code runs from two layouts: `src/deploy/paths.ts` in the Foundation
+ * workspace, and a bundle at `dist/bin/*.js` in the package published to npm.
+ * A fixed number of parent directories is right in one and silently wrong in
+ * the other.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The deploy tool's own package name; how its root is recognized. */
+export const PACKAGE_NAME = "@deployfoundation/foundation-deploy";
+
+/** Nearest ancestor directory holding this package's `package.json`. */
+function packageRoot(from: string): string {
+  let dir = from;
+  for (;;) {
+    const manifest = resolve(dir, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const { name } = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string };
+        if (name === PACKAGE_NAME) return dir;
+      } catch {
+        // A malformed package.json above us is not ours; keep climbing.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir)
+      throw new Error(`cannot find the ${PACKAGE_NAME} package root above ${from}`);
+    dir = parent;
+  }
+}
+
+/** The infra package root: where `cdk.json` sits, so `cdk` runs from here. */
+export const INFRA_ROOT = packageRoot(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * The Foundation checkout this package sits in — `<root>/packages/infra` →
+ * `<root>`.
+ *
+ * In the published package there is no such checkout: the two levels up are
+ * `node_modules/@deployfoundation`, which holds no `packages/gateway`. That absence
+ * is the signal `release.ts` uses to decide that a bare `deploy` deploys a
+ * release rather than a local build.
+ */
+export const FOUNDATION_ROOT = resolve(INFRA_ROOT, "..", "..");
+
+/** The agent container's Dockerfile, relative to {@link FOUNDATION_ROOT}. */
+export const AGENT_DOCKERFILE = "packages/infra/agent-image/Dockerfile";
+
+/**
+ * Files this package ships and reads at runtime — the Slack and GitHub App
+ * manifest templates. They are packaged under `src/deploy/assets`, which is
+ * published as-is, so this one path works from both layouts.
+ */
+export const PACKAGE_ASSETS = resolve(INFRA_ROOT, "src", "deploy", "assets");

package/src/deploy/post-deploy.ts

@@ -0,0 +1,97 @@
+/**
+ * What happens after `deploy` succeeds: prove the new runtime version answers,
+ * then move the pinned `live` endpoint onto it and prove that answers too.
+ *
+ *   foundation-deploy post-deploy --instance .foundation/instance.yaml
+ *
+ * It is a command rather than pipeline shell because there is more than one
+ * deployer: a GitHub Actions workflow and a per-instance CodePipeline
+ * (`pipeline-stack.ts`) run the very same steps, and two copies of a promotion
+ * gate is one copy too many — a fix to one would silently not reach the other.
+ *
+ * The gate is the point. Humans talk to `live`, never DEFAULT, so a version
+ * that fails either probe is never promoted and a broken image never answers a
+ * real message. Any failure exits non-zero, which fails the deploy.
+ */
+import { type AwsContext, stackOutput } from "./aws.ts";
+import {
+  type EndpointRunner,
+  cliRunner,
+  currentRuntimeVersion,
+  promoteEndpoint,
+  runtimeIdFromArn,
+  smokeInvoke,
+  smokeSessionId,
+} from "./endpoint.ts";
+
+/** The endpoint humans talk to. */
+export const LIVE = "live";
+
+/**
+ * The filesystem probe's payload and what a healthy answer says. The persistent
+ * mount is where the agent's memory lives; a runtime that cannot write it looks
+ * fine to `_smoke_test` and forgets everything.
+ */
+export const FS_PROBE_PAYLOAD = '{"_fs_probe":true}';
+export const FS_PROBE_EXPECT = ['"writable":true'];
+
+/**
+ * Smoke DEFAULT, probe the mount, promote `live`, smoke `live` — the order the
+ * workflow ran them in, with the same assertions.
+ *
+ * `runner` and `arn` are test seams: with both supplied nothing here talks to
+ * AWS, so the sequence can be asserted on argv alone.
+ */
+export async function postDeploy(
+  ctx: AwsContext,
+  opts: { runner?: EndpointRunner; arn?: string; log?: (line: string) => void } = {},
+): Promise<void> {
+  const dry = ctx.dryRun === true;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const runner = opts.runner ?? cliRunner(ctx);
+  const arn =
+    opts.arn ??
+    (dry
+      ? `<${ctx.names.agent}.AgentRuntimeArn>`
+      : await stackOutput(ctx, ctx.names.agent, "AgentRuntimeArn"));
+  const id =
+    dry && opts.arn === undefined ? `<${ctx.names.agent}.runtimeId>` : runtimeIdFromArn(arn);
+  const version = dry ? "<version>" : await currentRuntimeVersion(runner, id);
+  log(`deployed runtime version ${version}`);
+
+  log("▶ smoke test — authenticated (new version)");
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "DEFAULT",
+    sessionId: smokeSessionId("ci-smoke"),
+    dryRun: ctx.dryRun,
+    log,
+  });
+
+  log("▶ smoke test — persistent mount writable (new version)");
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: "DEFAULT",
+    sessionId: smokeSessionId("ci-probe"),
+    payload: FS_PROBE_PAYLOAD,
+    expect: FS_PROBE_EXPECT,
+    dryRun: ctx.dryRun,
+    log,
+  });
+
+  log(`▶ promote version ${version} to the ${LIVE} endpoint`);
+  await promoteEndpoint(runner, { id, name: LIVE, version, dryRun: ctx.dryRun, log });
+
+  // `live` is asserted on `authenticated` alone, as the workflow did: the
+  // version was already held to the stricter bar on DEFAULT a moment ago, and
+  // this call only has to show the endpoint now serves it.
+  log(`▶ smoke test — ${LIVE} endpoint answers`);
+  await smokeInvoke(runner, {
+    arn,
+    qualifier: LIVE,
+    sessionId: smokeSessionId("ci-live"),
+    expect: ['"authenticated":true'],
+    dryRun: ctx.dryRun,
+    log,
+  });
+}