feat(project): add 'project add credentials' (AgentCore Identity api-key + oauth)

src/assets/cdk/package.json

@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@aws/agentcore-cdk": "0.1.0-alpha.45",
-    "aws-cdk-lib": "~2.261.0",
+    "aws-cdk-lib": "~2.266.0",
     "constructs": "~10.7.0"
   }
 }

src/core/project/envLocal.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { parseEnv } from "node:util";
+import { EnvLocalFile } from "./envLocal";
+
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+});
+
+async function tempRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "envlocal-"));
+  roots.push(root);
+  // Real projects always have the agentcore/ dir; the class does not create it.
+  await mkdir(dirname(new EnvLocalFile(root).path), { recursive: true });
+  return root;
+}
+
+const ENTRY = { key: "SECRET", value: "v", comment: "c" };
+
+test("rollback deletes the file it created", async () => {
+  const root = await tempRoot();
+  const file = new EnvLocalFile(root);
+  await file.insertIfNew([ENTRY]);
+  expect(existsSync(file.path)).toBe(true);
+
+  await file.rollback();
+  expect(existsSync(file.path)).toBe(false);
+});
+
+test("rollback restores the prior content of an existing file", async () => {
+  const root = await tempRoot();
+  const file = new EnvLocalFile(root);
+  await Bun.write(file.path, "EXISTING=1\n");
+
+  await file.insertIfNew([ENTRY]);
+  expect(await Bun.file(file.path).text()).toContain("SECRET='v'");
+
+  await file.rollback();
+  expect(await Bun.file(file.path).text()).toBe("EXISTING=1\n");
+});
+
+test("rollback is a no-op when insertIfNew wrote nothing", async () => {
+  const root = await tempRoot();
+  const file = new EnvLocalFile(root);
+  await Bun.write(file.path, "SECRET=kept\n");
+
+  await file.insertIfNew([ENTRY]); // key already present, so nothing is written
+  await file.rollback();
+  expect(await Bun.file(file.path).text()).toBe("SECRET=kept\n");
+});
+
+test.each([
+  ["left#right", "left#right"],
+  ["  padded  ", "  padded  "],
+  ['has"double', 'has"double'],
+  ["back\\slash", "back\\slash"],
+  ["dollar$sign", "dollar$sign"],
+])("a value with %p round-trips through parseEnv", async (value, expected) => {
+  const root = await tempRoot();
+  const file = new EnvLocalFile(root);
+  await file.insertIfNew([{ key: "SECRET", value, comment: "c" }]);
+
+  const parsed = parseEnv(await Bun.file(file.path).text()) as Record<string, string>;
+  expect(parsed.SECRET).toBe(expected);
+});
+
+test("rejects a value that contains a single quote", async () => {
+  const root = await tempRoot();
+  const file = new EnvLocalFile(root);
+  await expect(file.insertIfNew([{ key: "SECRET", value: "a'b", comment: "c" }])).rejects.toThrow(
+    /single quote/,
+  );
+});

src/core/project/envLocal.ts

@@ -0,0 +1,97 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWrite, readTextFile } from "../../io";
+import { InputValidationError } from "../../errors";
+import type { EnvLocalEntry } from "../../handlers/project/types";
+
+/** The project-relative path of the local secrets file (read by `agentcore dev`). */
+export const ENV_LOCAL_RELATIVE_PATH = join("agentcore", ".env.local");
+
+const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+
+/**
+ * The project's `.env.local` secrets file, edited transactionally. `insertIfNew`
+ * appends entries (never overwriting an existing key) and snapshots the prior
+ * state so `rollback` can undo the write if a later step in the same operation
+ * fails. Mirrors the class shape of {@link SourceResolver} so callers hold one
+ * object and reverse its effect, rather than tracking loose paths.
+ */
+export class EnvLocalFile {
+  // undefined: no write yet; null: file did not exist before the write;
+  // string: the file's content before the write.
+  private snapshot?: string | null;
+
+  constructor(private readonly rootPath: string) {}
+
+  /** The absolute path of the secrets file. */
+  get path(): string {
+    return join(this.rootPath, ENV_LOCAL_RELATIVE_PATH);
+  }
+
+  /**
+   * Appends entries, creating the file when missing. Keys that already exist
+   * are left unchanged so user-managed values survive re-runs. Returns the keys
+   * written and those skipped.
+   */
+  async insertIfNew(entries: EnvLocalEntry[]): Promise<{ written: string[]; skipped: string[] }> {
+    const existing = await this.readOrNull();
+    const existingKeys = new Set(
+      (existing ?? "")
+        .split("\n")
+        .map((line) => KEY_LINE.exec(line)?.[1])
+        .filter((key) => key !== undefined),
+    );
+
+    const written: string[] = [];
+    const skipped: string[] = [];
+    let content = existing ?? "";
+    for (const entry of entries) {
+      if (existingKeys.has(entry.key)) {
+        skipped.push(entry.key);
+        continue;
+      }
+      const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+      // Each entry is two lines:  # <comment>\n<key>=<value>
+      content += `${separator}# ${entry.comment}\n${entry.key}=${formatValue(entry.value)}\n`;
+      written.push(entry.key);
+    }
+
+    if (written.length > 0) {
+      this.snapshot = existing;
+      await atomicWrite(this.path, content);
+    }
+    return { written, skipped };
+  }
+
+  /** Restores the file to its pre-write state; a no-op when nothing was written. */
+  async rollback(): Promise<void> {
+    if (this.snapshot === undefined) return;
+    if (this.snapshot === null) await rm(this.path, { force: true });
+    else await atomicWrite(this.path, this.snapshot);
+  }
+
+  private async readOrNull(): Promise<string | null> {
+    try {
+      return await readTextFile(this.path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+}
+
+/**
+ * Single-quotes a value so `node:util`'s `parseEnv` reads it back byte-for-byte.
+ * Single quotes are literal in that parser, so no character needs escaping,
+ * except a single quote itself, which the format cannot represent.
+ */
+function formatValue(value?: string): string {
+  if (!value) return "";
+  if (value.includes("'")) {
+    throw new InputValidationError(
+      "a secret value that contains a single quote (') cannot be written to " +
+        ".env.local; supply it with a Secrets Manager reference instead",
+    );
+  }
+  return `'${value}'`;
+}

src/core/project/manager.tsx

@@ -20,6 +20,7 @@ import {
   type ReadWriteJson,
 } from "../../io";
 import { defaultSource, type AssetSource } from "./source";
+import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "./envLocal";
 import { createHarnessTreeFromSpec, createProjectTreeFromTemplate, TEMPLATES } from "./templates";
 import { ProjectSpecSchema, type ManagedBy } from "../../projectSchemas/project";
 import { enclosingProjectRoot } from "./fsUtils";
@@ -151,8 +152,11 @@ export class FsProjectManager implements ProjectManager {
         `a ${resourceType} with name '${resourceConfig.name}' already exists`,
       );
 
+    // Widened: arms push their own shapes; the whole-spec safeParse below validates.
     const newResources: unknown[] = [...existingResources];
     const scaffoldedPaths: string[] = [];
+    // Non-file work that a failed spec write must also reverse.
+    let envFile: EnvLocalFile | undefined;
 
     switch (resourceType) {
       case "harness": {
@@ -172,6 +176,22 @@ export class FsProjectManager implements ProjectManager {
           "runtime case not yet implemented in FsProjectManager.addResource",
         );
       }
+      case "credential": {
+        // No file scaffolding; the secret placeholder is staged into .env.local
+        // and reversed with the spec write if that commit fails.
+        newResources.push(input.resourceConfig);
+        if (input.envEntries?.length) {
+          envFile = new EnvLocalFile(project.rootPath);
+          yield { message: `Updating secrets file at '${envFile.path}'` };
+          const { skipped } = await envFile.insertIfNew(input.envEntries);
+          for (const key of skipped) {
+            yield {
+              message: `'${key}' already exists in ${ENV_LOCAL_RELATIVE_PATH}; left unchanged`,
+            };
+          }
+        }
+        break;
+      }
       case "config-bundle":
       case "online-eval":
       case "online-insight":
@@ -186,37 +206,45 @@ export class FsProjectManager implements ProjectManager {
 
     yield { message: `Updating project spec file at '${agentCoreSpecPath}'` };
 
-    // rollback scaffolding changes on failed config writes to prevent bad state.
+    const newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+
+    // Validate and write inside the same boundary so a rejected spec rolls back
+    // staged side effects (.env.local, scaffolded files) rather than leaving them.
+    let newProjectSpec: z.infer<typeof ProjectSpecSchema>;
     try {
-      const newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
       const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
-
       if (!newSpecParseResult.success)
         throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
           cause: newSpecParseResult.error,
         });
-      const newProjectSpec = await this.json.write(agentCoreSpecPath, newSpecParseResult.data);
-
-      return {
-        ...project,
-        spec: newProjectSpec,
-      };
+      newProjectSpec = await this.json.write(agentCoreSpecPath, newSpecParseResult.data);
     } catch (err) {
       this.logger.warn(
-        `failed to update ${agentCoreSpecPath}; attempting best-effort cleanup of scaffolded files`,
+        `could not commit the spec update to ${agentCoreSpecPath}; attempting best-effort cleanup of staged changes`,
       );
-      await Promise.all(
-        scaffoldedPaths.map((p) =>
+      await Promise.all([
+        ...scaffoldedPaths.map((p) =>
           rm(p, { recursive: true, force: true }).catch((e) => {
             const error = AgentCoreCLIError.fromError(e);
             this.logger
               .child({ errorName: error.name, errorMessage: error.message })
               .warn(`failed to clean up ${p}`);
           }),
         ),
-      );
+        envFile?.rollback().catch((e) => {
+          const error = AgentCoreCLIError.fromError(e);
+          this.logger
+            .child({ errorName: error.name, errorMessage: error.message })
+            .warn(`failed to roll back ${ENV_LOCAL_RELATIVE_PATH}`);
+        }),
+      ]);
       throw err;
     }
+
+    return {
+      ...project,
+      spec: newProjectSpec,
+    };
   }
 
   private getProjectSpecPath(project: Project): string {
@@ -306,6 +334,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
       return "harnesses";
     case "runtime":
       return "runtimes";
+    case "credential":
+      return "credentials";
     case "config-bundle":
       return "configBundles";
     case "online-eval":

src/handlers/project/add/credentials/api-key/index.ts

@@ -0,0 +1,56 @@
+import z from "zod";
+import { createHandler, flag } from "../../../../../router";
+import { InputValidationError } from "../../../../../errors";
+import { SourceResolver } from "../../../../../io";
+import type { AddProjectResourceConfig } from "../../types";
+import type { EnvLocalEntry } from "../../../types";
+import { addCredentialToProject, credentialEnvVarName, parseExclusiveSecretRef } from "../shared";
+
+export const createAddApiKeyCredentialHandler = (config: AddProjectResourceConfig) =>
+  createHandler({
+    name: "api-key",
+    description: "add an API key credential provider to the current project",
+    flags: [
+      flag("name", "the name of the credential provider", z.string().optional()),
+      flag(
+        "api-key",
+        "the API key (file://path or - for stdin; inline values are rejected)",
+        z.string().optional(),
+        { sensitive: true },
+      ),
+      flag(
+        "api-key-secret-reference",
+        'external secret reference JSON: {"secretId":"<arn>","jsonKey":"<key>"}',
+        z.string().optional(),
+      ),
+    ],
+    handle: async (ctx, flags) => {
+      if (!flags.name)
+        throw new InputValidationError("required option '--name <name>' not specified");
+
+      const secretRef = parseExclusiveSecretRef(
+        "api-key-secret-reference",
+        flags["api-key-secret-reference"],
+        "api-key",
+        flags["api-key"],
+      );
+
+      const resolver = new SourceResolver({ stdin: config.io.stdin });
+      const apiKey = await resolver.resolveSecret("api-key", flags["api-key"]);
+
+      const envEntries: EnvLocalEntry[] = secretRef
+        ? []
+        : [
+            {
+              key: credentialEnvVarName(flags.name),
+              value: apiKey,
+              comment: `API key for credential provider '${flags.name}' (set before deploy)`,
+            },
+          ];
+
+      await addCredentialToProject(ctx, config, {
+        resourceConfig: { authorizerType: "ApiKeyCredentialProvider", name: flags.name, secretRef },
+        envEntries,
+      });
+    },
+  });

src/handlers/project/add/credentials/index.ts

@@ -0,0 +1,14 @@
+import { Router } from "../../../../router";
+import type { AddProjectResourceConfig } from "../types";
+import { createAddApiKeyCredentialHandler } from "./api-key";
+import { createAddOauthCredentialHandler } from "./oauth";
+
+export function createAddCredentialsHandler(config: AddProjectResourceConfig): Router {
+  const credentials = new Router(
+    "credentials",
+    "add AgentCore Identity credential providers to the current project",
+  );
+  credentials.handler(createAddApiKeyCredentialHandler(config));
+  credentials.handler(createAddOauthCredentialHandler(config));
+  return credentials;
+}