neon 4.4.0 → 4.5.0

package/README.md

@@ -64,6 +64,57 @@ neon projects list --api-key <neon_api_key>
 
 For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
+## Create a project without an account
+
+`neon claim create` provisions a temporary Claimable Neon project for an agent without
+requiring a Neon account or opening a browser:
+
+```bash
+# Lakebase Postgres is always included
+neon claim create
+
+# Request Managed Better Auth and the Data API too
+neon claim create --service auth --service data-api
+```
+
+When the current directory has a `neon.ts`, `claim create` also requests every service
+declared there. Explicit `--service` values are added to that set. Object Storage, Functions,
+and the AI Gateway are sent to the service so demand is recorded, but are reported as
+unavailable until the project is claimed; the CLI does not silently remove them.
+
+The command writes:
+
+- a `.neon` context that identifies the project and Claimable Neon service;
+- an owner-only identity assertion under the CLI config directory;
+- `DATABASE_URL` and any granted Auth or Data API variables to `.env` or `.env.local`
+  (disable this with `--no-env-pull`).
+
+Subsequent project commands automatically exchange the assertion for a short-lived agent
+token and send API calls to Claimable Neon. The service decides which operations are
+allowed before claim.
+
+```bash
+neon claim status                 # lifecycle and transfer status
+neon projects get <project-id>    # regular CLI command, same agent token
+neon psql --role-name neondb_owner -- -c "select now()"
+neon config plan
+neon env pull --service postgres --service auth --service data-api
+
+neon claim accept                 # create a claim code and open the transfer URL
+neon claim delete --yes           # permanently delete an unclaimed project
+neon claim list                   # local records, including expired
+neon claim delete <project-id> --yes
+```
+
+`status`, `accept`, and `delete` take an optional project id from `claim list`, so a
+project stays manageable after its original directory is gone. `list` prints `state`
+(`unclaimed` or `expired`) from the identity assertion clock and the project
+expiry, plus `project_expires_at`. `delete` also drops a
+local record whose identity assertion has expired or been revoked.
+
+`neon claimable` is an alias for `neon claim`. For local service development, set
+`CLAIMABLE_NEON_HOST=http://localhost:8787`; non-local origins must use HTTPS.
+
 ## Project and branch creation
 
 Choose the PostgreSQL version when creating a project:
@@ -1173,6 +1224,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
 | [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                              | Authenticate                       |
+| claim (`claimable`)                                                        | `create`, `status`, `accept`, `list`, `delete`                                                               | Manage claimable projects          |
 | profile                                                                    | `list`, `create`, `rotate-key`, `remove`                                                                     | Manage named sets of credentials   |
 | api-keys                                                                   | `list`, `create`, `revoke`                                                                                   | Manage API keys                    |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |

package/dist/_chunks/{auth_selection-Bx2NAgkk.js → auth_selection-ktL6uoEe.js}

@@ -1,4 +1,4 @@
-import "./profiles-CVXNvU2r.js";
+import "./profiles-D95AeZ5v.js";
 //#region ../../internals/cli-core/dist/auth_selection.js
 /**
 * # Which credential an invocation authenticates with

package/dist/_chunks/{credential_io-D2vw1UOw.js → credential_io-B1JxWELN.js}

@@ -1,5 +1,6 @@
-import { b as writeSecretFile, f as profilesFilePath, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "./profiles-CVXNvU2r.js";
+import { t as writeSecretFile } from "./secure_file-BucZj4yQ.js";
 import { o as isOwnedCredentialPath } from "./paths-g3DRqJiD.js";
+import { f as profilesFilePath, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "./profiles-D95AeZ5v.js";
 import { tryLoadKeyring } from "../keyring.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";

package/dist/_chunks/{profiles-CVXNvU2r.js → profiles-D95AeZ5v.js}

@@ -1,42 +1,7 @@
+import { t as writeSecretFile } from "./secure_file-BucZj4yQ.js";
 import { i as defaultDir, r as credentialsPath, s as resolveConfigFile } from "./paths-g3DRqJiD.js";
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-//#region ../../internals/cli-core/dist/secure_file.js
-/**
-* Write a secret to disk owner-only, by creating a temporary file in the same directory and
-* renaming it over the target.
-*
-* The rename is what makes this correct rather than merely tidy. `writeFileSync`'s `mode`
-* applies only when it *creates* the file, so writing over an existing credentials file
-* leaves whatever permissions it already had — a file created `0700` by an older release
-* stays `0700` forever, and one created before a umask change stays world-readable. Renaming
-* a fresh inode into place means every write lands at {@link SECRET_FILE_MODE}, so the
-* permissions repair themselves instead of being inherited.
-*
-* It also closes the window where a reader could see the file at default permissions: the
-* temporary file is created `0600` *before* it holds the secret's final name, and `rename`
-* is atomic within a directory, so there is no moment at which the target is readable by
-* anyone else and no moment at which it is half-written.
-*
-* The temporary name carries the pid so two processes writing at once cannot collide on it.
-*/
-const writeSecretFile = (path, contents) => {
-	const directory = dirname(path);
-	const temporary = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
-	try {
-		writeFileSync(temporary, contents, {
-			encoding: "utf8",
-			mode: 384
-		});
-		renameSync(temporary, path);
-	} catch (err) {
-		try {
-			unlinkSync(temporary);
-		} catch {}
-		throw err;
-	}
-};
-//#endregion
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
 //#region ../../internals/cli-core/dist/cli_config.js
 const CRED_STORAGE_FILE = "file";
 const CRED_STORAGE_KEYRING = "keyring";
@@ -254,4 +219,4 @@ function nonEmpty(value) {
 	return trimmed === "" ? void 0 : trimmed;
 }
 //#endregion
-export { upsertProfile as _, canDropProfilesFile as a, writeSecretFile as b, listProfiles as c, newProfileLocation as d, profilesFilePath as f, selectProfileName as g, resolveProfile as h, assertValidProfileName as i, locationForName as l, readProfiles as m, KEYRING_CREDENTIALS as n, credentialsDisplay as o, profilesUsingPath as p, assertProfilesUsable as r, isKeyringPointer as s, DEFAULT_PROFILE as t, locationOf as u, CRED_STORAGE_FILE as v, CRED_STORAGE_KEYRING as y };
+export { upsertProfile as _, canDropProfilesFile as a, listProfiles as c, newProfileLocation as d, profilesFilePath as f, selectProfileName as g, resolveProfile as h, assertValidProfileName as i, locationForName as l, readProfiles as m, KEYRING_CREDENTIALS as n, credentialsDisplay as o, profilesUsingPath as p, assertProfilesUsable as r, isKeyringPointer as s, DEFAULT_PROFILE as t, locationOf as u, CRED_STORAGE_FILE as v, CRED_STORAGE_KEYRING as y };

package/dist/_chunks/secure_file-BucZj4yQ.js

@@ -0,0 +1,39 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+//#region ../../internals/cli-core/dist/secure_file.js
+/**
+* Write a secret to disk owner-only, by creating a temporary file in the same directory and
+* renaming it over the target.
+*
+* The rename is what makes this correct rather than merely tidy. `writeFileSync`'s `mode`
+* applies only when it *creates* the file, so writing over an existing credentials file
+* leaves whatever permissions it already had — a file created `0700` by an older release
+* stays `0700` forever, and one created before a umask change stays world-readable. Renaming
+* a fresh inode into place means every write lands at {@link SECRET_FILE_MODE}, so the
+* permissions repair themselves instead of being inherited.
+*
+* It also closes the window where a reader could see the file at default permissions: the
+* temporary file is created `0600` *before* it holds the secret's final name, and `rename`
+* is atomic within a directory, so there is no moment at which the target is readable by
+* anyone else and no moment at which it is half-written.
+*
+* The temporary name carries the pid so two processes writing at once cannot collide on it.
+*/
+const writeSecretFile = (path, contents) => {
+	const directory = dirname(path);
+	const temporary = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+	try {
+		writeFileSync(temporary, contents, {
+			encoding: "utf8",
+			mode: 384
+		});
+		renameSync(temporary, path);
+	} catch (err) {
+		try {
+			unlinkSync(temporary);
+		} catch {}
+		throw err;
+	}
+};
+//#endregion
+export { writeSecretFile as t };

package/dist/analytics.js

@@ -1,4 +1,4 @@
-import { a as OAUTH, t as storeFor } from "./_chunks/credential_io-D2vw1UOw.js";
+import { a as OAUTH, t as storeFor } from "./_chunks/credential_io-B1JxWELN.js";
 import { getCliAgent, getGithubEnvVars, isCi } from "./env.js";
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";

package/dist/api.js

@@ -52,6 +52,13 @@ function messageFromBody(body) {
 		const message = body.message;
 		if (typeof message === "string") return message;
 	}
+	if (body && typeof body === "object" && "error" in body) {
+		const error = body.error;
+		if (error && typeof error === "object" && "message" in error) {
+			const message = error.message;
+			if (typeof message === "string") return message;
+		}
+	}
 }
 /** Extract a machine-readable `code` string from a parsed error body, if present. */
 function codeFromBody(body) {
@@ -59,6 +66,13 @@ function codeFromBody(body) {
 		const code = body.code;
 		if (typeof code === "string") return code;
 	}
+	if (body && typeof body === "object" && "error" in body) {
+		const error = body.error;
+		if (error && typeof error === "object" && "code" in error) {
+			const code = error.code;
+			if (typeof code === "string") return code;
+		}
+	}
 }
 /**
 * Adapt a WHATWG `ReadableStream` (what `fetch` gives us as `response.body`) to

package/dist/auth_context.js

@@ -38,6 +38,7 @@ const authFailureMessage = (context) => {
 	const profile = context?.profile ?? "the selected profile";
 	const where = context?.storage === "keyring" ? " (OS keyring)" : context?.credentialsPath !== void 0 ? ` (${context.credentialsPath})` : "";
 	if (context?.source === "profile-api-key") return `Authentication failed: the Neon API rejected profile "${profile}"'s API key${where}. Replace it with \`neon profile create ${profile} --mint\`, or store another with \`neon profile create ${profile} --api-key -\`.`;
+	if (context?.source === "claimable") return `Authentication failed: Claimable Neon rejected the linked project's short-lived access token${where}. Retry the command to exchange the saved identity assertion again; if it still fails, run \`neon claim status\`.`;
 	if (context?.source === "stored-credentials") {
 		if (context.storage === "keyring") return `Authentication failed: the Neon API rejected profile "${profile}"'s stored session (OS keyring). Sign in again with \`neon auth --profile ${profile}\`.`;
 		return `Authentication failed: the Neon API rejected profile "${profile}"'s stored session${where}. That file was not created by neon, so it was left alone — sign in again with \`neon auth --profile ${profile}\`.`;

package/dist/claimable/api.js

@@ -0,0 +1,242 @@
+//#region src/claimable/api.ts
+const REQUEST_TIMEOUT_MS = 6e4;
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+const DEFAULT_CLAIMABLE_ORIGIN = "https://claimable.neon.tech";
+var ClaimableServiceError = class extends Error {
+	constructor(status, metadata, details) {
+		super(metadata.message);
+		this.name = "ClaimableServiceError";
+		this.status = status;
+		this.code = metadata.code;
+		this.retryable = metadata.retryable;
+		this.requestId = metadata.requestId;
+		this.details = details;
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const record = (value, action) => {
+	if (!isRecord(value)) throw invalidResponse(action);
+	return value;
+};
+const stringField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "string" || field.length === 0) throw invalidResponse(action);
+	return field;
+};
+const stringFieldAllowEmpty = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "string") throw invalidResponse(action);
+	return field;
+};
+const numberField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "number" || !Number.isFinite(field) || field <= 0) throw invalidResponse(action);
+	return field;
+};
+const booleanField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "boolean") throw invalidResponse(action);
+	return field;
+};
+const stringArrayField = (value, key, action) => {
+	const field = value[key];
+	if (!Array.isArray(field) || !field.every((item) => typeof item === "string" && item.length > 0)) throw invalidResponse(action);
+	return field;
+};
+const invalidResponse = (action) => /* @__PURE__ */ new Error(`Claimable Neon returned an invalid response while ${action}. The response was not used.`);
+const parseCapabilityDecision = (value, action) => {
+	const decision = record(value, action);
+	const capability = stringField(decision, "capability", action);
+	if (booleanField(decision, "granted", action)) return {
+		capability,
+		granted: true
+	};
+	return {
+		capability,
+		granted: false,
+		reason: stringField(decision, "reason", action),
+		message: stringField(decision, "message", action)
+	};
+};
+const parseRegistrationResponse = (value) => {
+	const action = "registering an anonymous identity";
+	const response = record(value, action);
+	const project = record(response.project, action);
+	const capabilities = response.capabilities;
+	if (!Array.isArray(capabilities)) throw invalidResponse(action);
+	return {
+		registrationId: stringField(response, "registration_id", action),
+		identityAssertion: stringField(response, "identity_assertion", action),
+		assertionExpires: numberField(response, "assertion_expires", action),
+		scopes: stringArrayField(response, "scopes", action),
+		project: {
+			id: stringField(project, "id", action),
+			branchId: stringField(project, "branch_id", action),
+			expiresAt: stringField(project, "expires_at", action)
+		},
+		capabilities: capabilities.map((item) => parseCapabilityDecision(item, action))
+	};
+};
+const parseTokenResponse = (value) => {
+	const action = "exchanging the identity assertion";
+	const response = record(value, action);
+	if (response.token_type !== "Bearer") throw invalidResponse(action);
+	return {
+		accessToken: stringField(response, "access_token", action),
+		expiresIn: numberField(response, "expires_in", action),
+		scope: stringFieldAllowEmpty(response, "scope", action)
+	};
+};
+const parseCredentialsResponse = (value) => {
+	const action = "fetching project credentials";
+	const response = record(value, action);
+	const services = record(response.services, action);
+	const authValue = services.auth;
+	const dataApiValue = services.data_api;
+	const auth = authValue === void 0 ? void 0 : (() => {
+		const parsed = record(authValue, action);
+		return {
+			baseUrl: stringField(parsed, "base_url", action),
+			jwksUrl: stringField(parsed, "jwks_url", action)
+		};
+	})();
+	const dataApi = dataApiValue === void 0 ? void 0 : (() => {
+		const parsed = record(dataApiValue, action);
+		return { url: stringField(parsed, "url", action) };
+	})();
+	return {
+		projectId: stringField(response, "project_id", action),
+		branchId: stringField(response, "branch_id", action),
+		databaseUrl: stringField(response, "database_url", action),
+		expiresAt: stringField(response, "expires_at", action),
+		services: {
+			...auth === void 0 ? {} : { auth },
+			...dataApi === void 0 ? {} : { dataApi }
+		}
+	};
+};
+const parseClaimCodeResponse = (value) => {
+	const action = "creating a claim code";
+	const response = record(value, action);
+	return {
+		userCode: stringField(response, "user_code", action),
+		verificationUri: stringField(response, "verification_uri", action),
+		verificationUriComplete: stringField(response, "verification_uri_complete", action),
+		expiresIn: numberField(response, "expires_in", action),
+		interval: numberField(response, "interval", action)
+	};
+};
+const parseClaimStatusResponse = (value) => {
+	const action = "fetching claim status";
+	const response = record(value, action);
+	return {
+		state: stringField(response, "state", action),
+		expiresAt: stringField(response, "expires_at", action),
+		reconciled: booleanField(response, "reconciled", action)
+	};
+};
+const normalizeOrigin = (origin) => {
+	let url;
+	try {
+		url = new URL(origin);
+	} catch {
+		throw new Error(`Invalid Claimable Neon origin "${origin}".`);
+	}
+	if (url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error(`Claimable Neon origin must contain only a scheme and host, got "${origin}".`);
+	if (url.protocol !== "https:" && url.hostname !== "localhost") throw new Error("Claimable Neon requires HTTPS except when testing against localhost.");
+	return url.origin;
+};
+const parseErrorMetadata = (status, statusText, payload) => {
+	if (!isRecord(payload) || !isRecord(payload.error)) return {
+		code: "unknown_error",
+		message: `Claimable Neon returned HTTP ${status} ${statusText}.`,
+		retryable: status === 429 || status >= 500
+	};
+	const error = payload.error;
+	return {
+		code: typeof error.code === "string" && error.code.length > 0 ? error.code : "unknown_error",
+		message: typeof error.message === "string" && error.message.length > 0 ? error.message : `Claimable Neon returned HTTP ${status} ${statusText}.`,
+		retryable: typeof error.retryable === "boolean" ? error.retryable : status === 429 || status >= 500,
+		requestId: typeof error.request_id === "string" ? error.request_id : void 0
+	};
+};
+const readJson = async (response) => {
+	const text = await response.text();
+	if (text.trim() === "") return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error(`Claimable Neon returned non-JSON content with HTTP ${response.status}.`);
+	}
+};
+var ClaimableClient = class {
+	constructor(origin = DEFAULT_CLAIMABLE_ORIGIN) {
+		this.origin = normalizeOrigin(origin);
+	}
+	async register(input) {
+		return parseRegistrationResponse(await this.request("/v1/agent/identity", {
+			method: "POST",
+			json: {
+				type: "anonymous",
+				capabilities: input.capabilities,
+				source: input.source
+			}
+		}));
+	}
+	async exchange(identityAssertion) {
+		return parseTokenResponse(await this.request("/v1/oauth2/token", {
+			method: "POST",
+			form: new URLSearchParams({
+				grant_type: JWT_BEARER_GRANT,
+				assertion: identityAssertion,
+				resource: `${this.origin}/`
+			})
+		}));
+	}
+	async credentials(projectId, accessToken) {
+		return parseCredentialsResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/credentials`, { accessToken }));
+	}
+	async createClaim(projectId, accessToken) {
+		return parseClaimCodeResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/claim`, {
+			method: "POST",
+			accessToken
+		}));
+	}
+	async claimStatus(projectId, accessToken) {
+		return parseClaimStatusResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/claim`, { accessToken }));
+	}
+	async deleteProject(projectId, accessToken) {
+		await this.request(`/v1/projects/${encodeURIComponent(projectId)}`, {
+			method: "DELETE",
+			accessToken
+		});
+	}
+	async request(path, options = {}) {
+		const headers = new Headers({ accept: "application/json" });
+		if (options.accessToken) headers.set("authorization", `Bearer ${options.accessToken}`);
+		let body;
+		if (options.json !== void 0) {
+			headers.set("content-type", "application/json");
+			body = JSON.stringify(options.json);
+		} else if (options.form !== void 0) {
+			headers.set("content-type", "application/x-www-form-urlencoded");
+			body = options.form.toString();
+		}
+		let response;
+		try {
+			response = await fetch(new URL(path, `${this.origin}/`), {
+				method: options.method ?? "GET",
+				headers,
+				body,
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+			});
+		} catch {
+			throw new Error(`Could not reach Claimable Neon at ${this.origin}. Check the connection and retry.`);
+		}
+		const payload = await readJson(response);
+		if (!response.ok) throw new ClaimableServiceError(response.status, parseErrorMetadata(response.status, response.statusText, payload), payload);
+		return payload;
+	}
+};
+//#endregion
+export { ClaimableClient, ClaimableServiceError, DEFAULT_CLAIMABLE_ORIGIN, parseClaimCodeResponse, parseClaimStatusResponse, parseCredentialsResponse, parseRegistrationResponse, parseTokenResponse };

package/dist/claimable/state.js

@@ -0,0 +1,92 @@
+import { t as writeSecretFile } from "../_chunks/secure_file-BucZj4yQ.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+//#region src/claimable/state.ts
+const FILE_PREFIX = "claimable-credential.";
+const FILE_SUFFIX = ".json";
+const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
+const assertProjectId = (projectId) => {
+	if (!PROJECT_ID.test(projectId)) throw new Error(`Invalid Claimable Neon project ID "${projectId}".`);
+};
+const claimableCredentialsPath = (configDir, projectId) => {
+	assertProjectId(projectId);
+	return join(configDir, `${FILE_PREFIX}${projectId}${FILE_SUFFIX}`);
+};
+const parseStoredCredentials = (value, path, expectedProjectId) => {
+	if (!isRecord(value) || value.version !== 1 || !nonEmptyString(value.origin) || !nonEmptyString(value.registrationId) || !nonEmptyString(value.projectId) || !nonEmptyString(value.branchId) || !nonEmptyString(value.identityAssertion) || !nonEmptyString(value.expiresAt)) throw new Error(`${path} does not contain a valid Claimable Neon credential. Delete it and run \`neon claim create\` again.`);
+	assertProjectId(value.projectId);
+	if (expectedProjectId !== void 0 && value.projectId !== expectedProjectId) throw new Error(`${path} belongs to a different Claimable Neon project. Delete it and run \`neon claim create\` again.`);
+	const assertionExpires = optionalUnixSeconds(value.assertionExpires, path);
+	return {
+		version: 1,
+		origin: value.origin,
+		registrationId: value.registrationId,
+		projectId: value.projectId,
+		branchId: value.branchId,
+		identityAssertion: value.identityAssertion,
+		expiresAt: value.expiresAt,
+		...assertionExpires === void 0 ? {} : { assertionExpires }
+	};
+};
+const optionalUnixSeconds = (value, path) => {
+	if (value === void 0) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`${path} does not contain a valid Claimable Neon credential. Delete it and run \`neon claim create\` again.`);
+	return value;
+};
+const assertionHasExpired = (credentials, now = Date.now()) => credentials.assertionExpires !== void 0 && credentials.assertionExpires * 1e3 <= now;
+const writeClaimableCredentials = (configDir, credentials) => {
+	mkdirSync(configDir, { recursive: true });
+	const path = claimableCredentialsPath(configDir, credentials.projectId);
+	writeSecretFile(path, JSON.stringify(credentials));
+};
+const readClaimableCredentials = (configDir, projectId) => {
+	const path = claimableCredentialsPath(configDir, projectId);
+	if (!existsSync(path)) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new Error(`${path} is not valid JSON, so the Claimable Neon credential cannot be read. Delete it and run \`neon claim create\` again.`);
+	}
+	return parseStoredCredentials(parsed, path, projectId);
+};
+const listClaimableCredentials = (configDir) => {
+	if (!existsSync(configDir)) return [];
+	return readdirSync(configDir).filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX)).sort().map((name) => {
+		const path = join(configDir, name);
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(path, "utf8"));
+		} catch {
+			throw new Error(`${path} is not valid JSON, so the Claimable Neon credential cannot be listed. Delete it and run \`neon claim create\` again.`);
+		}
+		return parseStoredCredentials(parsed, path);
+	}).sort((left, right) => left.projectId.localeCompare(right.projectId));
+};
+const removeClaimableCredentials = (configDir, projectId) => {
+	const path = claimableCredentialsPath(configDir, projectId);
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if (isRecord(error) && typeof error.code === "string" && error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const resolveClaimableContext = (context) => {
+	const marker = context.claimable;
+	if (marker === void 0) return null;
+	if (!isRecord(marker)) throw new Error("The linked .neon file has an invalid \"claimable\" marker. Delete the claimable field from .neon, or delete .neon.");
+	if (marker.version !== 1) throw new Error(`Unsupported Claimable Neon context version in .neon. Update the Neon CLI before using this project.`);
+	if (!nonEmptyString(marker.origin) || !nonEmptyString(context.projectId)) throw new Error("The linked .neon file has an incomplete \"claimable\" marker. Delete the claimable field from .neon, or delete .neon.");
+	assertProjectId(context.projectId);
+	return {
+		origin: marker.origin,
+		projectId: context.projectId,
+		...nonEmptyString(context.branch) ? { branch: context.branch } : {}
+	};
+};
+const shouldUseClaimableCredentials = (inputs, profileFlag, context) => inputs.apiKeyFlag.trim() === "" && inputs.apiKeyEnv.trim() === "" && inputs.profileEnv.trim() === "" && (profileFlag === void 0 || profileFlag.trim() === "") && resolveClaimableContext(context) !== null;
+//#endregion
+export { assertionHasExpired, claimableCredentialsPath, listClaimableCredentials, readClaimableCredentials, removeClaimableCredentials, resolveClaimableContext, shouldUseClaimableCredentials, writeClaimableCredentials };

package/dist/commands/auth.js

@@ -1,15 +1,17 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { _ as upsertProfile, d as newProfileLocation, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, t as DEFAULT_PROFILE, u as locationOf } from "../_chunks/profiles-CVXNvU2r.js";
-import { a as OAUTH, i as API_KEY, l as interpretCredentials, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-D2vw1UOw.js";
+import { a as OAUTH, i as API_KEY, l as interpretCredentials, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-B1JxWELN.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { o as isOwnedCredentialPath } from "../_chunks/paths-g3DRqJiD.js";
 import { setAuthContext } from "../auth_context.js";
-import { isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand } from "../context.js";
+import { currentContextFile, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile } from "../context.js";
+import { _ as upsertProfile, d as newProfileLocation, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, t as DEFAULT_PROFILE, u as locationOf } from "../_chunks/profiles-D95AeZ5v.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { auth, refreshToken } from "../auth.js";
-import { i as selectCredential, n as displacedProfileWarning, t as credentialInputs } from "../_chunks/auth_selection-Bx2NAgkk.js";
+import { i as selectCredential, n as displacedProfileWarning, t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.js";
+import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
+import { assertionHasExpired, claimableCredentialsPath, readClaimableCredentials, resolveClaimableContext, shouldUseClaimableCredentials } from "../claimable/state.js";
 import { readOutgoingCredential, retirePreviousCredential } from "../retire_credential.js";
 import { existsSync } from "node:fs";
 import { createHash } from "node:crypto";
@@ -218,6 +220,7 @@ const ensureAuth = async (props) => {
 	if (isMcpOauth(props)) return;
 	if (props._[0] === "open") return;
 	if (isSkillsCommand(props) || isPluginsCommand(props)) return;
+	if (isClaimCommand(props)) return;
 	const isLocalDev = props._[0] === "dev";
 	const isBootstrap = props._[0] === "bootstrap";
 	const isInit = props._[0] === "init";
@@ -229,8 +232,42 @@ const ensureAuth = async (props) => {
 		});
 		return;
 	}
+	const inputs = credentialInputs();
+	const contextFile = typeof props.contextFile === "function" ? props.contextFile() : props.contextFile ?? currentContextFile();
+	const localContext = readContextFile(contextFile);
+	if (shouldUseClaimableCredentials(inputs, props.profile, localContext)) {
+		const linked = resolveClaimableContext(localContext);
+		if (linked === null) throw new Error("The linked Claimable Neon context could not be resolved.");
+		const stored = readClaimableCredentials(props.configDir, linked.projectId);
+		const path = claimableCredentialsPath(props.configDir, linked.projectId);
+		if (stored === null) throw new Error(`The linked project is claimable, but its identity assertion is missing from ${path}. Run \`neon claim create\` in a new directory, or \`neon link\` after claiming the project.`);
+		if (assertionHasExpired(stored)) throw new Error(`The identity assertion for ${linked.projectId} has expired. Run \`neon claim delete ${linked.projectId} --yes\` to drop the local record.`);
+		const client = new ClaimableClient(stored.origin);
+		if (client.origin !== new ClaimableClient(linked.origin).origin) throw new Error(`The linked .neon file and ${path} name different Claimable Neon services. Delete .neon or the assertion file and run \`neon claim create\` in a new directory.`);
+		let token;
+		try {
+			token = await client.exchange(stored.identityAssertion);
+		} catch (error) {
+			if (error instanceof ClaimableServiceError && error.code === "project_claimed") throw new Error("This project was claimed. Run `neon claim status` to drop the local assertion, then `neon auth` or `neon link`.");
+			throw error;
+		}
+		props.apiKey = token.accessToken;
+		props.apiHost = `${client.origin}/v1`;
+		props.apiClient = getApiClient({
+			apiKey: token.accessToken,
+			apiHost: props.apiHost
+		});
+		setAuthContext({
+			source: "claimable",
+			configDir: props.configDir,
+			credentialsPath: path
+		});
+		log.debug("Using the linked Claimable Neon project's short-lived access token");
+		return;
+	}
+	if (localContext.claimable !== void 0) log.warning("This directory is linked to a claimable project, but NEON_API_KEY or NEON_PROFILE is set. This command will use that account credential instead of the unclaimed project. Unset them to keep using the unclaimed project.");
 	const selection = selectCredential({
-		...credentialInputs(),
+		...inputs,
 		profileFlag: props.profile
 	});
 	const displaced = displacedProfileWarning(selection);

package/dist/commands/bootstrap.js

@@ -2,7 +2,7 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
-import { t as credentialInputs } from "../_chunks/auth_selection-Bx2NAgkk.js";
+import { t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.js";
 import { BootstrapInputError, FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
 import { DO_NOT_SUBSTITUTE_HINT, formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { existsSync } from "node:fs";