neon 2.43.0 → 2.44.0

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/auth_context.js

@@ -1,16 +1,61 @@
+import { isOwnedCredentialPath } from "./config.js";
 let current = null;
 export const setAuthContext = (context) => {
     current = context;
 };
 export const getAuthContext = () => current;
+/** Reset between tests, so one case cannot observe another's authentication. */
+export const clearAuthContext = () => {
+    current = null;
+};
 /**
- * The config directory whose credentials a 401 should clear, or `null` to leave
- * stored credentials alone.
+ * The credentials file a 401 should delete, or `null` to leave everything on disk.
+ *
+ * Only an expired OAuth token set is worth clearing: deleting it makes the next command log
+ * in again, which is the recovery. Neither key-shaped source is.
  *
- * An API key passed on the command line never touches the stored OAuth token,
- * so a 401 on that key says nothing about whether the stored credentials are
- * still good — clearing them would sign the user out of an account the failed
- * request never used. The directory comes from the context rather than the
- * default so that `--config-dir` isolates the deletion too.
+ * A key passed on the command line was never ours to store, so a 401 on it says nothing about
+ * any stored credential — clearing one would sign the user out of an account the failed
+ * request never used.
+ *
+ * A key read from a profile must survive for a sharper reason: unlike an OAuth token there is
+ * nothing to refresh and no automatic way back, so deleting it would destroy the only copy of
+ * a credential the user has to paste or mint again. It is also the expected state during
+ * rotation, where the whole point is that the old key is dead and the file must still be there
+ * to be replaced.
  */
-export const credentialsToClearOn401 = (context) => context?.source === "stored-credentials" ? context.configDir : null;
+export const credentialsToClearOn401 = (context) => {
+    if (context?.source !== "stored-credentials")
+        return null;
+    const path = context.credentialsPath;
+    if (path === undefined)
+        return null;
+    // Only a file the CLI created. A profile entry may point anywhere, and a credentials file
+    // we merely adopted is not ours to delete — `neon profile remove` already refuses to touch
+    // one, so a 401 must not quietly do what an explicit removal declines to.
+    //
+    // The legacy `neonctl` directory counts as ours: default resolution deliberately still
+    // reads it in place, so an install predating the rename would otherwise have its own
+    // credentials called "adopted" and never cleared.
+    return isOwnedCredentialPath(context.configDir, path) ? path : null;
+};
+/**
+ * What to tell the user when the API rejects their credential, naming the profile and file
+ * when one is involved so they know which of several accounts failed and what to re-run.
+ */
+export const authFailureMessage = (context) => {
+    const profile = context?.profile ?? "the selected profile";
+    const where = context?.credentialsPath !== undefined
+        ? ` (${context.credentialsPath})`
+        : "";
+    if (context?.source === "profile-api-key") {
+        // Not `rotate-key`: a rejected key cannot authenticate to mint its own replacement.
+        return `Authentication failed: the Neon API rejected profile "${profile}"'s API key${where}. Replace it with \`neon profile create ${profile} --mint --force\`, or store another with \`neon profile create ${profile} --api-key - --force\`.`;
+    }
+    // Reached only when the session was not ours to clear, i.e. an adopted credentials file.
+    // Saying "check --api-key" there would be nonsense; the fix is to sign in again.
+    if (context?.source === "stored-credentials") {
+        return `Authentication failed: the Neon API rejected profile "${profile}"'s stored session${where}. That file was not created by neon, so it was left alone — sign in again with \`neon auth --profile ${profile}\`.`;
+    }
+    return "Authentication failed: the Neon API rejected the API key. Check --api-key or NEON_API_KEY.";
+};

package/dist/commands/api_keys.js

@@ -1,5 +1,6 @@
 import { isNeonApiError } from "../api.js";
 import { log } from "../log.js";
+import { noPassthrough, single } from "../utils/flags.js";
 import { writer } from "../writer.js";
 const ACCOUNT_FIELDS = [
     "id",
@@ -43,55 +44,6 @@ const ALL_PROJECTS = "(all projects)";
  * its correctly-scoped key rejected and revoked.
  */
 const NO_PROJECT = Symbol("no-project");
-/**
- * A flag is either absent, or exactly one non-empty string. Anything else is an error.
- *
- * Every rejected shape otherwise ends the same way: the flag reads as falsy, the scope check
- * falls through, and an **account** key is minted instead of the narrow one asked for — the
- * worst thing this command can do, so none of them get a lenient reading.
- *
- * - `--project-id ""` — an unset shell variable; empty string, which is falsy.
- * - `--no-project-id` — yargs boolean negation; `false`, which is falsy.
- * - `--project-id a --project-id b` — an array, which would reach the API as `a,b`.
- *
- * A misspelled flag never binds and cannot be seen here; `.strict()` rejects it. Anything
- * after a `--` terminator is handled by {@link noPassthrough}.
- */
-const single = (name, { required = false } = {}) => (value) => {
-    if (value === undefined)
-        return undefined;
-    if (Array.isArray(value)) {
-        throw new Error(`--${name} was given more than once. Pass it at most once.`);
-    }
-    // `--no-x` is the negation form and yields `false`, so name it rather than telling
-    // the user their value was empty when they never gave one.
-    if (value === false) {
-        throw new Error(required
-            ? `--no-${name} is not valid: --${name} is required.`
-            : `--no-${name} is not a valid way to skip --${name}. Omit the flag entirely.`);
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        throw new Error(required
-            ? `--${name} needs a value.`
-            : `--${name} needs a value. Pass one, or omit the flag entirely.`);
-    }
-    return value;
-};
-/**
- * Refuse arguments after a `--` terminator.
- *
- * The CLI sets `populate--`, so everything past `--` lands in `argv["--"]` where `.strict()`
- * never looks — `create --name x -- --project-id p` would parse cleanly and mint an account
- * key from a line that names the scope flag. No `api-keys` subcommand takes passthrough
- * arguments, so their presence is always a mistake.
- */
-const noPassthrough = (argv) => {
-    const rest = argv["--"];
-    if (Array.isArray(rest) && rest.length > 0) {
-        throw new Error(`api-keys takes no arguments after \`--\`, and options placed there are ignored rather than applied. Remove the \`--\`.`);
-    }
-    return true;
-};
 export const command = "api-keys";
 export const aliases = ["api-key"];
 export const describe = "Manage API keys";
@@ -106,7 +58,7 @@ export const builder = (argv) => argv
     },
 })
     .strict()
-    .check(noPassthrough), async (args) => await list(args))
+    .check(noPassthrough("api-keys")), async (args) => await list(args))
     .command("create", "Create an API key. The key is shown once and cannot be retrieved again", (yargs) => yargs
     .options({
     name: {
@@ -131,7 +83,7 @@ export const builder = (argv) => argv
     // the project and cannot be chosen independently.
     .conflicts("org-id", "project-id")
     .strict()
-    .check(noPassthrough), async (args) => await create(args))
+    .check(noPassthrough("api-keys")), async (args) => await create(args))
     .command("revoke <id>", "Revoke an API key. Anything using it stops working immediately", (yargs) => yargs
     .positional("id", {
     describe: "The API key id, from `api-keys list`",
@@ -165,7 +117,7 @@ export const builder = (argv) => argv
     },
 })
     .strict()
-    .check(noPassthrough), async (args) => await revoke(args))
+    .check(noPassthrough("api-keys")), async (args) => await revoke(args))
     .demandCommand(1, "Run `neon api-keys --help` to see the subcommands.");
 export const handler = (args) => args;
 const list = async (props) => {
@@ -237,7 +189,7 @@ const create = async (props) => {
     // Project-scoped keys exist only on the organization endpoint, so an org is required.
     // Resolve it from the project rather than asking for both: `--project-id` alone would
     // otherwise fail for a reason that isn't visible from the command line.
-    const resolvedOrgId = await orgIdForProject(props, scopeTo);
+    const resolvedOrgId = await orgIdForProject(props.apiClient, scopeTo);
     const { data } = await props.apiClient.createOrgApiKey(resolvedOrgId, {
         key_name: name,
         project_id: scopeTo,
@@ -376,10 +328,10 @@ const revoke = async (props) => {
  * scoped key — the endpoint that accepts `project_id` is org-only — so that case fails here
  * with the reason, rather than as a 404 from a URL the user never typed.
  */
-const orgIdForProject = async (props, projectId) => {
+export const orgIdForProject = async (client, projectId) => {
     let orgId;
     try {
-        const { data: { project }, } = await props.apiClient.getProject(projectId);
+        const { data: { project }, } = await client.getProject(projectId);
         orgId = project.org_id;
     }
     catch (err) {
@@ -391,7 +343,7 @@ const orgIdForProject = async (props, projectId) => {
         throw err;
     }
     if (!orgId) {
-        throw new Error(`Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Create an account key by omitting --project-id.`);
+        throw new Error(`Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Omit --project-id to create an account key.`);
     }
     return orgId;
 };