@the-open-engine/zeroshot 6.27.0 → 6.28.0

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();
+}

package/src/target/discovery.ts

@@ -0,0 +1,149 @@
+import type { HttpTransport } from './device-flow.ts';
+
+const DISCOVERY_PATH = '/.well-known/openengine-hosted-target';
+const MAX_DISCOVERY_BYTES = 64 * 1024;
+
+export interface TargetSessionEndpoints {
+  readonly deviceAuthorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly revocationEndpoint?: string;
+  readonly clientId: string;
+}
+
+export class TargetDiscoveryError extends Error {
+  constructor(message: string) {
+    super(`Target discovery failed: ${message}`);
+    this.name = 'TargetDiscoveryError';
+  }
+}
+
+function record(value: unknown, field: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TargetDiscoveryError(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function stringField(source: Record<string, unknown>, field: string): string {
+  const value = source[field];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TargetDiscoveryError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function safeEndpoint(value: unknown, field: string, serviceOrigin: string): string {
+  if (typeof value !== 'string') {
+    throw new TargetDiscoveryError(`${field} must be an absolute URL`);
+  }
+  let endpoint: URL;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new TargetDiscoveryError(`${field} must be an absolute URL`);
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new TargetDiscoveryError(`${field} contains forbidden URL components`);
+  }
+  if (endpoint.origin !== serviceOrigin) {
+    throw new TargetDiscoveryError(`${field} must remain on the target origin`);
+  }
+  return endpoint.href;
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  const declaredLength = response.headers.get('content-length');
+  if (declaredLength !== null && Number(declaredLength) > MAX_DISCOVERY_BYTES) {
+    throw new TargetDiscoveryError('response exceeds the size limit');
+  }
+  if (!response.body) return response.json();
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_DISCOVERY_BYTES) {
+      await reader.cancel();
+      throw new TargetDiscoveryError('response exceeds the size limit');
+    }
+    chunks.push(value);
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new TargetDiscoveryError('response is not valid JSON');
+  }
+}
+
+async function fetchDocument(http: HttpTransport, url: string): Promise<Record<string, unknown>> {
+  const response = await http.fetch(url, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+  });
+  if (!response.ok) {
+    throw new TargetDiscoveryError(`request failed with status ${response.status}`);
+  }
+  return record(await readBoundedJson(response), 'response');
+}
+
+export async function discoverTargetSessionEndpoints(
+  targetUrl: string,
+  http: HttpTransport
+): Promise<TargetSessionEndpoints> {
+  const target = new URL(targetUrl);
+  const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+  if (discovery.kind !== 'openengine.hosted-target/v1') {
+    throw new TargetDiscoveryError('unsupported hosted-target version');
+  }
+  if (discovery.organization_binding !== 'device_approval') {
+    throw new TargetDiscoveryError('unsupported organization binding');
+  }
+
+  const oauth = record(discovery.oauth, 'oauth');
+  const metadataUrl = safeEndpoint(oauth.metadata_url, 'oauth.metadata_url', target.origin);
+  const deviceEndpoint = safeEndpoint(
+    oauth.device_authorization_endpoint,
+    'oauth.device_authorization_endpoint',
+    target.origin
+  );
+  const tokenEndpoint = safeEndpoint(oauth.token_endpoint, 'oauth.token_endpoint', target.origin);
+  const clientId = stringField(oauth, 'client_id');
+
+  const metadata = await fetchDocument(http, metadataUrl);
+  const metadataDeviceEndpoint = safeEndpoint(
+    metadata.device_authorization_endpoint,
+    'device_authorization_endpoint',
+    target.origin
+  );
+  const metadataTokenEndpoint = safeEndpoint(
+    metadata.token_endpoint,
+    'token_endpoint',
+    target.origin
+  );
+  if (metadataDeviceEndpoint !== deviceEndpoint || metadataTokenEndpoint !== tokenEndpoint) {
+    throw new TargetDiscoveryError('OAuth metadata does not match hosted-target discovery');
+  }
+
+  const revocationEndpoint =
+    metadata.revocation_endpoint === undefined
+      ? undefined
+      : safeEndpoint(metadata.revocation_endpoint, 'revocation_endpoint', target.origin);
+
+  return {
+    deviceAuthorizationEndpoint: deviceEndpoint,
+    tokenEndpoint,
+    ...(revocationEndpoint === undefined ? {} : { revocationEndpoint }),
+    clientId,
+  };
+}

package/src/target/index.ts

@@ -0,0 +1,55 @@
+export {
+  CredentialStoreUnavailableError,
+  KeyringCredentialStore,
+  FakeCredentialStore,
+  targetServiceKey,
+  TARGET_ACCOUNT,
+  type TargetCredentialStore,
+} from './credential-store.ts';
+
+export { acquireTargetLock } from './credential-lock.ts';
+
+export {
+  requestDeviceCode,
+  pollForToken,
+  DeviceFlowDeniedError,
+  DeviceFlowExpiredError,
+  UnboundSessionError,
+  type DeviceCodeResponse,
+  type TokenResponse,
+  type HttpTransport,
+  type Clock,
+} from './device-flow.ts';
+
+export {
+  addTarget,
+  removeTarget,
+  getTarget,
+  listTargets,
+  updateTargetOrganization,
+  validateTargetName,
+  normalizeAndValidateUrl,
+  TargetNameInvalidError,
+  TargetNameExistsError,
+  TargetNotFoundError,
+  TargetUrlInvalidError,
+  type TargetRecord,
+  type SettingsPort,
+} from './target-registry.ts';
+
+export {
+  targetLogin,
+  refreshAccessToken,
+  getAccessTokenProvider,
+  revokeAndCleanup,
+  LoginRequiredError,
+  type BrowserOpener,
+  type TargetSessionDeps,
+  type TargetAccessTokenProvider,
+} from './target-session.ts';
+
+export {
+  discoverTargetSessionEndpoints,
+  TargetDiscoveryError,
+  type TargetSessionEndpoints,
+} from './discovery.ts';

package/src/target/target-registry.ts

@@ -0,0 +1,174 @@
+import crypto from 'node:crypto';
+
+export interface TargetRecord {
+  readonly id: string;
+  readonly url: string;
+  readonly adapterVersion: string;
+  readonly deviceToken: string;
+  readonly organization?: { readonly id: string; readonly name: string };
+  readonly createdAt: string;
+}
+
+export class TargetNameInvalidError extends Error {
+  constructor(name: string) {
+    super(
+      `Invalid target name "${name}". Must be 1-64 characters, alphanumeric and hyphens only.`,
+    );
+    this.name = 'TargetNameInvalidError';
+  }
+}
+
+export class TargetNameExistsError extends Error {
+  constructor(name: string) {
+    super(`Target "${name}" already exists. Remove it first or choose a different name.`);
+    this.name = 'TargetNameExistsError';
+  }
+}
+
+export class TargetNotFoundError extends Error {
+  constructor(name: string) {
+    super(`Target "${name}" not found.`);
+    this.name = 'TargetNotFoundError';
+  }
+}
+
+export class TargetUrlInvalidError extends Error {
+  constructor(url: string, reason: string) {
+    super(`Invalid target URL "${url}": ${reason}`);
+    this.name = 'TargetUrlInvalidError';
+  }
+}
+
+const TARGET_NAME_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,62}[a-zA-Z0-9])?$/;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+export function validateTargetName(name: string): void {
+  if (!TARGET_NAME_PATTERN.test(name) || name.length > 64) {
+    throw new TargetNameInvalidError(name);
+  }
+}
+
+export function normalizeAndValidateUrl(rawUrl: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new TargetUrlInvalidError(rawUrl, 'not a valid URL');
+  }
+
+  if (parsed.username || parsed.password) {
+    throw new TargetUrlInvalidError(rawUrl, 'URL must not contain userinfo');
+  }
+
+  if (parsed.search || parsed.hash) {
+    throw new TargetUrlInvalidError(rawUrl, 'URL must not contain query or fragment');
+  }
+
+  const isLoopback = LOOPBACK_HOSTS.has(parsed.hostname);
+  if (parsed.protocol !== 'https:' && !isLoopback) {
+    throw new TargetUrlInvalidError(rawUrl, 'HTTPS required for non-loopback targets');
+  }
+
+  let normalized = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  if (normalized.endsWith('/') && normalized.length > 1) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+interface SettingsWithTargets {
+  _targets?: Record<string, TargetRecord>;
+  [key: string]: unknown;
+}
+
+export interface SettingsPort {
+  load(): SettingsWithTargets;
+  mutate(mutator: (settings: SettingsWithTargets) => void): void;
+}
+
+export function addTarget(
+  name: string,
+  rawUrl: string,
+  settings: SettingsPort,
+): TargetRecord {
+  validateTargetName(name);
+  const url = normalizeAndValidateUrl(rawUrl);
+
+  const existing = settings.load();
+  if (existing._targets?.[name]) {
+    throw new TargetNameExistsError(name);
+  }
+
+  const record: TargetRecord = {
+    id: crypto.randomUUID(),
+    url,
+    adapterVersion: 'v1',
+    deviceToken: crypto.randomUUID(),
+    createdAt: new Date().toISOString(),
+  };
+
+  settings.mutate((s) => {
+    if (!s._targets) {
+      s._targets = {};
+    }
+    s._targets[name] = record;
+  });
+
+  return record;
+}
+
+export function removeTarget(
+  name: string,
+  settings: SettingsPort,
+): TargetRecord {
+  const existing = settings.load();
+  const record = existing._targets?.[name];
+  if (!record) {
+    throw new TargetNotFoundError(name);
+  }
+
+  settings.mutate((s) => {
+    if (s._targets) {
+      delete s._targets[name];
+    }
+  });
+
+  return record;
+}
+
+export function getTarget(
+  name: string,
+  settings: SettingsPort,
+): TargetRecord | null {
+  const existing = settings.load();
+  return existing._targets?.[name] ?? null;
+}
+
+export function listTargets(
+  settings: SettingsPort,
+): Array<{ name: string; record: TargetRecord }> {
+  const existing = settings.load();
+  const targets = existing._targets ?? {};
+  return Object.entries(targets).map(([name, record]) => ({ name, record }));
+}
+
+export function updateTargetOrganization(
+  name: string,
+  organization: { id: string; name: string },
+  settings: SettingsPort,
+): void {
+  const existing = settings.load();
+  if (!existing._targets?.[name]) {
+    throw new TargetNotFoundError(name);
+  }
+
+  settings.mutate((s) => {
+    const target = s._targets?.[name];
+    if (target) {
+      (s._targets as Record<string, TargetRecord>)[name] = {
+        ...target,
+        organization,
+      };
+    }
+  });
+}