neon 2.47.0 → 3.1.0

package/dist/_shared/env-core/env.js

@@ -0,0 +1,395 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, resolveConfig } from "@neon/config/v1";
+//#region src/_shared/env-core/env.ts
+/**
+* The Neon env core — resolving a branch's env from the Neon API, and projecting it into
+* OS-level `{ KEY: value }` pairs.
+*
+* Shared source, not a package: `scripts/sync-shared.mjs` copies it into `@neon/env` (which
+* publishes it as `fetchEnv` / `toEntries`) and into the `neon` CLI (which needs the
+* credential-reuse half in `reuse-secrets.ts`). See `shared/env-core/README.md` for why it is
+* a copy rather than an import.
+*
+* The counterpart that reads `process.env` — `parseEnv` and its zod schemas — is not here. It
+* has no consumer outside `@neon/env`, so it stays in that package and imports this.
+*/
+/**
+* Mapping between the {@link NeonEnv} property paths and the OS-level env-var keys used
+* for cross-process transport (via `.env` files, `env run -- <cmd>`, or anything else
+* that talks to `process.env`).
+*
+* Each top-level key here is a {@link NeonEnv} namespace; the inner record maps the
+* camelCase property names exposed to TypeScript to the UPPER_SNAKE env-var names used
+* by the OS. Keep this in sync with {@link postgresEnvSchema} / {@link authEnvSchema} /
+* {@link dataApiEnvSchema}.
+*/
+/**
+* Neon's default branch owner role, created with every project. This is the role a
+* `DATABASE_URL` should connect as.
+*/
+const NEON_DEFAULT_OWNER_ROLE = "neondb_owner";
+/**
+* Neon's default database, created with every project. When a branch has several databases
+* and none was requested, this is preferred for the `DATABASE_URL` so the common case (a
+* user added a second database next to `neondb`) auto-picks without asking.
+*/
+const NEON_DEFAULT_DATABASE = "neondb";
+/**
+* Roles Neon provisions for the Auth / Data API (PostgREST) stack. They exist to back
+* RLS-scoped Data API requests authenticated by JWT — never to hold a `DATABASE_URL` —
+* so they're skipped when auto-picking the connection role. Enabling Neon Auth or the
+* Data API (`neon config apply`) adds these next to the owner role, which is why a plain
+* branch routinely reports more than one role.
+*/
+const NEON_MANAGED_AUTH_ROLES = /* @__PURE__ */ new Set([
+	"authenticator",
+	"anonymous",
+	"authenticated"
+]);
+const NEON_ENV_VAR_KEYS = {
+	/**
+	* Branch identity. `NEON_BRANCH` carries the branch **name** and is injected into the
+	* Neon Functions runtime on every branch (including the default) by default. `env pull` /
+	* `neon dev` / `neon-env run` emit it too so local dev mirrors the deployed runtime.
+	*/
+	branch: { name: "NEON_BRANCH" },
+	postgres: {
+		databaseUrl: "DATABASE_URL",
+		databaseUrlUnpooled: "DATABASE_URL_UNPOOLED"
+	},
+	auth: {
+		baseUrl: "NEON_AUTH_BASE_URL",
+		jwksUrl: "NEON_AUTH_JWKS_URL"
+	},
+	dataApi: { url: "NEON_DATA_API_URL" },
+	/**
+	* Object storage (Preview). The S3 SDKs read `AWS_*` from their standard config chain, so
+	* a branch credential + `neon dev` / `env pull` makes object storage work from env alone.
+	* `region` is injected under the SDK-standard `AWS_REGION`.
+	*/
+	storage: {
+		accessKeyId: "AWS_ACCESS_KEY_ID",
+		secretAccessKey: "AWS_SECRET_ACCESS_KEY",
+		endpoint: "AWS_ENDPOINT_URL_S3",
+		region: "AWS_REGION"
+	},
+	/**
+	* AI Gateway (Preview). Exposed under the Neon-branded env vars the deployed Functions
+	* runtime injects: `apiKey` is the minted credential's bearer (`NEON_AI_GATEWAY_TOKEN`)
+	* and `baseUrl` is the bare branch gateway host (`NEON_AI_GATEWAY_BASE_URL`,
+	* `scheme://host`, no path). Clients like `@neon/ai-sdk-provider` read these and append the
+	* dialect route (`/v1`, `/openai/v1`, `/anthropic/v1`) themselves (https://github.com/vercel/ai/pull/15997).
+	*/
+	aiGateway: {
+		apiKey: "NEON_AI_GATEWAY_TOKEN",
+		baseUrl: "NEON_AI_GATEWAY_BASE_URL"
+	}
+};
+async function fetchEnv(config, options) {
+	return fetchEnvKeys(config, options, options.keys ?? null);
+}
+/**
+* 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) {
+	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 result = {};
+	const [roles, databases] = await Promise.all([api.listBranchRoles(projectId, branch.id), api.listBranchDatabases(projectId, branch.id)]);
+	const roleName = pickRoleName(roles, branch, options.roleName);
+	const databaseName = pickDatabaseName(databases, branch, options.databaseName);
+	const K = NEON_ENV_VAR_KEYS;
+	const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
+	const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
+	const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all([
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: true
+		}),
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: false
+		}),
+		wantsAuth ? api.getNeonAuth(projectId, branch.id) : Promise.resolve(null),
+		wantsDataApi ? api.getNeonDataApi(projectId, branch.id, databaseName) : Promise.resolve(null)
+	]);
+	const postgres = {};
+	if (wants(K.postgres.databaseUrl)) postgres.databaseUrl = pooled.uri;
+	if (wants(K.postgres.databaseUrlUnpooled)) postgres.databaseUrlUnpooled = unpooled.uri;
+	if (Object.keys(postgres).length > 0) result.postgres = postgres;
+	if (wants(K.branch.name)) result.branch = { name: branch.name };
+	if (wantsAuth) {
+		if (!authSnapshot) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables auth but no Neon Auth integration is enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or `npx neon …`), in the Neon Console — then re-run fetchEnv. Or return auth.enabled=false."].join(" "), { details: {
+			projectId,
+			branchId: branch.id
+		} });
+		const auth = {};
+		if (wants(K.auth.baseUrl)) auth.baseUrl = authSnapshot.baseUrl ?? "";
+		if (wants(K.auth.jwksUrl)) auth.jwksUrl = authSnapshot.jwksUrl ?? "";
+		result.auth = auth;
+	}
+	if (wantsDataApi) {
+		if (!dataApiSnapshot) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${databaseName}.`, "Enable it via `apply(config, { projectId, branchId })` or in the Neon Console — then re-run fetchEnv. Or return dataApi.enabled=false."].join(" "), { details: {
+			projectId,
+			branchId: branch.id,
+			databaseName
+		} });
+		result.dataApi = { url: dataApiSnapshot.url };
+	}
+	const storageEnabled = (desired.preview?.buckets.length ?? 0) > 0;
+	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
+	const wantsStorage = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey) || wants(K.storage.endpoint) || wants(K.storage.region));
+	const wantsGateway = gatewayEnabled && (wants(K.aiGateway.apiKey) || wants(K.aiGateway.baseUrl));
+	const wantsCredential = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey)) || gatewayEnabled && wants(K.aiGateway.apiKey);
+	if (wantsStorage || wantsGateway) {
+		let storage = null;
+		if (wantsStorage) {
+			storage = await api.getProjectBranchStorage(projectId, branch.id);
+			if (!storage) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy declares object storage (preview.buckets) but storage is not enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or in the Neon Console) — then re-run fetchEnv. Or remove preview.buckets."].join(" "), { details: {
+				projectId,
+				branchId: branch.id
+			} });
+		}
+		const secrets = wantsCredential ? await mintBranchCredential({
+			api,
+			projectId,
+			branchId: branch.id,
+			branchName: branch.name,
+			scopes: previewCredentialScopes(desired.preview)
+		}) : null;
+		if (storage) {
+			const storageEnv = {};
+			if (secrets && wants(K.storage.accessKeyId)) storageEnv.accessKeyId = secrets.accessKeyId;
+			if (secrets && wants(K.storage.secretAccessKey)) storageEnv.secretAccessKey = secrets.secretAccessKey;
+			if (wants(K.storage.endpoint)) storageEnv.endpoint = storage.s3Endpoint;
+			if (wants(K.storage.region)) storageEnv.region = storage.region;
+			result.storage = storageEnv;
+		}
+		if (wantsGateway) {
+			const gateway = {};
+			if (secrets && wants(K.aiGateway.apiKey)) gateway.apiKey = secrets.apiToken;
+			if (wants(K.aiGateway.baseUrl)) gateway.baseUrl = aiGatewayBaseUrl(branch.id, unpooled.uri);
+			result.aiGateway = gateway;
+		}
+	}
+	return result;
+}
+/**
+* Resolve the target branch and evaluate the policy against it — the first thing any
+* branch-scoped operation needs. Shared by {@link fetchEnv} and {@link fetchEnvReusingSecrets}
+* so the two agree on which branch they're talking about and what it has enabled.
+*/
+async function resolveBranchPolicy(config, options, api) {
+	const projectId = options.projectId;
+	const branches = await api.listBranches(projectId);
+	if (branches.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: project ${projectId} has no branches.`, "Deploy your neon.ts policy (or create a branch) first, or pick a different project id."].join(" "), { details: { projectId } });
+	const branchRef = options.branch ?? options.branchId;
+	if (!branchRef) throw new PlatformError(ErrorCode.BranchNotFound, ["fetchEnv: no branch provided.", "Pass `branch` with a branch name (e.g. `main`) or id (`br-…`)."].join(" "), { details: { projectId } });
+	const branch = resolveBranch(branchRef, branches);
+	return {
+		branch,
+		desired: resolveConfig(config, {
+			name: branch.name,
+			id: branch.id,
+			exists: true,
+			...branch.parentId ? { parentId: branch.parentId } : {},
+			isDefault: branch.isDefault,
+			isProtected: branch.protected,
+			...branch.expiresAt ? { expiresAt: branch.expiresAt } : {}
+		})
+	};
+}
+/**
+* Scopes the branch credential should carry for a resolved branch policy. Only object storage
+* and the AI Gateway *require* a credential; functions never force one (they have no credential
+* of their own), but `functions:invoke` is added to the scope set when a credential is already
+* being minted for storage / the AI Gateway, so the one credential can invoke the branch's
+* functions too. Returns `[]` only when nothing credential-bearing is enabled.
+*/
+function previewCredentialScopes(preview) {
+	if (!preview) return [];
+	const storage = preview.buckets.length > 0;
+	const aiGateway = preview.aiGatewayEnabled;
+	if (!storage && !aiGateway) return [];
+	return deriveCredentialScopes({
+		storage,
+		aiGateway,
+		functions: preview.functions.length > 0
+	});
+}
+/** The `name` this tool stamps on every credential it mints, so it can recognize its own. */
+function credentialName(branchName) {
+	return `neon-env ${branchName}`;
+}
+/** The env-var keys a branch credential's secrets surface under, in emit order. */
+function credentialEnvKeys(flags) {
+	return [...flags.storage ? [NEON_ENV_VAR_KEYS.storage.accessKeyId, NEON_ENV_VAR_KEYS.storage.secretAccessKey] : [], ...flags.aiGateway ? [NEON_ENV_VAR_KEYS.aiGateway.apiKey] : []];
+}
+/**
+* Every OS-level env var a resolved branch policy produces, in emit order. Lets a caller
+* subtract the ones it already holds and pass the rest as {@link fetchEnv}'s `keys`, without
+* re-deriving which vars a policy implies.
+*/
+function policyEnvKeys(desired) {
+	const K = NEON_ENV_VAR_KEYS;
+	return [
+		K.postgres.databaseUrl,
+		K.postgres.databaseUrlUnpooled,
+		K.branch.name,
+		...desired.authEnabled ? [K.auth.baseUrl, K.auth.jwksUrl] : [],
+		...desired.dataApiEnabled ? [K.dataApi.url] : [],
+		...(desired.preview?.buckets.length ?? 0) > 0 ? [
+			K.storage.accessKeyId,
+			K.storage.secretAccessKey,
+			K.storage.endpoint,
+			K.storage.region
+		] : [],
+		...desired.preview?.aiGatewayEnabled ? [K.aiGateway.apiKey, K.aiGateway.baseUrl] : []
+	];
+}
+/**
+* Mint the branch credential backing object storage / the AI Gateway.
+*
+* `api_token` and `s3_secret_access_key` come back **exactly once** — they are not stored
+* server-side and the list endpoint returns metadata only — so the caller's copy is the only
+* copy. That is why {@link fetchEnv} mints rather than fetches: there is nothing to fetch. A
+* caller that already holds a valid copy should leave the secret keys out of `keys` (see
+* {@link fetchEnvReusingSecrets}) instead of minting one it will discard.
+*/
+async function mintBranchCredential(args) {
+	const minted = await args.api.createCredential(args.projectId, args.branchId, {
+		scopes: args.scopes,
+		principalType: "user",
+		name: credentialName(args.branchName)
+	});
+	return {
+		accessKeyId: minted.tokenId,
+		secretAccessKey: minted.s3SecretAccessKey,
+		apiToken: minted.apiToken
+	};
+}
+/**
+* The AI Gateway is a **branch-scoped host** — `<branchId>-api.ai.<host-suffix>` — NOT the
+* control-plane API origin. Derive the suffix from the branch's own Postgres connection host
+* by dropping only the endpoint label (the first segment) and keeping everything after it,
+* including any infra cell prefix (`c-N.`): a connection host of
+* `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 aiGatewayHost(branchId, connectionUri) {
+	let connectionHost = "";
+	try {
+		connectionHost = new URL(connectionUri).hostname;
+	} catch {
+		connectionHost = "";
+	}
+	return `${branchId}-api.ai.${connectionHost.split(".").slice(1).join(".")}`;
+}
+/** The AI Gateway's bare base URL (`NEON_AI_GATEWAY_BASE_URL`) on the branch gateway host. */
+function aiGatewayBaseUrl(branchId, connectionUri) {
+	return `https://${aiGatewayHost(branchId, connectionUri)}`;
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("fetchEnv", {
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+/**
+* Resolve a branch ref — a name or an id — to a concrete branch. Matches by id first
+* (exact `br-…`), then by name; both are unique within a project, so the lookup is
+* unambiguous. This lets `.neon` files written by `neonctl` (which pin the branch *name*)
+* and explicit `br-…` ids both work.
+*/
+function resolveBranch(branch, branches) {
+	const match = branches.find((b) => b.id === branch) ?? branches.find((b) => b.name === branch);
+	if (match) return match;
+	throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${JSON.stringify(branch)} not found on project (matched by id or name).`, `Existing branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ")}.`].join(" "), { details: {
+		branch,
+		available: branches.map((b) => `${b.name} (${b.id})`)
+	} });
+}
+function pickRoleName(roles, branch, requested) {
+	if (requested) {
+		if (!roles.some((r) => r.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: role "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing roles: ${roles.map((r) => r.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			roleName: requested,
+			availableRoles: roles.map((r) => r.name)
+		} });
+		return requested;
+	}
+	if (roles.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no roles.`, "Create one via the Neon console or pass `roleName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	if (roles.length === 1) return roles[0].name;
+	const owner = roles.find((r) => r.name === NEON_DEFAULT_OWNER_ROLE);
+	if (owner) return owner.name;
+	const appRoles = roles.filter((r) => !NEON_MANAGED_AUTH_ROLES.has(r.name));
+	if (appRoles.length === 1) return appRoles[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${roles.length} roles and none is "${NEON_DEFAULT_OWNER_ROLE}"; cannot auto-pick.`, `Pass \`roleName\` explicitly. Available: ${roles.map((r) => r.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableRoles: roles.map((r) => r.name)
+	} });
+}
+function pickDatabaseName(databases, branch, requested) {
+	if (requested) {
+		if (!databases.some((d) => d.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: database "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing databases: ${databases.map((d) => d.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			databaseName: requested,
+			availableDatabases: databases.map((d) => d.name)
+		} });
+		return requested;
+	}
+	if (databases.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no databases.`, "Create one via the Neon console or pass `databaseName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	const neondb = databases.find((d) => d.name === NEON_DEFAULT_DATABASE);
+	if (neondb) return neondb.name;
+	if (databases.length === 1) return databases[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${databases.length} databases and none is named "${NEON_DEFAULT_DATABASE}"; cannot auto-pick.`, `Rename one to "${NEON_DEFAULT_DATABASE}" or keep a single database on the branch (or, when calling fetchEnv directly, pass \`databaseName\`). Available: ${databases.map((d) => d.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableDatabases: databases.map((d) => d.name)
+	} });
+}
+/**
+* Project a fully-resolved {@link NeonEnv} into the OS-level `{ KEY: value }` pairs used
+* for cross-process transport. Named after the web-platform `.entries()` convention
+* (`URLSearchParams` / `Headers` / `FormData`); returns a `Record` rather than an
+* iterator of tuples since that's the shape env injection needs (wrap with
+* `Object.entries(...)` if you want literal `[key, value]` pairs). Used by `neon-env run`
+* to inject the vars into a subprocess's `process.env`.
+*
+* Walks the value at runtime so it works for any `NeonEnv<C>` regardless of which
+* conditional namespaces are present.
+*/
+function toEntries(env) {
+	const out = {};
+	const put = (key, value) => {
+		if (value !== void 0) out[key] = value;
+	};
+	const K = NEON_ENV_VAR_KEYS;
+	put(K.postgres.databaseUrl, env.postgres?.databaseUrl);
+	put(K.postgres.databaseUrlUnpooled, env.postgres?.databaseUrlUnpooled);
+	put(K.branch.name, env.branch?.name);
+	put(K.auth.baseUrl, env.auth?.baseUrl);
+	put(K.auth.jwksUrl, env.auth?.jwksUrl);
+	put(K.dataApi.url, env.dataApi?.url);
+	put(K.storage.accessKeyId, env.storage?.accessKeyId);
+	put(K.storage.secretAccessKey, env.storage?.secretAccessKey);
+	put(K.storage.endpoint, env.storage?.endpoint);
+	put(K.storage.region, env.storage?.region);
+	put(K.aiGateway.apiKey, env.aiGateway?.apiKey);
+	put(K.aiGateway.baseUrl, env.aiGateway?.baseUrl);
+	return out;
+}
+//#endregion
+export { NEON_ENV_VAR_KEYS, createApiFromOptions, credentialEnvKeys, credentialName, fetchEnv, fetchEnvKeys, policyEnvKeys, previewCredentialScopes, resolveBranchPolicy, toEntries };

package/dist/_shared/env-core/reuse-secrets.js

@@ -0,0 +1,179 @@
+import { NEON_ENV_VAR_KEYS, createApiFromOptions, credentialEnvKeys, credentialName, fetchEnvKeys, policyEnvKeys, previewCredentialScopes, resolveBranchPolicy, toEntries } from "./env.js";
+import { credentialScopesSatisfied } from "@neon/config/v1";
+//#region src/_shared/env-core/reuse-secrets.ts
+/**
+* Resolve a branch's env while keeping one-time secrets the caller already holds.
+*
+* {@link fetchEnvKeys} — and the public `fetchEnv` — only ever *fetch*. The Neon API returns a
+* credential's `api_token` / `s3_secret_access_key` exactly once, at mint time, so "fetching"
+* them means minting a new credential; a plain `fetchEnv` on every `neon dev` start or `env
+* pull` would leave a live credential behind each time. This is the wrapper that avoids that:
+* it looks at what the caller already has, decides what is still usable, and asks `fetchEnv`
+* for only the rest.
+*
+* The check is a real verification, not a presence test. A persisted secret is kept only when
+* it names a credential that still exists on this branch, is not revoked or expired, and
+* carries every scope the policy needs. A `.env.example` placeholder, a credential revoked in
+* the console, one copied in from another branch, or one predating a newly-enabled feature all
+* fail that check and get replaced.
+*
+* None of this needs local bookkeeping, because the secrets carry their own credential id:
+* `AWS_ACCESS_KEY_ID` **is** the credential's `tokenId` (the storage gateway authenticates
+* against the full id), and the AI Gateway token is minted as `nt_live_<tokenIdShort>_<secret>`,
+* where `tokenIdShort` is what the credentials list reports. The env source being replaced is
+* the record of what the last call issued.
+*
+* ```ts
+* import { fetchEnvReusingSecrets } from "../_shared/env-core/reuse-secrets.js";
+*
+* const { vars, credential } = await fetchEnvReusingSecrets(config, {
+*     projectId,
+*     branch: "main",
+*     env: { ...process.env, ...readEnvFile(".env") },
+* });
+* if (credential.issued) console.log(`new values for ${credential.keys.join(", ")}`);
+* ```
+*/
+async function fetchEnvReusingSecrets(config, options) {
+	const { env: source = process.env, revokeSuperseded = true, ...fetchOptions } = options;
+	const api = options.api ?? createApiFromOptions(options);
+	const { branch, desired } = await resolveBranchPolicy(config, options, api);
+	const storageEnabled = (desired.preview?.buckets.length ?? 0) > 0;
+	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
+	const secretKeys = credentialEnvKeys({
+		storage: storageEnabled,
+		aiGateway: gatewayEnabled
+	});
+	if (secretKeys.length === 0) {
+		const fetched = await fetchEnvKeys(config, fetchOptions, null);
+		return {
+			vars: preferPersisted(toEntries(fetched), source),
+			credential: {
+				issued: false,
+				keys: [],
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const persisted = readPersistedSecrets(source);
+	const complete = (!storageEnabled || Boolean(persisted.accessKeyId && persisted.secretAccessKey)) && (!gatewayEnabled || Boolean(persisted.apiToken));
+	const named = persisted.accessKeyId !== "" || persisted.apiToken !== "" ? namedCredentials(await api.listCredentials(options.projectId, branch.id), persisted) : {
+		storage: null,
+		gateway: null
+	};
+	const reusable = complete ? reusableCredential(named, {
+		storageEnabled,
+		gatewayEnabled
+	}) : null;
+	const scopes = previewCredentialScopes(desired.preview);
+	const keep = reusable !== null && credentialScopesSatisfied(reusable.scopes, scopes);
+	const allKeys = policyEnvKeys(desired);
+	const fetchKeys = keep ? allKeys.filter((key) => !secretKeys.includes(key)) : allKeys;
+	const fetched = await fetchEnvKeys(config, {
+		...fetchOptions,
+		branchId: branch.id,
+		api
+	}, fetchKeys);
+	const vars = preferPersisted(toEntries(fetched), source);
+	if (keep) {
+		for (const key of secretKeys) {
+			const value = source[key];
+			if (value !== void 0) vars[key] = value;
+		}
+		return {
+			vars,
+			credential: {
+				issued: false,
+				keys: secretKeys,
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const ours = /* @__PURE__ */ new Set();
+	for (const meta of [named.storage, named.gateway]) if (meta !== null && meta.principalType === "user" && meta.name === credentialName(branch.name)) ours.add(meta.tokenId);
+	if (revokeSuperseded) for (const tokenId of ours) await api.revokeCredential(options.projectId, branch.id, tokenId);
+	return {
+		vars,
+		credential: {
+			issued: true,
+			keys: secretKeys,
+			revoked: revokeSuperseded ? [...ours] : [],
+			superseded: revokeSuperseded ? [] : [...ours]
+		}
+	};
+}
+/** Read the branch credential's secrets out of an env source. */
+function readPersistedSecrets(source) {
+	const storage = NEON_ENV_VAR_KEYS.storage;
+	const gateway = NEON_ENV_VAR_KEYS.aiGateway;
+	return {
+		accessKeyId: source[storage.accessKeyId] ?? "",
+		secretAccessKey: source[storage.secretAccessKey] ?? "",
+		apiToken: source[gateway.apiKey] ?? ""
+	};
+}
+/**
+* Keep a persisted value rather than overwriting it with an empty fetched one.
+*
+* Neon Auth's `base_url` is the case that needs this: integrations created before the API
+* returned it answer with an empty string, and the persisted copy is the only one left. An
+* empty fetched value never carries more information than a non-empty persisted one, so
+* preferring the latter is safe for every var — and it keeps a pull from blanking a working
+* line in someone's `.env`.
+*/
+function preferPersisted(vars, source) {
+	const out = { ...vars };
+	for (const [key, value] of Object.entries(out)) {
+		if (value !== "") continue;
+		const persisted = source[key];
+		if (persisted !== void 0 && persisted !== "") out[key] = persisted;
+	}
+	return out;
+}
+/**
+* The credential id embedded in an AI Gateway token. The API mints them as
+* `nt_live_<tokenIdShort>_<secret>`, and `tokenIdShort` is the public identifier the credentials
+* list reports — so a persisted token names the credential that issued it. Returns `null` for
+* anything not in that shape (a `.env.example` placeholder, a hand-typed value), which callers
+* treat as unverifiable.
+*/
+function gatewayTokenIdShort(apiToken) {
+	return /^nt_live_([^_]+)_.+$/.exec(apiToken)?.[1] ?? null;
+}
+/** Whether an issued credential can still be used: not revoked, not past its expiry. */
+function isLiveCredential(meta, now) {
+	if (meta.revokedAt !== void 0) return false;
+	if (meta.expiresAt === void 0) return true;
+	const expiresAt = Date.parse(meta.expiresAt);
+	return Number.isNaN(expiresAt) || expiresAt > now;
+}
+/**
+* The live credentials the persisted secrets name — at most one per half. A half that names
+* nothing contributes nothing, which is what a placeholder, a credential revoked in the
+* console, and one copied in from another branch all look like from here.
+*/
+function namedCredentials(live, persisted) {
+	const usable = live.filter((meta) => isLiveCredential(meta, Date.now()));
+	const shortId = persisted.apiToken ? gatewayTokenIdShort(persisted.apiToken) : null;
+	return {
+		storage: persisted.accessKeyId ? usable.find((meta) => meta.tokenId === persisted.accessKeyId) ?? null : null,
+		gateway: shortId ? usable.find((meta) => meta.tokenIdShort === shortId) ?? null : null
+	};
+}
+/**
+* The credential the persisted secrets can be *reused* as, or `null`.
+*
+* Strict on purpose: every half the policy enables has to name a live credential, and when both
+* features are enabled they must name the *same* one — they share a single credential, so
+* halves that disagree came from two different calls and neither can be trusted.
+*/
+function reusableCredential(named, enabled) {
+	if (enabled.storageEnabled && enabled.gatewayEnabled) return named.storage && named.gateway && named.storage.tokenId === named.gateway.tokenId ? named.storage : null;
+	if (enabled.storageEnabled) return named.storage;
+	if (enabled.gatewayEnabled) return named.gateway;
+	return null;
+}
+//#endregion
+export { fetchEnvReusingSecrets };