@the-open-engine/zeroshot 6.26.0 → 6.28.0

package/scripts/build-cluster.js

@@ -4,8 +4,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const root = path.resolve(__dirname, '..');
-const buildRoot = path.join(root, '.cluster-build');
-const outputRoot = path.join(root, 'lib/cluster');
+const clusterBuildRoot = path.join(root, '.cluster-build');
+const hostedSessionBuildRoot = path.join(root, '.hosted-session-build');
+const clusterOutputRoot = path.join(root, 'lib/cluster');
+const hostedSessionOutputRoot = path.join(root, 'lib/hosted-session');
 
 function filesBelow(directory) {
   const entries = fs.readdirSync(directory, { withFileTypes: true });
@@ -15,7 +17,7 @@ function filesBelow(directory) {
   });
 }
 
-function copyBuild(sourceRoot, mode) {
+function copyBuild(sourceRoot, outputRoot, mode) {
   for (const source of filesBelow(sourceRoot)) {
     const relative = path.relative(sourceRoot, source);
     const extension = path.extname(relative);
@@ -37,7 +39,19 @@ function copyBuild(sourceRoot, mode) {
   }
 }
 
-fs.rmSync(outputRoot, { recursive: true, force: true });
-copyBuild(path.join(buildRoot, 'cjs'), 'cjs');
-copyBuild(path.join(buildRoot, 'esm'), 'esm');
-fs.rmSync(buildRoot, { recursive: true, force: true });
+fs.rmSync(clusterOutputRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionOutputRoot, { recursive: true, force: true });
+copyBuild(path.join(clusterBuildRoot, 'cjs'), clusterOutputRoot, 'cjs');
+copyBuild(path.join(clusterBuildRoot, 'esm'), clusterOutputRoot, 'esm');
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'cjs', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'cjs'
+);
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'esm', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'esm'
+);
+fs.rmSync(clusterBuildRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionBuildRoot, { recursive: true, force: true });

package/src/cluster/client.ts

@@ -16,16 +16,25 @@ import {
   WatchSubscriptionStream,
 } from './subscriptions.js';
 
+export interface WebSocketFactoryOptions {
+  readonly headers?: Readonly<Record<string, string>>;
+}
 export interface ConnectOptions {
   readonly protocols?: string | readonly string[];
-  readonly webSocketFactory?: (url: string, protocols?: string | readonly string[]) => WebSocketLike | Promise<WebSocketLike>;
+  readonly webSocketFactory?: (url: string, protocols?: string | readonly string[], options?: WebSocketFactoryOptions) => WebSocketLike | Promise<WebSocketLike>;
   readonly signal?: AbortSignal;
   readonly initialize?: InitializeParams;
+  readonly headers?: Readonly<Record<string, string>>;
 }
 export interface WatchSubscription { readonly result: WatchResult; readonly stream: WatchSubscriptionStream; }
 export interface LogsSubscription { readonly result: LogsResult; readonly stream: LogsSubscriptionStream; }
 export interface AgentAttachSubscription { readonly result: AgentAttachResult; readonly stream: AgentAttachSubscriptionStream; }
 export interface CoherentWatchSubscription extends WatchSubscription { readonly snapshot: GetResult; }
+export interface ConnectInitializedResult {
+  readonly connection: Connection;
+  readonly client: ClusterClient;
+  readonly initializeResult: InitializeResult;
+}
 
 export class ClusterClient {
   constructor(readonly connection: Connection) {}
@@ -114,6 +123,7 @@ export class ClusterClient {
 async function defaultWebSocketFactory(
   url: string,
   protocols?: string | readonly string[],
+  options?: WebSocketFactoryOptions,
 ): Promise<WebSocketLike> {
   const globalWebSocket = (globalThis as {
     readonly WebSocket?: new (
@@ -121,9 +131,16 @@ async function defaultWebSocketFactory(
       protocols?: string | readonly string[],
     ) => WebSocketLike;
   }).WebSocket;
-  if (globalWebSocket) return new globalWebSocket(url, protocols);
+  if (globalWebSocket) {
+    if (options?.headers && Object.keys(options.headers).length > 0) {
+      throw new ClusterConfigError(
+        'WebSocket upgrade headers require the ws library; the browser WebSocket API cannot carry request headers',
+        'HEADERS_UNSUPPORTED',
+      );
+    }
+    return new globalWebSocket(url, protocols);
+  }
   try {
-    // Dynamic loading keeps the optional Node runtime off the browser/global-WebSocket path.
     const imported: unknown = await import('ws');
     const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
       ? imported.default
@@ -134,8 +151,9 @@ async function defaultWebSocketFactory(
     const Constructor = candidate as new (
       url: string,
       protocols?: string | readonly string[],
+      options?: { readonly headers?: Readonly<Record<string, string>> },
     ) => WebSocketLike;
-    return new Constructor(url, protocols);
+    return options?.headers ? new Constructor(url, protocols, { headers: options.headers }) : new Constructor(url, protocols);
   } catch (cause) {
     throw new ClusterConfigError(
       "No WebSocket runtime is available; install 'ws' or pass webSocketFactory",
@@ -181,7 +199,7 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
   const factory = options.webSocketFactory ?? defaultWebSocketFactory;
   let socket: WebSocketLike | undefined;
   try {
-    socket = await factory(url, options.protocols);
+    socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
     await waitForOpen(socket, options.signal);
     const connection = new Connection(socket);
     await new ClusterClient(connection).initialize(
@@ -197,3 +215,25 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
     throw error;
   }
 }
+
+export async function connectInitialized(url: string, options: ConnectOptions = {}): Promise<ConnectInitializedResult> {
+  const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+  let socket: WebSocketLike | undefined;
+  try {
+    socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
+    await waitForOpen(socket, options.signal);
+    const connection = new Connection(socket);
+    const client = new ClusterClient(connection);
+    const initializeResult = await client.initialize(
+      options.initialize,
+      options.signal === undefined ? {} : { signal: options.signal },
+    );
+    return { connection, client, initializeResult };
+  } catch (error) {
+    if (socket) {
+      try { await socket.close(); }
+      catch { /* preserve the construction error */ }
+    }
+    throw error;
+  }
+}

package/src/cluster/connection.ts

@@ -27,6 +27,20 @@ export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly C
   CLOSED: Object.freeze([] as const),
 });
 export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export const CLOSE_REASON_MAX_BYTES = 123;
+const CLOSE_REASON_ENCODER = new TextEncoder();
+function boundedCloseReason(reason: string): string {
+  const retained: string[] = [];
+  const scratch = new Uint8Array(4);
+  let bytes = 0;
+  for (const codePoint of reason) {
+    const { written } = CLOSE_REASON_ENCODER.encodeInto(codePoint, scratch);
+    if (bytes + written > CLOSE_REASON_MAX_BYTES) break;
+    retained.push(codePoint);
+    bytes += written;
+  }
+  return retained.join('');
+}
 export interface CallOptions { readonly signal?: AbortSignal; readonly requestTimeoutMs?: number; }
 
 type Deferred<T> = {
@@ -70,6 +84,8 @@ export class Connection {
   readonly #removeSocketListeners: Array<() => void> = [];
   readonly #ownedSubscriptions = new WeakSet<SubscriptionRegistration>();
   #closePromise?: Promise<void>;
+  #closeCode: number | undefined;
+  #closeReason: string | undefined;
   readonly closeDiagnostics: unknown[] = [];
   readonly protocolDiagnostics: ClusterProtocolError[] = [];
 
@@ -80,12 +96,14 @@ export class Connection {
     this.#removeSocketListeners.push(
       addSocketListener(socket, 'message', (event) => this.#onMessage(event)),
       addSocketListener(socket, 'error', () => { void this.#startClose(false); }),
-      addSocketListener(socket, 'close', () => { void this.#startClose(false); }),
+      addSocketListener(socket, 'close', (...args: unknown[]) => { this.#captureCloseState(args); void this.#startClose(false); }),
     );
   }
   get state(): ConnectionState { return this.#state; }
   get pendingSize(): number { return this.#pending.size; }
   get subscriptionCount(): number { return this.#subscriptions.size; }
+  get closeCode(): number | undefined { return this.#closeCode; }
+  get closeReason(): string | undefined { return this.#closeReason; }
   call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options: CallOptions = {}): Promise<ClusterMethodResults[M]> {
     if (!(UNARY_METHODS as readonly string[]).includes(method)) {
       throw new ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
@@ -266,6 +284,19 @@ export class Connection {
     if (this.protocolDiagnostics.length === PROTOCOL_DIAGNOSTIC_CAPACITY) this.protocolDiagnostics.shift();
     this.protocolDiagnostics.push(new ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
   }
+  #captureCloseState(args: unknown[]): void {
+    if (args.length === 0) return;
+    const first = args[0];
+    if (typeof first === 'number') {
+      this.#closeCode = first;
+      const raw = args.length > 1 ? String(args[1]) : undefined;
+      this.#closeReason = raw === undefined ? undefined : boundedCloseReason(raw);
+    } else if (first !== null && typeof first === 'object') {
+      const event = first as { code?: unknown; reason?: unknown };
+      if (typeof event.code === 'number') this.#closeCode = event.code;
+      if (typeof event.reason === 'string') this.#closeReason = boundedCloseReason(event.reason);
+    }
+  }
   #startClose(sendCancels: boolean): Promise<void> {
     if (this.#closePromise) return this.#closePromise; if (this.#state === 'CLOSED') return Promise.resolve();
     this.#transition('CLOSING'); this.#closePromise = Promise.resolve().then(() => this.#finishClose(sendCancels)); return this.#closePromise;

package/src/cluster/index.ts

@@ -14,7 +14,7 @@ export {
 export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
 export * from './payload-value.js';
 export * from './json-source.js';
-export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export { CLOSE_REASON_MAX_BYTES, CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
 export type {
   CallOptions,
   ConnectionState,
@@ -32,11 +32,13 @@ export type {
   WatchSubscriptionItem,
   WatchSubscriptionClosedItem,
 } from './subscriptions.js';
-export { ClusterClient, connect } from './client.js';
+export { ClusterClient, connect, connectInitialized } from './client.js';
 export type {
   AgentAttachSubscription,
   CoherentWatchSubscription,
+  ConnectInitializedResult,
   ConnectOptions,
   LogsSubscription,
   WatchSubscription,
+  WebSocketFactoryOptions,
 } from './client.js';

package/src/cluster/ws.d.ts

@@ -2,6 +2,7 @@ declare module 'ws' {
   const WebSocket: new (
     url: string,
     protocols?: string | readonly string[],
+    options?: { readonly headers?: Readonly<Record<string, string>> },
   ) => import('./index.js').WebSocketLike;
   export default WebSocket;
 }

package/src/hosted-session/coordinator.ts

@@ -0,0 +1,110 @@
+import { ClusterConfigError, connectInitialized } from '../cluster/index.js';
+import type { ServerCapabilities, GraphProfile } from '../cluster/index.js';
+import type { ConnectOptions } from '../cluster/index.js';
+import type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+
+function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+  const defined = signals.filter((s): s is AbortSignal => s !== undefined);
+  if (defined.length === 0) return undefined;
+  if (defined.length === 1) return defined[0];
+  return AbortSignal.any(defined);
+}
+
+export class HostedSessionCoordinator {
+  readonly #getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly #connectOptions: Omit<ConnectOptions, 'headers' | 'signal'> | undefined;
+  readonly #clock: { now(): number };
+  readonly #closeController = new AbortController();
+  #referenceCapabilities: ServerCapabilities | undefined;
+  #closed = false;
+
+  constructor(init: HostedSessionInit) {
+    this.#getAccess = init.getAccess;
+    this.#connectOptions = init.connectOptions;
+    this.#clock = init.clock ?? Date;
+  }
+
+  async open(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#referenceCapabilities = session.initializeResult.capabilities;
+    return session;
+  }
+
+  async replace(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#verifyCapabilities(session.initializeResult.capabilities, session);
+    return session;
+  }
+
+  renewalDeadline(access: AccessResponse, receivedAt: number): number {
+    const expiresAt = Date.parse(access.expiresAt);
+    if (Number.isNaN(expiresAt)) {
+      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    }
+    const lifetime = expiresAt - receivedAt;
+    return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true;
+    this.#closeController.abort();
+  }
+
+  async #createSession(signal?: AbortSignal): Promise<InitializedSession> {
+    const combined = combineSignals([signal, this.#closeController.signal]);
+    const access = await this.#getAccess(combined);
+    const expiresAt = Date.parse(access.expiresAt);
+    if (Number.isNaN(expiresAt)) {
+      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    }
+    if (expiresAt <= this.#clock.now()) {
+      throw new ClusterConfigError('access token is already expired', 'ACCESS_EXPIRED');
+    }
+
+    let endpoint: URL;
+    try {
+      endpoint = new URL(access.endpoint);
+    } catch {
+      throw new ClusterConfigError('hosted access endpoint is invalid', 'INVALID_ENDPOINT');
+    }
+    if (endpoint.protocol !== 'wss:') {
+      throw new ClusterConfigError('hosted access endpoint must use wss', 'INSECURE_ENDPOINT');
+    }
+
+    return connectInitialized(endpoint.href, {
+      ...this.#connectOptions,
+      headers: { Authorization: `Bearer ${access.token}` },
+      ...(combined !== undefined ? { signal: combined } : {}),
+    });
+  }
+
+  #verifyCapabilities(incoming: ServerCapabilities, session: InitializedSession): void {
+    if (!this.#referenceCapabilities) return;
+    const ref = this.#referenceCapabilities;
+    const mismatches: string[] = [];
+
+    if (ref.graphProfiles) {
+      const incomingProfiles = new Set<GraphProfile>(incoming.graphProfiles ?? []);
+      for (const profile of ref.graphProfiles) {
+        if (!incomingProfiles.has(profile)) mismatches.push(`missing graphProfile: ${profile}`);
+      }
+    }
+    if (ref.logs && !incoming.logs) mismatches.push('missing capability: logs');
+    if (ref.agentAttach && !incoming.agentAttach)
+      mismatches.push('missing capability: agentAttach');
+
+    if (mismatches.length > 0) {
+      void session.connection.close();
+      throw new ClusterConfigError(
+        `replacement capabilities incompatible: ${mismatches.join(', ')}`,
+        'INCOMPATIBLE_CAPABILITIES'
+      );
+    }
+  }
+
+  #requireNotClosed(): void {
+    if (this.#closed) throw new ClusterConfigError('coordinator is closed', 'COORDINATOR_CLOSED');
+  }
+}

package/src/hosted-session/index.ts

@@ -0,0 +1,2 @@
+export { HostedSessionCoordinator } from './coordinator.js';
+export type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';

package/src/hosted-session/types.ts

@@ -0,0 +1,21 @@
+import type { Connection } from '../cluster/index.js';
+import type { ClusterClient, ConnectOptions } from '../cluster/index.js';
+import type { InitializeResult } from '../cluster/index.js';
+
+export interface AccessResponse {
+  readonly endpoint: string;
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export interface HostedSessionInit {
+  readonly getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly connectOptions?: Omit<ConnectOptions, 'headers' | 'signal'>;
+  readonly clock?: { now(): number };
+}
+
+export interface InitializedSession {
+  readonly connection: Connection;
+  readonly client: ClusterClient;
+  readonly initializeResult: InitializeResult;
+}

package/src/target/credential-lock.ts

@@ -0,0 +1,35 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+// @ts-expect-error no declaration file for proper-lockfile
+import lockfile from 'proper-lockfile';
+
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRIES = 100;
+const LOCK_RETRY_MIN_TIMEOUT_MS = 50;
+const LOCK_RETRY_MAX_TIMEOUT_MS = 5_000;
+
+export async function acquireTargetLock(targetId: string): Promise<() => Promise<void>> {
+  const lockDir = path.join(os.homedir(), '.zeroshot');
+  await fs.mkdir(lockDir, { recursive: true });
+
+  const lockTarget = path.join(lockDir, `target-${targetId}.lock`);
+  try {
+    await fs.writeFile(lockTarget, '', { flag: 'wx' });
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+  }
+
+  const release = await lockfile.lock(lockTarget, {
+    stale: LOCK_STALE_MS,
+    retries: {
+      retries: LOCK_RETRIES,
+      minTimeout: LOCK_RETRY_MIN_TIMEOUT_MS,
+      maxTimeout: LOCK_RETRY_MAX_TIMEOUT_MS,
+    },
+  });
+
+  return async () => {
+    await release();
+  };
+}

package/src/target/credential-store.ts

@@ -0,0 +1,107 @@
+export class CredentialStoreUnavailableError extends Error {
+  constructor(message?: string) {
+    super(
+      message ??
+        'OS secure store unavailable. Install libsecret (Linux), or run on macOS/Windows. No plaintext fallback.',
+    );
+    this.name = 'CredentialStoreUnavailableError';
+  }
+}
+
+export interface TargetCredentialStore {
+  get(service: string, account: string): Promise<string | null>;
+  set(service: string, account: string, token: string): Promise<void>;
+  delete(service: string, account: string): Promise<void>;
+}
+
+export function targetServiceKey(targetId: string): string {
+  return `zeroshot-target-${targetId}`;
+}
+
+export const TARGET_ACCOUNT = 'refresh-token';
+
+export class KeyringCredentialStore implements TargetCredentialStore {
+  private readonly Entry: new (service: string, account: string) => {
+    getPassword(): string;
+    setPassword(password: string): void;
+    deletePassword(): void;
+  };
+
+  private constructor(
+    Entry: new (service: string, account: string) => {
+      getPassword(): string;
+      setPassword(password: string): void;
+      deletePassword(): void;
+    },
+  ) {
+    this.Entry = Entry;
+  }
+
+  static async create(): Promise<KeyringCredentialStore> {
+    let keyringModule: { Entry: new (service: string, account: string) => {
+      getPassword(): string;
+      setPassword(password: string): void;
+      deletePassword(): void;
+    } };
+    try {
+      keyringModule = await import('@napi-rs/keyring') as typeof keyringModule;
+    } catch {
+      throw new CredentialStoreUnavailableError();
+    }
+    if (!keyringModule.Entry) {
+      throw new CredentialStoreUnavailableError();
+    }
+    return new KeyringCredentialStore(keyringModule.Entry);
+  }
+
+  async get(service: string, account: string): Promise<string | null> {
+    try {
+      const entry = new this.Entry(service, account);
+      return entry.getPassword();
+    } catch {
+      return null;
+    }
+  }
+
+  async set(service: string, account: string, token: string): Promise<void> {
+    const entry = new this.Entry(service, account);
+    entry.setPassword(token);
+  }
+
+  async delete(service: string, account: string): Promise<void> {
+    try {
+      const entry = new this.Entry(service, account);
+      entry.deletePassword();
+    } catch {
+      // Already deleted or not present
+    }
+  }
+}
+
+export class FakeCredentialStore implements TargetCredentialStore {
+  private readonly store = new Map<string, string>();
+
+  private key(service: string, account: string): string {
+    return `${service}::${account}`;
+  }
+
+  async get(service: string, account: string): Promise<string | null> {
+    return this.store.get(this.key(service, account)) ?? null;
+  }
+
+  async set(service: string, account: string, token: string): Promise<void> {
+    this.store.set(this.key(service, account), token);
+  }
+
+  async delete(service: string, account: string): Promise<void> {
+    this.store.delete(this.key(service, account));
+  }
+
+  has(service: string, account: string): boolean {
+    return this.store.has(this.key(service, account));
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}

package/src/target/device-flow.ts

@@ -0,0 +1,157 @@
+export interface DeviceCodeResponse {
+  readonly device_code: string;
+  readonly user_code: string;
+  readonly verification_uri: string;
+  readonly verification_uri_complete?: string;
+  readonly expires_in: number;
+  readonly interval: number;
+}
+
+export interface TokenResponse {
+  readonly access_token: string;
+  readonly refresh_token: string;
+  readonly token_type: string;
+  readonly expires_in: number;
+  readonly organization?: { readonly id: string; readonly name: string };
+}
+
+export interface HttpTransport {
+  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response>;
+}
+
+export interface Clock {
+  now(): number;
+}
+
+export class DeviceFlowDeniedError extends Error {
+  constructor() {
+    super('Device authorization denied by user');
+    this.name = 'DeviceFlowDeniedError';
+  }
+}
+
+export class DeviceFlowExpiredError extends Error {
+  constructor() {
+    super('Device authorization code expired');
+    this.name = 'DeviceFlowExpiredError';
+  }
+}
+
+export class UnboundSessionError extends Error {
+  readonly verificationUri: string;
+  constructor(verificationUri: string) {
+    super(
+      `Session not bound to an organization. Re-approve at ${verificationUri} and select an organization.`,
+    );
+    this.name = 'UnboundSessionError';
+    this.verificationUri = verificationUri;
+  }
+}
+
+const DEFAULT_CLOCK: Clock = { now: () => Date.now() };
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+      },
+      { once: true },
+    );
+  });
+}
+
+export async function requestDeviceCode(
+  deviceAuthorizationEndpoint: string,
+  clientId: string,
+  http: HttpTransport,
+  signal?: AbortSignal,
+): Promise<DeviceCodeResponse> {
+  const body = new URLSearchParams({
+    client_id: clientId,
+    scope: 'openid',
+  });
+
+  const init: RequestInit & { redirect: 'error' } = {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+    redirect: 'error',
+  };
+  if (signal) init.signal = signal;
+
+  const response = await http.fetch(deviceAuthorizationEndpoint, init);
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Device code request failed (${response.status}): ${text}`);
+  }
+
+  return (await response.json()) as DeviceCodeResponse;
+}
+
+export async function pollForToken(
+  tokenEndpoint: string,
+  clientId: string,
+  deviceCode: string,
+  interval: number,
+  expiresIn: number,
+  http: HttpTransport,
+  clock: Clock = DEFAULT_CLOCK,
+  signal?: AbortSignal,
+): Promise<TokenResponse> {
+  const deadline = clock.now() + expiresIn * 1000;
+  let currentInterval = interval;
+
+  while (clock.now() < deadline) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException('Aborted', 'AbortError');
+    }
+
+    await sleep(currentInterval * 1000, signal);
+
+    const body = new URLSearchParams({
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      device_code: deviceCode,
+      client_id: clientId,
+    });
+
+    const init: RequestInit & { redirect: 'error' } = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      redirect: 'error',
+    };
+    if (signal) init.signal = signal;
+
+    const response = await http.fetch(tokenEndpoint, init);
+
+    if (response.ok) {
+      return (await response.json()) as TokenResponse;
+    }
+
+    const errorBody = (await response.json()) as { error: string };
+    switch (errorBody.error) {
+      case 'authorization_pending':
+        continue;
+      case 'slow_down':
+        currentInterval += 5;
+        continue;
+      case 'access_denied':
+        throw new DeviceFlowDeniedError();
+      case 'expired_token':
+        throw new DeviceFlowExpiredError();
+      default:
+        throw new Error(`Token endpoint error: ${errorBody.error}`);
+    }
+  }
+
+  throw new DeviceFlowExpiredError();
+}