neon 4.13.0 → 4.14.0

package/dist/_chunks/{env_services-Tz9G4JeT.js → env_services-CAWrZTWa.js}

@@ -1,5 +1,5 @@
 import { NEON_SERVICES } from "../neon_services.js";
-import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, resolveConfig } from "@neon/config/v1";
+import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, isPlatformError, resolveConfig } from "@neon/config/v1";
 //#region ../../internals/env-core/dist/env.js
 /**
 * The Neon env core — resolving a branch's env from the Neon API, and projecting it into
@@ -84,26 +84,31 @@ const NEON_ENV_VAR_KEYS = {
 		baseUrl: "NEON_AI_GATEWAY_BASE_URL"
 	}
 };
+const FUNCTION_SLUG = /^[a-z0-9]{1,20}$/;
+const FUNCTION_BASE_URL_KEY = /^NEON_FUNCTION_([A-Z0-9]{1,20})_BASE_URL$/;
+function functionBaseUrlKey(slug) {
+	if (!FUNCTION_SLUG.test(slug)) throw new Error(`functionBaseUrlKey: ${JSON.stringify(slug)} is not a function slug ([a-z0-9]{1,20}).`);
+	return `NEON_FUNCTION_${slug.toUpperCase()}_BASE_URL`;
+}
+function parseFunctionBaseUrlKey(key) {
+	const match = FUNCTION_BASE_URL_KEY.exec(key);
+	return match ? match[1].toLowerCase() : null;
+}
+function isFunctionBaseUrlKey(key) {
+	return parseFunctionBaseUrlKey(key) !== null;
+}
 /** Fail loudly when selected-key dependency planning and execution disagree. */
 function requiredValue(value, description) {
 	if (value === null) throw new Error(`fetchEnv: missing ${description}.`);
 	return value;
 }
-/**
-* The {@link fetchEnv} body, with the key selection as a plain argument and no generic
-* narrowing. Exists for callers that compute the selection at runtime — notably
-* {@link fetchEnvReusingSecrets}, which decides which keys it still needs by checking the
-* branch — since the public overload's `keys` is bound to a literal union those callers cannot
-* produce without asserting.
-*
-* `keys === null` selects everything the policy enables.
-*/
-async function fetchEnvKeys(config, options, keys) {
+async function fetchEnvKeysState(config, options, keys) {
 	const api = options.api ?? createApiFromOptions(options);
 	const projectId = options.projectId;
 	const { branch, desired } = await resolveBranchPolicy(config, options, api);
 	const selection = keys ? new Set(keys) : null;
-	const wants = (key) => selection === null || selection.has(key);
+	const omitted = new Set(options.omitKeys ?? []);
+	const wants = (key) => !omitted.has(key) && (selection === null || selection.has(key));
 	const result = {};
 	const K = NEON_ENV_VAR_KEYS;
 	const wantsPooled = wants(K.postgres.databaseUrl);
@@ -111,7 +116,17 @@ async function fetchEnvKeys(config, options, keys) {
 	const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
 	const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
 	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
-	const needsUnpooled = wantsUnpooled || gatewayEnabled && wants(K.aiGateway.baseUrl);
+	const functionUrlMode = options.functionUrls ?? "policy";
+	const declaredSlugs = (desired.preview?.functions ?? []).map((fn) => fn.slug);
+	const selectedFunctionKeys = selection === null ? [] : [...selection].filter(isFunctionBaseUrlKey);
+	const constructSlugs = functionUrlSlugsToConstruct({
+		functionUrlMode,
+		selection,
+		declaredSlugs,
+		selectedFunctionKeys,
+		wants
+	});
+	const needsUnpooled = wantsUnpooled || gatewayEnabled && wants(K.aiGateway.baseUrl) || constructSlugs.length > 0;
 	const needsConnectionTarget = wantsPooled || needsUnpooled;
 	const needsDatabase = needsConnectionTarget || wantsDataApi;
 	const [roles, databases] = await Promise.all([needsConnectionTarget ? api.listBranchRoles(projectId, branch.id) : Promise.resolve([]), needsDatabase ? api.listBranchDatabases(projectId, branch.id) : Promise.resolve([])]);
@@ -200,7 +215,67 @@ async function fetchEnvKeys(config, options, keys) {
 			result.aiGateway = gateway;
 		}
 	}
-	return result;
+	const wantsAnyFunctionUrl = selection === null || selectedFunctionKeys.length > 0;
+	const functions = {};
+	let functionUrlsUnavailable = false;
+	if (functionUrlMode === "all-live" && wantsAnyFunctionUrl) {
+		const listed = options.listedFunctions === void 0 ? await listFunctionInvocationUrls(api, projectId, branch.id) : listedFromSnapshots(options.listedFunctions);
+		if (listed.status === "unavailable") {
+			if (selection === null) functionUrlsUnavailable = true;
+		} else for (const fn of listed.functions) {
+			if (!wants(functionBaseUrlKey(fn.slug))) continue;
+			functions[fn.slug] = { baseUrl: asEnvBaseUrl(fn.invocationUrl) };
+		}
+	}
+	const missingConstructSlugs = constructSlugs.filter((slug) => functions[slug] === void 0);
+	if (missingConstructSlugs.length > 0) {
+		const uri = requiredValue(unpooled, "direct connection URI for function invocation URLs").uri;
+		for (const slug of missingConstructSlugs) functions[slug] = { baseUrl: functionInvocationUrl(branch.id, slug, uri) };
+	}
+	assertSelectedFunctionUrls(selectedFunctionKeys, functions);
+	if (Object.keys(functions).length > 0) result.functions = functions;
+	return {
+		env: result,
+		functionUrlsUnavailable
+	};
+}
+function functionUrlSlugsToConstruct(args) {
+	const slugs = [];
+	if (args.functionUrlMode === "policy" && args.selection === null) {
+		for (const slug of args.declaredSlugs) if (args.wants(functionBaseUrlKey(slug))) slugs.push(slug);
+		return slugs;
+	}
+	for (const key of args.selectedFunctionKeys) {
+		const slug = parseFunctionBaseUrlKey(key);
+		if (slug !== null) slugs.push(slug);
+	}
+	return slugs;
+}
+function listedFromSnapshots(snapshots) {
+	return {
+		status: "ok",
+		functions: snapshots.filter((fn) => fn.invocationUrl !== "").map((fn) => ({
+			slug: fn.slug,
+			invocationUrl: fn.invocationUrl
+		})).sort((left, right) => left.slug.localeCompare(right.slug))
+	};
+}
+function assertSelectedFunctionUrls(keys, functions) {
+	for (const key of keys) {
+		const slug = parseFunctionBaseUrlKey(key);
+		if (slug === null || functions[slug] === void 0) throw new Error(`fetchEnv: missing ${key}.`);
+	}
+}
+async function listFunctionInvocationUrls(api, projectId, branchId) {
+	try {
+		return listedFromSnapshots(await api.listBranchFunctions(projectId, branchId));
+	} catch (error) {
+		if (isPlatformError(error) && error.code === ErrorCode.FeatureUnavailable) return {
+			status: "unavailable",
+			error
+		};
+		throw error;
+	}
 }
 /**
 * Resolve the target branch and evaluate the policy against it — the first thing any
@@ -302,15 +377,40 @@ async function mintBranchCredential(args) {
 * `ep-x.c-3.us-east-2.aws.neon.tech` yields the gateway host
 * `<branchId>-api.ai.c-3.us-east-2.aws.neon.tech`. The cell prefix is **load-bearing** —
 * the gateway is cell-routed, so dropping `c-N.` resolves to the wrong (or no) host.
+*
+* Function invocation URLs use the same suffix: `<branchId>-<slug>.compute.<suffix>`.
 */
-function aiGatewayHost(branchId, connectionUri) {
+function connectionHostSuffix(connectionUri) {
 	let connectionHost = "";
 	try {
 		connectionHost = new URL(connectionUri).hostname;
 	} catch {
 		connectionHost = "";
 	}
-	return `${branchId}-api.ai.${connectionHost.split(".").slice(1).join(".")}`;
+	return connectionHost.split(".").slice(1).join(".");
+}
+function aiGatewayHost(branchId, connectionUri) {
+	return `${branchId}-api.ai.${connectionHostSuffix(connectionUri)}`;
+}
+/**
+* The API's `invocation_url` ends with `/` so paths concatenate onto it. Neon `*_BASE_URL`
+* vars are origin-only (`NEON_AUTH_BASE_URL`, `NEON_AI_GATEWAY_BASE_URL`).
+*/
+function asEnvBaseUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`fetchEnv: function invocation URL is not a URL: ${JSON.stringify(url)}`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`fetchEnv: function invocation URL must be http(s): ${JSON.stringify(url)}`);
+	return parsed.origin;
+}
+/** Derived from the connection URI so undeployed functions have a cell-routed URL. */
+function functionInvocationUrl(branchId, slug, connectionUri) {
+	const suffix = connectionHostSuffix(connectionUri);
+	if (suffix === "") throw new Error(`fetchEnv: cannot derive the invocation URL for function "${slug}": the direct connection URI has no host suffix.`);
+	return `https://${branchId}-${slug}.compute.${suffix}`;
 }
 /** The AI Gateway's bare base URL (`NEON_AI_GATEWAY_BASE_URL`) on the branch gateway host. */
 function aiGatewayBaseUrl(branchId, connectionUri) {
@@ -403,19 +503,12 @@ function toEntries(env) {
 	put(K.storage.region, env.storage?.region);
 	put(K.aiGateway.apiKey, env.aiGateway?.apiKey);
 	put(K.aiGateway.baseUrl, env.aiGateway?.baseUrl);
+	if (env.functions) for (const slug of Object.keys(env.functions).sort()) put(functionBaseUrlKey(slug), env.functions[slug]?.baseUrl);
 	return out;
 }
 //#endregion
 //#region src/env_services.ts
-/**
-* The services `env pull --service` can select: every Neon service that produces branch env
-* vars. `functions` is the one left out — a function's env comes from the local `neon.ts`,
-* never from the branch, so there is nothing to pull.
-*/
-const ENV_PULL_SERVICES = NEON_SERVICES.filter((service) => service !== "functions");
-/** Why the services `env pull` leaves out are not selectable, for the refusal message. */
-const ENV_PULL_UNAVAILABLE = { functions: "a function's env comes from your neon.ts, not from the branch, so there is nothing to pull" };
-/** Every OS-level env var `env pull` can write, in stable emit order. */
+const ENV_PULL_SERVICES = NEON_SERVICES;
 const ENV_PULL_KEYS = [
 	...Object.values(NEON_ENV_VAR_KEYS.postgres),
 	NEON_ENV_VAR_KEYS.branch.name,
@@ -424,6 +517,7 @@ const ENV_PULL_KEYS = [
 	...Object.values(NEON_ENV_VAR_KEYS.storage),
 	...Object.values(NEON_ENV_VAR_KEYS.aiGateway)
 ];
+const ENV_PULL_KEY_HELP = `${ENV_PULL_KEYS.join(", ")}, or NEON_FUNCTION_<SLUG>_BASE_URL`;
 /** The OS-level env vars each service contributes to a pulled `.env`. */
 const SERVICE_ENV_KEYS = {
 	postgres: Object.values(NEON_ENV_VAR_KEYS.postgres),
@@ -437,18 +531,19 @@ const SERVICE_ENV_KEYS = {
 * The subset of {@link SERVICE_ENV_KEYS} a pull *owns*, and so may prune from the target file
 * when the branch no longer has it. Object storage is deliberately absent: it is emitted under
 * the third-party `AWS_*` names, which collide with credentials a user may set by hand, so
-* `env pull` only ever writes them.
+* `env pull` only ever writes them. Function URL keys cannot live here because slugs are
+* discovered at runtime.
 */
 const SERVICE_OWNED_ENV_KEYS = {
 	...SERVICE_ENV_KEYS,
-	"object-storage": []
+	"object-storage": [],
+	functions: []
 };
 /**
 * Branch identity. Not a service — every branch has a name — so a scoped pull refreshes it
 * alongside whatever services were selected.
 */
 const BRANCH_ENV_KEY = NEON_ENV_VAR_KEYS.branch.name;
-/** The service that produces a key, or `null` for branch identity. */
 const ENV_KEY_SERVICE = {
 	DATABASE_URL: "postgres",
 	DATABASE_URL_UNPOOLED: "postgres",
@@ -463,9 +558,9 @@ const ENV_KEY_SERVICE = {
 	NEON_AI_GATEWAY_TOKEN: "ai-gateway",
 	NEON_AI_GATEWAY_BASE_URL: "ai-gateway"
 };
-const serviceForEnvKey = (key) => ENV_KEY_SERVICE[key];
+const serviceForEnvKey = (key) => isFunctionBaseUrlKey(key) ? "functions" : ENV_KEY_SERVICE[key];
 /** Services that must be resolved to produce the selected env keys. */
-const servicesForEnvKeys = (keys) => ENV_PULL_SERVICES.filter((service) => keys.some((key) => ENV_KEY_SERVICE[key] === service));
+const servicesForEnvKeys = (keys) => ENV_PULL_SERVICES.filter((service) => keys.some((key) => serviceForEnvKey(key) === service));
 /** Every env var the selected services contribute, plus branch identity. */
 const envServiceKeys = (services) => {
 	const keys = /* @__PURE__ */ new Set([BRANCH_ENV_KEY]);
@@ -476,43 +571,45 @@ const envServiceKeys = (services) => {
 * The env vars a pull scoped to `services` may prune. Narrower than the unscoped set on
 * purpose: `env pull -s ai-gateway` says nothing about `DATABASE_URL`, so it must leave it
 * alone rather than treat its absence from this pull as "the branch no longer has it".
+* Function URL keys cannot live here because slugs are discovered at runtime.
 */
 const ownedEnvServiceKeys = (services) => services.flatMap((service) => SERVICE_OWNED_ENV_KEYS[service]);
-/**
-* The exact env vars an explicit selection writes. Services contribute their complete
-* bundles plus branch identity; `--env` contributes only the named keys. The two selectors
-* compose as a union.
-*/
 const envKeysForSelection = (services, envKeys) => {
 	const selected = services.length > 0 ? envServiceKeys(services) : /* @__PURE__ */ new Set();
 	for (const key of envKeys) selected.add(key);
 	if (selected.has(NEON_ENV_VAR_KEYS.storage.accessKeyId) !== selected.has(NEON_ENV_VAR_KEYS.storage.secretAccessKey)) throw new Error("AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must be selected together: they are two halves of one newly issued object-storage credential. Add the missing key to --env, or use --service object-storage.");
-	return ENV_PULL_KEYS.filter((key) => selected.has(key));
+	const staticKeys = ENV_PULL_KEYS.filter((key) => selected.has(key));
+	const functionKeys = [...selected].filter(isFunctionBaseUrlKey).sort((left, right) => left.localeCompare(right));
+	return [...staticKeys, ...functionKeys];
 };
 /** Parse repeated or comma-separated `--env` values into canonical env-key order. */
 const parseEnvPullKeys = (raw, flag) => {
 	const names = raw.flatMap((value) => value.split(",")).map((name) => name.trim()).filter((name) => name !== "");
-	const supported = `Supported values: ${ENV_PULL_KEYS.join(", ")}.`;
+	const supported = `Supported values: ${ENV_PULL_KEY_HELP}.`;
 	if (names.length === 0) throw new Error(`${flag} needs at least one env variable. ${supported}`);
-	const unknown = names.filter((name) => !ENV_PULL_KEYS.some((key) => key === name));
+	const unknown = names.filter((name) => !ENV_PULL_KEYS.some((key) => key === name) && !isFunctionBaseUrlKey(name));
 	if (unknown.length > 0) {
 		const displayNames = unknown.map(redactUnknownEnvValue);
 		const suggestions = [...new Set(unknown.map(suggestEnvPullKey).filter((key) => key !== null))];
 		const suggestion = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
 		throw new Error(`Unknown env variable${unknown.length === 1 ? "" : "s"} ${displayNames.join(", ")}.${suggestion} ${supported}`);
 	}
-	return ENV_PULL_KEYS.filter((key) => names.includes(key));
+	const staticKeys = ENV_PULL_KEYS.filter((key) => names.includes(key));
+	const functionKeys = [...new Set(names.filter(isFunctionBaseUrlKey))].sort((left, right) => left.localeCompare(right));
+	return [...staticKeys, ...functionKeys];
 };
+const isKnownEnvPullKey = (key) => ENV_PULL_KEYS.some((supportedKey) => supportedKey === key) || isFunctionBaseUrlKey(key);
 const redactUnknownEnvValue = (value) => {
 	const separator = value.indexOf("=");
 	if (separator !== -1) {
 		const key = value.slice(0, separator);
-		return ENV_PULL_KEYS.some((supportedKey) => supportedKey === key) ? `${key}=<redacted>` : "<redacted invalid value>";
+		return isKnownEnvPullKey(key) ? `${key}=<redacted>` : "<redacted invalid value>";
 	}
 	return "<redacted invalid value>";
 };
 const suggestEnvPullKey = (value) => {
 	if (value.includes("=")) return null;
+	if (parseFunctionBaseUrlKey(value) !== null) return null;
 	const closest = ENV_PULL_KEYS.map((key) => [key, editDistance(value, key)]).sort((a, b) => a[1] - b[1])[0];
 	return closest && closest[1] <= 2 ? closest[0] : null;
 };
@@ -528,4 +625,4 @@ const editDistance = (left, right) => {
 /** Narrow yargs' array option value without accepting any other runtime shape. */
 const envPullFlagValue = (value) => Array.isArray(value) ? value.map(String) : void 0;
 //#endregion
-export { policyEnvKeys as _, envKeysForSelection as a, toEntries as b, ownedEnvServiceKeys as c, servicesForEnvKeys as d, NEON_ENV_VAR_KEYS as f, fetchEnvKeys as g, credentialName as h, ENV_PULL_UNAVAILABLE as i, parseEnvPullKeys as l, credentialEnvKeys as m, ENV_PULL_KEYS as n, envPullFlagValue as o, createApiFromOptions as p, ENV_PULL_SERVICES as r, envServiceKeys as s, BRANCH_ENV_KEY as t, serviceForEnvKey as u, previewCredentialScopes as v, resolveBranchPolicy as y };
+export { toEntries as S, functionBaseUrlKey as _, envKeysForSelection as a, previewCredentialScopes as b, ownedEnvServiceKeys as c, servicesForEnvKeys as d, NEON_ENV_VAR_KEYS as f, fetchEnvKeysState as g, credentialName as h, ENV_PULL_SERVICES as i, parseEnvPullKeys as l, credentialEnvKeys as m, ENV_PULL_KEYS as n, envPullFlagValue as o, createApiFromOptions as p, ENV_PULL_KEY_HELP as r, envServiceKeys as s, BRANCH_ENV_KEY as t, serviceForEnvKey as u, isFunctionBaseUrlKey as v, resolveBranchPolicy as x, policyEnvKeys as y };

package/dist/_shared/auth_selection.js

@@ -0,0 +1,83 @@
+import "./profiles.js";
+//#region src/_shared/auth_selection.ts
+/**
+* # 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.
+*/
+let inputs = {
+	apiKeyFlag: "",
+	apiKeyEnv: "",
+	profileEnv: ""
+};
+const recordCredentialInputs = (recorded) => {
+	inputs = recorded;
+};
+const credentialInputs = () => inputs;
+const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv }) => {
+	const flagKey = nonEmpty(apiKeyFlag);
+	const flagProfile = nonEmpty(profileFlag);
+	if (flagKey !== void 0 && flagProfile !== void 0) throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+	if (flagKey !== void 0) return {
+		source: "explicit-api-key",
+		apiKey: flagKey
+	};
+	if (flagProfile !== void 0) return {
+		source: "profile",
+		profile: flagProfile,
+		explicit: true
+	};
+	const envKey = nonEmpty(apiKeyEnv);
+	const envProfile = nonEmpty(profileEnv);
+	if (envKey !== void 0) return {
+		source: "ambient-api-key",
+		apiKey: envKey,
+		...envProfile !== void 0 ? { ignoredProfile: envProfile } : {}
+	};
+	return {
+		source: "profile",
+		profile: envProfile ?? "DEFAULT",
+		explicit: envProfile !== void 0
+	};
+};
+/** The warning for an ambient key that displaced an ambient profile, or `null`. */
+const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" && selection.ignoredProfile !== void 0 ? `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 void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+export { credentialInputs, displacedProfileWarning, recordCredentialInputs, selectCredential };

package/dist/_shared/credentials.js

@@ -0,0 +1,188 @@
+import { writeSecretFile } from "./secure_file.js";
+import { readFileSync } from "node:fs";
+//#region src/_shared/credentials.ts
+/**
+* # 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`.
+*/
+const OAUTH = "oauth";
+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.
+*/
+const credentialKind = (credentials, at) => {
+	const declared = credentials.type;
+	if (declared === void 0 || declared === "oauth") return OAUTH;
+	if (declared === "api_key") return API_KEY;
+	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.
+*/
+const interpretCredentials = (credentials, at) => {
+	if (credentialKind(credentials, at) === "oauth") return { kind: OAUTH };
+	const apiKey = nonEmpty(credentials.api_key);
+	if (apiKey === void 0) 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.
+*/
+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 {
+		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.
+*/
+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;
+};
+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.
+*/
+const apiKeyCredentials = ({ apiKey, keyId, userId, scope }) => ({
+	type: API_KEY,
+	api_key: apiKey,
+	...keyId !== void 0 ? { key_id: keyId } : {},
+	...userId !== void 0 ? { user_id: userId } : {},
+	...scope?.orgId !== void 0 ? { org_id: scope.orgId } : {},
+	...scope?.projectId !== void 0 ? { project_id: scope.projectId } : {}
+});
+/** The scope recorded on a stored credential. */
+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. */
+const describeScope = (scope) => {
+	if (scope.projectId !== void 0) return `project ${scope.projectId}`;
+	if (scope.orgId !== void 0) return `org ${scope.orgId}`;
+	return "account";
+};
+function nonEmpty(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : 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.
+*/
+const isSameCredential = (existingKey, replacementKey) => {
+	if (existingKey === void 0 || replacementKey === void 0) return false;
+	const trimmed = existingKey.trim();
+	return trimmed !== "" && trimmed === replacementKey.trim();
+};
+//#endregion
+export { API_KEY, OAUTH, apiKeyCredentials, credentialKind, describeScope, inspectCredentials, interpretCredentials, isSameCredential, readCredentials, scopeOf, writeCredentials };