claude-aws-mfa 1.0.0 → 1.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,139 @@
+name: Release from Changelog
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  detect-release:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.parse.outputs.version }}
+      prerelease: ${{ steps.parse.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Parse latest changelog version
+        id: parse
+        run: |
+          # Extract the first heading that matches: ## [vX.Y.Z...] - YYYY-MM-DD
+          # The date is required — headings without a date are treated as drafts.
+          HEADING=$(grep -P '^## \[v[^\]]+\]\s+-\s+\d{4}-\d{2}-\d{2}' CHANGELOG.md | head -1)
+
+          if [ -z "$HEADING" ]; then
+            echo "No dated release heading found — nothing to release."
+            echo "version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          VERSION=$(echo "$HEADING" | grep -oP '(?<=\[)[^\]]+')
+
+          # Must be valid semver with v prefix
+          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9._-]+)?$ ]]; then
+            echo "::error::First changelog heading '$VERSION' is not valid semver with v prefix"
+            exit 1
+          fi
+
+          # Verify the date is today (UTC +/- 12h to accommodate any timezone)
+          ENTRY_DATE=$(echo "$HEADING" | grep -oP '\d{4}-\d{2}-\d{2}')
+          YESTERDAY=$(date -u -d '-12 hours' +%Y-%m-%d)
+          TODAY=$(date -u +%Y-%m-%d)
+          TOMORROW=$(date -u -d '+12 hours' +%Y-%m-%d)
+          if [[ "$ENTRY_DATE" != "$YESTERDAY" && "$ENTRY_DATE" != "$TODAY" && "$ENTRY_DATE" != "$TOMORROW" ]]; then
+            echo "::error::Changelog date $ENTRY_DATE does not match today — expected $YESTERDAY, $TODAY, or $TOMORROW"
+            exit 1
+          fi
+
+          # Check if this tag already exists on the remote
+          if git rev-parse "refs/tags/$VERSION" >/dev/null 2>&1; then
+            echo "Tag $VERSION already exists — skipping release."
+            echo "version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Check if a GitHub release already exists
+          if gh release view "$VERSION" >/dev/null 2>&1; then
+            echo "::error::GitHub release $VERSION already exists but tag does not — manual cleanup needed"
+            exit 1
+          fi
+
+          PRERELEASE="false"
+          SEMVER="${VERSION#v}"
+          if [[ "$SEMVER" =~ - ]]; then
+            PRERELEASE="true"
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
+          echo "Detected version=$VERSION prerelease=$PRERELEASE"
+
+  release:
+    needs: detect-release
+    if: needs.detect-release.outputs.version != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+
+      - run: bun test
+
+      - name: Set package version
+        run: |
+          VERSION="${{ needs.detect-release.outputs.version }}"
+          npm version "${VERSION#v}" --no-git-tag-version
+
+      - name: Extract changelog entry
+        id: changelog
+        run: |
+          VERSION="${{ needs.detect-release.outputs.version }}"
+          # Extract the body of the first changelog section (between first ## and second ##)
+          BODY=$(awk '/^## \[/{if(found) exit; found=1; next} found' CHANGELOG.md)
+          # Write to file for the release body
+          echo "$BODY" > /tmp/release-body.md
+
+      - name: Create Git tag
+        run: |
+          VERSION="${{ needs.detect-release.outputs.version }}"
+          git tag "$VERSION"
+          git push origin "$VERSION"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+        run: |
+          VERSION="${{ needs.detect-release.outputs.version }}"
+          PRERELEASE="${{ needs.detect-release.outputs.prerelease }}"
+          FLAGS=""
+          if [ "$PRERELEASE" = "true" ]; then
+            FLAGS="--prerelease"
+          fi
+          gh release create "$VERSION" \
+            --title "$VERSION" \
+            --notes-file /tmp/release-body.md \
+            $FLAGS
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish to npm
+        run: |
+          TAG="latest"
+          if [ "${{ needs.detect-release.outputs.prerelease }}" = "true" ]; then
+            TAG="next"
+          fi
+          npm publish --access public --tag "$TAG"

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+### Releasing
+
+Releases are automated via CI. To create a new release:
+
+1. Add a new entry at the top of this file with heading `## [vX.Y.Z]` (without a
+   date). This is a draft — it can be merged to `main` without triggering a
+   release.
+2. When ready to publish, update the heading to `## [vX.Y.Z] - YYYY-MM-DD` and
+   merge to `main`. The date signals "ready to release".
+3. The workflow will run tests, create a Git tag, GitHub Release, and npm publish.
+4. If the tag already exists, the workflow skips (safe to re-merge).
+5. If tests fail, no tag/release is created. The release will be re-attempted on
+   each subsequent push to `main`, or can be manually retried from the Actions UI.
+
+Stable versions (e.g. `v1.2.0`) publish to npm `@latest`. Pre-release versions
+(e.g. `v1.2.0-rc.1`) publish to npm `@next` and create a GitHub pre-release.
+
+## [v1.1.0] - 2026-06-04
+
+### Added
+- **Session caching** (`--cache-session`): Cache STS session credentials in the config file and reuse them until they expire, avoiding repeated MFA prompts.
+- **Auto-MFA** (`--auto-mfa`): Automatically run the configured MFA command to obtain credentials without showing the dialog. Falls back to the dialog if the command fails.
+- **Single-instance lock** (`--single-instance-lock`): Prevent multiple concurrent instances from showing overlapping dialogs. Subsequent invocations wait for the first to finish and reuse its cached session.
+- New CLI flags with `--no-` negation support for all new options.
+- New config file options: `cacheSession`, `autoMfa`, `singleInstanceLock`.
+- Tests for session caching, lock mechanism, and CLI flag parsing.
+- CHANGELOG.md to track project changes.
+- Updated README with documentation for new CLI flags and features.
+
+### Changed
+- Automated release pipeline: releases are now triggered by changelog entries pushed to `main`, replacing the previous manual GitHub Release workflow.
+
+### Fixed
+- Release workflow: use `RELEASE_PAT` via `actions/checkout` token so git credential helper authenticates with the PAT instead of the default `GITHUB_TOKEN` (which cannot bypass tag rulesets).
+
+## [v1.0.0] - 2026-03-28
+
+### Added
+- Initial stable release.
+- Native GUI dialog for AWS credential and MFA code entry.
+- MFA Command mode: provide a shell command (e.g. `op item get --otp …`) to fetch TOTP codes automatically.
+- Automatic STS session duration negotiation (12h → 6h → 2h → 1h).
+- Guided setup wizard (`--setup`) for Claude Code Bedrock configuration.
+- Configuration persistence in `~/.config/claude-aws-mfa.json` (mode 0600).
+- Credential masking in error output.
+- Cross-platform support (macOS, Linux, Windows).
+- CI test workflows (unit + GUI screenshot tests).
+- npm publish workflow triggered by GitHub Releases.

package/README.md

@@ -32,6 +32,17 @@ Add this (plus any addtitional config you prefer) to your Claude Code settings (
 }
 ```
 
+## CLI Flags
+
+All flags can be negated with a `--no-` prefix (e.g. `--no-cache-session`). CLI flags override values saved in the config file.
+
+| Flag | Description |
+|------|-------------|
+| `--setup` | Launch the guided setup wizard |
+| `--cache-session` | Cache STS session credentials and reuse them until they expire |
+| `--auto-mfa` | Automatically run the configured MFA command and obtain credentials without showing the dialog (requires MFA Command mode) |
+| `--single-instance-lock` | Prevent multiple concurrent instances from showing overlapping dialogs; subsequent invocations wait for the first to finish and reuse its cached session |
+
 ## How it works
 
 1. On first run, seeds the dialog with credentials from your existing AWS config (`~/.aws/credentials`, environment variables, SSO, etc.)
@@ -44,6 +55,18 @@ Add this (plus any addtitional config you prefer) to your Claude Code settings (
 
 On subsequent runs, all fields are pre-populated from the saved config — just enter a fresh MFA code and hit OK. If you use the command mode, the TOTP code is fetched automatically so no manual entry is needed at all.
 
+### Session caching
+
+With `--cache-session` (or `"cacheSession": true` in the config file), temporary credentials are saved to the config file and reused on subsequent runs until they expire. This avoids prompting for MFA on every invocation.
+
+### Auto-MFA
+
+With `--auto-mfa` (or `"autoMfa": true` in the config file), when a MFA command is configured, credentials are obtained automatically without showing the dialog at all. If the command fails or isn't configured, the dialog is shown as a fallback.
+
+### Single-instance lock
+
+With `--single-instance-lock` (or `"singleInstanceLock": true` in the config file), only one instance of the tool will show a dialog at a time. Additional invocations will wait for the first to finish and then reuse its cached session (when session caching is also enabled). The lock file is stored at `~/.config/claude-aws-mfa.lock` and is automatically cleaned up after 2 minutes if the holding process crashes.
+
 ## System requirements
 
 The GUI dialog uses [webview-bun](https://github.com/tr1ckydev/webview-bun), which requires:
@@ -60,6 +83,10 @@ bun run src/index.ts       # run locally
 bun test                   # run tests
 ```
 
+## Releasing
+
+See the [Releasing section of CHANGELOG.md](CHANGELOG.md#releasing) for how to publish new versions.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-aws-mfa",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "repository": "https://github.com/p120ph37/claude-aws-mfa",
   "bin": {

package/src/config.ts

@@ -6,11 +6,20 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  rmSync,
   statSync,
   writeFileSync,
+  writeSync,
 } from "fs";
 import { STSClient } from "@aws-sdk/client-sts";
 
+export interface CachedSession {
+  AccessKeyId: string;
+  SecretAccessKey: string;
+  SessionToken: string;
+  Expiration: string; // ISO 8601
+}
+
 export interface Config {
   region: string;
   accessKeyId: string;
@@ -20,6 +29,10 @@ export interface Config {
   duration: number;
   mfaMode?: "code" | "command";
   mfaCommand?: string;
+  cacheSession?: boolean;
+  autoMfa?: boolean;
+  singleInstanceLock?: boolean;
+  cachedSession?: CachedSession;
 }
 
 const CONFIG_PATH = join(homedir(), ".config", "claude-aws-mfa.json");
@@ -104,6 +117,66 @@ export function saveConfig(config: Config) {
   writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
 }
 
+// --- Single-instance lock ---
+
+const LOCK_PATH = join(homedir(), ".config", "claude-aws-mfa.lock");
+const LOCK_POLL_MS = 500;
+const LOCK_STALE_MS = 120_000; // 2 minutes — assume stale if holder crashed
+
+/**
+ * Attempt to acquire an exclusive lock.  Returns true if acquired.
+ * Uses O_EXCL to atomically create the lock file.
+ */
+export function tryAcquireLock(): boolean {
+  ensureConfigDir();
+  try {
+    const fd = openSync(LOCK_PATH, "wx", 0o600);
+    writeSync(fd, String(process.pid));
+    closeSync(fd);
+    return true;
+  } catch (err: any) {
+    if (err?.code === "EEXIST") {
+      // Check for stale lock
+      try {
+        const st = statSync(LOCK_PATH);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+          // Stale lock — remove and retry once
+          try { rmSync(LOCK_PATH); } catch {}
+          return tryAcquireLock();
+        }
+      } catch {}
+      return false;
+    }
+    throw err;
+  }
+}
+
+/** Release the lock file. */
+export function releaseLock(): void {
+  try { rmSync(LOCK_PATH); } catch {}
+}
+
+/**
+ * Wait until the lock is released, polling every LOCK_POLL_MS.
+ * Returns once the lock file disappears (or becomes stale).
+ */
+export async function waitForLock(): Promise<void> {
+  while (true) {
+    try {
+      const st = statSync(LOCK_PATH);
+      if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+        // Stale — break out so caller can acquire
+        try { rmSync(LOCK_PATH); } catch {}
+        return;
+      }
+    } catch {
+      // Lock file gone — we can proceed
+      return;
+    }
+    await Bun.sleep(LOCK_POLL_MS);
+  }
+}
+
 export async function seedDefaults(): Promise<Partial<Config>> {
   const defaults: Partial<Config> = {};
   try {

package/src/flags.ts

@@ -0,0 +1,42 @@
+export interface CliFlags {
+  setup: boolean;
+  cacheSession: boolean | undefined;  // undefined = use config default
+  autoMfa: boolean | undefined;
+  singleInstanceLock: boolean | undefined;
+}
+
+export function parseFlags(argv: string[]): CliFlags {
+  const flags: CliFlags = {
+    setup: false,
+    cacheSession: undefined,
+    autoMfa: undefined,
+    singleInstanceLock: undefined,
+  };
+  for (const arg of argv.slice(2)) {
+    switch (arg) {
+      case "setup":
+      case "--setup":
+        flags.setup = true;
+        break;
+      case "--cache-session":
+        flags.cacheSession = true;
+        break;
+      case "--no-cache-session":
+        flags.cacheSession = false;
+        break;
+      case "--auto-mfa":
+        flags.autoMfa = true;
+        break;
+      case "--no-auto-mfa":
+        flags.autoMfa = false;
+        break;
+      case "--single-instance-lock":
+        flags.singleInstanceLock = true;
+        break;
+      case "--no-single-instance-lock":
+        flags.singleInstanceLock = false;
+        break;
+    }
+  }
+  return flags;
+}

package/src/index.ts

@@ -15,25 +15,107 @@ if (process.platform === "linux" && !process.env.WEBKIT_DISABLE_SANDBOX_THIS_IS_
   process.exit(proc.exitCode);
 }
 
-const arg = process.argv[2];
-if (arg === "setup" || arg === "--setup") {
+import { parseFlags } from "./flags";
+
+const flags = parseFlags(process.argv);
+
+if (flags.setup) {
   const { runSetup } = await import("./setup");
   process.exit(runSetup() ? 0 : 2);
 }
 
-import { loadConfig, saveConfig, seedDefaults } from "./config";
+import type { CachedSession, Config } from "./config";
+import { loadConfig, saveConfig, seedDefaults, tryAcquireLock, releaseLock, waitForLock } from "./config";
 import { showDialog } from "./dialog";
 import { assumeRoleWithMfa, STANDARD_DURATIONS } from "./sts";
 
-const defaults = loadConfig() ?? await seedDefaults();
+// --- Resolve effective flags (CLI overrides config defaults) ---
 
-const result = showDialog(defaults);
-if (!result) {
-  process.stderr.write("User cancelled dialog.\n");
-  process.exit(2);
+const config = loadConfig();
+const defaults: Partial<Config> = config ?? await seedDefaults();
+
+const useCache = flags.cacheSession ?? defaults.cacheSession ?? false;
+const useAutoMfa = flags.autoMfa ?? defaults.autoMfa ?? false;
+const useLock = flags.singleInstanceLock ?? defaults.singleInstanceLock ?? false;
+
+// --- Helper: check if a cached session is still valid ---
+
+function isSessionValid(session: CachedSession | undefined): session is CachedSession {
+  if (!session) return false;
+  return new Date(session.Expiration).getTime() > Date.now();
 }
 
-try {
+// --- Helper: output credentials and save config ---
+
+function outputCredentials(session: CachedSession): void {
+  console.log(JSON.stringify({
+    Credentials: {
+      AccessKeyId: session.AccessKeyId,
+      SecretAccessKey: session.SecretAccessKey,
+      SessionToken: session.SessionToken,
+    },
+  }));
+}
+
+// --- Helper: run MFA command and attempt to obtain credentials without dialog ---
+
+async function tryAutoMfa(cfg: Partial<Config>): Promise<CachedSession | null> {
+  if (!cfg.mfaCommand || cfg.mfaMode !== "command") return null;
+  if (!cfg.region || !cfg.accessKeyId || !cfg.secretAccessKey || !cfg.mfaArn || !cfg.roleArn) return null;
+
+  try {
+    const proc = Bun.spawnSync(["sh", "-c", cfg.mfaCommand]);
+    if (proc.exitCode !== 0) return null;
+    const mfaCode = proc.stdout.toString().trim();
+    if (!mfaCode) return null;
+
+    const { credentials, duration } = await assumeRoleWithMfa({
+      region: cfg.region,
+      accessKeyId: cfg.accessKeyId,
+      secretAccessKey: cfg.secretAccessKey,
+      mfaArn: cfg.mfaArn,
+      roleArn: cfg.roleArn,
+      mfaCode,
+      duration: cfg.duration ?? STANDARD_DURATIONS[0],
+    });
+
+    const session: CachedSession = {
+      AccessKeyId: credentials.AccessKeyId,
+      SecretAccessKey: credentials.SecretAccessKey,
+      SessionToken: credentials.SessionToken,
+      Expiration: credentials.Expiration,
+    };
+
+    saveConfig({
+      region: cfg.region,
+      accessKeyId: cfg.accessKeyId,
+      secretAccessKey: cfg.secretAccessKey,
+      mfaArn: cfg.mfaArn,
+      roleArn: cfg.roleArn,
+      duration,
+      mfaMode: cfg.mfaMode,
+      mfaCommand: cfg.mfaCommand,
+      cacheSession: cfg.cacheSession,
+      autoMfa: cfg.autoMfa,
+      singleInstanceLock: cfg.singleInstanceLock,
+      ...(useCache ? { cachedSession: session } : {}),
+    });
+
+    return session;
+  } catch {
+    return null;
+  }
+}
+
+// --- Helper: show dialog and obtain credentials ---
+
+async function obtainViaDialog(cfg: Partial<Config>): Promise<void> {
+  const result = showDialog(cfg);
+  if (!result) {
+    process.stderr.write("User cancelled dialog.\n");
+    process.exit(2);
+  }
+
   let mfaCode = result.mfaCode;
   if (result.mfaMode === "command") {
     const proc = Bun.spawnSync(["sh", "-c", result.mfaCommand]);
@@ -54,6 +136,13 @@ try {
     duration: parseInt(result.duration, 10) || STANDARD_DURATIONS[0],
   });
 
+  const session: CachedSession = {
+    AccessKeyId: credentials.AccessKeyId,
+    SecretAccessKey: credentials.SecretAccessKey,
+    SessionToken: credentials.SessionToken,
+    Expiration: credentials.Expiration,
+  };
+
   saveConfig({
     region: result.region,
     accessKeyId: result.accessKeyId,
@@ -63,10 +152,81 @@ try {
     duration,
     mfaMode: result.mfaMode,
     mfaCommand: result.mfaCommand || undefined,
+    cacheSession: defaults.cacheSession,
+    autoMfa: defaults.autoMfa,
+    singleInstanceLock: defaults.singleInstanceLock,
+    ...(useCache ? { cachedSession: session } : {}),
   });
 
-  console.log(JSON.stringify({ Credentials: credentials }));
+  outputCredentials(session);
+}
+
+// --- Main flow ---
+
+try {
+  // 1. If cache-session is enabled, check for unexpired cached credentials
+  if (useCache && config?.cachedSession) {
+    if (isSessionValid(config.cachedSession)) {
+      // Return cached credentials without showing dialog
+      outputCredentials(config.cachedSession);
+      process.exit(0);
+    }
+    // Expired — clear the cached session
+    saveConfig({ ...config, cachedSession: undefined });
+  }
+
+  // 2. If auto-mfa is enabled, try to obtain credentials without dialog
+  if (useAutoMfa) {
+    const session = await tryAutoMfa(defaults);
+    if (session) {
+      outputCredentials(session);
+      process.exit(0);
+    }
+  }
+
+  // 3. If single-instance-lock is enabled, acquire lock before showing dialog
+  if (useLock) {
+    if (!tryAcquireLock()) {
+      // Another instance holds the lock — wait for it
+      process.stderr.write("Waiting for another instance to finish...\n");
+      await waitForLock();
+
+      // After lock releases, re-check cached session (another instance may have refreshed it)
+      if (useCache) {
+        const freshConfig = loadConfig();
+        if (freshConfig?.cachedSession && isSessionValid(freshConfig.cachedSession)) {
+          outputCredentials(freshConfig.cachedSession);
+          process.exit(0);
+        }
+      }
+
+      // Still need credentials — acquire lock and show dialog
+      if (!tryAcquireLock()) {
+        // Edge case: another waiter grabbed the lock first — wait again
+        await waitForLock();
+        if (useCache) {
+          const freshConfig = loadConfig();
+          if (freshConfig?.cachedSession && isSessionValid(freshConfig.cachedSession)) {
+            outputCredentials(freshConfig.cachedSession);
+            process.exit(0);
+          }
+        }
+        // Final attempt to acquire — proceed regardless
+        tryAcquireLock();
+      }
+    }
+
+    try {
+      await obtainViaDialog(defaults);
+    } finally {
+      releaseLock();
+    }
+  } else {
+    // No lock — just show dialog directly
+    await obtainViaDialog(defaults);
+  }
 } catch (err) {
+  if (useLock) releaseLock();
   // Mask any AWS access-key IDs or secret keys that may appear in error messages
   const raw = String(err);
   const masked = raw

package/src/sts.ts

@@ -47,6 +47,7 @@ export async function assumeRoleWithMfa(params: {
           AccessKeyId: c!.AccessKeyId!,
           SecretAccessKey: c!.SecretAccessKey!,
           SessionToken: c!.SessionToken!,
+          Expiration: c!.Expiration ? c!.Expiration.toISOString() : new Date(Date.now() + ladder[i] * 1000).toISOString(),
         },
         duration: ladder[i],
       };

package/test/index.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "bun:test";
+import { parseFlags } from "../src/flags";
+
+describe("parseFlags", () => {
+  // argv[0] is the runtime, argv[1] is the script — flags start at index 2
+  const base = ["/usr/bin/bun", "/path/to/index.ts"];
+
+  test("returns defaults when no flags", () => {
+    const flags = parseFlags(base);
+    expect(flags.setup).toBe(false);
+    expect(flags.cacheSession).toBeUndefined();
+    expect(flags.autoMfa).toBeUndefined();
+    expect(flags.singleInstanceLock).toBeUndefined();
+  });
+
+  test("parses --setup", () => {
+    expect(parseFlags([...base, "--setup"]).setup).toBe(true);
+    expect(parseFlags([...base, "setup"]).setup).toBe(true);
+  });
+
+  test("parses --cache-session and --no-cache-session", () => {
+    expect(parseFlags([...base, "--cache-session"]).cacheSession).toBe(true);
+    expect(parseFlags([...base, "--no-cache-session"]).cacheSession).toBe(false);
+  });
+
+  test("parses --auto-mfa and --no-auto-mfa", () => {
+    expect(parseFlags([...base, "--auto-mfa"]).autoMfa).toBe(true);
+    expect(parseFlags([...base, "--no-auto-mfa"]).autoMfa).toBe(false);
+  });
+
+  test("parses --single-instance-lock and --no-single-instance-lock", () => {
+    expect(parseFlags([...base, "--single-instance-lock"]).singleInstanceLock).toBe(true);
+    expect(parseFlags([...base, "--no-single-instance-lock"]).singleInstanceLock).toBe(false);
+  });
+
+  test("last flag wins for conflicting flags", () => {
+    const flags = parseFlags([...base, "--cache-session", "--no-cache-session"]);
+    expect(flags.cacheSession).toBe(false);
+  });
+
+  test("parses multiple flags together", () => {
+    const flags = parseFlags([...base, "--cache-session", "--auto-mfa", "--single-instance-lock"]);
+    expect(flags.cacheSession).toBe(true);
+    expect(flags.autoMfa).toBe(true);
+    expect(flags.singleInstanceLock).toBe(true);
+  });
+
+  test("ignores unknown flags", () => {
+    const flags = parseFlags([...base, "--unknown-flag", "--cache-session"]);
+    expect(flags.cacheSession).toBe(true);
+    expect(flags.setup).toBe(false);
+  });
+});

package/test/lock.test.ts

@@ -0,0 +1,47 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import { tryAcquireLock, releaseLock, waitForLock } from "../src/config";
+
+describe("single-instance lock", () => {
+  afterEach(() => {
+    releaseLock();
+  });
+
+  test("tryAcquireLock succeeds on first call", () => {
+    expect(tryAcquireLock()).toBe(true);
+  });
+
+  test("tryAcquireLock fails when lock is already held", () => {
+    expect(tryAcquireLock()).toBe(true);
+    expect(tryAcquireLock()).toBe(false);
+  });
+
+  test("releaseLock allows re-acquisition", () => {
+    expect(tryAcquireLock()).toBe(true);
+    releaseLock();
+    expect(tryAcquireLock()).toBe(true);
+  });
+
+  test("releaseLock is safe to call when no lock exists", () => {
+    releaseLock(); // should not throw
+    releaseLock(); // double release should not throw
+  });
+
+  test("waitForLock resolves immediately when no lock exists", async () => {
+    const start = Date.now();
+    await waitForLock();
+    expect(Date.now() - start).toBeLessThan(100);
+  });
+
+  test("waitForLock resolves after lock is released", async () => {
+    expect(tryAcquireLock()).toBe(true);
+
+    // Release the lock after a short delay
+    setTimeout(() => releaseLock(), 200);
+
+    const start = Date.now();
+    await waitForLock();
+    const elapsed = Date.now() - start;
+    // Should resolve within ~200ms + poll interval (500ms)
+    expect(elapsed).toBeLessThan(1000);
+  });
+});

package/test/session-cache.test.ts

@@ -0,0 +1,89 @@
+import { describe, test, expect } from "bun:test";
+import type { CachedSession, Config } from "../src/config";
+
+describe("session cache validation", () => {
+  function isSessionValid(session: CachedSession | undefined): session is CachedSession {
+    if (!session) return false;
+    return new Date(session.Expiration).getTime() > Date.now();
+  }
+
+  const validSession: CachedSession = {
+    AccessKeyId: "ASIATEMP",
+    SecretAccessKey: "TempSecret",
+    SessionToken: "TempToken",
+    Expiration: new Date(Date.now() + 3600_000).toISOString(), // 1 hour from now
+  };
+
+  const expiredSession: CachedSession = {
+    AccessKeyId: "ASIATEMP",
+    SecretAccessKey: "TempSecret",
+    SessionToken: "TempToken",
+    Expiration: new Date(Date.now() - 1000).toISOString(), // 1 second ago
+  };
+
+  test("returns true for unexpired session", () => {
+    expect(isSessionValid(validSession)).toBe(true);
+  });
+
+  test("returns false for expired session", () => {
+    expect(isSessionValid(expiredSession)).toBe(false);
+  });
+
+  test("returns false for undefined session", () => {
+    expect(isSessionValid(undefined)).toBe(false);
+  });
+
+  test("cached session round-trips through config JSON", () => {
+    const config: Config = {
+      region: "us-west-2",
+      accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+      secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+      mfaArn: "arn:aws:iam::123456789012:mfa/user",
+      roleArn: "arn:aws:iam::123456789012:role/TestRole",
+      duration: 7200,
+      cacheSession: true,
+      cachedSession: validSession,
+    };
+
+    const json = JSON.stringify(config, null, 2);
+    const parsed = JSON.parse(json) as Config;
+    expect(parsed.cachedSession).toEqual(validSession);
+    expect(parsed.cacheSession).toBe(true);
+  });
+
+  test("config without cached session is valid", () => {
+    const config: Config = {
+      region: "us-west-2",
+      accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+      secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+      mfaArn: "arn:aws:iam::123456789012:mfa/user",
+      roleArn: "arn:aws:iam::123456789012:role/TestRole",
+      duration: 7200,
+    };
+
+    const json = JSON.stringify(config, null, 2);
+    const parsed = JSON.parse(json) as Config;
+    expect(parsed.cachedSession).toBeUndefined();
+    expect(parsed.cacheSession).toBeUndefined();
+  });
+
+  test("feature flags round-trip through config JSON", () => {
+    const config: Config = {
+      region: "us-west-2",
+      accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+      secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+      mfaArn: "arn:aws:iam::123456789012:mfa/user",
+      roleArn: "arn:aws:iam::123456789012:role/TestRole",
+      duration: 7200,
+      cacheSession: true,
+      autoMfa: true,
+      singleInstanceLock: false,
+    };
+
+    const json = JSON.stringify(config, null, 2);
+    const parsed = JSON.parse(json) as Config;
+    expect(parsed.cacheSession).toBe(true);
+    expect(parsed.autoMfa).toBe(true);
+    expect(parsed.singleInstanceLock).toBe(false);
+  });
+});

package/test/sts.test.ts

@@ -37,6 +37,7 @@ const MOCK_CREDENTIALS = {
     AccessKeyId: "ASIATEMP",
     SecretAccessKey: "TempSecret",
     SessionToken: "TempToken",
+    Expiration: new Date("2099-01-01T00:00:00Z"),
   },
 };
 
@@ -98,6 +99,7 @@ describe("assumeRoleWithMfa", () => {
       AccessKeyId: "ASIATEMP",
       SecretAccessKey: "TempSecret",
       SessionToken: "TempToken",
+      Expiration: "2099-01-01T00:00:00.000Z",
     });
     expect(result.duration).toBe(43200);
   });

package/.github/workflows/publish.yml

@@ -1,76 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Validate release tag
-        run: |
-          TAG="${GITHUB_REF_NAME}"
-          IS_PRERELEASE="${{ github.event.release.prerelease }}"
-
-          # Must start with "v"
-          if [[ "$TAG" != v* ]]; then
-            echo "::error::Tag must start with 'v' (got '$TAG')"
-            exit 1
-          fi
-
-          VERSION="${TAG#v}"
-
-          # Must be valid semver (X.Y.Z or X.Y.Z-prerelease)
-          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9._-]+)?$ ]]; then
-            echo "::error::Tag must be a valid semver with a 'v' prefix (got '$TAG')"
-            exit 1
-          fi
-
-          HAS_PRERELEASE_SUFFIX="false"
-          if [[ "$VERSION" =~ - ]]; then
-            HAS_PRERELEASE_SUFFIX="true"
-          fi
-
-          # Prerelease checkbox must match tag format
-          if [ "$IS_PRERELEASE" = "true" ] && [ "$HAS_PRERELEASE_SUFFIX" = "false" ]; then
-            echo "::error::Release is marked as prerelease but tag '$TAG' has no prerelease suffix (e.g. v1.0.0-beta.1)"
-            exit 1
-          fi
-
-          if [ "$IS_PRERELEASE" = "false" ] && [ "$HAS_PRERELEASE_SUFFIX" = "true" ]; then
-            echo "::error::Tag '$TAG' has a prerelease suffix but release is not marked as prerelease"
-            exit 1
-          fi
-
-          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
-
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - run: bun install --frozen-lockfile
-
-      - run: bun test
-
-      - name: Set package version from release tag
-        run: npm version "$VERSION" --no-git-tag-version
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-
-      - name: Publish to npm
-        run: |
-          TAG="latest"
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
-            TAG="next"
-          fi
-          npm publish --access public --tag "$TAG"