neon 2.46.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/analytics.js

@@ -1,5 +1,5 @@
 import { Analytics } from "@segment/analytics-node";
-import { inspectCredentials } from "./_shared/credentials.js";
+import { inspectCredentials, OAUTH } from "./_shared/credentials.js";
 import { getApiClient, isNeonApiError } from "./api.js";
 import { getAuthContext } from "./auth_context.js";
 import { credentialsPath } from "./config.js";
@@ -14,6 +14,63 @@ const WRITE_KEY = "3SQXn5ejjXWLEJ8xU2PRYhAotLtTaeeV";
  * not be populated yet, so we also scan `process.argv` directly to be safe.
  */
 const hasCurrentBranchArgv = () => process.argv.includes("--current-branch");
+const ANONYMOUS = "anonymous";
+/**
+ * Who to attribute an event to, given whatever identified this invocation.
+ *
+ * Nothing is guaranteed to have identified it: a command can run with no credentials at all,
+ * leaving the id empty. Segment accepts an empty `userId` and forwards it as-is rather than
+ * rejecting it, so the substitution has to happen here. `""` is falsy but not nullish, which
+ * is why the fallback has to be `||`.
+ *
+ * Exported for tests.
+ */
+export const analyticsUserId = (userId) => userId || ANONYMOUS;
+/**
+ * The account an invocation that presented no API key may claim, which is nothing at all
+ * unless stored credentials named a user.
+ *
+ * Both fields are omitted together. An empty account reported under a named method describes
+ * an authentication that did not happen, which is worse than reporting neither.
+ *
+ * Exported for tests.
+ */
+export const storedCredentialAttribution = (storedUserId) => storedUserId ? { accountId: storedUserId, authMethod: OAUTH } : {};
+/**
+ * Which credential telemetry may describe this invocation with.
+ *
+ * `ensureAuth` records a context only when it selected a credential for this invocation, so a
+ * missing context means the global auth middleware selected nothing before this ran. A key
+ * sitting in `args.apiKey` is then not the credential the middleware chose — `neon profile list`
+ * never used it — and must not be queried on its behalf, which would attribute the run to an
+ * account it never authenticated as and add a telemetry-only API call. The local default is the
+ * guess.
+ *
+ * The boundary is deliberately the credential the middleware selected, not every key a handler
+ * may go on to use. Several `profile` subcommands authenticate inside their own handlers —
+ * `create --api-key` verifies the key it is about to store, `rotate-key` mints and revokes — and
+ * those runs are attributed to the local default rather than to the account the handler talked
+ * to. Attributing them to that key puts an `identify` for the signed-in user beside an
+ * `accountId` for a different account.
+ *
+ * A selected key records no file, because it authenticates as its own account rather than out
+ * of one. Reading `DEFAULT` for it would identify the run as whoever is signed in locally, and
+ * that borrowed id would suppress the API lookup that names the key's real owner.
+ *
+ * Exported for tests.
+ */
+export const telemetryCredential = (authContext, apiKey, defaultCredentialsPath) => {
+    if (authContext === null) {
+        return { credentialsPath: defaultCredentialsPath };
+    }
+    if (authContext.source === "api-key") {
+        return { apiKey };
+    }
+    return {
+        apiKey,
+        credentialsPath: authContext.credentialsPath ?? defaultCredentialsPath,
+    };
+};
 let client;
 let clientInitialized = false;
 let userId = "";
@@ -42,7 +99,7 @@ export const initAnalyticsClientMiddleware = (args) => {
     });
     log.debug("Initialized CLI analytics client");
     client.identify({
-        userId: "anonymous",
+        userId: ANONYMOUS,
     });
 };
 /**
@@ -56,28 +113,27 @@ export const analyticsMiddleware = async (args) => {
     if (isCurrentBranchProbe(args)) {
         return;
     }
-    // Read the credentials this invocation actually authenticated with, which `ensureAuth`
-    // recorded. Reading `DEFAULT`'s unconditionally attributed every `--profile`-selected
-    // command to whichever account happened to be the default one.
-    const authenticatedAs = getAuthContext()?.credentialsPath ?? credentialsPath(args.configDir);
-    // Telemetry must never turn a damaged or unreadable credentials file into a failed command.
-    try {
-        const read = inspectCredentials(authenticatedAs);
-        if (read.kind === "ok" &&
-            typeof read.credentials.user_id === "string") {
-            userId = read.credentials.user_id;
+    const { apiKey: keyToQuery, credentialsPath: fileToRead } = telemetryCredential(getAuthContext(), args.apiKey, credentialsPath(args.configDir));
+    if (fileToRead !== undefined) {
+        // Telemetry must never turn a damaged or unreadable credentials file into a failed command.
+        try {
+            const read = inspectCredentials(fileToRead);
+            if (read.kind === "ok" &&
+                typeof read.credentials.user_id === "string") {
+                userId = read.credentials.user_id;
+            }
+            else if (read.kind !== "ok") {
+                log.debug("No usable credentials at %s", fileToRead);
+            }
         }
-        else if (read.kind !== "ok") {
-            log.debug("No usable credentials at %s", authenticatedAs);
+        catch (err) {
+            log.debug("Could not read %s: %s", fileToRead, err);
         }
     }
-    catch (err) {
-        log.debug("Could not read %s: %s", authenticatedAs, err);
-    }
     try {
-        if (args.apiKey) {
+        if (keyToQuery) {
             const apiClient = getApiClient({
-                apiKey: args.apiKey,
+                apiKey: keyToQuery,
                 apiHost: args.apiHost,
             });
             // Populating api key details for analytics
@@ -93,18 +149,19 @@ export const analyticsMiddleware = async (args) => {
             }
         }
         else {
-            args.accountId = userId;
-            args.authMethod = "oauth";
+            const { accountId, authMethod } = storedCredentialAttribution(userId);
+            args.accountId = accountId;
+            args.authMethod = authMethod;
         }
     }
     catch (err) {
         log.debug("Failed to get user id from api", err);
     }
     client.identify({
-        userId: userId?.toString() ?? "anonymous",
+        userId: analyticsUserId(userId),
     });
     client.track({
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         event: "CLI Started",
         properties: getAnalyticsEventProperties(args),
         context: {
@@ -145,7 +202,7 @@ export const sendError = (err, errCode) => {
     }
     client.track({
         event: "CLI Error",
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         properties: getErrorAnalyticsEventProperties(err, errCode, errorEventContext),
     });
     log.debug("Sent CLI error event: %s", errCode);
@@ -156,7 +213,7 @@ export const trackEvent = (event, properties) => {
     }
     client.track({
         event,
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         properties,
     });
     log.debug("Sent CLI event: %s", event);

package/dist/commands/config.js

@@ -1,15 +1,16 @@
 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";
-import { FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, NEON_SERVICES, NO_SERVICES, parseServices, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView, } from "../config_template.js";
+import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView, } from "../config_template.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { log } from "../log.js";
+import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption, } from "../neon_services.js";
 import { assertAiGatewayProvisionable, warnAiGateway, } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { getCliName } from "../utils/cli_name.js";
@@ -27,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
@@ -120,7 +155,13 @@ const missingDependencies = (cwd) => {
  */
 const resolveServices = async (props) => {
     if (props.services !== undefined) {
-        return parseServices(props.services);
+        return parseServices(props.services, {
+            allowed: CONFIG_INIT_SERVICES,
+            whyUnavailable: CONFIG_INIT_UNAVAILABLE,
+            flag: "--services",
+            noneMeans: CONFIG_INIT_NONE_MEANS,
+            onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical)),
+        });
     }
     if (props.pickServices) {
         return props.pickServices();
@@ -217,7 +258,7 @@ export const initCmd = async (props) => {
         log.info("%s are already installed.", REQUIRED_PACKAGES.join(" and "));
     }
     else {
-        const pm = resolvePackageManager();
+        const pm = resolvePackageManager(cwd);
         const args = addDependenciesArgs(pm, missing);
         if (props.install === false) {
             log.info("Install the Neon config packages to use neon.ts: %s %s", pm, args.join(" "));
@@ -285,12 +326,14 @@ export const builder = (argv) => argv
         type: "boolean",
         default: true,
     },
-    services: {
-        describe: `Services the scaffolded neon.ts declares, comma-separated: ${NEON_SERVICES.join(", ")}. ` +
-            `Pass "${NO_SERVICES}" for the bare starter policy. Omitted: pick interactively on a ` +
-            "terminal, starter policy in CI or without a TTY.",
-        type: "string",
-    },
+    services: servicesOption({
+        key: "services",
+        allowed: CONFIG_INIT_SERVICES,
+        noneMeans: CONFIG_INIT_NONE_MEANS,
+        describe: "Services the scaffolded neon.ts declares",
+        also: "Omitted: pick interactively on a terminal, starter policy in " +
+            "CI or without a TTY.",
+    }),
     "from-branch": {
         describe: "Seed neon.ts from a branch's live Neon state instead of asking. Uses the " +
             "branch pinned in .neon, or --branch <name|id>, or the project's default " +
@@ -300,7 +343,12 @@ export const builder = (argv) => argv
         // `default: false` makes `conflicts` reject every `--services` run.
         conflicts: "services",
     },
-}), (args) => initCmd(args));
+}), (args) => initCmd({
+    ...args,
+    // `args` is untyped here, and "flag omitted" has to stay distinct from
+    // "flag given" — it decides whether the picker runs at all.
+    services: servicesFlagValue(args.services),
+}));
 export const handler = (args) => {
     return args;
 };