neon 2.47.0 → 3.0.0

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

@@ -0,0 +1,223 @@
+import { credentialScopesSatisfied, } from "@neon/config/v1";
+import { createApiFromOptions, credentialEnvKeys, credentialName, fetchEnvKeys, NEON_ENV_VAR_KEYS, policyEnvKeys, previewCredentialScopes, resolveBranchPolicy, toEntries, } from "./env.js";
+/**
+ * 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(", ")}`);
+ * ```
+ */
+export 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,
+    });
+    // Nothing credential-backed on this branch, so there is nothing to preserve and no
+    // credential to spend: fetch everything and skip the credentials endpoint entirely.
+    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));
+    // Look the persisted secrets up whenever there are any — not only when they're complete.
+    // An incomplete set still names the credential a newly-enabled feature is about to
+    // supersede (a storage-only credential on a branch that just gained the AI Gateway), and
+    // that one should be revoked rather than left live.
+    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);
+    // Ask for everything the policy produces, minus the secrets we're keeping — which is what
+    // stops `fetchEnv` from minting a credential it doesn't need.
+    const allKeys = policyEnvKeys(desired);
+    const fetchKeys = keep
+        ? allKeys.filter((key) => !secretKeys.includes(key))
+        : allKeys;
+    const fetched = await fetchEnvKeys(config, 
+    // Pass the resolved id so `fetchEnv` targets the same branch this call verified against,
+    // even if `options.branch` was a name that has since been reused.
+    { ...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 !== undefined)
+                vars[key] = value;
+        }
+        return {
+            vars,
+            credential: {
+                issued: false,
+                keys: secretKeys,
+                revoked: [],
+                superseded: [],
+            },
+        };
+    }
+    // A replacement was minted, so revoke what it supersedes: the credentials the old secrets
+    // named, minus any this tool did not issue. Their secrets lived nowhere but the env source
+    // this call replaces, so revoking them strands nothing — and it keeps a branch from
+    // accumulating a live credential per call. Everything else on the branch is left alone: it
+    // may belong to a teammate, another checkout, or a deployed function, and nothing
+    // observable distinguishes those from an orphan of our own.
+    //
+    // Revoked *after* the fetch, so a failed fetch leaves the caller's existing secrets working.
+    const ours = 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 !== undefined && 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 !== undefined)
+        return false;
+    if (meta.expiresAt === undefined)
+        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;
+}

package/dist/commands/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { resolveConfig } from "@neon/config";
-import { apply, createBranch as createBranchFromPolicy, inspect, isPartialBranchCreateError, loadConfigFromFile, PushConflictError, plan, } from "@neon/config-runtime";
+import { dirname, join } from "node:path";
+import { packagesToStage, resolveConfig } from "@neon/config";
+import { apply, assertZipWithinLimits, createBranch as createBranchFromPolicy, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, loadConfigFromFile, PushConflictError, plan, traceNativePackages, } from "@neon/config-runtime";
 import chalk from "chalk";
 import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
@@ -28,11 +28,45 @@ import { autoPullEnvAfterPin } from "./env.js";
  * out of config-runtime's static module graph — and therefore out of the packaged
  * neonctl snapshot, which resolves esbuild dynamically at deploy time.
  */
-const neonctlBundler = async (fn) => zipBundle(await bundleEntry(fn.source, {
-    ...(fn.externalPackages
-        ? { externalPackages: fn.externalPackages }
-        : {}),
-}));
+const neonctlBundler = async (fn) => {
+    const externalPackages = fn.externalPackages ?? [];
+    const { files, metafile, warnings } = await bundleEntry(fn.source, {
+        externalPackages: externalPackages.map((pkg) => pkg.name),
+    });
+    for (const warning of warnings)
+        log.warning(warning);
+    // Advisory only — the evidence cannot prove the code path is reached, so a package with a
+    // working JavaScript fallback must not have its deploy blocked. See native-detect.
+    for (const finding of findUndeclaredNativePackages({
+        metafile,
+        declared: externalPackages.map((pkg) => pkg.name),
+        projectDir: dirname(fn.source),
+    })) {
+        log.warning(describeNativeFinding(fn.slug, finding));
+    }
+    const staged = packagesToStage(externalPackages);
+    // Nothing to stage is the pre-existing path: zip the esbuild output and nothing else,
+    // producing the archive it always did.
+    if (staged.length === 0)
+        return zipBundle(files);
+    // Staged packages are installed for the runtime target, traced, and merged in under their
+    // `node_modules/...` paths. The tree layout is load-bearing — a `.node` addon finds its
+    // sibling shared libraries relative to its own directory.
+    const traced = await traceNativePackages({
+        slug: fn.slug,
+        packages: staged,
+        projectDir: dirname(fn.source),
+    });
+    for (const warning of traced.warnings)
+        log.warning(warning);
+    const entries = { ...files, ...traced.entries };
+    // Re-checked against the final archive: the staged files were measured without the
+    // bundle, so the entry count and uncompressed total are only complete now.
+    enforceLimits(fn.slug, entries);
+    const zip = zipBundle(entries);
+    assertZipWithinLimits(fn.slug, zip, entries);
+    return zip;
+};
 const INSPECT_FIELDS = ["project", "branch", "config"];
 /**
  * Shared `--env` flag for `config plan|apply` and `deploy`. Loads a `.env` into

package/dist/commands/dev.js

@@ -1,8 +1,9 @@
 import { spawn, spawnSync } from "node:child_process";
 import { once } from "node:events";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { describeNativeFinding, findUndeclaredNativePackages, } from "@neon/config-runtime";
 import chalk from "chalk";
 import { resolveDevEnv } from "../dev/env.js";
 import { resolveFunctionsFromConfig, } from "../dev/functions.js";
@@ -119,7 +120,7 @@ const runSingleSource = async (props) => {
     const unit = {
         slug: null,
         source,
-        bundleDir: join(process.cwd(), "node_modules", ".neon-dev"),
+        bundleDir: devBundleDir(process.cwd()),
         childEnv: buildChildEnv(neonEnv, portFromProps(props.port)),
         label: null,
         envSummary: { neon: Object.keys(neonEnv), fn: [] },
@@ -213,6 +214,19 @@ const portFromProps = (port) => {
     }
     return { mode: "search", from: DEFAULT_PORT_BASE };
 };
+/**
+ * Where a locally-served function's bundle is written.
+ *
+ * The location inside the project's own `node_modules` is load-bearing, not a tidiness
+ * choice. A function's `externalPackages` are left unbundled, and Node resolves an unbundled
+ * import by walking up from the importing file — so from here it reaches the project's real
+ * `node_modules` and finds them, at the host architecture that can actually run locally.
+ * Moving this directory anywhere outside `node_modules` breaks `neon dev` for those
+ * functions with a `Cannot find module`, so the path is pinned by a test.
+ */
+export const devBundleDir = (cwd, slug) => slug === undefined
+    ? join(cwd, "node_modules", ".neon-dev")
+    : join(cwd, "node_modules", ".neon-dev", slug);
 /**
  * Translate a {@link PlannedFunction} into a {@link ServedUnit}. Port rules:
  *   - explicit `dev.port`: bind exactly, fail if taken.
@@ -227,7 +241,7 @@ const plannedToUnit = (fn, branchEnv, searchBase) => {
     return {
         slug: fn.slug,
         source: fn.source,
-        bundleDir: join(process.cwd(), "node_modules", ".neon-dev", fn.slug),
+        bundleDir: devBundleDir(process.cwd(), fn.slug),
         childEnv,
         label: fn.slug,
         envSummary: { neon: Object.keys(branchEnv), fn: Object.keys(fn.env) },
@@ -286,7 +300,9 @@ const runSupervisor = async (units, options = {}) => {
     const bundleAndStart = async (r) => {
         let bundlePath;
         try {
-            bundlePath = await writeBundle(r.unit.source, r.unit.bundleDir, r.unit.externalPackages);
+            bundlePath = await writeBundle(r.unit.source, r.unit.bundleDir, r.unit.externalPackages, 
+            // The `neon.ts` key, so a function is named the same way here as at deploy.
+            r.unit.slug ?? undefined);
         }
         catch (err) {
             r.status = "error";
@@ -534,10 +550,35 @@ const spawnChild = (unit, runtimePath, bundlePath) => {
         detached: true,
     });
 };
-const writeBundle = async (source, bundleDir, externalPackages) => {
-    const files = await bundleEntry(source, {
+/**
+ * Findings already reported for a served unit, so an advisory that cannot change between
+ * saves is not reprinted on every one. A dev session on a project with a standing false
+ * positive would otherwise repeat the whole block for its lifetime.
+ */
+const reportedFindings = new Map();
+const writeBundle = async (source, bundleDir, externalPackages, label) => {
+    // Left unbundled only. `bundleDir` sits inside the project's node_modules, so an
+    // externalized package resolves from the real tree at the host architecture — no install
+    // or copy is needed or wanted locally, whatever `includeFiles` says for a deploy.
+    const { files, metafile, warnings } = await bundleEntry(source, {
         ...(externalPackages ? { externalPackages } : {}),
     });
+    for (const warning of warnings)
+        log.warning(warning);
+    // Local runs resolve native packages from the real tree, so a missing declaration is
+    // invisible until deploy. Reporting it here is the only signal before then.
+    const findings = findUndeclaredNativePackages({
+        metafile,
+        declared: externalPackages ?? [],
+        projectDir: dirname(source),
+    });
+    const signature = findings.map((f) => f.name).join(",");
+    if (reportedFindings.get(source) !== signature) {
+        reportedFindings.set(source, signature);
+        for (const finding of findings) {
+            log.warning(describeNativeFinding(label ?? basename(source), finding));
+        }
+    }
     mkdirSync(bundleDir, { recursive: true });
     // bundleEntry emits a single `index.mjs` (no source map). The `.mjs` extension makes Node
     // load it as ESM directly, so no `package.json` `"type": "module"` marker is needed.

package/dist/commands/env.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import { NEON_ENV_VAR_KEYS } from "@neon/env";
 import chalk from "chalk";
+import { NEON_ENV_VAR_KEYS } from "../_shared/env-core/env.js";
 import { ensureGitignored } from "../context.js";
 import { resolveNeonEnvVars } from "../dev/env.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";

package/dist/commands/functions.js

@@ -1,5 +1,6 @@
 import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { describeNativeFinding, findUndeclaredNativePackages, } from "@neon/config-runtime";
 import { isNeonApiError, retryOnLock } from "../api.js";
 import { createDeployment, deleteFunction, getFunction, listFunctions, } from "../functions_api.js";
 import { log } from "../log.js";
@@ -194,7 +195,20 @@ const deploy = async (props) => {
         throw new Error(`No entry file found in ${src}. Expected one of: ${ENTRY_CANDIDATES.join(", ")}.`);
     }
     // Bundle before any network round-trip so a bundling failure fails fast.
-    const zip = zipBundle(await bundleEntry(source));
+    const bundled = await bundleEntry(source);
+    for (const warning of bundled.warnings)
+        log.warning(warning);
+    // `--src` bypasses `neon.ts`, so there is no policy to declare anything in and no way to
+    // stage files here. The advisory still runs: this is the shortest path to a function that
+    // deploys clean and then fails at invoke, so it is the last place to stay silent.
+    for (const finding of findUndeclaredNativePackages({
+        metafile: bundled.metafile,
+        declared: [],
+        projectDir: dirname(source),
+    })) {
+        log.warning(describeNativeFinding(props.slug, finding));
+    }
+    const zip = zipBundle(bundled.files);
     const branchId = await branchIdFromProps(props);
     // Snapshot the current version before deploy so we can detect the new one
     // afterward. A missing function (404) or no deployment yet → undefined.

package/dist/dev/env.js

@@ -1,7 +1,7 @@
 import { createNeonApiFromOptions, loadConfigFromFile, } from "@neon/config";
 import { plan, pullConfig } from "@neon/config-runtime";
-import { NEON_ENV_VAR_KEYS } from "@neon/env";
-import { fetchEnvReusingSecrets, } from "@neon/env/runtime";
+import { NEON_ENV_VAR_KEYS } from "../_shared/env-core/env.js";
+import { fetchEnvReusingSecrets, } from "../_shared/env-core/reuse-secrets.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 /** The API-targeting options every runtime call forwards from the context. */

package/dist/dev/functions.js

@@ -36,8 +36,12 @@ export const resolveFunctionsFromConfig = async (cwd, branchName) => {
                 ? { port: devPort(fn.dev) }
                 : {}),
             env: { ...fn.env },
+            // Names only: locally every entry is simply left unbundled, and `includeFiles`
+            // governs the deployed archive, which `neon dev` does not build.
             ...(fn.externalPackages
-                ? { externalPackages: [...fn.externalPackages] }
+                ? {
+                    externalPackages: fn.externalPackages.map((pkg) => pkg.name),
+                }
                 : {}),
         };
     });

package/dist/env_services.js

@@ -1,4 +1,4 @@
-import { NEON_ENV_VAR_KEYS } from "@neon/env";
+import { NEON_ENV_VAR_KEYS } from "./_shared/env-core/env.js";
 import { NEON_SERVICES } from "./neon_services.js";
 /**
  * The services `env pull --service` can select: every Neon service that produces branch env