@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 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
npm i @aooth/login-client # Node >= 18
Use
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
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).