neon 2.42.0 → 2.44.0

package/dist/_shared/paths.js

@@ -0,0 +1,149 @@
+/**
+ * # Where the Neon CLIs keep their files on disk
+ *
+ **Deliberately impure.** It reads environment variables and touches the filesystem, which
+ * `@neon/config` — the package this used to be a subpath of — must never do from its root
+ * export. It lives here instead of there precisely so that a policy-facing package does not
+ * carry implementor-only code, and so `neon-init`, which has no workspace dependencies, can use
+ * the same resolution as everything else.
+ *
+ * It exists because three separate readers each grew their own answer to "where is the
+ * config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
+ * not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and
+ * `packages/init` hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+ * credentials somewhere the other two never looked.
+ *
+ * ## The directory
+ *
+ * `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,
+ * each entry winning over the next:
+ *
+ * 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.
+ * 2. `NEON_CONFIG_DIR` — exact.
+ * 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.
+ * 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.
+ *
+ * An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that
+ * quietly read `~/.config/neonctl` would defeat the point of passing it.
+ *
+ * ## The files
+ *
+ * {@link resolveConfigFile} answers "which path should I use for this file", and it is the
+ * same answer for reading and writing:
+ *
+ * - Present in `neon/` → use it.
+ * - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is
+ *   never copied or moved, so nothing is left behind to go stale and no other tool starts
+ *   reading an abandoned token.
+ * - Present in neither → the new location. New files only ever appear under `neon/`.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Current directory name. New files are created here. */
+export const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+export const LEGACY_CONFIG_DIR_NAME = "neonctl";
+/** Where files are created. See the module docs for the precedence. */
+export function configDir(options = {}) {
+    const explicit = explicitDir(options);
+    if (explicit)
+        return explicit;
+    return join(configHome(options.env ?? process.env), CONFIG_DIR_NAME);
+}
+/**
+ * The legacy directory, or `undefined` when the location was chosen explicitly (in which
+ * case there is no legacy counterpart to fall back to).
+ */
+export function legacyConfigDir(options = {}) {
+    if (explicitDir(options))
+        return undefined;
+    return join(configHome(options.env ?? process.env), LEGACY_CONFIG_DIR_NAME);
+}
+/**
+ * Resolve one file inside the config directory. Prefers the current location, falls back to
+ * an existing legacy file **in place**, and otherwise points at the current location so new
+ * files are created there.
+ */
+export function resolveConfigFile(fileName, options = {}) {
+    const dir = configDir(options);
+    const current = resolve(dir, fileName);
+    if (existsSync(current))
+        return { path: current, dir, isLegacy: false, exists: true };
+    const legacyDir = legacyConfigDir(options);
+    if (legacyDir) {
+        const legacy = resolve(legacyDir, fileName);
+        if (existsSync(legacy))
+            return {
+                path: legacy,
+                dir: legacyDir,
+                isLegacy: true,
+                exists: true,
+            };
+    }
+    return { path: current, dir, isLegacy: false, exists: false };
+}
+/** `$XDG_CONFIG_HOME`, else `<home>/.config`. Falls back to a relative `.config` with no home. */
+function configHome(env) {
+    const xdg = nonEmpty(env.XDG_CONFIG_HOME);
+    if (xdg)
+        return xdg;
+    const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+    return home ? join(home, ".config") : ".config";
+}
+function explicitDir(options) {
+    const env = options.env ?? process.env;
+    return (nonEmpty(options.dir) ??
+        nonEmpty(env.NEON_CONFIG_DIR) ??
+        nonEmpty(env.NEONCTL_CONFIG_DIR));
+}
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export const CREDENTIALS_FILE = "credentials.json";
+/**
+ * Default for `--config-dir`: `$XDG_CONFIG_HOME/neon`, else `~/.config/neon`.
+ *
+ * The directory was called `neonctl` until the CLI was renamed. An existing one is still read —
+ * see {@link credentialsPath} — but it is never written to, moved, or deleted.
+ */
+export const defaultDir = configDir();
+/**
+ * Where this invocation's `credentials.json` lives.
+ *
+ * When `--config-dir` was left at its default, an existing file in the legacy `neonctl`
+ * directory is used **in place**: an install that predates the rename keeps working, and its
+ * credentials are never duplicated into a second location where one copy could go stale while
+ * another tool still reads it.
+ *
+ * A `--config-dir` the user actually passed is used exactly as given. Falling back out of an
+ * explicitly chosen directory would defeat the reason for choosing it — a CI run pointed at a
+ * scratch directory must never pick up a developer's real credentials.
+ */
+export const credentialsPath = (dir) => resolveConfigFile(CREDENTIALS_FILE, dir === defaultDir ? {} : { dir }).path;
+/**
+ * Whether a credentials file is one the CLI created, rather than a path a profile adopted.
+ *
+ * Anything that deletes a credential has to ask this first. A profile entry may point anywhere —
+ * that is what makes adopting an existing directory a one-line edit — and a file we did not
+ * create is not ours to remove.
+ */
+export const isInsideConfigDir = (configDirectory, file) => `${resolve(file)}/`.startsWith(`${resolve(configDirectory)}/`);
+/**
+ * Whether a credentials file is one the CLI owns, counting the legacy `neonctl` directory.
+ *
+ * {@link credentialsPath} deliberately reads an existing legacy file in place rather than
+ * migrating it, so for a default config directory that file is ours even though it sits outside
+ * `neon/`. Judging ownership on the current directory alone would call an install that predates
+ * the rename "adopted".
+ */
+export const isOwnedCredentialPath = (configDirectory, file) => {
+    if (isInsideConfigDir(configDirectory, file))
+        return true;
+    if (configDirectory !== defaultDir)
+        return false;
+    const legacy = legacyConfigDir();
+    return legacy !== undefined && isInsideConfigDir(legacy, file);
+};

package/dist/{profiles.js → _shared/profiles.js}

@@ -37,14 +37,13 @@
  *
  * An install with no `profiles.json` is already a valid `DEFAULT`-only state: `DEFAULT`
  * resolves to `credentials.json` in the config directory (including an existing one in the
- * legacy `neonctl` directory — see `@neon/config/paths`). Nothing is created until a second
+ * legacy `neonctl` directory — see `./paths.ts`). Nothing is created until a second
  * profile is, and nothing is ever moved.
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-import { resolveConfigFile } from "@neon/config/paths";
-import { credentialsPath, defaultDir } from "./config.js";
-import { log } from "./log.js";
+import { credentialsPath, defaultDir, resolveConfigFile } from "./paths.js";
+import { writeSecretFile } from "./secure_file.js";
 export const PROFILES_FILE = "profiles.json";
 /** The implicit profile. Backed by plain `credentials.json`, with or without a profiles file. */
 export const DEFAULT_PROFILE = "DEFAULT";
@@ -60,36 +59,106 @@ export const assertValidProfileName = (name) => {
 /** Where `profiles.json` lives for this config directory (whether or not it exists yet). */
 export const profilesFilePath = (dir) => resolveConfigFile(PROFILES_FILE, dir === defaultDir ? {} : { dir }).path;
 /**
- * Read `profiles.json`, or `null` when there isn't one — the normal single-account state.
- * A malformed file is reported and treated as absent rather than breaking every command;
- * the worst case is that a named profile is "not found", which is recoverable, whereas
- * throwing here would lock the user out of `neon auth` itself.
+ * Read and classify `profiles.json` without deciding what to do about it.
+ *
+ * Entry keys and shapes are validated here rather than at each use. A key is a profile name,
+ * and a name that `assertValidProfileName` would reject cannot have been written by this CLI —
+ * it would travel into error messages as a recovery command nobody can run, and into a
+ * `credentials.<name>.json` filename.
  */
-export const readProfiles = (dir) => {
+export const inspectProfiles = (dir) => {
     const path = profilesFilePath(dir);
     if (!existsSync(path))
-        return null;
+        return { kind: "absent" };
+    const broken = (why) => ({
+        kind: "unusable",
+        reason: `${path} could not be read as a profiles file: ${why}`,
+    });
+    // Reading and parsing are separate failures with separate answers. Sharing one catch
+    // reported `EACCES` as "not valid JSON", which sends the user to edit a file that is
+    // perfectly valid and that they cannot open.
+    let contents;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed === null ||
-            typeof parsed !== "object" ||
-            Array.isArray(parsed))
-            throw new Error("not an object");
-        const profiles = parsed.profiles;
-        if (profiles === null ||
-            typeof profiles !== "object" ||
-            Array.isArray(profiles))
-            throw new Error("missing `profiles`");
-        return { version: 1, profiles };
+        contents = readFileSync(path, "utf8");
     }
     catch (err) {
-        log.warning("Ignoring malformed %s: %s", path, err instanceof Error ? err.message : String(err));
-        return null;
+        const code = err.code;
+        return broken(code ? `reading it failed with ${code}` : "reading it failed");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        return broken("it is not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return broken("it does not contain an object");
+    const profiles = parsed.profiles;
+    if (profiles === null ||
+        typeof profiles !== "object" ||
+        Array.isArray(profiles))
+        return broken("it has no `profiles` object");
+    for (const [name, entry] of Object.entries(profiles)) {
+        if (!NAME_PATTERN.test(name))
+            return broken(`"${name}" is not a valid profile name`);
+        if (entry === null ||
+            typeof entry !== "object" ||
+            typeof entry.credentials !== "string" ||
+            entry.credentials.trim() === "") {
+            return broken(`profile "${name}" has no \`credentials\` path`);
+        }
+    }
+    return { kind: "ok", file: { version: 1, profiles } };
+};
+/**
+ * Read `profiles.json`, or `null` when there is nothing usable there.
+ *
+ * A malformed file is reported through `onWarn` and treated as absent, because for a *read* the
+ * worst case is a named profile turning up missing, which is recoverable — whereas throwing
+ * would lock the user out of `neon auth` itself. Writing is the opposite: see
+ * {@link upsertProfile}, which refuses rather than rebuilding a file it cannot read.
+ */
+export const readProfiles = (dir, 
+/** Called with the reason a profiles file was ignored. The consumer owns how it reports. */
+onWarn = () => { }) => {
+    const read = inspectProfiles(dir);
+    if (read.kind === "ok")
+        return read.file;
+    if (read.kind === "unusable")
+        onWarn(read.reason);
+    return null;
+};
+/**
+ * Refuse to act on a named profile when the file that defines it cannot be read.
+ *
+ * Call this **before** anything that writes a credential, opens a browser, or spends an API
+ * call. {@link upsertProfile} refuses too, but it runs last: by then `create` has already
+ * overwritten `credentials.<name>.json` and revoked the key it replaced, and `neon auth
+ * --profile` has already signed in over it — a refusal that arrives after the destruction it
+ * exists to prevent. The path resolution itself is the unsound part, since with the metadata
+ * unreadable the conventional filename is a guess about which account that file belongs to.
+ *
+ * `DEFAULT` is exempt: it is defined by the absence of metadata rather than by an entry, so
+ * signing in normally must keep working while a broken `profiles.json` is repaired.
+ */
+export const assertProfilesUsable = (dir, name) => {
+    if (name === DEFAULT_PROFILE)
+        return;
+    const read = inspectProfiles(dir);
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. Fix or delete the file before working with profile "${name}" — it is the only record of where each account's credentials live.`);
     }
 };
 /** Resolve a profile to an absolute credentials path. Throws when a named profile is unknown. */
 export const resolveProfile = (dir, name) => {
-    const file = readProfiles(dir);
+    const read = inspectProfiles(dir);
+    // A broken file must not be reported as `Unknown profile "work"`. That names the wrong
+    // problem, and the user goes looking for a profile they can see in the file in front of them.
+    if (read.kind === "unusable" && name !== DEFAULT_PROFILE) {
+        throw new Error(`${read.reason}. Fix or delete the file — every named profile is defined in it.`);
+    }
+    const file = read.kind === "ok" ? read.file : null;
     const entry = file?.profiles[name];
     if (entry) {
         return {
@@ -112,7 +181,7 @@ export const resolveProfile = (dir, name) => {
     const known = file
         ? Object.keys(file.profiles).join(", ")
         : DEFAULT_PROFILE;
-    throw new Error(`Unknown profile "${name}". Known profiles: ${known}. Create it with \`neon auth --profile ${name}\`.`);
+    throw new Error(`Unknown profile "${name}". Known profiles: ${known}. Create it with \`neon profile create ${name}\`.`);
 };
 /** Default location for a new named profile's credentials file. */
 export const newProfileCredentialsPath = (dir, name) => resolve(dir, `credentials.${name}.json`);
@@ -128,14 +197,24 @@ export const newProfileCredentialsPath = (dir, name) => resolve(dir, `credential
 export const upsertProfile = (dir, name, entry) => {
     assertValidProfileName(name);
     const path = profilesFilePath(dir);
-    const file = readProfiles(dir) ?? {
-        version: 1,
-        profiles: {
-            [DEFAULT_PROFILE]: {
-                credentials: relativeToProfiles(path, credentialsPath(dir)),
+    const read = inspectProfiles(dir);
+    // Refusing is the point. Treating a broken file as absent here rebuilt it from a single
+    // `DEFAULT` entry and dropped every named profile in it — silent data loss, in the file
+    // that is the only record of where each account's credentials live. The credentials
+    // themselves survive, so fixing the file by hand recovers everything.
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. Refusing to rewrite it, because doing so would discard the profiles it defines. Fix or delete the file, then re-run.`);
+    }
+    const file = read.kind === "ok"
+        ? read.file
+        : {
+            version: 1,
+            profiles: {
+                [DEFAULT_PROFILE]: {
+                    credentials: relativeToProfiles(path, credentialsPath(dir)),
+                },
             },
-        },
-    };
+        };
     file.profiles[name] = {
         credentials: relativeToProfiles(path, entry.credentials),
         ...(entry.label ? { label: entry.label } : {}),
@@ -163,7 +242,14 @@ export const onlyDefaultRemains = (file) => {
         (names.length === 1 && names[0] === DEFAULT_PROFILE));
 };
 export const listProfiles = (dir) => {
-    const file = readProfiles(dir);
+    const read = inspectProfiles(dir);
+    // Listing is the command run to find out what is there, so a broken file is the answer
+    // rather than an obstacle. Showing only `DEFAULT` would state, as fact, that the profiles
+    // in that file do not exist.
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. Fix or delete the file — every named profile is defined in it.`);
+    }
+    const file = read.kind === "ok" ? read.file : null;
     if (!file)
         return [resolveProfile(dir, DEFAULT_PROFILE)];
     const names = Object.keys(file.profiles);
@@ -172,7 +258,7 @@ export const listProfiles = (dir) => {
     return names.map((name) => resolveProfile(dir, name));
 };
 const writeProfiles = (path, file) => {
-    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    writeSecretFile(path, `${JSON.stringify(file, null, 2)}\n`);
 };
 const resolveEntryPath = (dir, entry) => isAbsolute(entry) ? entry : resolve(profilesDir(dir), entry);
 /** `profiles.json` may sit in the legacy directory, so entries resolve against its own dir. */

package/dist/_shared/secure_file.js

@@ -0,0 +1,43 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/** Owner read/write. A credential needs those two and nothing else. */
+export const SECRET_FILE_MODE = 0o600;
+/**
+ * Write a secret to disk owner-only, by creating a temporary file in the same directory and
+ * renaming it over the target.
+ *
+ * The rename is what makes this correct rather than merely tidy. `writeFileSync`'s `mode`
+ * applies only when it *creates* the file, so writing over an existing credentials file
+ * leaves whatever permissions it already had — a file created `0700` by an older release
+ * stays `0700` forever, and one created before a umask change stays world-readable. Renaming
+ * a fresh inode into place means every write lands at {@link SECRET_FILE_MODE}, so the
+ * permissions repair themselves instead of being inherited.
+ *
+ * It also closes the window where a reader could see the file at default permissions: the
+ * temporary file is created `0600` *before* it holds the secret's final name, and `rename`
+ * is atomic within a directory, so there is no moment at which the target is readable by
+ * anyone else and no moment at which it is half-written.
+ *
+ * The temporary name carries the pid so two processes writing at once cannot collide on it.
+ */
+export const writeSecretFile = (path, contents) => {
+    const directory = dirname(path);
+    const temporary = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        writeFileSync(temporary, contents, {
+            encoding: "utf8",
+            mode: SECRET_FILE_MODE,
+        });
+        renameSync(temporary, path);
+    }
+    catch (err) {
+        // Never leave the secret behind under a temporary name the caller doesn't know about.
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The temp file was never created, or is already gone. Report the original error.
+        }
+        throw err;
+    }
+};

package/dist/analytics.js

@@ -1,6 +1,7 @@
-import { readFileSync } from "node:fs";
 import { Analytics } from "@segment/analytics-node";
+import { inspectCredentials } from "./_shared/credentials.js";
 import { getApiClient, isNeonApiError } from "./api.js";
+import { getAuthContext } from "./auth_context.js";
 import { credentialsPath } from "./config.js";
 import { isCurrentBranchProbe } from "./context.js";
 import { getGithubEnvVars, isCi } from "./env.js";
@@ -55,14 +56,23 @@ export const analyticsMiddleware = async (args) => {
     if (isCurrentBranchProbe(args)) {
         return;
     }
+    // Read the credentials this invocation actually authenticated with, which `ensureAuth`
+    // recorded. Reading `DEFAULT`'s unconditionally attributed every `--profile`-selected
+    // command to whichever account happened to be the default one.
+    const authenticatedAs = getAuthContext()?.credentialsPath ?? credentialsPath(args.configDir);
+    // Telemetry must never turn a damaged or unreadable credentials file into a failed command.
     try {
-        const credentials = readFileSync(credentialsPath(args.configDir), {
-            encoding: "utf-8",
-        });
-        userId = JSON.parse(credentials).user_id;
+        const read = inspectCredentials(authenticatedAs);
+        if (read.kind === "ok" &&
+            typeof read.credentials.user_id === "string") {
+            userId = read.credentials.user_id;
+        }
+        else if (read.kind !== "ok") {
+            log.debug("No usable credentials at %s", authenticatedAs);
+        }
     }
     catch (err) {
-        log.debug("Failed to read credentials file", err);
+        log.debug("Could not read %s: %s", authenticatedAs, err);
     }
     try {
         if (args.apiKey) {

package/dist/api.js

@@ -111,9 +111,44 @@ function headersToObject(headers) {
     });
     return out;
 }
+/**
+ * Raised by {@link makeTimedFetch} when the CLI's own request timeout fires. Owning the
+ * type is what makes the timeout recognisable further up: `@neon/sdk` reports every
+ * transport failure as a `NeonNetworkError`, so matching on names or codes cannot tell a
+ * timeout from a reset connection.
+ */
+class RequestTimeoutError extends Error {
+    constructor(timeoutMs, reason) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = "RequestTimeoutError";
+        this.reason = reason;
+    }
+}
+/**
+ * Whether a failure was a request timeout rather than a connectivity problem.
+ *
+ * Walks the `cause` chain, because the SDK wraps whatever `fetch` threw. Before this, the
+ * check only looked at the top-level error's `name` — which is `NeonNetworkError` on every
+ * SDK path — so a timeout fell through to the connectivity branch and the user was told to
+ * check an internet connection that was working.
+ */
 function isAbortError(err) {
-    return (err instanceof Error &&
-        (err.name === "AbortError" || err.name === "TimeoutError"));
+    let current = err;
+    for (let depth = 0; depth < 6 && current != null; depth++) {
+        if (current instanceof RequestTimeoutError)
+            return true;
+        if (current instanceof Error &&
+            (current.name === "AbortError" || current.name === "TimeoutError")) {
+            return true;
+        }
+        // `@neon/sdk` classifies its own deadlines and cancellations by kind; the CLI
+        // does not set them today, but reading them keeps this correct if it ever does.
+        const kind = current.kind;
+        if (kind === "timeout" || kind === "aborted")
+            return true;
+        current = current.cause;
+    }
+    return false;
 }
 /**
  * Walk an error's `cause` chain to find the underlying socket/DNS `code` (e.g.
@@ -182,17 +217,53 @@ function networkError(err) {
  * and lightweight debug logging of the request line + response status — the
  * fetch-native replacement for the old `axios-debug-log` wiring.
  */
-const timedFetch = async (input, init) => {
-    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+/**
+ * The largest delay a timer can represent. Above it Node warns
+ * (`TimeoutOverflowWarning`) and fires after 1ms instead.
+ */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Reject a timeout `AbortSignal.timeout` would refuse or silently mistreat.
+ *
+ * Without this the bad value surfaces as the very failure this classification exists to
+ * prevent: `-1`, `NaN`, `Infinity`, fractions and anything above `4294967295` throw
+ * `ERR_OUT_OF_RANGE` from inside the fetch wrapper, which is then wrapped as a
+ * `NeonNetworkError` and reported as a broken internet connection.
+ *
+ * `0`, and the band from {@link MAX_TIMER_MS} + 1 up to `4294967295`, are worse still:
+ * both are accepted, and both make every request time out immediately — `0` by asking for
+ * it, the band because a timer above the signed 32-bit ceiling collapses to 1ms.
+ */
+function validateRequestTimeout(ms) {
+    if (!Number.isInteger(ms) || ms < 1 || ms > MAX_TIMER_MS) {
+        throw new Error(`requestTimeoutMs must be a whole number of milliseconds between 1 and ${MAX_TIMER_MS}; received ${ms}.`);
+    }
+    return ms;
+}
+const makeTimedFetch = (requestTimeoutMs) => async (input, init) => {
+    const timeout = AbortSignal.timeout(requestTimeoutMs);
     const signal = init?.signal
         ? AbortSignal.any([init.signal, timeout])
         : timeout;
     const method = init?.method ?? (input instanceof Request ? input.method : "GET");
     const url = input instanceof Request ? input.url : String(input);
     log.debug("%s %s", method.toUpperCase(), url);
-    const response = await fetch(input, { ...init, signal });
-    log.debug("%d %s", response.status, response.statusText);
-    return response;
+    try {
+        const response = await fetch(input, { ...init, signal });
+        log.debug("%d %s", response.status, response.statusText);
+        return response;
+    }
+    catch (err) {
+        // Our own timeout fired, and we are the only code that knows that: by the
+        // time this reaches `networkError` the SDK has wrapped it as a
+        // `NeonNetworkError`, and neither its name nor its `cause` chain carries a
+        // string code to recognise. Raise something we own instead of leaving the
+        // classification to guess.
+        if (timeout.aborted && !init?.signal?.aborted) {
+            throw new RequestTimeoutError(requestTimeoutMs, err);
+        }
+        throw err;
+    }
 };
 const RETRY_COUNT = 5;
 const RETRY_DELAY = 3000;
@@ -246,12 +317,15 @@ async function readJsonBody(response) {
         return text;
     }
 }
-export const getApiClient = ({ apiKey, apiHost }) => {
+export const getApiClient = ({ apiKey, apiHost, requestTimeoutMs = REQUEST_TIMEOUT_MS, }) => {
     const baseUrl = apiHost ?? DEFAULT_API_HOST;
+    // Shared by the generated client and the low-level `request()` escape hatch, so both
+    // paths get the same timeout and the same timeout classification.
+    const fetchWithTimeout = makeTimedFetch(validateRequestTimeout(requestTimeoutMs));
     const client = createClient(createConfig({
         auth: () => apiKey,
         baseUrl,
-        fetch: timedFetch,
+        fetch: fetchWithTimeout,
         headers: { "User-Agent": USER_AGENT },
     }));
     /** Await a raw call, unwrap to a `{ data, status, headers }` envelope, or throw {@link NeonApiError}. */
@@ -306,7 +380,7 @@ export const getApiClient = ({ apiKey, apiHost }) => {
         }
         let response;
         try {
-            response = await timedFetch(url, {
+            response = await fetchWithTimeout(url, {
                 method: params.method,
                 headers,
                 ...(payload !== undefined ? { body: payload } : {}),
@@ -346,6 +420,20 @@ export const getApiClient = ({ apiKey, apiHost }) => {
         getCurrentUserOrganizations: () => call(() => raw.getCurrentUserOrganizations({ client })),
         getAuthDetails: () => call(() => raw.getAuthDetails({ client })),
         getActiveRegions: () => call(() => raw.getActiveRegions({ client })),
+        // ─── API keys ────────────────────────────────────────────────────────
+        // Account keys reach everything the account can. Org keys can additionally be
+        // narrowed to a single project via `project_id`, which is the only way to mint a
+        // least-privilege credential — so the org endpoints are not merely the org
+        // equivalent of the account ones.
+        listApiKeys: () => call(() => raw.listApiKeys({ client })),
+        createApiKey: (body) => call(() => raw.createApiKey({ client, body })),
+        revokeApiKey: (keyId) => call(() => raw.revokeApiKey({ client, path: { key_id: keyId } })),
+        listOrgApiKeys: (orgId) => call(() => raw.listOrgApiKeys({ client, path: { org_id: orgId } })),
+        createOrgApiKey: (orgId, body) => call(() => raw.createOrgApiKey({ client, path: { org_id: orgId }, body })),
+        revokeOrgApiKey: (orgId, keyId) => call(() => raw.revokeOrgApiKey({
+            client,
+            path: { org_id: orgId, key_id: keyId },
+        })),
         // ─── Projects ────────────────────────────────────────────────────────
         listProjects: (query = {}) => call(() => raw.listProjects({ client, query })),
         listSharedProjects: (query = {}) => call(() => raw.listSharedProjects({