neon 2.42.0 → 2.44.0

package/README.md

@@ -644,12 +644,12 @@ The CLI holds one Neon account by default. A profile adds another, and is nothin
 ```
 ~/.config/neon/
 ├── credentials.json          # this IS the DEFAULT profile
-├── credentials.work.json     # created by `neon auth --profile work`
+├── credentials.work.json     # created by `neon profile create work`
 └── profiles.json             # created only once a second profile exists
 ```
 
 ```bash
-neon auth --profile work     # create it, or sign in again
+neon profile create work     # a browser sign-in, or an API key — see below
 neon profile list
 neon profile remove work
 ```
@@ -657,14 +657,21 @@ neon profile remove work
 ```console
 $ neon profile list
 Profiles
-┌────────┬─────────┬──────────────────────┬──────────┬──────────────────────────────────────┐
-│ Active │ Name    │ Account              │ SignedIn │ Credentials                          │
-├────────┼─────────┼──────────────────────┼──────────┼──────────────────────────────────────┤
-│ *      │ DEFAULT │ me@example.com       │ yes      │ ~/.config/neon/credentials.json      │
-├────────┼─────────┼──────────────────────┼──────────┼──────────────────────────────────────┤
-│        │ work    │ me@work.example.com  │ yes      │ ~/.config/neon/credentials.work.json │
-└────────┴─────────┴──────────────────────┴──────────┴──────────────────────────────────────┘
-```
+┌────────┬─────────┬───────────────────────┬─────────┬────────────────┬──────┬────────────────────────┐
+│ Active │ Name    │ Account               │ Auth    │ Scope          │ File │ Credentials            │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│ *      │ DEFAULT │ me@example.com        │ oauth   │ -              │ ok   │ credentials.json       │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│        │ work    │ me@example.com        │ api key │ account        │ ok   │ credentials.work.json  │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│        │ ci      │ org-old-flower-827148 │ api key │ project proj-1 │ ok   │ credentials.ci.json    │
+└────────┴─────────┴───────────────────────┴─────────┴────────────────┴──────┴────────────────────────┘
+```
+
+`Scope` is what a key can reach; an OAuth session has none of its own, so it shows `-`. `File`
+says whether the credentials file can be read and understood — `ok`, `invalid` or `missing` —
+which is not the same as the credential still working; only using it shows that. The table shows
+the file name, `--output json` the full path.
 
 Select one per invocation with `--profile`, or per shell with `NEON_PROFILE`. There is no `profile use` command and nothing is stored about which profile is "current", so what you type is always what runs.
 
@@ -680,14 +687,176 @@ Entries in `profiles.json` are paths, and a path may point anywhere — which is
 }
 ```
 
-`neon profile remove` revokes the refresh token at the authorization server, not just locally. It deletes the credentials file only when the CLI created it: an adopted path like the one above is unlinked and left on disk, and the command says so. Removing the last named profile deletes `profiles.json`, returning you to the single-account layout. `neon profile remove DEFAULT` signs you out.
+`neon profile remove` revokes what the profile holds — an OAuth refresh token at the
+authorization server, or an API key this CLI minted — rather than only forgetting it locally. A
+key you supplied is the exception and stays live, because nothing records its id; the command
+says so. It asks for confirmation first, which `--yes` skips; without a terminal on stdin, in
+CI or behind a pipe, it refuses rather than prompting into the void. It deletes the credentials
+file only when the CLI created it: an adopted path like the one above is unlinked and left on
+disk, and the command says so. Removing the last named profile deletes `profiles.json`,
+returning you to the single-account layout. `neon profile remove DEFAULT` signs you out.
+
+### A profile holds either a sign-in or an API key
+
+`neon profile create` makes a profile, and how you call it decides which kind of credential it holds. A key-backed profile is what you want for an agent, a shared machine, or anything that must never be interrupted by a browser:
+
+```bash
+neon profile create work                            # sign in with the browser, like `neon auth`
+neon profile create work --api-key "$KEY"           # store a key you already have
+echo "$KEY" | neon profile create work --api-key -  # or pipe it, keeping it out of argv
+neon profile create ci --mint                       # sign in once, keep only a minted key
+neon profile create ci --mint --org-id org-abc-123  # minted for an organization
+neon profile create ci --mint --project-id proj-1   # minted for one project only
+neon profile create work --force                    # replace it, revoking what it holds now
+neon profile rotate-key work                        # mint a replacement, revoke the old one
+```
+
+`--force` is not only a local edit: replacing a profile revokes the credential it held, so a key
+this CLI minted stops working everywhere it was pasted, and an OAuth session is signed out.
+Without `--force`, `create` refuses and names what would be revoked. To keep a working profile
+and swap only its key, use `rotate-key`.
+
+`create` and `rotate-key` print the profile they wrote, so an agent needn't follow up with
+`list`. Under `--output json` that is a record, and it never carries the secret:
+
+```console
+$ neon profile create ci --mint --org-id org-abc-123 --output json
+{"name":"ci","account":"org-abc-123","auth":"api key","scope":"org org-abc-123","keyId":3239771,"credentials":"/home/me/.config/neon/credentials.ci.json"}
+```
+
+One flag takes the key, because the shell already covers the variations: `--api-key "$(cat
+~/keys/work)"` reads a file and `--api-key "$KEY"` takes a variable. Those put the key in the
+process arguments, where `ps` and shell history can see it, so `--api-key -` reads it from stdin
+instead — the usual convention for a piped value. `--mint` avoids the question entirely, because
+the key never leaves the CLI.
+
+**A profile is one kind or the other, never both.** `type` in the credentials file states which:
+
+```json
+// oauth: what a plain `create` (or `neon auth --profile`) writes. An absent `type` means this.
+{ "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
+
+// api_key: what `--api-key` writes
+{ "type": "api_key", "api_key": "napi_…", "user_id": "…" }
+
+// api_key from `--mint --org-id`, which records the scope it was issued at
+{ "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
+```
+
+Nothing is carried over when a profile is replaced, so one profile can never hold two credentials — or two different accounts. The secret stays in that file and never goes into `profiles.json`, so listing profiles cannot leak one. Both files are written owner-only through a temporary file and a rename, which also repairs the permissions of a file created too permissively.
+
+`--mint` is the one to reach for. It signs you in through the browser once, mints a key with that session, stores only the key, and signs the session back out — so afterwards nothing about the profile can open a browser, and no half-forgotten login is left behind. `--org-id` and `--project-id` narrow what the minted key can reach, exactly as they do on [`neon api-keys create`](#api-keys); a project-scoped key cannot create projects, mint keys, or read any other project.
+
+Every key is verified against the API before it is stored, and the account it belongs to is recorded so `profile list` can show it. Only a real API key is accepted: an OAuth access token authenticates today and then expires with nothing to refresh it.
+
+`rotate-key` mints at the scope the profile already has — replacing an org key with an account key would quietly widen everything it reaches — and stores the new key before revoking the old one, so a failed write leaves the old key working.
+
+One thing it cannot do: **an organization key cannot mint its own replacement.** Neon only accepts a personal credential when creating organization keys, so rotating an org- or project-scoped profile means signing in again — `neon profile create ci --mint --org-id org-abc-123 --force`. `rotate-key` checks this before minting and says so, rather than letting the API answer with a rule you had no reason to expect.
+
+Two things the CLI cannot do for a key you supplied rather than minted. It cannot revoke it, because `GET /api_keys` exposes no prefix and a stored secret cannot be matched to a listing entry, so both `rotate-key` and `profile remove` say the old key is still live and point you at `neon api-keys list`. For a key you supplied it records the organization the API reports, but cannot know whether that key was narrowed to a single project — so `rotate-key` will not suggest an organization-wide replacement without telling you to check `neon api-keys list` first.
+
+If a stored key stops working there is nothing to refresh, so recovery is one browser sign-in: `neon profile create work --mint --force`.
+
+### Which credential an invocation uses
+
+An explicit flag always beats an environment variable:
+
+| Given | What runs |
+| --- | --- |
+| `--api-key` and `--profile` | neither — contradictory, so the command fails |
+| `--api-key` and `NEON_PROFILE` | the flag's key |
+| `--profile` and `NEON_API_KEY` | the profile |
+| `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+| `--profile` or `NEON_PROFILE` alone | that profile |
+| nothing | `DEFAULT` |
+
+Passing both flags fails rather than picking a winner: `--api-key` supplies a credential and `--profile` selects a stored one, so there is no reading of the command that makes both true.
+
+When both are only environment variables the key wins, which keeps a CI pipeline that injects `NEON_API_KEY` working even if a `NEON_PROFILE` leaks into the environment — but the disregarded profile is named on stderr rather than passed over silently.
+
+`neon auth` and the `profile` subcommands are outside all of this, because they read the same flags to mean something else: `neon auth --profile work` names where to write a credential, and `neon profile create work --api-key …` names one to store.
+
+`neon init` does not support `--profile` yet. It hands its whole auth flow to `neon-init`, which reads the default credentials directly, so passing the flag fails instead of quietly running as the default account.
+
+## API keys (`api-keys`)
+
+```bash
+neon api-keys list                                        # your account's keys
+neon api-keys list --org-id org-…                         # an organization's, with scope shown
+
+neon api-keys create --name ci                            # account key
+neon api-keys create --name ci    --org-id org-…          # organization key
+neon api-keys create --name agent --project-id frosty-…   # can access only that project
+
+neon api-keys revoke <id> [--org-id org-…]
+```
+
+The key is returned once, on create, and cannot be retrieved again. It prints on its own line below the table, so it can be selected in one gesture regardless of terminal width — and `… | tail -1` on stdout yields exactly the key, since both notices go to stderr.
+
+```console
+$ neon api-keys create --name agent --project-id proj-in-org
+API key
+┌─────┬───────┬─────────────┐
+│ Id  │ Name  │ Project     │
+├─────┼───────┼─────────────┤
+│ 303 │ agent │ proj-in-org │
+└─────┴───────┴─────────────┘
+
+napi_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+WARNING: Store this key now: it is not shown again.
+INFO: Limited to proj-in-org: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.
+```
+
+`--org-id` and `--project-id` are mutually exclusive. A project-scoped key *is* an organization key, and its organization is looked up from the project rather than chosen separately. With neither flag you get an account key.
+
+### Project-scoped keys
+
+A key created with `--project-id` bounds what it can reach to one project. Verified against a real scoped key:
+
+| Attempt | Result |
+| --- | --- |
+| Read and write its own project | works |
+| Read any other project | `project not found` — not even an existence oracle |
+| `neon projects create` | `project-scoped keys are not allowed to create projects` |
+| `neon projects list` | refused |
+| `neon api-keys create` / `list` | refused (true of any organization key, not only scoped ones) |
+| `neon orgs list` | **works** — it can see the id, name and handle of the organization it belongs to |
+| Anything else about that organization (`GET /organizations/{id}`, members) | refused |
+
+It is **not** read-only. Inside its one project it can do everything the API allows, including deleting branches and the project itself — `neon deploy` working at all is proof of that. What it bounds is *reach*, which is what lets you hand it to an agent or a CI job without handing over your account:
+
+```bash
+neon link --project-id frosty-…       # once, as yourself — writes .neon
+NEON_API_KEY=napi_… neon deploy       # then the agent, reaching only that project
+```
+
+`neon link` needs `--project-id` explicitly when using a scoped key: the interactive picker lists your projects, which a scoped key cannot do.
+
+`api-keys` deliberately ignores the `.neon` context file, unlike every other project command. Otherwise `neon api-keys create --name ci` inside a linked directory would silently mint a key scoped to that project instead of the account key you asked for. How far a credential reaches comes only from a flag you typed.
+
+### Seeing what is scoped
+
+```console
+$ neon api-keys list --org-id org-7
+API keys in org-7
+┌─────┬──────────┬────────────────┬──────────────────────┬──────────────────────┬─────────────────────┐
+│ Id  │ Name     │ Project        │ Created At           │ Last Used At         │ Last Used From Addr │
+├─────┼──────────┼────────────────┼──────────────────────┼──────────────────────┼─────────────────────┤
+│ 301 │ scoped   │ proj-in-org    │ 2026-01-02T00:00:00Z │                      │                     │
+├─────┼──────────┼────────────────┼──────────────────────┼──────────────────────┼─────────────────────┤
+│ 302 │ org-wide │ (all projects) │ 2026-01-03T00:00:00Z │ 2026-02-03T00:00:00Z │ 203.0.113.9         │
+└─────┴──────────┴────────────────┴──────────────────────┴──────────────────────┴─────────────────────┘
+```
+
+`last_used_at` and `last_used_from_addr` are how you spot a key worth revoking.
 
 ## Commands
 
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
 | [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                              | Authenticate                       |
-| profile                                                                    | `list`, `remove`                                                                                             | Manage named sets of credentials   |
+| profile                                                                    | `list`, `create`, `rotate-key`, `remove`                                                                     | Manage named sets of credentials   |
+| api-keys                                                                   | `list`, `create`, `revoke`                                                                                   | Manage API keys                    |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |
 | [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                                             | Manage IP Allow                    |
 | [me](https://neon.com/docs/reference/cli-me)                               |                                                                                                              | Show current user                  |

package/dist/_shared/auth_selection.js

@@ -0,0 +1,86 @@
+/**
+ * # Which credential an invocation authenticates with
+ *
+ * Four inputs can each answer "who am I": the `--api-key` flag, `NEON_API_KEY`, the
+ * `--profile` flag, and `NEON_PROFILE`. This module decides between them, and it is pure so
+ * the decision can be tested without a filesystem, a network, or a config directory.
+ *
+ * ## The rule
+ *
+ * **An explicit flag beats an ambient environment variable.** That single rule fixes the bug
+ * this module exists for: before it, any API key — including one merely exported into the
+ * shell — silently voided `--profile`, so `neon --profile work …` would quietly run as
+ * whoever `NEON_API_KEY` belonged to and say nothing about it.
+ *
+ * | Given | What runs |
+ * | --- | --- |
+ * | `--api-key` and `--profile` | neither: contradictory explicit flags, so this throws |
+ * | `--api-key` and `NEON_PROFILE` | the flag's key |
+ * | `--profile` and `NEON_API_KEY` | the profile |
+ * | `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+ * | `--profile` or `NEON_PROFILE` alone | that profile |
+ * | nothing | `DEFAULT` |
+ *
+ * Two explicit flags throw rather than picking a winner. They express different intents —
+ * `--api-key` supplies a credential, `--profile` selects a stored one — so there is no
+ * reading of the command that makes both true, and guessing is how the original bug behaved.
+ *
+ * When both are merely ambient, the key wins. That keeps CI exactly as it was: a pipeline
+ * that injects `NEON_API_KEY` must not change behaviour because a `NEON_PROFILE` leaked into
+ * the environment. It warns instead of staying silent, because a disregarded account
+ * selection is precisely what nobody noticed last time.
+ *
+ * `auth` and the `profile` subcommands do not use any of this. They read the same flags with
+ * different meanings — `neon auth --profile work` names where to *write* a credential, and
+ * `neon profile create work --api-key …` names one to *store* — so their callers skip
+ * selection entirely rather than passing exemptions down here.
+ */
+import { DEFAULT_PROFILE } from "./profiles.js";
+const NO_INPUTS = {
+    apiKeyFlag: "",
+    apiKeyEnv: "",
+    profileEnv: "",
+};
+let inputs = NO_INPUTS;
+export const recordCredentialInputs = (recorded) => {
+    inputs = recorded;
+};
+export const credentialInputs = () => inputs;
+export const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv, }) => {
+    const flagKey = nonEmpty(apiKeyFlag);
+    const flagProfile = nonEmpty(profileFlag);
+    if (flagKey !== undefined && flagProfile !== undefined) {
+        throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+    }
+    if (flagKey !== undefined) {
+        return { source: "explicit-api-key", apiKey: flagKey };
+    }
+    if (flagProfile !== undefined) {
+        return { source: "profile", profile: flagProfile, explicit: true };
+    }
+    const envKey = nonEmpty(apiKeyEnv);
+    const envProfile = nonEmpty(profileEnv);
+    if (envKey !== undefined) {
+        return {
+            source: "ambient-api-key",
+            apiKey: envKey,
+            ...(envProfile !== undefined ? { ignoredProfile: envProfile } : {}),
+        };
+    }
+    return {
+        source: "profile",
+        profile: envProfile ?? DEFAULT_PROFILE,
+        explicit: envProfile !== undefined,
+    };
+};
+/** The warning for an ambient key that displaced an ambient profile, or `null`. */
+export const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" &&
+    selection.ignoredProfile !== undefined
+    ? `NEON_API_KEY is set, so profile "${selection.ignoredProfile}" from NEON_PROFILE was ignored. Pass --profile ${selection.ignoredProfile} to use it instead.`
+    : null;
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/_shared/credentials.js

@@ -0,0 +1,209 @@
+/**
+ * # Stored credentials — one file per account, two kinds
+ *
+ * A profile points at exactly one credentials file (see `./profiles.ts`), and that file says
+ * what kind of credential it holds. Adding API-key support this way rather than adding a
+ * second pointer to `profiles.json` keeps a profile what it already was — one name, one path
+ * — and means `profiles.json` needs no schema change at all.
+ *
+ * ```json
+ * // oauth: every file written before this existed. An absent `type` means this.
+ * { "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
+ *
+ * // api_key, stored by `neon profile create --api-key`
+ * { "type": "api_key", "api_key": "napi_…", "user_id": "…" }
+ *
+ * // api_key minted by `--mint --org-id`, which records the scope it was issued at
+ * { "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
+ * ```
+ *
+ * ## One profile, one kind
+ *
+ * A credentials file holds an API key or an OAuth session, never both, and `type` states
+ * which. An earlier draft let the two coexist — the idea being that a key could keep the
+ * session it was minted from and so rotate without a browser. It did not survive review, for
+ * two reasons that are worth recording so nobody rebuilds it:
+ *
+ * 1. **It never worked.** The resolver returned the key without testing it, so a revoked key
+ *    failed to mint and never fell back to the session sitting beside it.
+ * 2. **It could mix accounts.** Nothing compared the identity of the credential being written
+ *    with the one already there, so a profile could hold one account's session and another's
+ *    key, told apart only by a single string. Flip or lose `type` and the profile silently
+ *    becomes a different person.
+ *
+ * Recovery from a dead key is therefore one browser login — `neon profile create <name>
+ * --mint --force` — which is what the retained session was supposed to save and never did.
+ *
+ * ## Older releases
+ *
+ * A CLI predating this reads the pointer, finds no `type` it understands, ignores it, and
+ * looks for `access_token`. An `api_key` profile has none, so an older release falls through
+ * to its browser login rather than crashing. That it does not crash is why `credentials`
+ * stays a required pointer: an entry without one makes 2.41 and 2.42 throw
+ * `ERR_INVALID_ARG_TYPE` from `resolveEntryPath`.
+ */
+import { readFileSync } from "node:fs";
+import { writeSecretFile } from "./secure_file.js";
+export const OAUTH = "oauth";
+export const API_KEY = "api_key";
+/**
+ * Which credential in this file authenticates, by declaration alone.
+ *
+ * An unrecognised `type` throws rather than falling back to `oauth`. A file we cannot
+ * interpret is a misconfiguration the user has to see: treating it as OAuth would send them
+ * to a browser login that silently replaces a credential they meant to keep, and treating it
+ * as an API key would authenticate with whatever `api_key` happened to be there.
+ *
+ * This deliberately does not check that an `api_key` file has a key — `neon profile list`
+ * needs the kind of a file it is not about to authenticate with, and must be able to report a
+ * broken one rather than throwing halfway through a table.
+ */
+export const credentialKind = (credentials, at) => {
+    const declared = credentials.type;
+    if (declared === undefined || declared === OAUTH)
+        return OAUTH;
+    if (declared === API_KEY)
+        return API_KEY;
+    // The value is not quoted back. Everything in this file is secret material, and a
+    // corrupted or hand-edited file can put a key anywhere in it — including here. Naming the
+    // file is enough to act on, and it cannot leak what the file holds.
+    throw new Error(`${at.path} declares a "type" this version does not understand. Expected "${OAUTH}" or "${API_KEY}". ${repair(at)}`);
+};
+/**
+ * The way out of a credentials file that cannot be read.
+ *
+ * One sentence, shared by every such error, because they all have the same two answers: write
+ * a new credential over it, or delete it and start again.
+ */
+const repair = (at) => `Replace it deliberately with \`neon profile create ${at.profile} --force\`, or delete the file.`;
+/**
+ * Resolve what to authenticate with, validating that the declared kind is actually usable.
+ *
+ * An `api_key` file with no key is a hard error rather than a fall-through to OAuth: the user
+ * asked for a key, and quietly opening a browser instead would replace the credential they
+ * were trying to fix.
+ */
+export const interpretCredentials = (credentials, at) => {
+    if (credentialKind(credentials, at) === OAUTH)
+        return { kind: OAUTH };
+    const apiKey = nonEmpty(credentials.api_key);
+    if (apiKey === undefined) {
+        throw new Error(`${at.path} declares "type": "${API_KEY}" but has no "api_key" value. ${repair(at)}`);
+    }
+    return { kind: API_KEY, apiKey };
+};
+/**
+ * Read and classify a credentials file, without deciding what to do about it.
+ *
+ * A permission or I/O error still throws: there may be a perfectly good credential here that
+ * we cannot see, and treating that as absent would send the user to a browser login that
+ * overwrites it.
+ */
+export const inspectCredentials = (path) => {
+    let contents;
+    try {
+        contents = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { kind: "absent" };
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        // The parser's message is deliberately discarded. V8 quotes a window of the input
+        // around the syntax error — on Node 24 a truncated credentials file produced
+        // `Unexpected token 'a', ..."api_key":napi_SUPERS"... is not valid JSON` — and this
+        // reason is printed by `profile list` and by every failed authentication. A malformed
+        // secret file is exactly when a diagnostic must say less, not more.
+        return {
+            kind: "unusable",
+            reason: `${path} is not valid JSON, so the credential in it cannot be read`,
+        };
+    }
+    if (parsed === null ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed)) {
+        return {
+            kind: "unusable",
+            reason: `${path} does not contain a credentials object`,
+        };
+    }
+    return { kind: "ok", credentials: parsed };
+};
+/**
+ * The credential at `path`, or `null` when the file is not there.
+ *
+ * A damaged file is an error, not an absence. Treating it as absent — which is what this used to
+ * do — meant any read-only command could repair it by starting a browser sign-in and overwriting
+ * it, **possibly as a different account**, with the user never having asked for a repair and no
+ * way back to whatever was in the file. Failing here costs one deliberate command; the message
+ * names it.
+ *
+ * `profile list` and telemetry use {@link inspectCredentials} instead, because describing a
+ * broken credential is not the same as using one.
+ */
+export const readCredentials = (at) => {
+    const read = inspectCredentials(at.path);
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. ${repair(at)}`);
+    }
+    return read.kind === "ok" ? read.credentials : null;
+};
+export const writeCredentials = (path, credentials) => {
+    writeSecretFile(path, JSON.stringify(credentials));
+};
+/**
+ * Build an `api_key` credentials object. Nothing from a previous credential is carried over.
+ *
+ * The scope is stored because it is not recoverable from the secret: `rotate-key` has to mint
+ * the replacement on the same endpoint, and an org or project key minted as an account key
+ * would silently widen what the profile reaches.
+ */
+export const apiKeyCredentials = ({ apiKey, keyId, userId, scope, }) => ({
+    type: API_KEY,
+    api_key: apiKey,
+    ...(keyId !== undefined ? { key_id: keyId } : {}),
+    ...(userId !== undefined ? { user_id: userId } : {}),
+    ...(scope?.orgId !== undefined ? { org_id: scope.orgId } : {}),
+    ...(scope?.projectId !== undefined ? { project_id: scope.projectId } : {}),
+});
+/** The scope recorded on a stored credential. */
+export const scopeOf = (credentials) => ({
+    ...(typeof credentials.org_id === "string"
+        ? { orgId: credentials.org_id }
+        : {}),
+    ...(typeof credentials.project_id === "string"
+        ? { projectId: credentials.project_id }
+        : {}),
+});
+/** How to describe a scope in output. */
+export const describeScope = (scope) => {
+    if (scope.projectId !== undefined)
+        return `project ${scope.projectId}`;
+    if (scope.orgId !== undefined)
+        return `org ${scope.orgId}`;
+    return "account";
+};
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * Whether a stored credential is the same secret as the one about to replace it.
+ *
+ * Re-storing the key a profile already holds is a no-op, not a replacement — and retiring it
+ * would revoke the credential the command has just committed to. Trimmed on both sides, because
+ * a key read from a file or a pipe arrives with a trailing newline.
+ */
+export const isSameCredential = (existingKey, replacementKey) => {
+    if (existingKey === undefined || replacementKey === undefined)
+        return false;
+    const trimmed = existingKey.trim();
+    return trimmed !== "" && trimmed === replacementKey.trim();
+};