neon 2.42.0 → 2.44.0

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

@@ -0,0 +1,349 @@
+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",
+    "name",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+/**
+ * Table view of an org listing. `project` is the rendered column; the raw `project_id` is
+ * what structured output keeps. See {@link list} for why the two differ.
+ */
+const ORG_TABLE_FIELDS = [
+    "id",
+    "name",
+    "project",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+const ORG_FIELDS = [
+    "id",
+    "name",
+    "project_id",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+const CREATE_FIELDS = ["id", "name", "key"];
+/** Metadata only: the secret is printed separately so it can be copied cleanly. */
+const CREATE_TABLE_FIELDS = ["id", "name"];
+const CREATE_TABLE_FIELDS_SCOPED = ["id", "name", "project"];
+const CREATE_FIELDS_SCOPED = ["id", "name", "project_id", "key"];
+/** Rendered for an org key that was not narrowed to a project. Table output only. */
+const ALL_PROJECTS = "(all projects)";
+/**
+ * "This key should carry no project scope."
+ *
+ * A symbol rather than a string, because project ids are `^[a-z0-9-]{1,60}$` — any sentinel
+ * spelled as a string is a legal project id, and a project genuinely called that would have
+ * its correctly-scoped key rejected and revoked.
+ */
+const NO_PROJECT = Symbol("no-project");
+export const command = "api-keys";
+export const aliases = ["api-key"];
+export const describe = "Manage API keys";
+export const builder = (argv) => argv
+    .usage("$0 api-keys <sub-command> [options]")
+    .command("list", "List API keys for your account, or for an organization", (yargs) => yargs
+    .options({
+    "org-id": {
+        describe: "List the organization's keys instead of your account's",
+        type: "string",
+        coerce: single("org-id"),
+    },
+})
+    .strict()
+    .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: {
+        describe: "A name to identify the key later",
+        type: "string",
+        demandOption: true,
+        coerce: single("name", { required: true }),
+    },
+    "org-id": {
+        describe: "Create a key for this organization instead of your account",
+        type: "string",
+        coerce: single("org-id"),
+    },
+    "project-id": {
+        describe: "Create a key that can access only this project. Its organization is looked up from the project",
+        type: "string",
+        coerce: single("project-id"),
+    },
+})
+    // A key scoped to a project is already an organization key, so naming
+    // both is contradictory rather than redundant — the org is derived from
+    // the project and cannot be chosen independently.
+    .conflicts("org-id", "project-id")
+    .strict()
+    .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`",
+    // Deliberately not `type: "number"`. That coerces before `coerce`
+    // runs, so an unparseable id arrives as NaN and the error can only
+    // echo `NaN` — a JavaScript artifact the user never typed. Taking
+    // the raw string lets the message name what they actually passed,
+    // and stops NaN reaching the API, which answers "not found" and
+    // blames the key rather than the input.
+    type: "string",
+    demandOption: true,
+    coerce: (value) => {
+        // Digits only, checked before Number(): `Number("0x65")` is 101
+        // and `Number("1e3")` is 1000, so either would revoke a key the
+        // user never named while the message promises "a numeric id".
+        const id = Number(value);
+        if (typeof value !== "string" ||
+            !/^\d+$/.test(value.trim()) ||
+            !Number.isSafeInteger(id) ||
+            id <= 0) {
+            throw new Error(`api-keys revoke needs a numeric key id, from \`neon api-keys list\`. Got \`${String(value)}\`.`);
+        }
+        return id;
+    },
+})
+    .options({
+    "org-id": {
+        describe: "Revoke an organization key instead of an account key",
+        type: "string",
+        coerce: single("org-id"),
+    },
+})
+    .strict()
+    .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) => {
+    const out = writer(props);
+    if (props.orgId) {
+        const { data } = await props.apiClient.listOrgApiKeys(props.orgId);
+        // `writeTable` drops any column empty in every row, so an all-absent `project_id`
+        // would take the whole column with it — hiding the answer exactly when it is "none
+        // of them are scoped". Fill it in for the table, but leave structured output alone:
+        // json/yaml serialize the whole object, so a synthetic field there would change the
+        // machine-readable shape and duplicate `project_id` under a second name.
+        if (props.output === "table") {
+            out.write(data.map((key) => ({
+                ...key,
+                project: key.project_id ?? ALL_PROJECTS,
+            })), {
+                fields: ORG_TABLE_FIELDS,
+                title: `API keys in ${props.orgId}`,
+                emptyMessage: `No API keys in ${props.orgId}.`,
+            });
+        }
+        else {
+            out.write(data, {
+                fields: ORG_FIELDS,
+                title: `API keys in ${props.orgId}`,
+                emptyMessage: `No API keys in ${props.orgId}.`,
+            });
+        }
+        out.end();
+        return;
+    }
+    const { data } = await props.apiClient.listApiKeys();
+    out.write(data, {
+        fields: ACCOUNT_FIELDS,
+        title: "Account API keys",
+        emptyMessage: "You have no account API keys.",
+    });
+    out.end();
+    // Organization keys live on a different endpoint, so a heading of plain "API keys"
+    // would claim to be everything while showing only half.
+    if (props.output === "table") {
+        log.info("Organization keys are listed separately: neon api-keys list --org-id <org> (see `neon orgs list`).");
+    }
+};
+const create = async (props) => {
+    const { name, projectId, orgId } = props;
+    // Neither flag: an account key, matching `POST /api_keys`. `api-keys` is exempt from
+    // `.neon` enrichment (see `isApiKeysCommand`), so reaching this branch means the user
+    // really did ask for account scope rather than inheriting a checked-out project.
+    if (!projectId && !orgId) {
+        const { data } = await props.apiClient.createApiKey({ key_name: name });
+        await assertUsable(props, data, { orgId: null, expect: NO_PROJECT });
+        report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+        // The only key here that reaches everything, and the only one that used to say
+        // nothing about its reach.
+        log.warning("This key reaches everything your account can, in every organization. Pass --org-id or --project-id to narrow it.");
+        return;
+    }
+    if (!projectId && orgId) {
+        const { data } = await props.apiClient.createOrgApiKey(orgId, {
+            key_name: name,
+        });
+        await assertUsable(props, data, { orgId, expect: NO_PROJECT });
+        report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+        log.warning("This key reaches every project in %s, including ones created later. Pass --project-id instead to restrict it to one.", orgId);
+        return;
+    }
+    const scopeTo = projectId;
+    // 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.apiClient, scopeTo);
+    const { data } = await props.apiClient.createOrgApiKey(resolvedOrgId, {
+        key_name: name,
+        project_id: scopeTo,
+    });
+    // `project_id` is optional on the response. Printing a key and calling it scoped
+    // without checking would hand over a credential whose reach we never confirmed — the
+    // one thing this command must not get wrong.
+    await assertUsable(props, data, {
+        orgId: resolvedOrgId,
+        expect: scopeTo,
+    });
+    report(props, data, CREATE_FIELDS_SCOPED, CREATE_TABLE_FIELDS_SCOPED);
+    log.info("Limited to %s: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.", scopeTo);
+};
+/**
+ * Print the issued key.
+ *
+ * In a terminal the secret goes on its own line rather than into a table cell: `cli-table`
+ * neither wraps nor truncates, so a 50-odd character key makes the row wider than most
+ * terminals and the wrapped remainder ends up beside box-drawing characters. Since this is
+ * the only time the key is ever shown, it has to be selectable in one gesture. Structured
+ * output keeps the key in the object, where a script expects it.
+ */
+const report = (props, data, fields, tableFields) => {
+    const out = writer(props);
+    if (props.output === "table") {
+        // `project` mirrors the column name `list` uses. Added here rather than by the
+        // caller so structured output keeps the API's own `project_id` and gains no
+        // duplicate under a second name.
+        const row = typeof data.project_id === "string"
+            ? { ...data, project: data.project_id }
+            : data;
+        out.write(row, {
+            fields: tableFields,
+            title: "API key",
+        });
+        out.end();
+        // Blank line so the key is visually detached from the table border, and so
+        // `| tail -1` on stdout yields exactly the key (both notices go to stderr).
+        out.text(`\n${data.key}\n`);
+    }
+    else {
+        out.write(data, { fields: fields, title: "API key" });
+        out.end();
+    }
+    log.warning("Store this key now: it is not shown again.");
+};
+/**
+ * Refuse to report a key that isn't what we asked for, and take it back.
+ *
+ * Two ways a 2xx can still be wrong: no `key` in the body, which leaves a live credential
+ * the user can never see or use; and a `project_id` that doesn't match the requested
+ * project, which would mean announcing a scope the key does not have. Both withdraw the key
+ * before throwing.
+ *
+ * The thrown message states whether the withdrawal actually succeeded. Saying "the key has
+ * been revoked" when the revoke itself failed would be worse than saying nothing — it would
+ * leave an unverified credential live while telling the user it is gone.
+ */
+const assertUsable = async (props, data, scope) => {
+    // `expect` is always stated, never inferred from a missing field: "no project" has to be
+    // checked as deliberately as an exact project, or a key that came back narrower than
+    // requested would be reported as reaching the whole organization.
+    const wanted = scope.expect === NO_PROJECT ? undefined : scope.expect;
+    const problem = typeof data.key !== "string" || data.key.trim() === ""
+        ? "Neon returned no key."
+        : data.project_id !== wanted
+            ? `Neon returned a key scoped to ${data.project_id ?? "nothing"} rather than ${wanted ?? "the whole organization"}.`
+            : null;
+    if (!problem)
+        return;
+    const withdrawn = await withdraw(props, scope.orgId, data.id);
+    throw new Error(`${problem} ${withdrawn
+        ? "The key has been revoked; nothing was issued."
+        : `The key could NOT be revoked and may still be live${data.id === undefined
+            ? ""
+            : `. Remove it with \`neon api-keys revoke ${data.id}${scope.orgId
+                ? ` --org-id ${scope.orgId}`
+                : ""}\``}.`}`);
+};
+/**
+ * Revoke, turning the most likely mistake into a usable message.
+ *
+ * Account and organization keys live on different endpoints, and `api-keys list --org-id X`
+ * shows ids that the account endpoint cannot see. Copying one and forgetting the flag — or
+ * leaving it on for an account key — is the easy error, and a bare "API key not found" sends
+ * the user looking for a deleted key rather than a misplaced flag.
+ *
+ * Only the key id is worth second-guessing here: an org id that is wrong or not yours does
+ * not reach this path at all, because the API answers "not an organization member" (verified
+ * against production) rather than a 404.
+ */
+const revokeOrExplain = async (props) => {
+    try {
+        return props.orgId
+            ? await props.apiClient.revokeOrgApiKey(props.orgId, props.id)
+            : await props.apiClient.revokeApiKey(props.id);
+    }
+    catch (err) {
+        if (isNeonApiError(err) && err.status === 404) {
+            throw new Error(props.orgId
+                ? `No API key with id ${props.id} in ${props.orgId}. If it is one of your account's own keys, drop --org-id.`
+                : `No account API key with id ${props.id}. If it belongs to an organization, pass --org-id. Organization keys are not visible to your account.`);
+        }
+        throw err;
+    }
+};
+/** Best-effort withdrawal of a key we are refusing to report. Never throws. */
+const withdraw = async (props, orgId, keyId) => {
+    if (!Number.isSafeInteger(keyId) || keyId <= 0)
+        return false;
+    try {
+        const { data } = orgId
+            ? await props.apiClient.revokeOrgApiKey(orgId, keyId)
+            : await props.apiClient.revokeApiKey(keyId);
+        // Check which key the response names: a `revoked: true` for some other id is not
+        // evidence that the one we issued is gone.
+        return data.revoked === true && data.id === keyId;
+    }
+    catch (err) {
+        log.error("Failed to revoke API key %d: %s", keyId, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+};
+const revoke = async (props) => {
+    const out = writer(props);
+    const { data } = await revokeOrExplain(props);
+    out.write(data, {
+        fields: ["id", "name", "revoked", "last_used_at"],
+        title: "API key",
+    });
+    out.end();
+};
+/**
+ * The organization a project belongs to. A project outside any organization cannot have a
+ * 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.
+ */
+export const orgIdForProject = async (client, projectId) => {
+    let orgId;
+    try {
+        const { data: { project }, } = await client.getProject(projectId);
+        orgId = project.org_id;
+    }
+    catch (err) {
+        if (isNeonApiError(err) && err.status === 404) {
+            throw new Error(projectId.startsWith("org-")
+                ? `Project ${projectId} not found. That looks like an organization id. Pass it as --org-id instead.`
+                : `Project ${projectId} not found. Check the id with \`neon projects list\`.`);
+        }
+        throw err;
+    }
+    if (!orgId) {
+        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;
+};