@aooth/login-client 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 aoothjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @aooth/login-client
+
+Zero-dependency helper that logs a user in through their **browser** and hands a
+token back to a local process — the `gh auth login` pattern, for any
+[aoothjs](https://github.com/moostjs/aoothjs) authorization server.
+
+It runs the authorization-code + PKCE flow against a one-shot **loopback**
+redirect (`http://127.0.0.1:<ephemeral-port>/callback`), so nothing is ever
+copy-pasted. Built on Node built-ins (`node:http`, `node:crypto`,
+`node:child_process`) and global `fetch` only — **no runtime dependencies**.
+
+## Install
+
+```bash
+npm i @aooth/login-client   # Node >= 18
+```
+
+## Use
+
+```ts
+import { authorize } from "@aooth/login-client";
+
+const { accessToken, expiresIn, userId } = await authorize({
+  authorizeUrl: "https://main.example.com/auth/authorize",
+  tokenUrl: "https://main.example.com/auth/token",
+  // clientId,                 // omit for a public/loopback client (PKCE is the binding)
+  // scope: ["api"],
+  // statusUrl: "https://main.example.com/auth/status",  // optional: confirm the token works
+});
+
+// send it: Authorization: Bearer <accessToken>
+```
+
+What it does: opens a one-shot `127.0.0.1` listener, generates `state` + PKCE,
+opens the browser to `authorizeUrl`, awaits the single callback, **verifies
+`state`** (the CSRF check), then `POST tokenUrl { code, code_verifier }` and
+returns the token. It does **not** crypto-validate the token — that is the
+server's opaque credential; TLS + PKCE + `state` are the binding.
+
+### Headless / SSH
+
+```ts
+await authorize({
+  authorizeUrl,
+  tokenUrl,
+  openBrowser: false,
+  onUrl: (url) => console.log(`Open this URL to sign in:\n${url}`),
+});
+```
+
+The loopback listener still catches the callback once the user opens the URL
+elsewhere on the same machine.
+
+## Options
+
+| Option         | Default  | Notes                                                        |
+| -------------- | -------- | ------------------------------------------------------------ |
+| `authorizeUrl` | —        | the server's `GET /auth/authorize`                           |
+| `tokenUrl`     | —        | the server's `POST /auth/token`                              |
+| `clientId`     | —        | omit for a public/loopback client                            |
+| `scope`        | —        | `string[]`, joined with spaces                               |
+| `openBrowser`  | `true`   | set `false` + `onUrl` for headless                           |
+| `onUrl`        | —        | always called with the authorize URL (print a fallback line) |
+| `statusUrl`    | —        | optional bearer-confirm `GET`; adopts its `userId`           |
+| `timeoutMs`    | `300000` | wait for the browser callback                                |
+| `signal`       | —        | `AbortSignal` to cancel (e.g. on SIGINT)                     |
+
+Failures throw an `AuthorizeError` with a `.code`
+(`provider_denied` · `state_mismatch` · `exchange_failed` · `timeout` ·
+`status_check_failed`).

package/dist/index.cjs

@@ -0,0 +1,203 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_child_process = require("node:child_process");
+let node_crypto = require("node:crypto");
+let node_http = require("node:http");
+//#region src/index.ts
+/** A typed failure of the loopback login flow. */
+var AuthorizeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "AuthorizeError";
+		this.code = code;
+	}
+};
+const DEFAULT_TIMEOUT_MS = 5 * 6e4;
+/** RFC 4648 §5 base64url (no padding) of raw bytes. */
+function base64url(bytes) {
+	return bytes.toString("base64url");
+}
+/** A PKCE verifier + its S256 challenge, plus a fresh anti-CSRF `state`. */
+function newPkceAndState() {
+	const verifier = base64url((0, node_crypto.randomBytes)(32));
+	return {
+		verifier,
+		challenge: base64url((0, node_crypto.createHash)("sha256").update(verifier).digest()),
+		state: base64url((0, node_crypto.randomBytes)(16))
+	};
+}
+function buildAuthorizeUrl(opts, redirectUri, p) {
+	const url = new URL(opts.authorizeUrl);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("redirect_uri", redirectUri);
+	url.searchParams.set("state", p.state);
+	url.searchParams.set("code_challenge", p.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (opts.clientId !== void 0) url.searchParams.set("client_id", opts.clientId);
+	if (opts.scope && opts.scope.length > 0) url.searchParams.set("scope", opts.scope.join(" "));
+	return url.toString();
+}
+/** Spawn the platform browser opener, detached; never throws (best-effort). */
+function openInBrowser(url) {
+	try {
+		const platform = process.platform;
+		const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
+			"/c",
+			"start",
+			"",
+			url
+		]] : ["xdg-open", [url]];
+		const child = (0, node_child_process.spawn)(cmd, [...args], {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+const DONE_HTML = "<!doctype html><meta charset=utf-8><title>Signed in</title><body style=\"font:16px system-ui;margin:3rem;text-align:center\"><h1>✓ Signed in</h1><p>You can close this tab and return to the terminal.</p></body>";
+/**
+* Stand up a one-shot loopback listener, return its `redirect_uri` and a promise
+* that resolves with the `{ code }` from the first `/callback` hit (after the
+* `state` CSRF check) or rejects with an {@link AuthorizeError}.
+*/
+function awaitLoopbackCallback(expectedState, timeoutMs, signal) {
+	return new Promise((resolveSetup, rejectSetup) => {
+		let settle;
+		let fail;
+		const ready = new Promise((res, rej) => {
+			settle = res;
+			fail = rej;
+		});
+		const server = (0, node_http.createServer)((req, res) => {
+			const url = new URL(req.url ?? "/", "http://127.0.0.1");
+			if (url.pathname !== "/callback") {
+				res.writeHead(404).end();
+				return;
+			}
+			const error = url.searchParams.get("error");
+			const code = url.searchParams.get("code");
+			const state = url.searchParams.get("state");
+			if (error) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("provider_denied", `Authorization server returned error=${error}`));
+			} else if (state !== expectedState) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("state_mismatch", "Callback state did not match the request"));
+			} else if (!code) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("exchange_failed", "Callback carried no authorization code"));
+			} else {
+				res.writeHead(200, { "content-type": "text/html" }).end(DONE_HTML);
+				settle?.(code);
+			}
+		});
+		const cleanup = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			server.close();
+		};
+		const onAbort = () => fail?.(new AuthorizeError("timeout", "Login aborted"));
+		const timer = setTimeout(() => fail?.(new AuthorizeError("timeout", `No callback within ${timeoutMs}ms`)), timeoutMs);
+		timer.unref?.();
+		signal?.addEventListener("abort", onAbort, { once: true });
+		ready.then(cleanup, cleanup);
+		server.on("error", rejectSetup);
+		server.listen(0, "127.0.0.1", () => {
+			resolveSetup({
+				redirectUri: `http://127.0.0.1:${server.address().port}/callback`,
+				ready
+			});
+		});
+	});
+}
+/** Back-channel `code` → token exchange (PKCE-verified at the server). */
+async function exchangeCode(opts, code, verifier) {
+	const body = new URLSearchParams({
+		grant_type: "authorization_code",
+		code,
+		code_verifier: verifier
+	});
+	if (opts.clientId !== void 0) body.set("client_id", opts.clientId);
+	let resp;
+	try {
+		resp = await fetch(opts.tokenUrl, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body,
+			signal: opts.signal
+		});
+	} catch (e) {
+		throw new AuthorizeError("exchange_failed", `Token endpoint unreachable: ${String(e)}`);
+	}
+	if (!resp.ok) throw new AuthorizeError("exchange_failed", `Token endpoint returned ${resp.status}`);
+	let json;
+	try {
+		json = await resp.json();
+	} catch {
+		throw new AuthorizeError("exchange_failed", "Token endpoint returned a non-JSON body");
+	}
+	if (!json.access_token) throw new AuthorizeError("exchange_failed", "Token endpoint returned no access_token");
+	return json;
+}
+/** Optional `GET statusUrl` confirmation; returns the reported `userId` if any. */
+async function confirmStatus(statusUrl, accessToken, signal) {
+	let resp;
+	try {
+		resp = await fetch(statusUrl, {
+			headers: {
+				authorization: `Bearer ${accessToken}`,
+				accept: "application/json"
+			},
+			signal
+		});
+	} catch (e) {
+		throw new AuthorizeError("status_check_failed", `Status endpoint unreachable: ${String(e)}`);
+	}
+	if (!resp.ok) throw new AuthorizeError("status_check_failed", `Status endpoint returned ${resp.status}`);
+	try {
+		return (await resp.json()).userId;
+	} catch {
+		return;
+	}
+}
+/**
+* Run the full browser-login round trip and return a token:
+*
+* 1. open a one-shot `127.0.0.1` loopback listener (ephemeral port),
+* 2. generate `state` + PKCE, open the browser to `authorizeUrl?...`,
+* 3. await the single loopback callback and verify `state` (the CSRF check),
+* 4. `POST tokenUrl { code, code_verifier, ... }` and return the token,
+* 5. optionally confirm it against `statusUrl`.
+*
+* The helper does NOT cryptographically validate the token — it is an opaque,
+* server-owned credential; the TLS token endpoint + PKCE + the `state` check are
+* the binding. (Tier-2 `id_token` signature verification is the relying
+* service's job via an OIDC client, not a CLI's.)
+*/
+async function authorize(opts) {
+	const pkce = newPkceAndState();
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const { redirectUri, ready } = await awaitLoopbackCallback(pkce.state, timeoutMs, opts.signal);
+	const authUrl = buildAuthorizeUrl(opts, redirectUri, pkce);
+	opts.onUrl?.(authUrl);
+	if (opts.openBrowser !== false) openInBrowser(authUrl);
+	const token = await exchangeCode(opts, await ready, pkce.verifier);
+	let userId = token.userId;
+	if (opts.statusUrl) {
+		const confirmed = await confirmStatus(opts.statusUrl, token.access_token, opts.signal);
+		userId = userId ?? confirmed;
+	}
+	return {
+		accessToken: token.access_token,
+		...token.expires_in !== void 0 && { expiresIn: token.expires_in },
+		...token.id_token !== void 0 && { idToken: token.id_token },
+		...userId !== void 0 && { userId }
+	};
+}
+//#endregion
+exports.AuthorizeError = AuthorizeError;
+exports.authorize = authorize;

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+//#region src/index.d.ts
+/**
+ * `@aooth/login-client` — a zero-dependency helper that obtains a token from an
+ * aoothjs authorization server by driving the user through a **browser login**
+ * and catching the result on an ephemeral **loopback** redirect (the
+ * `gh auth login` pattern). Built on Node built-ins + global `fetch` only, so it
+ * drops into any CLI with no transitive deps.
+ *
+ * It is also usable as a generic "Sign in with <main app>" hatch for a
+ * first-party service: only the `redirect_uri` differs (a real loopback URL on a
+ * developer machine vs. — in a hosted relying service — that service's own
+ * callback). The flow (authorization-code + PKCE + back-channel token exchange)
+ * is identical.
+ */
+/** Error codes surfaced by {@link authorize}. */
+type AuthorizeErrorCode = /** The provider returned `?error=` on the callback (e.g. the user declined). */"provider_denied" /** The callback `state` did not match the one we generated (CSRF / instance mismatch). */ | "state_mismatch" /** The `POST /token` exchange failed (non-2xx, network, or malformed body). */ | "exchange_failed" /** No callback arrived before `timeoutMs` (or the `signal` aborted). */ | "timeout" /** The optional `statusUrl` confirmation did not return 200. */ | "status_check_failed";
+/** A typed failure of the loopback login flow. */
+declare class AuthorizeError extends Error {
+  readonly code: AuthorizeErrorCode;
+  constructor(code: AuthorizeErrorCode, message: string);
+}
+interface AuthorizeOptions {
+  /** The authorization server's `GET /auth/authorize` URL. */
+  authorizeUrl: string;
+  /** The authorization server's `POST /auth/token` URL. */
+  tokenUrl: string;
+  /** Client id for a registered client; omit for a public/loopback client (PKCE is the binding). */
+  clientId?: string;
+  /** Requested scopes, joined with spaces into the `scope` param. */
+  scope?: string[];
+  /**
+   * Open the system browser to the authorize URL automatically. Default `true`.
+   * Set `false` for headless/SSH and use {@link onUrl} to surface the URL.
+   */
+  openBrowser?: boolean;
+  /**
+   * Called with the full authorize URL before (or instead of) opening a browser.
+   * Use it to print the URL for the user to open elsewhere — the loopback
+   * listener still catches the callback. Always invoked, even when
+   * `openBrowser` is `true`, so a CLI can print a fallback line.
+   */
+  onUrl?: (url: string) => void;
+  /**
+   * Optional `GET` URL hit with the returned bearer to confirm the token works
+   * (e.g. `/auth/status`). On a 200 the helper adopts its `userId` when the
+   * token response did not carry one. A non-200 throws `status_check_failed`.
+   */
+  statusUrl?: string;
+  /** How long to wait for the browser callback before failing. Default 300_000 (5 min). */
+  timeoutMs?: number;
+  /** Abort the wait early (e.g. on SIGINT). */
+  signal?: AbortSignal;
+}
+interface AuthorizeResult {
+  /** The bearer access token to send as `Authorization: Bearer <accessToken>`. */
+  accessToken: string;
+  /** Access-token lifetime in seconds, as reported by the token endpoint. */
+  expiresIn?: number;
+  /** An OIDC id_token, when the server is acting as a Tier-2 OIDC provider. Opaque here. */
+  idToken?: string;
+  /** The authenticated user id, from the token response or the `statusUrl` confirmation. */
+  userId?: string;
+}
+/**
+ * Run the full browser-login round trip and return a token:
+ *
+ * 1. open a one-shot `127.0.0.1` loopback listener (ephemeral port),
+ * 2. generate `state` + PKCE, open the browser to `authorizeUrl?...`,
+ * 3. await the single loopback callback and verify `state` (the CSRF check),
+ * 4. `POST tokenUrl { code, code_verifier, ... }` and return the token,
+ * 5. optionally confirm it against `statusUrl`.
+ *
+ * The helper does NOT cryptographically validate the token — it is an opaque,
+ * server-owned credential; the TLS token endpoint + PKCE + the `state` check are
+ * the binding. (Tier-2 `id_token` signature verification is the relying
+ * service's job via an OIDC client, not a CLI's.)
+ */
+declare function authorize(opts: AuthorizeOptions): Promise<AuthorizeResult>;
+//#endregion
+export { AuthorizeError, AuthorizeErrorCode, AuthorizeOptions, AuthorizeResult, authorize };

package/dist/index.d.mts

@@ -0,0 +1,80 @@
+//#region src/index.d.ts
+/**
+ * `@aooth/login-client` — a zero-dependency helper that obtains a token from an
+ * aoothjs authorization server by driving the user through a **browser login**
+ * and catching the result on an ephemeral **loopback** redirect (the
+ * `gh auth login` pattern). Built on Node built-ins + global `fetch` only, so it
+ * drops into any CLI with no transitive deps.
+ *
+ * It is also usable as a generic "Sign in with <main app>" hatch for a
+ * first-party service: only the `redirect_uri` differs (a real loopback URL on a
+ * developer machine vs. — in a hosted relying service — that service's own
+ * callback). The flow (authorization-code + PKCE + back-channel token exchange)
+ * is identical.
+ */
+/** Error codes surfaced by {@link authorize}. */
+type AuthorizeErrorCode = /** The provider returned `?error=` on the callback (e.g. the user declined). */"provider_denied" /** The callback `state` did not match the one we generated (CSRF / instance mismatch). */ | "state_mismatch" /** The `POST /token` exchange failed (non-2xx, network, or malformed body). */ | "exchange_failed" /** No callback arrived before `timeoutMs` (or the `signal` aborted). */ | "timeout" /** The optional `statusUrl` confirmation did not return 200. */ | "status_check_failed";
+/** A typed failure of the loopback login flow. */
+declare class AuthorizeError extends Error {
+  readonly code: AuthorizeErrorCode;
+  constructor(code: AuthorizeErrorCode, message: string);
+}
+interface AuthorizeOptions {
+  /** The authorization server's `GET /auth/authorize` URL. */
+  authorizeUrl: string;
+  /** The authorization server's `POST /auth/token` URL. */
+  tokenUrl: string;
+  /** Client id for a registered client; omit for a public/loopback client (PKCE is the binding). */
+  clientId?: string;
+  /** Requested scopes, joined with spaces into the `scope` param. */
+  scope?: string[];
+  /**
+   * Open the system browser to the authorize URL automatically. Default `true`.
+   * Set `false` for headless/SSH and use {@link onUrl} to surface the URL.
+   */
+  openBrowser?: boolean;
+  /**
+   * Called with the full authorize URL before (or instead of) opening a browser.
+   * Use it to print the URL for the user to open elsewhere — the loopback
+   * listener still catches the callback. Always invoked, even when
+   * `openBrowser` is `true`, so a CLI can print a fallback line.
+   */
+  onUrl?: (url: string) => void;
+  /**
+   * Optional `GET` URL hit with the returned bearer to confirm the token works
+   * (e.g. `/auth/status`). On a 200 the helper adopts its `userId` when the
+   * token response did not carry one. A non-200 throws `status_check_failed`.
+   */
+  statusUrl?: string;
+  /** How long to wait for the browser callback before failing. Default 300_000 (5 min). */
+  timeoutMs?: number;
+  /** Abort the wait early (e.g. on SIGINT). */
+  signal?: AbortSignal;
+}
+interface AuthorizeResult {
+  /** The bearer access token to send as `Authorization: Bearer <accessToken>`. */
+  accessToken: string;
+  /** Access-token lifetime in seconds, as reported by the token endpoint. */
+  expiresIn?: number;
+  /** An OIDC id_token, when the server is acting as a Tier-2 OIDC provider. Opaque here. */
+  idToken?: string;
+  /** The authenticated user id, from the token response or the `statusUrl` confirmation. */
+  userId?: string;
+}
+/**
+ * Run the full browser-login round trip and return a token:
+ *
+ * 1. open a one-shot `127.0.0.1` loopback listener (ephemeral port),
+ * 2. generate `state` + PKCE, open the browser to `authorizeUrl?...`,
+ * 3. await the single loopback callback and verify `state` (the CSRF check),
+ * 4. `POST tokenUrl { code, code_verifier, ... }` and return the token,
+ * 5. optionally confirm it against `statusUrl`.
+ *
+ * The helper does NOT cryptographically validate the token — it is an opaque,
+ * server-owned credential; the TLS token endpoint + PKCE + the `state` check are
+ * the binding. (Tier-2 `id_token` signature verification is the relying
+ * service's job via an OIDC client, not a CLI's.)
+ */
+declare function authorize(opts: AuthorizeOptions): Promise<AuthorizeResult>;
+//#endregion
+export { AuthorizeError, AuthorizeErrorCode, AuthorizeOptions, AuthorizeResult, authorize };

package/dist/index.mjs

@@ -0,0 +1,201 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+//#region src/index.ts
+/** A typed failure of the loopback login flow. */
+var AuthorizeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "AuthorizeError";
+		this.code = code;
+	}
+};
+const DEFAULT_TIMEOUT_MS = 5 * 6e4;
+/** RFC 4648 §5 base64url (no padding) of raw bytes. */
+function base64url(bytes) {
+	return bytes.toString("base64url");
+}
+/** A PKCE verifier + its S256 challenge, plus a fresh anti-CSRF `state`. */
+function newPkceAndState() {
+	const verifier = base64url(randomBytes(32));
+	return {
+		verifier,
+		challenge: base64url(createHash("sha256").update(verifier).digest()),
+		state: base64url(randomBytes(16))
+	};
+}
+function buildAuthorizeUrl(opts, redirectUri, p) {
+	const url = new URL(opts.authorizeUrl);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("redirect_uri", redirectUri);
+	url.searchParams.set("state", p.state);
+	url.searchParams.set("code_challenge", p.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	if (opts.clientId !== void 0) url.searchParams.set("client_id", opts.clientId);
+	if (opts.scope && opts.scope.length > 0) url.searchParams.set("scope", opts.scope.join(" "));
+	return url.toString();
+}
+/** Spawn the platform browser opener, detached; never throws (best-effort). */
+function openInBrowser(url) {
+	try {
+		const platform = process.platform;
+		const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
+			"/c",
+			"start",
+			"",
+			url
+		]] : ["xdg-open", [url]];
+		const child = spawn(cmd, [...args], {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+const DONE_HTML = "<!doctype html><meta charset=utf-8><title>Signed in</title><body style=\"font:16px system-ui;margin:3rem;text-align:center\"><h1>✓ Signed in</h1><p>You can close this tab and return to the terminal.</p></body>";
+/**
+* Stand up a one-shot loopback listener, return its `redirect_uri` and a promise
+* that resolves with the `{ code }` from the first `/callback` hit (after the
+* `state` CSRF check) or rejects with an {@link AuthorizeError}.
+*/
+function awaitLoopbackCallback(expectedState, timeoutMs, signal) {
+	return new Promise((resolveSetup, rejectSetup) => {
+		let settle;
+		let fail;
+		const ready = new Promise((res, rej) => {
+			settle = res;
+			fail = rej;
+		});
+		const server = createServer((req, res) => {
+			const url = new URL(req.url ?? "/", "http://127.0.0.1");
+			if (url.pathname !== "/callback") {
+				res.writeHead(404).end();
+				return;
+			}
+			const error = url.searchParams.get("error");
+			const code = url.searchParams.get("code");
+			const state = url.searchParams.get("state");
+			if (error) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("provider_denied", `Authorization server returned error=${error}`));
+			} else if (state !== expectedState) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("state_mismatch", "Callback state did not match the request"));
+			} else if (!code) {
+				res.writeHead(400, { "content-type": "text/plain" }).end("Sign-in failed.");
+				fail?.(new AuthorizeError("exchange_failed", "Callback carried no authorization code"));
+			} else {
+				res.writeHead(200, { "content-type": "text/html" }).end(DONE_HTML);
+				settle?.(code);
+			}
+		});
+		const cleanup = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			server.close();
+		};
+		const onAbort = () => fail?.(new AuthorizeError("timeout", "Login aborted"));
+		const timer = setTimeout(() => fail?.(new AuthorizeError("timeout", `No callback within ${timeoutMs}ms`)), timeoutMs);
+		timer.unref?.();
+		signal?.addEventListener("abort", onAbort, { once: true });
+		ready.then(cleanup, cleanup);
+		server.on("error", rejectSetup);
+		server.listen(0, "127.0.0.1", () => {
+			resolveSetup({
+				redirectUri: `http://127.0.0.1:${server.address().port}/callback`,
+				ready
+			});
+		});
+	});
+}
+/** Back-channel `code` → token exchange (PKCE-verified at the server). */
+async function exchangeCode(opts, code, verifier) {
+	const body = new URLSearchParams({
+		grant_type: "authorization_code",
+		code,
+		code_verifier: verifier
+	});
+	if (opts.clientId !== void 0) body.set("client_id", opts.clientId);
+	let resp;
+	try {
+		resp = await fetch(opts.tokenUrl, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body,
+			signal: opts.signal
+		});
+	} catch (e) {
+		throw new AuthorizeError("exchange_failed", `Token endpoint unreachable: ${String(e)}`);
+	}
+	if (!resp.ok) throw new AuthorizeError("exchange_failed", `Token endpoint returned ${resp.status}`);
+	let json;
+	try {
+		json = await resp.json();
+	} catch {
+		throw new AuthorizeError("exchange_failed", "Token endpoint returned a non-JSON body");
+	}
+	if (!json.access_token) throw new AuthorizeError("exchange_failed", "Token endpoint returned no access_token");
+	return json;
+}
+/** Optional `GET statusUrl` confirmation; returns the reported `userId` if any. */
+async function confirmStatus(statusUrl, accessToken, signal) {
+	let resp;
+	try {
+		resp = await fetch(statusUrl, {
+			headers: {
+				authorization: `Bearer ${accessToken}`,
+				accept: "application/json"
+			},
+			signal
+		});
+	} catch (e) {
+		throw new AuthorizeError("status_check_failed", `Status endpoint unreachable: ${String(e)}`);
+	}
+	if (!resp.ok) throw new AuthorizeError("status_check_failed", `Status endpoint returned ${resp.status}`);
+	try {
+		return (await resp.json()).userId;
+	} catch {
+		return;
+	}
+}
+/**
+* Run the full browser-login round trip and return a token:
+*
+* 1. open a one-shot `127.0.0.1` loopback listener (ephemeral port),
+* 2. generate `state` + PKCE, open the browser to `authorizeUrl?...`,
+* 3. await the single loopback callback and verify `state` (the CSRF check),
+* 4. `POST tokenUrl { code, code_verifier, ... }` and return the token,
+* 5. optionally confirm it against `statusUrl`.
+*
+* The helper does NOT cryptographically validate the token — it is an opaque,
+* server-owned credential; the TLS token endpoint + PKCE + the `state` check are
+* the binding. (Tier-2 `id_token` signature verification is the relying
+* service's job via an OIDC client, not a CLI's.)
+*/
+async function authorize(opts) {
+	const pkce = newPkceAndState();
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const { redirectUri, ready } = await awaitLoopbackCallback(pkce.state, timeoutMs, opts.signal);
+	const authUrl = buildAuthorizeUrl(opts, redirectUri, pkce);
+	opts.onUrl?.(authUrl);
+	if (opts.openBrowser !== false) openInBrowser(authUrl);
+	const token = await exchangeCode(opts, await ready, pkce.verifier);
+	let userId = token.userId;
+	if (opts.statusUrl) {
+		const confirmed = await confirmStatus(opts.statusUrl, token.access_token, opts.signal);
+		userId = userId ?? confirmed;
+	}
+	return {
+		accessToken: token.access_token,
+		...token.expires_in !== void 0 && { expiresIn: token.expires_in },
+		...token.id_token !== void 0 && { idToken: token.id_token },
+		...userId !== void 0 && { userId }
+	};
+}
+//#endregion
+export { AuthorizeError, authorize };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aooth/login-client",
+  "version": "0.1.8",
+  "description": "Zero-dependency CLI/loopback login helper for an aoothjs authorization server (browser round-trip + PKCE, returns a token)",
+  "keywords": [
+    "aoothjs",
+    "authorization-code",
+    "cli",
+    "login",
+    "loopback",
+    "oauth2",
+    "pkce"
+  ],
+  "homepage": "https://github.com/moostjs/aoothjs/tree/main/packages/login-client#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/aoothjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/aoothjs.git",
+    "directory": "packages/login-client"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}