atmn 1.1.25 → 2.0.0

package/src/auth/createOrgApiKeys.ts

@@ -0,0 +1,46 @@
+import { autumnFetch } from "../http/autumnFetch";
+import { getApiKeysEndpoint } from "./oauthConfig";
+import type { OrgApiKeys } from "./types/orgApiKeys";
+
+type ApiKeysResponse = {
+	sandbox_key?: string;
+	prod_key?: string;
+	org_id?: string;
+	message?: string;
+	error?: string;
+};
+
+/** Mint the org's sandbox and production keys from the OAuth access token. */
+export const createOrgApiKeys = async ({
+	accessToken,
+	backendUrl,
+	fetch = autumnFetch,
+}: {
+	accessToken: string;
+	backendUrl: string;
+	fetch?: typeof globalThis.fetch;
+}): Promise<OrgApiKeys> => {
+	const response = await fetch(getApiKeysEndpoint({ backendUrl }), {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${accessToken}`,
+			"content-type": "application/json",
+		},
+	});
+
+	const body = (await response.json().catch(() => ({}))) as ApiKeysResponse;
+
+	if (!response.ok) {
+		throw new Error(
+			body.message ??
+				body.error ??
+				`Failed to create API keys (${response.status})`,
+		);
+	}
+
+	return {
+		sandboxKey: body.sandbox_key,
+		prodKey: body.prod_key,
+		orgId: body.org_id,
+	};
+};

package/src/auth/keyless.ts

@@ -0,0 +1,119 @@
+import { AutumnApiError } from "../generated/client";
+import { autumnFetch } from "../http/autumnFetch";
+
+/**
+ * Keyless onboarding: a sandbox org with no owner, minted for an agent or a
+ * human who has no account yet, and linked to an account later. Not in the
+ * spec, so hand-written like the key-minting call rather than generated.
+ */
+
+export type ProvisionedOrg = {
+	organizationId: string;
+	organizationSlug: string;
+	apiKey: string;
+	claimToken: string;
+	/** ISO 8601: after this the org can no longer be linked to anyone. */
+	claimExpiresAt: string;
+};
+
+export type ClaimStarted = {
+	claimUrl: string;
+	/** ISO 8601: after this the browser claim link stops working. */
+	expiresAt: string;
+};
+
+type Fetch = typeof globalThis.fetch;
+
+const post = async ({
+	baseUrl,
+	path,
+	body,
+	secretKey,
+	fetch = autumnFetch,
+}: {
+	baseUrl: string;
+	path: string;
+	body: Record<string, unknown>;
+	secretKey?: string;
+	fetch?: Fetch;
+}): Promise<Record<string, unknown>> => {
+	const response = await fetch(`${baseUrl}${path}`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...(secretKey === undefined
+				? {}
+				: { authorization: `Bearer ${secretKey}` }),
+		},
+		body: JSON.stringify(body),
+	});
+	const text = await response.text();
+	const parsed: unknown = text ? JSON.parse(text) : null;
+	if (!response.ok)
+		throw new AutumnApiError({ status: response.status, body: parsed, path });
+	return (parsed ?? {}) as Record<string, unknown>;
+};
+
+export const provisionKeylessOrg = async ({
+	baseUrl,
+	name,
+	slug,
+	fetch,
+}: {
+	baseUrl: string;
+	name: string;
+	slug: string;
+	fetch?: Fetch;
+}): Promise<ProvisionedOrg> => {
+	const body = await post({
+		baseUrl,
+		path: "/agent.provision",
+		body: { name: name.slice(0, MAX_NAME_LENGTH), slug },
+		fetch,
+	});
+	return {
+		organizationId: String(body.organization_id),
+		organizationSlug: String(body.organization_slug),
+		apiKey: String(body.api_key),
+		claimToken: String(body.claim_token),
+		claimExpiresAt: String(body.claim_expires_at),
+	};
+};
+
+/** Creates and emails a browser claim link for the org `secretKey` belongs to. */
+export const startClaim = async ({
+	baseUrl,
+	secretKey,
+	email,
+	fetch,
+}: {
+	baseUrl: string;
+	secretKey: string;
+	email: string;
+	fetch?: Fetch;
+}): Promise<ClaimStarted> => {
+	const body = await post({
+		baseUrl,
+		path: "/agent.start_claim",
+		body: { email },
+		secretKey,
+		fetch,
+	});
+	return {
+		claimUrl: String(body.claim_url),
+		expiresAt: String(body.expires_at),
+	};
+};
+
+/** A slug the server accepts: lowercase alphanumerics, `-` or `_` between words. */
+/** The server caps a name and a slug at 100 characters. */
+const MAX_NAME_LENGTH = 100;
+
+export const slugFor = (name: string): string =>
+	name
+		.toLowerCase()
+		.replace(/^@[^/]+\//, "")
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, MAX_NAME_LENGTH)
+		.replace(/-+$/, "") || "autumn";

package/src/auth/oauthConfig.ts

@@ -0,0 +1,63 @@
+/**
+ * The registered Better Auth client for the atmn CLI, carried over from v2 so
+ * existing consent records keep working. `resolveTarget` lets `--client-id`
+ * or `AUTUMN_CLIENT_ID` replace it.
+ */
+export const CLI_CLIENT_ID = "hAWUopQqLnsSwuRgeRzIBzKslwXmQUSr";
+
+const OAUTH_PORT_BASE = 31448;
+const OAUTH_PORT_RANGE = 5;
+
+/** Callback ports tried in order; every one is registered as a redirect URI. */
+export const OAUTH_PORTS = Array.from(
+	{ length: OAUTH_PORT_RANGE },
+	(_, offset) => OAUTH_PORT_BASE + offset,
+);
+
+/**
+ * Modern read/write scopes covering everything the CLI reads and everything the
+ * minted keys are used for. The server rewrites v2's CRUDL scopes to these.
+ * platform:* is what `atmn sandbox create|delete` needs, migrations:write what
+ * `atmn reset` needs, and organisation:write what a config's `settings` block
+ * needs; a key minted before any was requested has to be re-minted with
+ * `atmn login`.
+ */
+export const CLI_OAUTH_SCOPES = [
+	"organisation:read",
+	"organisation:write",
+	"customers:read",
+	"customers:write",
+	"features:read",
+	"features:write",
+	"plans:read",
+	"plans:write",
+	"migrations:read",
+	"migrations:write",
+	"rewards:read",
+	"rewards:write",
+	"apiKeys:read",
+	"apiKeys:write",
+	"platform:read",
+	"platform:write",
+] as const;
+
+export const getOAuthRedirectUri = ({ port }: { port: number }): string =>
+	`http://localhost:${port}/`;
+
+export const getAuthorizationEndpoint = ({
+	backendUrl,
+}: {
+	backendUrl: string;
+}): string => `${backendUrl}/api/auth/oauth2/authorize`;
+
+export const getTokenEndpoint = ({
+	backendUrl,
+}: {
+	backendUrl: string;
+}): string => `${backendUrl}/api/auth/oauth2/token`;
+
+export const getApiKeysEndpoint = ({
+	backendUrl,
+}: {
+	backendUrl: string;
+}): string => `${backendUrl}/cli/api-keys`;

package/src/auth/runOAuthFlow.ts

@@ -0,0 +1,230 @@
+import { createServer } from "node:http";
+import {
+	generateCodeVerifier,
+	generateState,
+	type OAuth2Client,
+	OAuth2RequestError,
+} from "arctic";
+import {
+	buildAuthorizationUrl,
+	createOAuthClient,
+} from "./buildAuthorizationUrl";
+import { renderErrorPage, renderSuccessPage } from "./callbackPages";
+import { getTokenEndpoint, OAUTH_PORTS } from "./oauthConfig";
+import { readImpersonationTokens } from "./types/impersonationTokens";
+import type { AuthorizationOutcome } from "./types/oauthTokens";
+
+const AUTHORIZATION_TIMEOUT_MS = 5 * 60 * 1000;
+
+export type AuthorizationUrlListener = ({
+	url,
+}: {
+	url: string;
+}) => Promise<void> | void;
+
+export type RunOAuthFlowOptions = {
+	clientId: string;
+	backendUrl: string;
+	scopes: readonly string[];
+	onAuthorizationUrl: AuthorizationUrlListener;
+};
+
+type CallbackOutcome = {
+	page: string;
+	outcome?: AuthorizationOutcome;
+	error?: Error;
+};
+
+const failedCallback = ({ message }: { message: string }): CallbackOutcome => ({
+	page: renderErrorPage({ message }),
+	error: new Error(message),
+});
+
+const exchangeAuthorizationCode = async ({
+	client,
+	backendUrl,
+	code,
+	codeVerifier,
+}: {
+	client: OAuth2Client;
+	backendUrl: string;
+	code: string;
+	codeVerifier: string;
+}): Promise<CallbackOutcome> => {
+	try {
+		const tokens = await client.validateAuthorizationCode(
+			getTokenEndpoint({ backendUrl }),
+			code,
+			codeVerifier,
+		);
+		return {
+			page: renderSuccessPage(),
+			outcome: {
+				kind: "oauth",
+				tokens: {
+					accessToken: tokens.accessToken(),
+					tokenType: "Bearer",
+					expiresInSeconds: tokens.accessTokenExpiresInSeconds(),
+					refreshToken: tokens.hasRefreshToken()
+						? tokens.refreshToken()
+						: undefined,
+				},
+			},
+		};
+	} catch (error) {
+		const message =
+			error instanceof OAuth2RequestError
+				? `OAuth error: ${error.code}`
+				: "Token exchange failed";
+		return failedCallback({ message });
+	}
+};
+
+const readCallback = async ({
+	callbackUrl,
+	client,
+	backendUrl,
+	state,
+	codeVerifier,
+}: {
+	callbackUrl: URL;
+	client: OAuth2Client;
+	backendUrl: string;
+	state: string;
+	codeVerifier: string;
+}): Promise<CallbackOutcome> => {
+	const denial = callbackUrl.searchParams.get("error");
+	if (denial) {
+		return failedCallback({
+			message: callbackUrl.searchParams.get("error_description") ?? denial,
+		});
+	}
+	if (callbackUrl.searchParams.get("state") !== state) {
+		return failedCallback({ message: "Invalid state — possible CSRF" });
+	}
+
+	// An impersonating dashboard session hands back tokens instead of a code.
+	const impersonation = readImpersonationTokens(callbackUrl.searchParams);
+	if (impersonation) {
+		return {
+			page: renderSuccessPage(),
+			outcome: { kind: "impersonation", tokens: impersonation },
+		};
+	}
+
+	const code = callbackUrl.searchParams.get("code");
+	if (!code) return failedCallback({ message: "Missing authorization code" });
+
+	return await exchangeAuthorizationCode({
+		client,
+		backendUrl,
+		code,
+		codeVerifier,
+	});
+};
+
+/** Resolves null when the port is taken, so the caller can try the next one. */
+const listenForCallback = ({
+	port,
+	onCallback,
+	onListening,
+}: {
+	port: number;
+	onCallback: ({
+		callbackUrl,
+	}: {
+		callbackUrl: URL;
+	}) => Promise<CallbackOutcome>;
+	onListening: () => void;
+}): Promise<AuthorizationOutcome | null> =>
+	new Promise((resolve, reject) => {
+		const server = createServer(async (request, response) => {
+			const callbackUrl = new URL(
+				request.url ?? "/",
+				`http://localhost:${port}`,
+			);
+			if (callbackUrl.pathname !== "/") {
+				response.writeHead(404).end("Not found");
+				return;
+			}
+
+			const { page, outcome, error } = await onCallback({ callbackUrl });
+			clearTimeout(timeout);
+
+			// Settle only once the page is flushed — the browser's keep-alive socket
+			// would otherwise outlive the command and hang the CLI.
+			response.writeHead(200, { "Content-Type": "text/html" }).end(page, () => {
+				shutDown();
+				if (outcome) resolve(outcome);
+				else reject(error ?? new Error("Authorization returned no tokens"));
+			});
+		});
+
+		const shutDown = () => {
+			server.close();
+			server.closeAllConnections();
+		};
+
+		const timeout = setTimeout(() => {
+			shutDown();
+			reject(new Error("Authorization timed out. Please try again."));
+		}, AUTHORIZATION_TIMEOUT_MS);
+
+		server.once("error", (error: NodeJS.ErrnoException) => {
+			clearTimeout(timeout);
+			if (error.code === "EADDRINUSE") resolve(null);
+			else reject(error);
+		});
+
+		server.listen(port, onListening);
+	});
+
+/**
+ * PKCE authorization against a loopback callback. The URL is handed to the
+ * caller the moment the server is listening, so it can be shown and opened.
+ */
+export const runOAuthFlow = async ({
+	clientId,
+	backendUrl,
+	scopes,
+	onAuthorizationUrl,
+}: RunOAuthFlowOptions): Promise<AuthorizationOutcome> => {
+	const codeVerifier = generateCodeVerifier();
+	const state = generateState();
+
+	for (const port of OAUTH_PORTS) {
+		const client = createOAuthClient({ clientId, port });
+		const authorizationUrl = buildAuthorizationUrl({
+			client,
+			backendUrl,
+			scopes,
+			state,
+			codeVerifier,
+		});
+
+		const outcome = await listenForCallback({
+			port,
+			onCallback: ({ callbackUrl }) =>
+				readCallback({
+					callbackUrl,
+					client,
+					backendUrl,
+					state,
+					codeVerifier,
+				}),
+			onListening: () => {
+				void Promise.resolve(
+					onAuthorizationUrl({ url: authorizationUrl.toString() }),
+				).catch(() => {
+					// Announcing is best-effort; the flow still works if it fails.
+				});
+			},
+		});
+
+		if (outcome) return outcome;
+	}
+
+	throw new Error(
+		`All OAuth callback ports (${OAUTH_PORTS.at(0)}-${OAUTH_PORTS.at(-1)}) are in use.`,
+	);
+};

package/src/auth/types/browserOpener.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves once a browser was actually launched, and rejects otherwise — the
+ * rejection is the only honest headless signal, since a TTY proves nothing.
+ */
+export type BrowserOpener = ({ url }: { url: string }) => Promise<void>;

package/src/auth/types/impersonationTokens.ts

@@ -0,0 +1,23 @@
+/** One-hour OAuth tokens handed back when the dashboard session impersonates a customer. */
+export type ImpersonationTokens = {
+	sandboxToken: string;
+	liveToken: string;
+	/** ISO 8601. */
+	expiresAt: string;
+};
+
+export const IMPERSONATION_CALLBACK_PARAMS = {
+	sandboxToken: "impersonation_sandbox_token",
+	liveToken: "impersonation_live_token",
+	expiresAt: "impersonation_expires_at",
+} as const;
+
+export const readImpersonationTokens = (
+	params: URLSearchParams,
+): ImpersonationTokens | null => {
+	const sandboxToken = params.get(IMPERSONATION_CALLBACK_PARAMS.sandboxToken);
+	const liveToken = params.get(IMPERSONATION_CALLBACK_PARAMS.liveToken);
+	const expiresAt = params.get(IMPERSONATION_CALLBACK_PARAMS.expiresAt);
+	if (!sandboxToken || !liveToken || !expiresAt) return null;
+	return { sandboxToken, liveToken, expiresAt };
+};

package/src/auth/types/oauthTokens.ts

@@ -0,0 +1,13 @@
+import type { ImpersonationTokens } from "./impersonationTokens";
+
+export type OAuthTokens = {
+	accessToken: string;
+	tokenType: "Bearer";
+	expiresInSeconds?: number;
+	refreshToken?: string;
+};
+
+/** What the loopback callback delivered: a grant to exchange, or ready-made tokens. */
+export type AuthorizationOutcome =
+	| { kind: "oauth"; tokens: OAuthTokens }
+	| { kind: "impersonation"; tokens: ImpersonationTokens };

package/src/auth/types/orgApiKeys.ts

@@ -0,0 +1,6 @@
+/** Either key can be absent when the org's OAuth client is bound to one env. */
+export type OrgApiKeys = {
+	sandboxKey?: string;
+	prodKey?: string;
+	orgId?: string;
+};

package/src/bin.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "./cli";
+
+// The npm entry: node has no import.meta.main, so the run happens here.
+run({ argv: process.argv }).catch((error: unknown) => {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`${message}\n`);
+	process.exit(1);
+});