@aztec/aztec 0.0.1-commit.858058eac → 0.0.1-commit.85d7d01

package/dest/testing/anvil_test_watcher.js

@@ -22,6 +22,12 @@ import { getAddress, getContract } from 'viem';
     markingAsProvenRunningPromise;
     logger;
     isMarkingAsProven;
+    // Optional callback to check if there are pending txs in the mempool.
+    getPendingTxCount;
+    // Optional callback to check if the sequencer is actively building a block.
+    isSequencerBuilding;
+    // Tracks when we first observed the current unfilled slot with pending txs (real wall time).
+    unfilledSlotFirstSeen;
     constructor(cheatcodes, rollupAddress, l1Client, dateProvider){
         this.cheatcodes = cheatcodes;
         this.dateProvider = dateProvider;
@@ -45,6 +51,12 @@ import { getAddress, getContract } from 'viem';
     setisLocalNetwork(isLocalNetwork) {
         this.isLocalNetwork = isLocalNetwork;
     }
+    /** Sets a callback to check for pending txs, used to skip unfilled slots faster when txs are waiting. */ setGetPendingTxCount(fn) {
+        this.getPendingTxCount = fn;
+    }
+    /** Sets a callback to check if the sequencer is actively building, to avoid warping while it works. */ setIsSequencerBuilding(fn) {
+        this.isSequencerBuilding = fn;
+    }
     async start() {
         if (this.filledRunningPromise) {
             throw new Error('Watcher already watching for filled slot');
@@ -111,14 +123,8 @@ import { getAddress, getContract } from 'viem';
                 BigInt(nextSlot)
             ]));
             if (BigInt(currentSlot) === checkpointLog.slotNumber) {
-                // We should jump to the next slot
-                try {
-                    await this.cheatcodes.warp(nextSlotTimestamp, {
-                        resetBlockInterval: true
-                    });
-                } catch (e) {
-                    this.logger.error(`Failed to warp to timestamp ${nextSlotTimestamp}: ${e}`);
-                }
+                // The current slot has been filled, we should jump to the next slot.
+                await this.warpToTimestamp(nextSlotTimestamp);
                 this.logger.info(`Slot ${currentSlot} was filled, jumped to next slot`);
                 return;
             }
@@ -126,19 +132,50 @@ import { getAddress, getContract } from 'viem';
             if (!this.isLocalNetwork) {
                 return;
             }
+            // If there are pending txs and the sequencer missed them, warp quickly (after a 2s real-time debounce) so the
+            // sequencer can retry in the next slot. Without this, we'd have to wait a full real-time slot duration (~36s) for
+            // the dateProvider to catch up to the next slot timestamp. We skip the warp if the sequencer is actively building
+            // to avoid invalidating its in-progress work.
+            if (this.getPendingTxCount) {
+                const pendingTxs = await this.getPendingTxCount();
+                if (pendingTxs > 0) {
+                    if (this.isSequencerBuilding?.()) {
+                        this.unfilledSlotFirstSeen = undefined;
+                        return;
+                    }
+                    const realNow = Date.now();
+                    if (!this.unfilledSlotFirstSeen || this.unfilledSlotFirstSeen.slot !== currentSlot) {
+                        this.unfilledSlotFirstSeen = {
+                            slot: currentSlot,
+                            realTime: realNow
+                        };
+                        return;
+                    }
+                    if (realNow - this.unfilledSlotFirstSeen.realTime > 2000) {
+                        await this.warpToTimestamp(nextSlotTimestamp);
+                        this.unfilledSlotFirstSeen = undefined;
+                        this.logger.info(`Slot ${currentSlot} was missed with pending txs, jumped to next slot`);
+                    }
+                    return;
+                }
+            }
+            // Fallback: warp when the dateProvider time has passed the next slot timestamp.
             const currentTimestamp = this.dateProvider?.now() ?? Date.now();
             if (currentTimestamp > nextSlotTimestamp * 1000) {
-                try {
-                    await this.cheatcodes.warp(nextSlotTimestamp, {
-                        resetBlockInterval: true
-                    });
-                } catch (e) {
-                    this.logger.error(`Failed to warp to timestamp ${nextSlotTimestamp}: ${e}`);
-                }
+                await this.warpToTimestamp(nextSlotTimestamp);
                 this.logger.info(`Slot ${currentSlot} was missed, jumped to next slot`);
             }
         } catch  {
             this.logger.error('mineIfSlotFilled failed');
         }
     }
+    async warpToTimestamp(timestamp) {
+        try {
+            await this.cheatcodes.warp(timestamp, {
+                resetBlockInterval: true
+            });
+        } catch (e) {
+            this.logger.error(`Failed to warp to timestamp ${timestamp}: ${e}`);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/aztec",
-  "version": "0.0.1-commit.858058eac",
+  "version": "0.0.1-commit.85d7d01",
   "type": "module",
   "exports": {
     ".": "./dest/index.js",
@@ -28,39 +28,39 @@
     "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/accounts": "0.0.1-commit.858058eac",
-    "@aztec/archiver": "0.0.1-commit.858058eac",
-    "@aztec/aztec-faucet": "0.0.1-commit.858058eac",
-    "@aztec/aztec-node": "0.0.1-commit.858058eac",
-    "@aztec/aztec.js": "0.0.1-commit.858058eac",
-    "@aztec/bb-prover": "0.0.1-commit.858058eac",
-    "@aztec/bb.js": "0.0.1-commit.858058eac",
-    "@aztec/blob-client": "0.0.1-commit.858058eac",
-    "@aztec/bot": "0.0.1-commit.858058eac",
-    "@aztec/builder": "0.0.1-commit.858058eac",
-    "@aztec/cli": "0.0.1-commit.858058eac",
-    "@aztec/constants": "0.0.1-commit.858058eac",
-    "@aztec/entrypoints": "0.0.1-commit.858058eac",
-    "@aztec/ethereum": "0.0.1-commit.858058eac",
-    "@aztec/foundation": "0.0.1-commit.858058eac",
-    "@aztec/kv-store": "0.0.1-commit.858058eac",
-    "@aztec/l1-artifacts": "0.0.1-commit.858058eac",
-    "@aztec/node-lib": "0.0.1-commit.858058eac",
-    "@aztec/noir-contracts.js": "0.0.1-commit.858058eac",
-    "@aztec/noir-protocol-circuits-types": "0.0.1-commit.858058eac",
-    "@aztec/p2p": "0.0.1-commit.858058eac",
-    "@aztec/p2p-bootstrap": "0.0.1-commit.858058eac",
-    "@aztec/protocol-contracts": "0.0.1-commit.858058eac",
-    "@aztec/prover-client": "0.0.1-commit.858058eac",
-    "@aztec/prover-node": "0.0.1-commit.858058eac",
-    "@aztec/pxe": "0.0.1-commit.858058eac",
-    "@aztec/sequencer-client": "0.0.1-commit.858058eac",
-    "@aztec/stdlib": "0.0.1-commit.858058eac",
-    "@aztec/telemetry-client": "0.0.1-commit.858058eac",
-    "@aztec/txe": "0.0.1-commit.858058eac",
-    "@aztec/validator-ha-signer": "0.0.1-commit.858058eac",
-    "@aztec/wallets": "0.0.1-commit.858058eac",
-    "@aztec/world-state": "0.0.1-commit.858058eac",
+    "@aztec/accounts": "0.0.1-commit.85d7d01",
+    "@aztec/archiver": "0.0.1-commit.85d7d01",
+    "@aztec/aztec-faucet": "0.0.1-commit.85d7d01",
+    "@aztec/aztec-node": "0.0.1-commit.85d7d01",
+    "@aztec/aztec.js": "0.0.1-commit.85d7d01",
+    "@aztec/bb-prover": "0.0.1-commit.85d7d01",
+    "@aztec/bb.js": "0.0.1-commit.85d7d01",
+    "@aztec/blob-client": "0.0.1-commit.85d7d01",
+    "@aztec/bot": "0.0.1-commit.85d7d01",
+    "@aztec/builder": "0.0.1-commit.85d7d01",
+    "@aztec/cli": "0.0.1-commit.85d7d01",
+    "@aztec/constants": "0.0.1-commit.85d7d01",
+    "@aztec/entrypoints": "0.0.1-commit.85d7d01",
+    "@aztec/ethereum": "0.0.1-commit.85d7d01",
+    "@aztec/foundation": "0.0.1-commit.85d7d01",
+    "@aztec/kv-store": "0.0.1-commit.85d7d01",
+    "@aztec/l1-artifacts": "0.0.1-commit.85d7d01",
+    "@aztec/node-lib": "0.0.1-commit.85d7d01",
+    "@aztec/noir-contracts.js": "0.0.1-commit.85d7d01",
+    "@aztec/noir-protocol-circuits-types": "0.0.1-commit.85d7d01",
+    "@aztec/p2p": "0.0.1-commit.85d7d01",
+    "@aztec/p2p-bootstrap": "0.0.1-commit.85d7d01",
+    "@aztec/protocol-contracts": "0.0.1-commit.85d7d01",
+    "@aztec/prover-client": "0.0.1-commit.85d7d01",
+    "@aztec/prover-node": "0.0.1-commit.85d7d01",
+    "@aztec/pxe": "0.0.1-commit.85d7d01",
+    "@aztec/sequencer-client": "0.0.1-commit.85d7d01",
+    "@aztec/stdlib": "0.0.1-commit.85d7d01",
+    "@aztec/telemetry-client": "0.0.1-commit.85d7d01",
+    "@aztec/txe": "0.0.1-commit.85d7d01",
+    "@aztec/validator-ha-signer": "0.0.1-commit.85d7d01",
+    "@aztec/wallets": "0.0.1-commit.85d7d01",
+    "@aztec/world-state": "0.0.1-commit.85d7d01",
     "@types/chalk": "^2.2.0",
     "abitype": "^0.8.11",
     "chalk": "^5.3.0",

package/scripts/aztec.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
-shopt -s inherit_errexit
 
 # Re-execute using correct version if we have an .aztecrc file.
 if [ "${AZTEC_VERSIONED:-0}" -eq 0 ] && [ -f .aztecrc ] && command -v aztec-up &>/dev/null; then
@@ -21,13 +20,13 @@ function aztec {
 
 case $cmd in
   test)
-    export LOG_LEVEL="${LOG_LEVEL:-error}"
+    export LOG_LEVEL="${LOG_LEVEL:-"error;trace:contract_log"}"
     aztec start --txe --port 8081 &
     server_pid=$!
     trap 'kill $server_pid &>/dev/null || true' EXIT
     while ! nc -z 127.0.0.1 8081 &>/dev/null; do sleep 0.2; done
     export NARGO_FOREIGN_CALL_TIMEOUT=300000
-    nargo test --silence-warnings  --oracle-resolver http://127.0.0.1:8081 "$@"
+    nargo test --silence-warnings --oracle-resolver http://127.0.0.1:8081 --test-threads 16 "$@"
     ;;
   start)
     if [ "${1:-}" == "--local-network" ]; then
@@ -47,16 +46,20 @@ case $cmd in
       export ETHEREUM_HOSTS=${ETHEREUM_HOSTS:-"http://127.0.0.1:${ANVIL_PORT}"}
 
       anvil --version
-      anvil --silent &
+      anvil --silent --port "$ANVIL_PORT" &
       anvil_pid=$!
       trap 'kill $anvil_pid &>/dev/null' EXIT
     fi
 
     aztec start "$@"
     ;;
-  compile|new|init|flamegraph)
+  new|init)
     $script_dir/${cmd}.sh "$@"
     ;;
+  flamegraph)
+    echo "Warning: 'aztec flamegraph' is deprecated. Use 'aztec profile flamegraph' instead." >&2
+    aztec profile flamegraph "$@"
+    ;;
   *)
     aztec $cmd "$@"
     ;;

package/scripts/init.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-NARGO=${NARGO:-nargo}
 script_path=$(realpath $(dirname "$0"))
 
+name_arg=""
+
+# Check for help first
 for arg in "$@"; do
   if [ "$arg" == "--help" ] || [ "$arg" == "-h" ]; then
     cat << 'EOF'
@@ -13,23 +15,31 @@ Usage: aztec init [OPTIONS]
 
 Options:
   --name <NAME>  Name of the package [default: current directory name]
-  --lib          Use a library template
   -h, --help     Print help
 
-This command creates a new Aztec Noir project in the current directory using nargo
-and automatically adds the Aztec.nr dependency to your Nargo.toml file.
-
+This command creates a new Aztec Noir project in the current directory with
+a workspace containing a contract crate and a test crate, and automatically
+adds the Aztec.nr dependency to both.
 EOF
     exit 0
   fi
-  if [ "$arg" == "--lib" ]; then
-    is_contract=0
-  fi
 done
 
-echo "Initializing Noir project..."
-$NARGO init "$@"
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --name)
+      name_arg="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Derive package name: use --name if provided, otherwise use current directory name
+package_name="${name_arg:-$(basename $(pwd))}"
 
-if [ "${is_contract:-1}" -eq 1 ]; then
-  $script_path/setup_project.sh
-fi
+echo "Initializing Aztec contract project..."
+$script_path/setup_workspace.sh "$package_name"

package/scripts/new.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-NARGO=${NARGO:-nargo}
 script_path=$(realpath $(dirname "$0"))
 
-type_arg="--contract"
+name_arg=""
+project_path=""
 
 while [[ $# -gt 0 ]]; do
   case $1 in
@@ -19,20 +19,16 @@ Arguments:
 
 Options:
   --name <NAME>  Name of the package [default: package directory name]
-  --lib          Create a library template instead of a contract
   -h, --help     Print help
 
-This command creates a new Aztec Noir project using nargo and automatically
-adds the Aztec.nr dependency to your Nargo.toml file.
+This command creates a new Aztec Noir project with a workspace containing
+a contract crate and a test crate, and automatically adds the Aztec.nr
+dependency to both.
 EOF
       exit 0
       ;;
-    --lib)
-      type_arg="--lib"
-      shift
-      ;;
     --name)
-      name_arg="--name $2"
+      name_arg="$2"
       shift 2
       ;;
     *)
@@ -50,10 +46,15 @@ if [ -z "$project_path" ]; then
   exit 1
 fi
 
-echo "Creating new Noir project at $project_path..."
-$NARGO new $type_arg ${name_arg:-} $project_path
-
-if [ "$type_arg" == "--contract" ]; then
-  cd $project_path
-  $script_path/setup_project.sh
+if [ -d "$project_path" ] && [ "$(ls -A $project_path 2>/dev/null)" ]; then
+  echo "Error: $project_path already exists and is not empty"
+  exit 1
 fi
+
+# Derive package name: use --name if provided, otherwise use directory basename
+package_name="${name_arg:-$(basename $project_path)}"
+
+echo "Creating new Aztec contract project at $project_path..."
+mkdir -p "$project_path"
+cd "$project_path"
+$script_path/setup_workspace.sh "$package_name"

package/scripts/setup_workspace.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Creates an Aztec contract workspace with a contract crate and a test crate.
+# Usage: setup_workspace.sh <package_name>
+# Must be called from the workspace root directory.
+
+package_name=$1
+
+if [ -z "$package_name" ]; then
+  echo "Error: package name is required"
+  exit 1
+fi
+
+if [ -f "Nargo.toml" ]; then
+  echo "Error: Nargo.toml already exists in the current directory"
+  exit 1
+fi
+
+# Get the actual aztec version for the git tag.
+AZTEC_VERSION=$(jq -r '.version' $(dirname $0)/../package.json)
+
+# Create workspace root Nargo.toml
+cat > Nargo.toml << 'EOF'
+[workspace]
+members = ["contract", "test"]
+EOF
+
+# Create contract crate
+mkdir -p contract/src
+cat > contract/Nargo.toml << CEOF
+[package]
+name = "${package_name}"
+type = "contract"
+
+[dependencies]
+aztec = { git="https://github.com/AztecProtocol/aztec-nr", tag="v${AZTEC_VERSION}", directory="aztec" }
+CEOF
+
+cat > contract/src/main.nr << 'EOF'
+use aztec::macros::aztec;
+
+#[aztec]
+pub contract Main {
+    use aztec::macros::functions::{external, initializer};
+
+    #[initializer]
+    #[external("private")]
+    fn constructor() {}
+}
+EOF
+
+# Create test crate
+mkdir -p test/src
+cat > test/Nargo.toml << TEOF
+[package]
+name = "${package_name}_test"
+type = "lib"
+
+[dependencies]
+aztec = { git="https://github.com/AztecProtocol/aztec-nr", tag="v${AZTEC_VERSION}", directory="aztec" }
+${package_name} = { path = "../contract" }
+TEOF
+
+cat > test/src/lib.nr << 'NOIR'
+use aztec::test::helpers::test_environment::TestEnvironment;
+use __PACKAGE_NAME__::Main;
+
+#[test]
+unconstrained fn test_constructor() {
+    let mut env = TestEnvironment::new();
+    let deployer = env.create_light_account();
+
+    // Deploy the contract with the default constructor:
+    let contract_address = env.deploy("@__PACKAGE_NAME__/Main").with_private_initializer(
+        deployer,
+        Main::interface().constructor(),
+    );
+
+    // Deploy without an initializer:
+    let contract_address = env.deploy("@__PACKAGE_NAME__/Main").without_initializer();
+}
+NOIR
+
+sed -i "s/__PACKAGE_NAME__/${package_name}/g" test/src/lib.nr
+
+# Create README
+cat > README.md << REOF
+# ${package_name}
+
+An Aztec Noir contract project.
+
+## Compile
+
+\`\`\`bash
+aztec compile
+\`\`\`
+
+This compiles the contract in \`contract/\` and outputs artifacts to \`target/\`.
+
+## Test
+
+\`\`\`bash
+aztec test
+\`\`\`
+
+This runs the tests in \`test/\`.
+
+## Generate TypeScript bindings
+
+\`\`\`bash
+aztec codegen target -o src/artifacts
+\`\`\`
+
+This generates TypeScript contract artifacts from the compiled output in \`target/\` into \`src/artifacts/\`.
+REOF
+
+# Create .gitignore
+cat > .gitignore << 'GEOF'
+target/
+codegenCache.json
+GEOF
+
+echo "Created Aztec contract workspace with crates '${package_name}' and '${package_name}_test'"

package/src/bin/index.ts

@@ -14,7 +14,9 @@ import { createConsoleLogger, createLogger } from '@aztec/foundation/log';
 
 import { Command } from 'commander';
 
+import { injectCompileCommand } from '../cli/cmds/compile.js';
 import { injectMigrateCommand } from '../cli/cmds/migrate_ha_db.js';
+import { injectProfileCommand } from '../cli/cmds/profile.js';
 import { injectAztecCommands } from '../cli/index.js';
 import { getCliVersion } from '../cli/release_version.js';
 
@@ -47,7 +49,7 @@ async function main() {
 
   const cliVersion = getCliVersion();
   let program = new Command('aztec');
-  program.description('Aztec command line interface').version(cliVersion);
+  program.description('Aztec command line interface').version(cliVersion).enablePositionalOptions();
   program = injectAztecCommands(program, userLog, debugLogger);
   program = injectBuilderCommands(program);
   program = injectContractCommands(program, userLog, debugLogger);
@@ -56,6 +58,8 @@ async function main() {
   program = injectAztecNodeCommands(program, userLog, debugLogger);
   program = injectMiscCommands(program, userLog);
   program = injectValidatorKeysCommands(program, userLog);
+  program = injectCompileCommand(program, userLog);
+  program = injectProfileCommand(program, userLog);
   program = injectMigrateCommand(program, userLog);
 
   await program.parseAsync(process.argv);

package/src/cli/admin_api_key_store.ts

@@ -0,0 +1,128 @@
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { sha256Hash } from '@aztec/foundation/json-rpc/server';
+import type { Logger } from '@aztec/foundation/log';
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+/** Subdirectory under dataDirectory for admin API key storage. */
+const ADMIN_STORE_DIR = 'admin';
+const HASH_FILE_NAME = 'api_key_hash';
+
+/**
+ * Result of resolving the admin API key.
+ * Contains the SHA-256 hex hash of the API key to be used by the auth middleware,
+ * and optionally the raw key when newly generated (so the caller can display it).
+ */
+export interface AdminApiKeyResolution {
+  /** The SHA-256 hash of the API key. */
+  apiKeyHash: Buffer;
+  /**
+   * The raw API key, only present when a new key was generated during this call.
+   * The caller MUST display this to the operator — it will not be stored or returned again.
+   */
+  rawKey?: string;
+}
+
+export interface ResolveAdminApiKeyOptions {
+  /** SHA-256 hex hash of a pre-generated API key. When set, the node uses this hash directly. */
+  adminApiKeyHash?: string;
+  /** If true, disable admin API key auth entirely. */
+  disableAdminApiKey?: boolean;
+  /** If true, force-generate a new key even if one is already persisted. */
+  resetAdminApiKey?: boolean;
+  /** Root data directory for persistent storage. */
+  dataDirectory?: string;
+}
+
+/**
+ * Resolves the admin API key for the admin RPC endpoint.
+ *
+ * Strategy:
+ * 1. If opt-out flag is set (`disableAdminApiKey`), return undefined (no auth).
+ * 2. If a pre-generated hash is provided (`adminApiKeyHash`), use it directly.
+ * 3. If a data directory exists, look for a persisted hash file
+ *    at `<dataDirectory>/admin/api_key_hash`:
+ *    - If `resetAdminApiKey` is set, skip loading and force-generate a new key.
+ *    - Found: use the stored hash (operator already saved the key from first run).
+ *    - Not found: auto-generate a random key, display it once, persist the hash.
+ * 3. If no data directory: generate a random key
+ *    each run and display it (cannot persist).
+ *
+ * @param options - The options for resolving the admin API key.
+ * @param log - Logger for outputting the key and status messages.
+ * @returns The resolved API key hash, or undefined if auth is disabled.
+ */
+export async function resolveAdminApiKey(
+  options: ResolveAdminApiKeyOptions,
+  log: Logger,
+): Promise<AdminApiKeyResolution | undefined> {
+  // Operator explicitly opted out of admin auth
+  if (options.disableAdminApiKey) {
+    log.warn('Admin API key authentication is DISABLED (--disable-admin-api-key / AZTEC_DISABLE_ADMIN_API_KEY)');
+    return undefined;
+  }
+
+  // Operator provided a pre-generated hash (e.g. via AZTEC_ADMIN_API_KEY_HASH env var)
+  if (options.adminApiKeyHash) {
+    const hex = options.adminApiKeyHash.trim();
+    if (hex.length !== 64 || !/^[0-9a-f]{64}$/.test(hex)) {
+      throw new Error(`Invalid admin API key hash: expected 64-char hex string, got "${hex}"`);
+    }
+    log.info('Admin API key authentication enabled (using pre-configured key hash)');
+    return { apiKeyHash: Buffer.from(hex, 'hex') };
+  }
+
+  // Persistent storage available, load or generate key
+  if (options.dataDirectory) {
+    const adminDir = join(options.dataDirectory, ADMIN_STORE_DIR);
+    const hashFilePath = join(adminDir, HASH_FILE_NAME);
+
+    // Unless a reset is forced, try to load the existing hash from disk
+    if (!options.resetAdminApiKey) {
+      try {
+        const storedHash = (await fs.readFile(hashFilePath, 'utf-8')).trim();
+        if (storedHash.length === 64) {
+          log.info('Admin API key authentication enabled (loaded stored key hash from disk)');
+          return { apiKeyHash: Buffer.from(storedHash, 'hex') };
+        }
+        log.warn(`Invalid stored admin API key hash at ${hashFilePath}, regenerating...`);
+      } catch (err: any) {
+        if (err.code !== 'ENOENT') {
+          log.warn(`Failed to read admin API key hash from ${hashFilePath}: ${err.message}`);
+        }
+        // File doesn't exist — fall through to generate
+      }
+    } else {
+      log.warn('Admin API key reset requested — generating a new key');
+    }
+
+    // Generate a new key, persist the hash, and return the raw key for the caller to display
+    const { rawKey, hash } = generateApiKey();
+    await fs.mkdir(adminDir, { recursive: true });
+    await fs.writeFile(hashFilePath, hash.toString('hex'), 'utf-8');
+    // Set restrictive permissions (owner read/write only)
+    await fs.chmod(hashFilePath, 0o600);
+
+    log.info('Admin API key authentication enabled (new key generated and hash persisted to disk)');
+    return { apiKeyHash: hash, rawKey };
+  }
+
+  // No data directory, generate a temporary key per session
+  const { rawKey, hash } = generateApiKey();
+
+  log.warn('No data directory configured — admin API key cannot be persisted.');
+  log.warn('A temporary key has been generated for this session only.');
+
+  return { apiKeyHash: hash, rawKey };
+}
+
+/**
+ * Generates a cryptographically random API key and its SHA-256 hash.
+ * @returns The raw key (hex string) and its SHA-256 hash as a Buffer.
+ */
+function generateApiKey(): { rawKey: string; hash: Buffer } {
+  const rawKey = randomBytes(32).toString('hex');
+  const hash = sha256Hash(rawKey);
+  return { rawKey, hash };
+}