@neondatabase/env 1.2.3 → 1.3.0

package/README.md

@@ -153,13 +153,15 @@ functions.hello.baseUrl; // string
 
 ### The branch credential
 
-Object storage and the AI Gateway are backed by one branch credential, and the Neon API returns its secrets (`s3_secret_access_key`, `api_token`) **once**, at mint time — they aren't stored server-side, and the list endpoint returns metadata only. So there is nothing to *fetch*: `fetchEnv` mints. Call it on every `neon dev` start and you leave a live credential behind each time.
+Object storage and the AI Gateway are backed by platform default credentials on every branch in a region that has those products (`Default object storage credential`, `Default AI gateway credential`). `fetchEnv` reveals those by exact name. It mints a combined `neon-env ${branch}` credential only when a needed default is missing.
 
-Handling that is the caller's problem, and it is not just "cache the secret": a persisted secret is only reusable if it still names a live credential on that branch — unrevoked, unexpired, and carrying every scope the policy needs. A presence check cannot tell a real secret from a `.env.example` placeholder.
+Secrets (`s3_secret_access_key`, `api_token`) are returned from reveal as well as at mint time. Call `fetchEnv` on every `neon dev` start without reusing what you already hold and you re-reveal the same defaults — or, in a region with no defaults, you leave a live minted credential behind each time.
+
+A persisted secret is only reusable if it still names the platform default (when one exists), or a still-live minted credential (when none does). A presence check cannot tell a real secret from a `.env.example` placeholder.
 
 No local bookkeeping is needed to do it, because the secrets carry their own credential id: `AWS_ACCESS_KEY_ID` **is** the credential's token id, and the AI Gateway token is minted as `nt_live_<tokenIdShort>_<secret>`. So the `.env` you are about to rewrite already records which credential issued it.
 
-The [`neon` CLI](../cli) does all of this — `neon env pull` and `neon dev` reuse a branch credential rather than issuing one per run. If you are calling `fetchEnv` on a loop yourself, `credentialScopesSatisfied` and `deriveCredentialScopes` from `@neon/config/v1`, plus `listCredentials` / `createCredential` / `revokeCredential` on a `NeonApi`, are the pieces you need.
+The [`neon` CLI](../cli) additionally reuses persisted secrets (`neon env pull`, `neon dev`) so a loop does not re-reveal every start. `fetchEnv` itself reveals or mints on every call.
 
 ### Fetching a subset
 
@@ -187,7 +189,7 @@ selected.branch?.name; // string | undefined
 
 `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are one credential and must be selected together. Literal lists that contain only one half are a type error; a runtime-built list that resolves to one half throws before any API request or credential issuance.
 
-Work is skipped, not just the result narrowed. Leave out `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `NEON_AI_GATEWAY_TOKEN` and **no credential is minted at all** — which is exactly how `fetchEnvReusingSecrets` refreshes everything else while keeping secrets you already have. The non-secret vars of those features (`AWS_ENDPOINT_URL_S3`, `AWS_REGION`, `NEON_AI_GATEWAY_BASE_URL`) are branch metadata and stay available on their own.
+Work is skipped, not just the result narrowed. Leave out `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `NEON_AI_GATEWAY_TOKEN` and **no credential is revealed or minted at all** — which is exactly how `fetchEnvReusingSecrets` refreshes everything else while keeping secrets you already have. The non-secret vars of those features (`AWS_ENDPOINT_URL_S3`, `AWS_REGION`, `NEON_AI_GATEWAY_BASE_URL`) are branch metadata and stay available on their own.
 
 ## Connection role & database selection
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as isFunctionBaseUrlKey, d as previewCredentialScopes, f as resolveBranchPolicy, i as credentialName, n as createApiFromOptions, o as fetchEnvKeysState, p as toEntries, r as credentialEnvKeys, t as NEON_ENV_VAR_KEYS, u as policyEnvKeys } from "./env.js";
+import { a as defaultAiGatewayCredential, c as fetchEnvKeysState, d as isLiveCredential, h as toEntries, i as credentialName, m as resolveBranchPolicy, n as createApiFromOptions, o as defaultStorageCredential, p as policyEnvKeys, r as credentialEnvKeys, t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "./env.js";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -12,20 +12,19 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 //#region ../../internals/env-core/dist/reuse-secrets.js
 /**
-* Resolve a branch's env while keeping one-time secrets the caller already holds.
+* Resolve a branch's env while keeping 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.
+* {@link fetchEnvKeys} reveals the platform default credentials (or mints a fallback when a
+* region has none). Calling it on every `neon dev` start would rewrite `.env` with freshly
+* revealed secrets each time. This wrapper looks at what the caller already has, keeps a
+* half when it already *is* that default (storage and gateway are independent credentials),
+* 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.
+* it names a credential that still exists on this branch, is not revoked or expired, and —
+* when defaults exist — *is* that default. A leftover `neon-env ${branch}` credential this
+* tool minted is replaced by the defaults and revoked. A `.env.example` placeholder, a
+* credential revoked in the console, or one copied in from another branch fails that check.
 *
 * 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
@@ -75,47 +74,47 @@ async function fetchEnvReusingSecrets(config, options) {
 	const persisted = readPersistedSecrets(source);
 	const storageCredentialManaged = requested === null || storageCredentialSelected;
 	const gatewayCredentialManaged = requested === null || gatewayCredentialSelected;
-	const complete = (!storageCredentialSelected || Boolean(persisted.accessKeyId && persisted.secretAccessKey)) && (!gatewayCredentialSelected || Boolean(persisted.apiToken));
-	const named = storageCredentialManaged && persisted.accessKeyId !== "" || gatewayCredentialManaged && persisted.apiToken !== "" ? namedCredentials(await api.listCredentials(options.projectId, branch.id), persisted) : {
+	const storageComplete = Boolean(persisted.accessKeyId && persisted.secretAccessKey);
+	const gatewayComplete = Boolean(persisted.apiToken);
+	const listed = storageCredentialManaged && persisted.accessKeyId !== "" || gatewayCredentialManaged && persisted.apiToken !== "" ? await api.listCredentials(options.projectId, branch.id) : [];
+	const named = listed.length > 0 ? namedCredentials(listed, persisted) : {
 		storage: null,
 		gateway: null
 	};
-	const reusable = complete ? reusableCredential(named, {
-		storageEnabled: storageCredentialSelected,
-		gatewayEnabled: gatewayCredentialSelected
-	}) : null;
-	const scopes = previewCredentialScopes(desired.preview, {
-		storage: storageCredentialSelected,
-		aiGateway: gatewayCredentialSelected
-	});
-	const keep = reusable !== null && credentialScopesSatisfied(reusable.scopes, scopes);
-	const fetchKeys = requested === null ? null : keep ? selectedPolicyKeys.filter((key) => !secretKeys.includes(key)) : selectedPolicyKeys;
+	const now = Date.now();
+	const storageDefault = defaultStorageCredential(listed, now);
+	const gatewayDefault = defaultAiGatewayCredential(listed, now);
+	const keepStorage = !storageCredentialSelected || storageComplete && halfReusable(named.storage, storageDefault, ["storage:read", "storage:write"]);
+	const keepGateway = !gatewayCredentialSelected || gatewayComplete && halfReusable(named.gateway, gatewayDefault, ["ai_gateway:invoke"]);
+	const keptSecretKeys = credentialEnvKeys({
+		storage: storageCredentialSelected && keepStorage,
+		aiGateway: gatewayCredentialSelected && keepGateway
+	}).filter((key) => selected.has(key));
+	const fetchKeys = requested === null ? null : selectedPolicyKeys.filter((key) => !keptSecretKeys.includes(key));
 	const fetched = await fetchEnvKeysState(config, {
 		...fetchOptions,
 		branchId: branch.id,
 		api,
-		...keep && requested === null ? { omitKeys: secretKeys } : {}
+		...keptSecretKeys.length > 0 && requested === null ? { omitKeys: keptSecretKeys } : {}
 	}, fetchKeys);
 	const vars = preferPersisted(toEntries(fetched.env), source);
 	const unavailable = fetched.functionUrlsUnavailable ? { functionUrlsUnavailable: true } : {};
-	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: []
-			},
-			...unavailable
-		};
+	for (const key of keptSecretKeys) {
+		const value = source[key];
+		if (value !== void 0) vars[key] = value;
 	}
+	if (!(storageCredentialSelected && !keepStorage || gatewayCredentialSelected && !keepGateway)) return {
+		vars,
+		credential: {
+			issued: false,
+			keys: secretKeys,
+			revoked: [],
+			superseded: []
+		},
+		...unavailable
+	};
 	const ours = /* @__PURE__ */ new Set();
-	for (const meta of [storageCredentialManaged ? named.storage : null, gatewayCredentialManaged ? named.gateway : null]) if (meta !== null && meta.principalType === "user" && meta.name === credentialName(branch.name)) ours.add(meta.tokenId);
+	for (const meta of [storageCredentialManaged && !keepStorage ? named.storage : null, gatewayCredentialManaged && !keepGateway ? named.gateway : null]) 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,
@@ -166,13 +165,6 @@ function preferPersisted(vars, source) {
 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
@@ -187,17 +179,17 @@ function namedCredentials(live, persisted) {
 	};
 }
 /**
-* The credential the persisted secrets can be *reused* as, or `null`.
+* Whether a persisted half can be reused.
 *
-* 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.
+* When a platform default exists, only that default is reusable — a leftover
+* `neon-env ${branch}` mint is replaced. When no default exists (mint fallback),
+* any live credential the secrets name is reusable if it still carries the
+* scopes that half needs.
 */
-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;
+function halfReusable(named, defaultMeta, requiredScopes) {
+	if (named === null) return false;
+	if (defaultMeta !== null) return named.tokenId === defaultMeta.tokenId;
+	return credentialScopesSatisfied(named.scopes, requiredScopes);
 }
 //#endregion
 //#region ../../internals/cli-core/dist/cli_config.js