Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { failCommand } from "../utils/commandResult.js";
/**
* OAuth 2.0 + PKCE driver for the HeyGen public OAuth flow.
*
* Entry points:
* - `startAuthorizationCodeFlow()` — full interactive login (browser
* opens, loopback waits, code → tokens, persist).
* - `refreshTokens()` — POST <token-endpoint> with grant_type=refresh_token.
* - `revokeTokens()` — best-effort POST <revoke-endpoint>.
*
* Endpoints split across two hosts (verified live):
* - **Authorize** — GET https://app.heygen.com/oauth/authorize
* Renders the consent screen, has to live on the same origin as the
* user's web session (cookies). The Next.js SPA shell serves this.
* - **Token** — POST https://api2.heygen.com/v1/oauth/token
* Server-to-server JSON API. `app.heygen.com/oauth/token` returns
* the SPA HTML for direct POSTs — confirmed by curl; only the api2
* route returns JSON OAuth responses.
* - **Revoke** — POST https://api2.heygen.com/v1/oauth/revoke
* Same host/prefix as token.
*
* The `heygen-oauth-urls.ts` default in `hyperframes-internal/demo-next`
* lists `app.heygen.com/oauth/token` as the default — that's either
* proxied via a Next.js rewrite or set via `HEYGEN_OAUTH_TOKEN_URL` in
* their prod env. A direct fetch to it returns the SPA shell, so we
* use the api2 endpoint here.
*
* Overrides:
* - `HYPERFRAMES_OAUTH_AUTHORIZE_URL`
* - `HYPERFRAMES_OAUTH_TOKEN_URL`
* - `HYPERFRAMES_OAUTH_REVOKE_URL`
* - `HYPERFRAMES_OAUTH_CLIENT_ID`
*
* Public client — no `client_secret`.
*/
import {
ErrApi,
ErrDeviceAuthFailed,
ErrLoginChanged,
ErrOAuthNotConfigured,
ErrRefreshFailed,
isAuthError,
} from "./errors.js";
import { generatePkcePair, generateState } from "./pkce.js";
import { startLoopback } from "./loopback.js";
import { openBrowser } from "./browser.js";
import { scrubCredentials } from "./scrub.js";
import {
isHeaderSafe,
readStore,
writeStore,
type Credentials,
type OAuthTokens,
type StoredUserInfo,
} from "./store.js";
import { c } from "../ui/colors.js";
const REVOKE_TIMEOUT_MS = 5_000;
const MIN_EXPIRES_IN_SECONDS = 30;
/**
* Default OAuth client_id baked at build time. Override with the
* `HYPERFRAMES_OAUTH_CLIENT_ID` env var. Empty string means "not
* configured" — `resolveClientId()` errors cleanly with a pointer
* at `--api-key`.
*/
const DEFAULT_CLIENT_ID = "q2A2QRSke2LrFTPJhoDbHtXh";
const DEFAULT_SCOPES = "openid profile email";
// Endpoint defaults — see file-header comment for why these straddle two
// hosts. Each is independently overridable.
const DEFAULT_AUTHORIZE_URL = "https://app.heygen.com/oauth/authorize";
const DEFAULT_TOKEN_URL = "https://api2.heygen.com/v1/oauth/token";
const DEFAULT_REVOKE_URL = "https://api2.heygen.com/v1/oauth/revoke";
const DEFAULT_DEVICE_AUTHORIZATION_URL = "https://api2.heygen.com/v1/oauth/device_authorization";
const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
const MAX_DEVICE_FLOW_SECONDS = 30 * 60;
const MIN_DEVICE_POLL_SECONDS = 5;
const MAX_DEVICE_POLL_SECONDS = 60;
const MAX_DEVICE_RESPONSE_BYTES = 64 * 1024;
const DEVICE_REQUEST_TIMEOUT_MS = 15_000;
function authorizeEndpoint(): string {
return process.env["HYPERFRAMES_OAUTH_AUTHORIZE_URL"] || DEFAULT_AUTHORIZE_URL;
}
function tokenEndpoint(): string {
return process.env["HYPERFRAMES_OAUTH_TOKEN_URL"] || DEFAULT_TOKEN_URL;
}
function revokeEndpoint(): string {
return process.env["HYPERFRAMES_OAUTH_REVOKE_URL"] || DEFAULT_REVOKE_URL;
}
function deviceAuthorizationEndpoint(): string {
return process.env["HYPERFRAMES_OAUTH_DEVICE_URL"] || DEFAULT_DEVICE_AUTHORIZATION_URL;
}
export interface AuthorizeFlowOptions {
/** Override scopes (default `openid profile email`). */
scope?: string;
/** Inject a custom fetch (used by tests). */
fetchImpl?: typeof fetch;
/** Override timeout in ms (default 120s). */
timeoutMs?: number;
}
export interface AuthorizeFlowResult {
tokens: OAuthTokens;
/** Returned identity info for friendly post-login UX. */
userInfo?: Record<string, unknown>;
}
export interface RefreshOptions {
fetchImpl?: typeof fetch;
}
export interface DeviceAuthorizationChallenge {
userCode: string;
verificationUri: string;
verificationUriComplete?: string;
}
export interface DeviceAuthorizationFlowOptions {
/** Override scopes (default `openid profile email`). */
scope?: string;
/** Inject a custom fetch (used by tests). */
fetchImpl?: typeof fetch;
/** Inject polling sleep (used by tests). */
sleepImpl?: (ms: number) => Promise<void>;
/** Inject a monotonic-enough clock in epoch milliseconds (used by tests). */
now?: () => number;
/** Bound each authorization-server request, including its response body (default 15s). */
requestTimeoutMs?: number;
/** Present the user code and verification URI without exposing device_code. */
onChallenge?: (challenge: DeviceAuthorizationChallenge) => void | Promise<void>;
}
/** Read the client_id, throwing `ErrOAuthNotConfigured` when unset. */
export function resolveClientId(): string {
const override = process.env["HYPERFRAMES_OAUTH_CLIENT_ID"];
const id = override && override.length > 0 ? override : DEFAULT_CLIENT_ID;
if (!id || id.length === 0) throw ErrOAuthNotConfigured();
return id;
}
/**
* For command-entry points: throw the standard `ErrOAuthNotConfigured`
* via `resolveClientId()`; on a real misconfig, print a friendly hint
* and exit with status 1 rather than dumping a stack. Throws non-auth
* errors so callers can surface programmer bugs.
*/
export function assertOAuthConfiguredOrExit(): void {
try {
resolveClientId();
} catch (err) {
if (isAuthError(err) && err.code === "OAUTH_NOT_CONFIGURED") {
console.error(`Error: ${err.message}`);
if (err.hint) console.error(err.hint);
failCommand();
}
throw err;
}
}
export async function startAuthorizationCodeFlow(
opts: AuthorizeFlowOptions = {},
): Promise<AuthorizeFlowResult> {
const clientId = resolveClientId();
const scope = opts.scope ?? DEFAULT_SCOPES;
const pkce = generatePkcePair();
const state = generateState();
const loopback = await startLoopback({ state, timeoutMs: opts.timeoutMs });
const authorizeUrl = buildAuthorizeUrl({
clientId,
redirectUri: loopback.redirectUri,
scope,
state,
challenge: pkce.challenge,
});
// Print the host+path only (no state / code_challenge) so live
// values can't leak into scrollback / CI logs during the 120s window.
console.log(`Opening browser to ${c.dim(authorizeHost(authorizeUrl))} ...`);
const { opened } = await openBrowser(authorizeUrl);
if (!opened) {
// openBrowser already printed the manual URL; surface it as the
// last on-screen instruction so it isn't buried above "Waiting…".
console.log(c.dim("(open the URL above to continue)"));
}
console.log(`Waiting for callback on ${c.accent(loopback.redirectUri)} ...`);
let codeResult;
try {
codeResult = await loopback.result;
} catch (err) {
await loopback.close().catch(() => {});
throw err;
}
const tokens = await exchangeCodeForTokens({
clientId,
code: codeResult.code,
redirectUri: codeResult.redirectUri,
verifier: pkce.verifier,
fetchImpl: opts.fetchImpl,
});
// Fresh login → clean OAuth block (no inherited refresh_token).
await persistOAuth(tokens);
return { tokens };
}
/**
* RFC 8628 attended device flow. This function deliberately returns an
* unpersisted token set: the command must verify `/v3/users/me` first and only
* then call `persistFreshOAuth`. That ordering prevents a token for the wrong
* account/resource from ever becoming the active shared credential.
*/
export async function startDeviceAuthorizationFlow(
opts: DeviceAuthorizationFlowOptions = {},
): Promise<OAuthTokens> {
const runtime: DeviceFlowRuntime = {
clientId: resolveClientId(),
fetchImpl: opts.fetchImpl ?? fetch,
sleepImpl:
opts.sleepImpl ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms))),
now: opts.now ?? Date.now,
requestTimeoutMs: opts.requestTimeoutMs ?? DEVICE_REQUEST_TIMEOUT_MS,
};
const issuance = await requestDeviceAuthorization(runtime, opts.scope ?? DEFAULT_SCOPES);
await opts.onChallenge?.({
userCode: issuance.userCode,
verificationUri: issuance.verificationUri,
...(issuance.verificationUriComplete
? { verificationUriComplete: issuance.verificationUriComplete }
: {}),
});
return await pollDeviceToken(runtime, issuance);
}
interface DeviceFlowRuntime {
clientId: string;
fetchImpl: typeof fetch;
sleepImpl: (ms: number) => Promise<void>;
now: () => number;
requestTimeoutMs: number;
}
async function requestDeviceAuthorization(
runtime: DeviceFlowRuntime,
scope: string,
): Promise<ParsedDeviceAuthorization> {
return await withDeviceRequestTimeout(
runtime,
"could not reach the authorization server",
async (signal) => {
const response = await runtime.fetchImpl(deviceAuthorizationEndpoint(), {
method: "POST",
headers: {
"content-type": "application/x-www-form-urlencoded",
accept: "application/json",
},
body: new URLSearchParams({ client_id: runtime.clientId, scope }).toString(),
signal,
});
if (!response.ok) {
throw ErrDeviceAuthFailed(`authorization server returned HTTP ${response.status}`);
}
return parseDeviceAuthorizationResponse(await readJsonOrDeviceError(response));
},
);
}
async function pollDeviceToken(
runtime: DeviceFlowRuntime,
issuance: ParsedDeviceAuthorization,
): Promise<OAuthTokens> {
const deadline = runtime.now() + Math.min(issuance.expiresIn, MAX_DEVICE_FLOW_SECONDS) * 1000;
let intervalSeconds = issuance.interval;
while (runtime.now() < deadline) {
const remainingMs = deadline - runtime.now();
if (remainingMs <= 0) break;
await runtime.sleepImpl(Math.min(intervalSeconds * 1000, remainingMs));
const result = await requestDeviceToken(runtime, issuance.deviceCode);
if (result.tokens) return result.tokens;
if (result.slowDown) {
intervalSeconds = Math.min(
Math.max(intervalSeconds + 5, result.retryAfterSeconds ?? 0),
MAX_DEVICE_POLL_SECONDS,
);
}
}
throw ErrDeviceAuthFailed("the code expired");
}
async function requestDeviceToken(
runtime: DeviceFlowRuntime,
deviceCode: string,
): Promise<DevicePollResult> {
return await withDeviceRequestTimeout(
runtime,
"lost contact with the authorization server",
async (signal) => {
const response = await runtime.fetchImpl(tokenEndpoint(), {
method: "POST",
headers: {
"content-type": "application/x-www-form-urlencoded",
accept: "application/json",
},
body: new URLSearchParams({
grant_type: DEVICE_CODE_GRANT_TYPE,
device_code: deviceCode,
client_id: runtime.clientId,
}).toString(),
signal,
});
return await evaluateDevicePollResponse(response, runtime.now());
},
);
}
interface DevicePollResult {
tokens?: OAuthTokens;
slowDown?: boolean;
retryAfterSeconds?: number;
}
async function evaluateDevicePollResponse(
response: Response,
nowMs: number,
): Promise<DevicePollResult> {
if (response.ok) {
return { tokens: parseTokenResponse(await readJsonOrDeviceError(response)) };
}
const error = await readDeviceOAuthError(response);
switch (error) {
case "authorization_pending":
return {};
case "slow_down":
return { slowDown: true, retryAfterSeconds: retryAfterSeconds(response, nowMs) };
case "access_denied":
throw ErrDeviceAuthFailed("access was denied");
case "expired_token":
throw ErrDeviceAuthFailed("the code expired");
default:
if (response.status === 429) {
return { slowDown: true, retryAfterSeconds: retryAfterSeconds(response, nowMs) };
}
throw ErrDeviceAuthFailed(`authorization server returned HTTP ${response.status}`);
}
}
async function withDeviceRequestTimeout<T>(
runtime: DeviceFlowRuntime,
networkError: string,
operation: (signal: AbortSignal) => Promise<T>,
): Promise<T> {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), runtime.requestTimeoutMs);
try {
return await operation(controller.signal);
} catch (err) {
if (controller.signal.aborted) {
throw ErrDeviceAuthFailed("authorization server request timed out");
}
if (isAuthError(err)) throw err;
throw ErrDeviceAuthFailed(networkError);
} finally {
clearTimeout(timer);
}
}
function retryAfterSeconds(response: Response, nowMs: number): number | undefined {
const value = response.headers.get("retry-after")?.trim();
if (!value) return undefined;
if (/^\d+$/.test(value)) return Math.min(Number(value), MAX_DEVICE_POLL_SECONDS);
const retryAt = Date.parse(value);
if (!Number.isFinite(retryAt)) return undefined;
return Math.min(Math.max(Math.ceil((retryAt - nowMs) / 1000), 0), MAX_DEVICE_POLL_SECONDS);
}
export async function refreshTokens(
refresh_token: string,
opts: RefreshOptions = {},
): Promise<OAuthTokens> {
const clientId = resolveClientId();
const fetchImpl = opts.fetchImpl ?? fetch;
const body = new URLSearchParams({
grant_type: "refresh_token",
refresh_token,
client_id: clientId,
});
const res = await fetchImpl(tokenEndpoint(), {
method: "POST",
headers: {
"content-type": "application/x-www-form-urlencoded",
accept: "application/json",
},
body: body.toString(),
});
if (res.status === 400 || res.status === 401) {
throw ErrRefreshFailed(await safeText(res));
}
if (!res.ok) {
throw ErrApi(res.status, (await safeText(res)) || res.statusText);
}
const payload = await readJsonOrThrow(res);
const tokens = parseTokenResponse(payload);
// Refresh grant → preserve a refresh_token the server didn't rotate.
await persistOAuth(tokens, { refreshed: refresh_token });
return tokens;
}
export interface RevokeOptions extends RefreshOptions {
/** Hint to the server about which token we're sending (RFC 7009). */
token_type_hint?: "access_token" | "refresh_token";
/** Abort the revoke after this many ms (default 5s). */
timeoutMs?: number;
}
/**
* RFC 7009 revoke. Best-effort: never throws. A hung IdP or unset
* client_id MUST NOT block local logout — both are caught here so the
* caller can wipe local state immediately afterward regardless.
*/
export async function revokeTokens(token: string, opts: RevokeOptions = {}): Promise<void> {
let clientId: string;
try {
clientId = resolveClientId();
} catch {
// OAuth not configured — nothing to revoke server-side.
return;
}
const fetchImpl = opts.fetchImpl ?? fetch;
const params: Record<string, string> = { token, client_id: clientId };
if (opts.token_type_hint) params["token_type_hint"] = opts.token_type_hint;
const body = new URLSearchParams(params);
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? REVOKE_TIMEOUT_MS);
try {
const res = await fetchImpl(revokeEndpoint(), {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: body.toString(),
signal: controller.signal,
});
if (!res.ok) {
console.error(
c.dim(`Note: token revoke returned HTTP ${res.status}; local credentials cleared anyway.`),
);
}
} catch {
/* timeout or network error — silent, this is best-effort */
} finally {
clearTimeout(timer);
}
}
function authorizeHost(fullUrl: string): string {
try {
const u = new URL(fullUrl);
return `${u.origin}${u.pathname}`;
} catch {
return fullUrl.split("?")[0] ?? fullUrl;
}
}
function buildAuthorizeUrl(args: {
clientId: string;
redirectUri: string;
scope: string;
state: string;
challenge: string;
}): string {
const params = new URLSearchParams({
response_type: "code",
client_id: args.clientId,
redirect_uri: args.redirectUri,
scope: args.scope,
state: args.state,
code_challenge: args.challenge,
code_challenge_method: "S256",
});
return `${authorizeEndpoint()}?${params.toString()}`;
}
async function exchangeCodeForTokens(args: {
clientId: string;
code: string;
redirectUri: string;
verifier: string;
fetchImpl?: typeof fetch;
}): Promise<OAuthTokens> {
const fetchImpl = args.fetchImpl ?? fetch;
const body = new URLSearchParams({
grant_type: "authorization_code",
code: args.code,
redirect_uri: args.redirectUri,
client_id: args.clientId,
code_verifier: args.verifier,
});
const res = await fetchImpl(tokenEndpoint(), {
method: "POST",
headers: {
"content-type": "application/x-www-form-urlencoded",
accept: "application/json",
},
body: body.toString(),
});
if (res.status === 400 || res.status === 401) {
// The authorization code is single-use and short-lived. A 400/401
// here almost always means it expired during the loopback wait or
// was already redeemed — surface an actionable message instead of
// a bare "HeyGen API error (400)".
const detail = (await safeText(res)) || res.statusText;
throw ErrRefreshFailed(
`authorization code rejected (${detail}); please run \`auth login\` again`,
);
}
if (!res.ok) {
throw ErrApi(res.status, (await safeText(res)) || res.statusText);
}
return parseTokenResponse(await readJsonOrThrow(res));
}
/**
* Parse the RFC 6749 token response. Backend may also include
* `id_token` (OIDC) but we ignore that today.
*
* Throws `ErrInvalidTokenResponse` (an AuthError carrying
* REFRESH_FAILED code, so callers using `tryRefresh` consistently
* route the user to "log in again" instead of a generic API error)
* on shape failures.
*/
// fallow-ignore-next-line complexity
export function parseTokenResponse(payload: unknown): OAuthTokens {
if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
throw ErrRefreshFailed("token endpoint returned a non-object payload");
}
const obj = payload as Record<string, unknown>;
const accessToken = stringField(obj, "access_token");
if (!accessToken) {
throw ErrRefreshFailed("token endpoint did not return an access_token");
}
if (!isHeaderSafe(accessToken)) {
throw ErrRefreshFailed("access_token contains control characters");
}
const out: OAuthTokens = { access_token: accessToken };
const refreshToken = stringField(obj, "refresh_token");
if (refreshToken) {
if (!isHeaderSafe(refreshToken)) {
throw ErrRefreshFailed("refresh_token contains control characters");
}
out.refresh_token = refreshToken;
}
const tokenType = stringField(obj, "token_type");
if (tokenType) out.token_type = tokenType;
const scope = stringField(obj, "scope");
if (scope) out.scope = scope;
const expiresIn = numericField(obj, "expires_in");
if (expiresIn !== undefined) {
// Clamp to a sensible minimum so a misbehaving / clock-skewed
// server returning 0 or a negative value doesn't put expires_at in
// the past and cause the 401-refresh path to loop.
const clamped = Math.max(expiresIn, MIN_EXPIRES_IN_SECONDS);
out.expires_at = new Date(Date.now() + clamped * 1000).toISOString();
}
return out;
}
function stringField(obj: Record<string, unknown>, key: string): string | undefined {
const v = obj[key];
return typeof v === "string" && v.length > 0 ? v : undefined;
}
function numericField(obj: Record<string, unknown>, key: string): number | undefined {
const v = obj[key];
if (typeof v === "number" && Number.isFinite(v)) return v;
if (typeof v === "string") {
const n = Number.parseFloat(v);
return Number.isFinite(n) ? n : undefined;
}
return undefined;
}
/**
* Persist a new OAuth token set, always preserving a co-located `api_key`.
*
* `refreshed` (the refresh_token that was exchanged) controls how the new
* tokens combine with whatever OAuth block is already on disk:
* - absent (fresh authorization-code login): overwrite the OAuth
* block entirely. A new interactive login is a clean session — it
* must NOT inherit the previous session's refresh_token, or a
* response that omits one would pair a new access token with a
* stale refresh token and break/misroute the next refresh.
* - set (refresh grant): keep the prior refresh_token / scope /
* token_type when the response omits them. RFC 6749 §6 lets the
* token endpoint skip refresh_token on a no-rotation refresh, and
* dropping it would brick future refreshes. Throws `LOGIN_CHANGED`
* without writing if the stored login is no longer the refreshed one.
*/
async function persistOAuth(tokens: OAuthTokens, opts: { refreshed?: string } = {}): Promise<void> {
let existing: Credentials = {};
try {
const { credentials } = await readStore();
existing = credentials;
} catch (err) {
// A fresh login overwrites the OAuth block anyway; a refresh must not guess.
if (opts.refreshed !== undefined) throw err;
}
if (opts.refreshed !== undefined && existing.oauth?.refresh_token !== opts.refreshed) {
throw ErrLoginChanged();
}
const oauth: OAuthTokens =
opts.refreshed !== undefined ? { ...existing.oauth, ...tokens } : { ...tokens };
// Start from the existing record so co-located data survives: the
// api_key, the friendly-display `user` block, AND any unknown/foreign
// keys another CLI wrote (carried on a hidden symbol slot by spread).
// Only the `oauth` block is overwritten here.
await writeStore({ ...existing, oauth });
}
/** Persist a verified fresh OAuth login while preserving cross-CLI fields. */
export async function persistFreshOAuth(tokens: OAuthTokens): Promise<void> {
await persistOAuth(tokens);
}
/**
* Atomically install a verified device session and its identity metadata.
*
* This is intentionally one credential-file rename: if the write fails, the
* previous credential remains intact and the caller can revoke the freshly
* minted tokens without leaving a half-installed session or stale identity.
*/
export async function persistVerifiedOAuthSession(
tokens: OAuthTokens,
user: StoredUserInfo,
): Promise<void> {
let credentials: Credentials = {};
try {
({ credentials } = await readStore());
} catch {
// Match the other fresh-login path: a corrupt prior file must not prevent
// installing a newly verified session.
credentials = {};
}
const next: Credentials = {
...credentials,
oauth: { ...tokens },
};
if (user.email || user.first_name || user.last_name || user.username) {
// Preserve only unknown/foreign user fields from the existing record.
// Assigning every known field (including undefined) prevents identity
// fields from the previous account surviving when the new response omits
// them; serializeUser skips undefined values.
next.user = {
...credentials.user,
email: user.email,
first_name: user.first_name,
last_name: user.last_name,
username: user.username,
};
} else {
delete next.user;
}
await writeStore(next);
}
interface ParsedDeviceAuthorization {
deviceCode: string;
userCode: string;
verificationUri: string;
verificationUriComplete?: string;
expiresIn: number;
interval: number;
}
function parseDeviceAuthorizationResponse(payload: unknown): ParsedDeviceAuthorization {
const data = requireDeviceAuthorizationRecord(payload);
const deviceCode = stringField(data, "device_code");
const userCode = stringField(data, "user_code");
const verificationUri = requiredSafeVerificationUri(data, "verification_uri");
const verificationUriComplete = optionalSafeVerificationUri(data, "verification_uri_complete");
const expiresIn = strictNumericField(data, "expires_in");
const interval = strictNumericField(data, "interval");
requireSafeDeviceCode(deviceCode);
requireSafeDeviceCode(userCode);
const timing = normalizeDeviceAuthorizationTiming(data, expiresIn, interval);
return {
deviceCode,
userCode,
verificationUri,
...(verificationUriComplete ? { verificationUriComplete } : {}),
...timing,
};
}
function requireSafeDeviceCode(value: string | undefined): asserts value is string {
if (!value || !isHeaderSafe(value)) {
throw ErrDeviceAuthFailed("authorization server returned an invalid response");
}
}
function normalizeDeviceAuthorizationTiming(
data: Record<string, unknown>,
expiresIn: number | undefined,
interval: number | undefined,
): Pick<ParsedDeviceAuthorization, "expiresIn" | "interval"> {
if (
!isPositiveNumber(expiresIn) ||
(data["interval"] !== undefined && !isPositiveNumber(interval))
) {
throw ErrDeviceAuthFailed("authorization server returned invalid timing values");
}
return {
expiresIn,
interval: Math.min(
Math.max(Math.ceil(interval ?? MIN_DEVICE_POLL_SECONDS), MIN_DEVICE_POLL_SECONDS),
MAX_DEVICE_POLL_SECONDS,
),
};
}
function requiredSafeVerificationUri(data: Record<string, unknown>, key: string): string {
const value = normalizeSafeVerificationUri(stringField(data, key));
if (!value) throw ErrDeviceAuthFailed("authorization server returned an unsafe verification URL");
return value;
}
function optionalSafeVerificationUri(
data: Record<string, unknown>,
key: string,
): string | undefined {
if (data[key] === undefined) return undefined;
return requiredSafeVerificationUri(data, key);
}
function requireDeviceAuthorizationRecord(payload: unknown): Record<string, unknown> {
if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
throw ErrDeviceAuthFailed("authorization server returned an invalid response");
}
return payload as Record<string, unknown>;
}
function isPositiveNumber(value: number | undefined): value is number {
return value !== undefined && value > 0;
}
function normalizeSafeVerificationUri(value: string | undefined): string | undefined {
if (!value || !isHeaderSafe(value)) return undefined;
try {
const url = new URL(value);
if (url.username || url.password) return undefined;
const allowed =
url.protocol === "https:" ||
(url.protocol === "http:" && ["127.0.0.1", "localhost"].includes(url.hostname));
return allowed ? url.href : undefined;
} catch {
return undefined;
}
}
async function readJsonOrDeviceError(res: Response): Promise<unknown> {
return await readBoundedDeviceJson(res);
}
async function readDeviceOAuthError(res: Response): Promise<string | undefined> {
try {
const payload = await readBoundedDeviceJson(res);
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
const error = (payload as Record<string, unknown>)["error"];
return typeof error === "string" ? error : undefined;
} catch {
return undefined;
}
}
function strictNumericField(obj: Record<string, unknown>, key: string): number | undefined {
const value = obj[key];
if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
if (typeof value !== "string" || value.trim() === "") return undefined;
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : undefined;
}
async function readBoundedDeviceJson(res: Response): Promise<unknown> {
if (!res.body) throw ErrDeviceAuthFailed("authorization server returned no data");
const reader = res.body.getReader();
const chunks: Uint8Array[] = [];
let total = 0;
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (!value) continue;
total += value.byteLength;
if (total > MAX_DEVICE_RESPONSE_BYTES) {
await reader.cancel();
throw ErrDeviceAuthFailed("authorization server response was too large");
}
chunks.push(value);
}
const body = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
body.set(chunk, offset);
offset += chunk.byteLength;
}
return JSON.parse(new TextDecoder().decode(body));
} catch (err) {
if (isAuthError(err)) throw err;
throw ErrDeviceAuthFailed("authorization server returned non-JSON data");
} finally {
reader.releaseLock();
}
}
async function readJsonOrThrow(res: Response): Promise<unknown> {
try {
return await res.json();
} catch (err) {
throw ErrApi(res.status, `non-JSON body: ${(err as Error).message}`);
}
}
async function safeText(res: Response): Promise<string> {
try {
// Token/revoke requests carry refresh_token, authorization code, and
// code_verifier in the form body; a server/proxy error page can echo
// request data back. Scrub before the text reaches any error message.
return scrubCredentials((await res.text()).slice(0, 500));
} catch {
return "";
}
}