@deployfoundation/foundation-deploy 0.1.0

package/src/lambda-bundle-context.ts

@@ -0,0 +1,64 @@
+/**
+ * The build context a Lambda bundle is produced from: the Foundation
+ * workspace, and nothing else.
+ *
+ * It is a copy rather than the checkout itself so the Docker builder never
+ * receives a developer's repository root, where ignored local credential files
+ * may sit. Symlinks are rejected outright rather than followed, because a
+ * symlink is how something outside the workspace would get into the image.
+ */
+import { copyFileSync, cpSync, lstatSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+
+const contextByRoot = new Map<string, string>();
+const IGNORED_DIRECTORIES: Record<string, true> = {
+  ".git": true,
+  "cdk.out": true,
+  dist: true,
+  node_modules: true,
+};
+
+/** Root files a frozen workspace install needs; every one must exist. */
+const WORKSPACE_FILES = ["package.json", "bun.lock", "bunfig.toml", "tsconfig.json"] as const;
+
+function copySourceTree(source: string, destination: string): void {
+  cpSync(source, destination, {
+    recursive: true,
+    filter(candidate) {
+      const relative = path.relative(source, candidate);
+      if (relative === "") return true;
+      if (relative.split(path.sep).some((component) => component in IGNORED_DIRECTORIES))
+        return false;
+      if (lstatSync(candidate).isSymbolicLink())
+        throw new Error(`Lambda bundle input contains a symlink: ${candidate}`);
+      return true;
+    },
+  });
+}
+
+/**
+ * Build the minimal workspace required for frozen-install Lambda bundling and
+ * return its path. Cached per root: one synth bundles several entry points out
+ * of the same tree, and copying it once per Lambda would dominate the run.
+ */
+export function lambdaBundleContext(workspaceRoot: string): string {
+  const existing = contextByRoot.get(workspaceRoot);
+  if (existing !== undefined) return existing;
+
+  const context = mkdtempSync(path.join(tmpdir(), "foundation-lambda-bundle-"));
+  try {
+    for (const file of WORKSPACE_FILES)
+      copyFileSync(path.join(workspaceRoot, file), path.join(context, file));
+    // Every workspace, because `bun install --frozen-lockfile` refuses a
+    // workspace the lockfile names and the disk lacks — and because a proxy
+    // bundle pulls its capability package, which pulls core and connectors.
+    copySourceTree(path.join(workspaceRoot, "packages"), path.join(context, "packages"));
+  } catch (error) {
+    rmSync(context, { recursive: true, force: true });
+    throw error;
+  }
+
+  contextByRoot.set(workspaceRoot, context);
+  return context;
+}

package/src/names.ts

@@ -0,0 +1,170 @@
+/**
+ * Names for the CDK app, and how it finds the deployment it is synthesizing.
+ *
+ * Nothing here identifies a deployment: `namesFor(instance)` derives every
+ * stack, secret, role, gateway and ECR name from the instance file the caller
+ * names, and the deploy tool imports the same function from core so the two
+ * cannot drift.
+ *
+ * The instance file is a PATH the caller supplies (`-c instanceFile=…`), not a
+ * name looked up in an `instances/` directory this package does not have.
+ * Foundation ships no instance file and no company configuration; an instance
+ * repository owns both, and its `config:` key resolves relative to the instance
+ * file's own directory rather than to a repository root.
+ *
+ * What remains below are genuine constants — strings that are the same for
+ * every deployment because they name an AWS-side thing.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { type CapabilityId, INTEGRATION_CAPABILITY_IDS } from "@deployfoundation/foundation-core";
+import {
+  type Instance,
+  type InstanceNames,
+  instanceNames,
+  parseInstance,
+} from "@deployfoundation/foundation-core/instance";
+import { parse as parseYaml } from "yaml";
+
+export { instanceNames as namesFor };
+export type { Instance, InstanceNames };
+
+/**
+ * One instance file, parsed, plus the paths everything else resolves against.
+ *
+ * Stacks take `instance` and, where they read runtime configuration at synth,
+ * `configPath`. Both travel explicitly rather than through a module-level repo
+ * root, because there is no repository root to assume: the file may sit
+ * anywhere the deployer's checkout puts it.
+ */
+export interface InstanceFile {
+  instance: Instance;
+  /** Absolute path of the instance YAML itself. */
+  path: string;
+  /** Absolute path of the runtime config `instance.config` names. */
+  configPath: string;
+}
+
+/**
+ * Read and validate the instance file at `path`, absolute or relative to
+ * `cwd`. A plain file read — the CDK app must synthesize with no AWS
+ * credentials and no network.
+ *
+ * Unlike the sky-tags version this does not check the parsed `name` against a
+ * filename: the file no longer has to be called anything in particular, and
+ * the name is one of the values it declares rather than the key it was found
+ * under.
+ */
+export function loadInstanceFile(path: string, cwd: string = process.cwd()): InstanceFile {
+  const absolute = isAbsolute(path) ? path : resolve(cwd, path);
+  let text: string;
+  try {
+    text = readFileSync(absolute, "utf8");
+  } catch {
+    throw new Error(`no instance file at ${absolute}`);
+  }
+  const instance = parseInstance(text);
+  return { instance, path: absolute, configPath: configPathFor(instance, absolute) };
+}
+
+/**
+ * Where an instance's runtime config lives: `config:` resolved against the
+ * DIRECTORY OF THE INSTANCE FILE. An instance repository holding
+ * `instance.yaml` and `config.yaml` side by side therefore writes
+ * `config: config.yaml`, and moving the pair somewhere else needs no edit.
+ */
+export function configPathFor(instance: Instance, instanceFilePath: string): string {
+  return isAbsolute(instance.config)
+    ? instance.config
+    : resolve(dirname(instanceFilePath), instance.config);
+}
+
+/** The runtime config document, read at synth. Never cached across paths. */
+function configDocument(configPath: string): Record<string, unknown> {
+  const doc = parseYaml(readFileSync(configPath, "utf8")) as Record<string, unknown> | null;
+  return doc ?? {};
+}
+
+/**
+ * Is `capability` switched ON in the instance's runtime config?
+ *
+ * Read at synth the same way {@link adminsFor} reads `admins`: the CDK app
+ * must synthesize with no AWS credentials and no network, so the file on disk
+ * is the only source. Defaults to `false`, matching the schema default for
+ * every opt-in capability — this is not the place to learn a capability's
+ * default, only whether an instance asked for it.
+ *
+ * Use it ONLY for a capability that needs infrastructure of its own (Mongo's
+ * 27017 egress). That makes turning such a capability ON a deploy rather than
+ * a config sync; turning one OFF still removes its tools on the next turn.
+ */
+export function capabilityEnabled(configPath: string, capability: CapabilityId): boolean {
+  const doc = configDocument(configPath) as {
+    capabilities?: Record<string, { enabled?: unknown } | undefined>;
+  };
+  const enabled = doc.capabilities?.[capability]?.enabled;
+  if (enabled !== undefined && typeof enabled !== "boolean")
+    throw new Error(`${configPath}: capabilities.${capability}.enabled must be a boolean`);
+  return enabled ?? false;
+}
+
+/**
+ * Whether normal queue turns must be gateway-signed before the invoker accepts
+ * them.
+ *
+ * The switch is the capability registry, not a hand-kept list: an integration
+ * capability is one whose infrastructure the instance file opts into, and
+ * every one of them mints actor capabilities the agent must not be able to
+ * forge. A new integration capability is therefore covered by its registry
+ * entry alone.
+ */
+export function requiresAuthenticatedQueue(instance: Instance): boolean {
+  return enabledIntegrations(instance).length > 0;
+}
+
+/**
+ * The integration capabilities this instance opted into, from the registry.
+ * `INTEGRATION_CAPABILITY_IDS` is the source of truth for which capabilities
+ * have an `integrations.<id>` switch at all.
+ */
+export function enabledIntegrations(instance: Instance): CapabilityId[] {
+  const integrations = instance.integrations as Record<string, boolean | undefined>;
+  return INTEGRATION_CAPABILITY_IDS.filter((id) => integrations[id] === true);
+}
+
+/**
+ * Does this instance provision `id`'s durable infrastructure?
+ *
+ * Every per-capability branch in the stacks asks this rather than reading
+ * `instance.integrations.<id>` directly, so the registry's `integration` flag
+ * is visibly what decides. An id with no registry entry, or one whose entry
+ * carries no `integration` flag, is a programming error rather than a silent
+ * `false`: it would otherwise quietly stop provisioning a capability's IAM.
+ */
+export function provisionsIntegration(instance: Instance, id: CapabilityId): boolean {
+  if (!INTEGRATION_CAPABILITY_IDS.includes(id))
+    throw new Error(`${id} is not an integration capability in the registry`);
+  return (instance.integrations as Record<string, boolean | undefined>)[id] === true;
+}
+
+/**
+ * The instance's admin Slack user ids, as the CSV the gateway Lambda expects.
+ *
+ * `-c admins=…` overrides this; without it a bare `cdk synth` still produces
+ * the same list the running deployment has, because it comes from the very
+ * runtime config the agent reads at session start. No id is written down here.
+ */
+export function adminsFor(configPath: string): string {
+  const doc = configDocument(configPath) as { admins?: unknown };
+  const admins = doc.admins;
+  if (admins === undefined || admins === null) return "";
+  if (!Array.isArray(admins) || admins.some((id) => typeof id !== "string"))
+    throw new Error(`${configPath}: admins must be a list of Slack user ids`);
+  return (admins as string[]).join(",");
+}
+
+/** Target name; the MCP tool is exposed as `<target>___<tool>`. */
+export const WEB_SEARCH_TARGET = "websearch";
+export const WEB_SEARCH_CONNECTOR_VERSION = "1.2.0";
+/** The runtime endpoint humans talk to; the pipeline promotes versions onto it after smoke tests. */
+export const LIVE_ENDPOINT_NAME = "live";

package/src/release/kms.ts

@@ -0,0 +1,86 @@
+/**
+ * The real KMS client behind manifest signing and verification.
+ *
+ * Kept apart from `manifest.ts` so that module stays pure: a CDK synth reads
+ * manifests and must not drag an AWS client into the synth, and the manifest
+ * tests must not need one either.
+ *
+ * The key lives in the Foundation release account and the REGION comes from
+ * its ARN, not from the deployment: a customer deploying into `eu-west-1`
+ * still verifies against the key where it was created. Its key policy is what
+ * lets them — `kms:Verify` and `kms:GetPublicKey` for the registered customer
+ * accounts, exactly as the ECR repository policy lets them pull the image
+ * (`release-account-stack.ts`).
+ */
+import { KMSClient, SignCommand, VerifyCommand } from "@aws-sdk/client-kms";
+import {
+  type KmsVerifier,
+  type ReleaseManifest,
+  type ReleaseSignature,
+  type SigningAlgorithm,
+  manifestSigningPayload,
+} from "./manifest.ts";
+
+/** Default signing algorithm for a new Foundation release key (RSA 4096). */
+export const DEFAULT_SIGNING_ALGORITHM: SigningAlgorithm = "RSASSA_PSS_SHA_256";
+
+/** `arn:aws:kms:<region>:<account>:key/<id>` → `<region>`. */
+export function regionOfKeyArn(keyArn: string): string {
+  const region = keyArn.split(":")[3];
+  if (region === undefined || region === "")
+    throw new Error(`not a KMS key ARN: ${keyArn} (expected arn:aws:kms:<region>:<account>:key/…)`);
+  return region;
+}
+
+export interface KmsOptions {
+  /** Named AWS profile, or `""`/omitted for the ambient credential chain. */
+  profile?: string;
+}
+
+function client(keyArn: string, options: KmsOptions = {}): KMSClient {
+  const profile = options.profile ?? "";
+  return new KMSClient({
+    region: regionOfKeyArn(keyArn),
+    ...(profile === "" ? {} : { profile }),
+  });
+}
+
+/** A {@link KmsVerifier} backed by the AWS SDK. */
+export function kmsVerifier(keyArn: string, options: KmsOptions = {}): KmsVerifier {
+  const kms = client(keyArn, options);
+  return {
+    async verify(input) {
+      const result = await kms.send(new VerifyCommand(input));
+      return {
+        ...(result.SignatureValid === undefined ? {} : { SignatureValid: result.SignatureValid }),
+      };
+    },
+  };
+}
+
+/**
+ * Sign a freshly built manifest. Only the release workflow calls this, with
+ * the Foundation release role's credentials; a deployer never signs anything.
+ */
+export async function signManifest(
+  manifest: ReleaseManifest,
+  keyArn: string,
+  options: KmsOptions & { algorithm?: SigningAlgorithm } = {},
+): Promise<ReleaseSignature> {
+  const algorithm = options.algorithm ?? DEFAULT_SIGNING_ALGORITHM;
+  const kms = client(keyArn, options);
+  const result = await kms.send(
+    new SignCommand({
+      KeyId: keyArn,
+      Message: manifestSigningPayload(manifest),
+      MessageType: "RAW",
+      SigningAlgorithm: algorithm,
+    }),
+  );
+  if (result.Signature === undefined) throw new Error(`KMS returned no signature for ${keyArn}`);
+  return {
+    kmsKeyArn: keyArn,
+    algorithm,
+    value: Buffer.from(result.Signature).toString("base64"),
+  };
+}

package/src/release/manifest.ts

@@ -0,0 +1,265 @@
+/**
+ * The release manifest: what `vX.Y.Z` *is*, and how a deployer proves it.
+ *
+ * Foundation publishes one immutable release per tag — an agent image in
+ * Foundation's own ECR, one Lambda bundle per entry point in the release
+ * bucket, and the product skills tarball — and this document is the list of
+ * their digests, signed with a KMS key in the Foundation account. It replaces
+ * `foundation.lock.json` and the tree-hash gate: pinning is the version, and
+ * integrity is the signature over these digests.
+ *
+ * Deliberately pure. Nothing here talks to AWS or to the network: the builder
+ * hashes files on disk, and {@link verifyManifest} takes the KMS verifier and
+ * the artifact reader as arguments. `src/release/kms.ts` supplies the real
+ * ones; a test supplies fakes.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { z } from "zod";
+
+/** `vMAJOR.MINOR.PATCH` — the Git tag a release is built from, verbatim. */
+export const RELEASE_VERSION_RE = /^v\d+\.\d+\.\d+$/;
+
+const Sha256 = z.string().regex(/^[0-9a-f]{64}$/, "must be a lowercase hex sha256");
+
+const ReleaseArtifactSchema = z
+  .object({
+    /** Key inside the release bucket, e.g. `releases/v0.1.0/lambda/gateway.zip`. */
+    key: z.string().min(1),
+    sha256: Sha256,
+    bytes: z.number().int().nonnegative(),
+  })
+  .strict();
+
+/**
+ * How a manifest may be signed. Only asymmetric algorithms KMS offers for
+ * `Verify`, listed explicitly so a tampered manifest cannot name a weaker one
+ * — the signature is checked against the algorithm the *manifest* declares,
+ * so that field has to be constrained.
+ */
+export const SIGNING_ALGORITHMS = [
+  "RSASSA_PSS_SHA_256",
+  "RSASSA_PSS_SHA_384",
+  "RSASSA_PSS_SHA_512",
+  "RSASSA_PKCS1_V1_5_SHA_256",
+  "RSASSA_PKCS1_V1_5_SHA_384",
+  "RSASSA_PKCS1_V1_5_SHA_512",
+  "ECDSA_SHA_256",
+  "ECDSA_SHA_384",
+  "ECDSA_SHA_512",
+] as const;
+
+export type SigningAlgorithm = (typeof SIGNING_ALGORITHMS)[number];
+
+const ReleaseManifestSchema = z
+  .object({
+    version: z.string().regex(RELEASE_VERSION_RE, "must be vMAJOR.MINOR.PATCH"),
+    /** The Foundation commit the release was built from. */
+    gitCommit: z.string().regex(/^[0-9a-f]{40}$/, "must be a full commit sha"),
+    createdAt: z.string().datetime(),
+    agentImage: z
+      .object({
+        /** ECR repository URI without a tag: `<account>.dkr.ecr.<region>.amazonaws.com/foundation/agent`. */
+        repository: z.string().min(1),
+        tag: z.string().min(1),
+        /** The manifest digest the runtime is pinned to. */
+        digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+      })
+      .strict(),
+    /** One entry per `LAMBDA_ENTRY_POINTS` id. */
+    lambda: z.record(ReleaseArtifactSchema),
+    /** `skills.tar.gz`; no `bytes`, because nothing streams it in pieces. */
+    skills: z.object({ key: z.string().min(1), sha256: Sha256 }).strict(),
+    /**
+     * Absent only in the moment between building and signing. A deploy
+     * refuses an unsigned manifest — see {@link verifyManifest}.
+     */
+    signature: z
+      .object({
+        kmsKeyArn: z.string().min(1),
+        algorithm: z.enum(SIGNING_ALGORITHMS),
+        /** Base64 of the raw KMS signature. */
+        value: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type ReleaseArtifact = z.infer<typeof ReleaseArtifactSchema>;
+export type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
+export type ReleaseSignature = NonNullable<ReleaseManifest["signature"]>;
+
+/** Parse and validate a manifest document. Throws on any schema violation. */
+export function parseManifest(json: string | unknown): ReleaseManifest {
+  return ReleaseManifestSchema.parse(typeof json === "string" ? JSON.parse(json) : json);
+}
+
+/** Where a release's files live in the release bucket. One layout, one place. */
+export function releasePrefix(version: string): string {
+  return `releases/${version}`;
+}
+
+export function manifestKey(version: string): string {
+  return `${releasePrefix(version)}/manifest.json`;
+}
+
+export function lambdaKey(version: string, id: string): string {
+  return `${releasePrefix(version)}/lambda/${id}.zip`;
+}
+
+export function skillsKey(version: string): string {
+  return `${releasePrefix(version)}/skills.tar.gz`;
+}
+
+/** Lowercase hex sha256 of some bytes. */
+export function sha256Hex(bytes: Uint8Array | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Lowercase hex sha256 of a file, read whole: release artifacts are megabytes, not gigabytes. */
+export function sha256File(path: string): string {
+  return sha256Hex(readFileSync(path));
+}
+
+export interface BuildManifestInput {
+  version: string;
+  gitCommit: string;
+  /** Defaults to now; pinned by the tests so a manifest is reproducible. */
+  createdAt?: string;
+  agentImage: ReleaseManifest["agentImage"];
+  /** Lambda id → the built `.zip` on disk. The ids become the manifest's keys. */
+  lambda: Record<string, string>;
+  /** The product skills tarball on disk. */
+  skills: string;
+}
+
+/**
+ * Hash what was built and describe it. The result is unsigned: signing is a
+ * separate step because it needs AWS and this does not.
+ */
+export function buildManifest(input: BuildManifestInput): ReleaseManifest {
+  const lambda: Record<string, ReleaseArtifact> = {};
+  for (const [id, path] of Object.entries(input.lambda).sort(([a], [b]) => (a < b ? -1 : 1)))
+    lambda[id] = {
+      key: lambdaKey(input.version, id),
+      sha256: sha256File(path),
+      bytes: statSync(path).size,
+    };
+  return parseManifest({
+    version: input.version,
+    gitCommit: input.gitCommit,
+    createdAt: input.createdAt ?? new Date().toISOString(),
+    agentImage: input.agentImage,
+    lambda,
+    skills: { key: skillsKey(input.version), sha256: sha256File(input.skills) },
+  });
+}
+
+/**
+ * The exact bytes a signature covers: the manifest without its `signature`,
+ * serialized canonically (object keys sorted, no insignificant whitespace).
+ *
+ * Canonical because the signer and the verifier are different programs on
+ * different machines, and `JSON.stringify` preserves insertion order — a
+ * round trip through S3 must not be able to change one byte of what was
+ * signed.
+ */
+export function manifestSigningPayload(manifest: ReleaseManifest): Uint8Array {
+  const { signature: _signature, ...unsigned } = manifest;
+  return new TextEncoder().encode(canonicalJson(unsigned));
+}
+
+/** JSON with every object's keys in sorted order. Arrays keep their order. */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+
+/** What {@link verifyManifest} needs of a KMS client: one `Verify` call. */
+export interface KmsVerifier {
+  verify(input: {
+    KeyId: string;
+    Message: Uint8Array;
+    MessageType: "RAW";
+    Signature: Uint8Array;
+    SigningAlgorithm: SigningAlgorithm;
+  }): Promise<{ SignatureValid?: boolean }>;
+}
+
+export interface VerifyManifestOptions {
+  /** The key the deployer expects. A manifest naming another key is rejected. */
+  kmsKeyArn: string;
+  kms: KmsVerifier;
+  /**
+   * Reads one artifact's bytes by its manifest key. Omitted, only the
+   * signature is checked — which is what a `--dry-run` wants and what a
+   * deploy must NOT settle for.
+   */
+  readArtifact?: (key: string) => Promise<Uint8Array>;
+  /** Refuse a manifest that is not this version (the version the caller asked for). */
+  expectVersion?: string;
+}
+
+/**
+ * Prove a manifest is Foundation's and that the bytes behind it are the ones
+ * it names. Throws with a specific message on the first failure; returns the
+ * parsed manifest.
+ *
+ * Order matters and is the point of this function: the signature is checked
+ * BEFORE anything is downloaded or deployed, because every other value in the
+ * document — the image digest included — is only as trustworthy as it is.
+ */
+export async function verifyManifest(
+  manifest: ReleaseManifest | unknown,
+  options: VerifyManifestOptions,
+): Promise<ReleaseManifest> {
+  const parsed = parseManifest(manifest);
+  if (options.expectVersion !== undefined && parsed.version !== options.expectVersion)
+    throw new Error(
+      `release manifest is ${parsed.version}, not the requested ${options.expectVersion}`,
+    );
+  const signature = parsed.signature;
+  if (signature === undefined)
+    throw new Error(`release ${parsed.version} carries an unsigned manifest; refusing to deploy`);
+  if (signature.kmsKeyArn !== options.kmsKeyArn)
+    throw new Error(
+      `release ${parsed.version} is signed by ${signature.kmsKeyArn}, not the expected ${options.kmsKeyArn}`,
+    );
+  const result = await options.kms.verify({
+    KeyId: options.kmsKeyArn,
+    Message: manifestSigningPayload(parsed),
+    MessageType: "RAW",
+    Signature: Uint8Array.from(Buffer.from(signature.value, "base64")),
+    SigningAlgorithm: signature.algorithm,
+  });
+  if (result.SignatureValid !== true)
+    throw new Error(`release ${parsed.version}: KMS rejected the manifest signature`);
+
+  const readArtifact = options.readArtifact;
+  if (readArtifact === undefined) return parsed;
+  for (const [id, artifact] of Object.entries(parsed.lambda)) {
+    const bytes = await readArtifact(artifact.key);
+    if (bytes.byteLength !== artifact.bytes)
+      throw new Error(
+        `release ${parsed.version}: ${id} is ${bytes.byteLength} bytes, manifest says ${artifact.bytes}`,
+      );
+    assertDigest(`${parsed.version}: ${id}`, bytes, artifact.sha256);
+  }
+  assertDigest(
+    `${parsed.version}: skills`,
+    await readArtifact(parsed.skills.key),
+    parsed.skills.sha256,
+  );
+  return parsed;
+}
+
+function assertDigest(what: string, bytes: Uint8Array, expected: string): void {
+  const actual = sha256Hex(bytes);
+  if (actual !== expected)
+    throw new Error(`release ${what}: sha256 ${actual}, manifest says ${expected}`);
+}