@the-open-engine/zeroshot 6.26.0 → 6.28.0

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

package/src/target/target-session.ts

@@ -0,0 +1,249 @@
+import type { TargetCredentialStore } from './credential-store.ts';
+import type { TargetRecord, SettingsPort } from './target-registry.ts';
+import {
+  requestDeviceCode,
+  pollForToken,
+  UnboundSessionError,
+  type HttpTransport,
+  type Clock,
+  type TokenResponse,
+} from './device-flow.ts';
+import { targetServiceKey, TARGET_ACCOUNT } from './credential-store.ts';
+import { updateTargetOrganization } from './target-registry.ts';
+
+export class LoginRequiredError extends Error {
+  readonly targetName: string;
+  constructor(targetName: string) {
+    super(`Login required. Run: zeroshot target login ${targetName}`);
+    this.name = 'LoginRequiredError';
+    this.targetName = targetName;
+  }
+}
+
+export interface BrowserOpener {
+  open(url: string): Promise<void>;
+}
+
+export interface TargetSessionDeps {
+  readonly http: HttpTransport;
+  readonly clock: Clock;
+  readonly browserOpener: BrowserOpener;
+  readonly stderr: { write(s: string): void };
+  readonly discoveryEndpoints: {
+    readonly deviceAuthorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly revocationEndpoint?: string;
+    readonly clientId: string;
+  };
+}
+
+export async function targetLogin(
+  targetName: string,
+  target: TargetRecord,
+  credentialStore: TargetCredentialStore,
+  acquireLock: () => Promise<() => Promise<void>>,
+  settings: SettingsPort,
+  deps: TargetSessionDeps
+): Promise<{ organization: { id: string; name: string } }> {
+  const { http, clock, browserOpener, stderr, discoveryEndpoints } = deps;
+  const { deviceAuthorizationEndpoint, tokenEndpoint, clientId } = discoveryEndpoints;
+
+  const codeResponse = await requestDeviceCode(deviceAuthorizationEndpoint, clientId, http);
+
+  stderr.write(
+    `\nOpen this URL to authorize:\n  ${codeResponse.verification_uri}\n\nEnter code: ${codeResponse.user_code}\n\n`
+  );
+
+  if (codeResponse.verification_uri_complete) {
+    try {
+      await browserOpener.open(codeResponse.verification_uri_complete);
+    } catch {
+      // Browser open is best-effort
+    }
+  }
+
+  const tokenResponse = await pollForToken(
+    tokenEndpoint,
+    clientId,
+    codeResponse.device_code,
+    codeResponse.interval,
+    codeResponse.expires_in,
+    http,
+    clock
+  );
+
+  if (!tokenResponse.organization) {
+    throw new UnboundSessionError(codeResponse.verification_uri);
+  }
+
+  const serviceKey = targetServiceKey(target.id);
+  const release = await acquireLock();
+  try {
+    await credentialStore.set(serviceKey, TARGET_ACCOUNT, tokenResponse.refresh_token);
+  } finally {
+    await release();
+  }
+
+  updateTargetOrganization(targetName, tokenResponse.organization, settings);
+
+  return { organization: tokenResponse.organization };
+}
+
+export async function refreshAccessToken(
+  targetName: string,
+  target: TargetRecord,
+  credentialStore: TargetCredentialStore,
+  acquireLock: () => Promise<() => Promise<void>>,
+  deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>
+): Promise<{ accessToken: string; expiresIn: number }> {
+  const { http, discoveryEndpoints } = deps;
+  const { tokenEndpoint, revocationEndpoint, clientId } = discoveryEndpoints;
+  const serviceKey = targetServiceKey(target.id);
+
+  const release = await acquireLock();
+  try {
+    const currentRefreshToken = await credentialStore.get(serviceKey, TARGET_ACCOUNT);
+    if (!currentRefreshToken) {
+      throw new LoginRequiredError(targetName);
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: currentRefreshToken,
+      client_id: clientId,
+    });
+
+    let tokenResponse: TokenResponse;
+    const response = await http.fetch(tokenEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      redirect: 'error',
+    });
+
+    if (!response.ok) {
+      const errorBody = (await response.json().catch(() => ({ error: 'unknown' }))) as {
+        error: string;
+      };
+      if (errorBody.error === 'invalid_grant') {
+        await credentialStore.delete(serviceKey, TARGET_ACCOUNT);
+        throw new LoginRequiredError(targetName);
+      }
+      throw new Error(`Token refresh failed (${response.status}): ${errorBody.error}`);
+    }
+
+    tokenResponse = (await response.json()) as TokenResponse;
+
+    try {
+      await credentialStore.set(serviceKey, TARGET_ACCOUNT, tokenResponse.refresh_token);
+    } catch {
+      await bestEffortRevoke(tokenResponse.refresh_token, revocationEndpoint, clientId, http);
+      await credentialStore.delete(serviceKey, TARGET_ACCOUNT);
+      throw new LoginRequiredError(targetName);
+    }
+
+    return { accessToken: tokenResponse.access_token, expiresIn: tokenResponse.expires_in };
+  } finally {
+    await release();
+  }
+}
+
+async function bestEffortRevoke(
+  token: string,
+  revocationEndpoint: string | undefined,
+  clientId: string,
+  http: HttpTransport
+): Promise<void> {
+  if (!revocationEndpoint) return;
+  try {
+    const body = new URLSearchParams({
+      token,
+      client_id: clientId,
+      token_type_hint: 'refresh_token',
+    });
+    await http.fetch(revocationEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      redirect: 'error',
+    });
+  } catch {
+    // Best-effort
+  }
+}
+
+export interface TargetAccessTokenProvider {
+  getAccessToken(signal?: AbortSignal): Promise<string>;
+}
+
+export function getAccessTokenProvider(
+  targetName: string,
+  target: TargetRecord,
+  credentialStore: TargetCredentialStore,
+  acquireLock: () => Promise<() => Promise<void>>,
+  deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>,
+  clock: Clock = { now: () => Date.now() }
+): TargetAccessTokenProvider {
+  let cachedToken: string | null = null;
+  let expiresAt = 0;
+
+  return {
+    async getAccessToken(_signal?: AbortSignal): Promise<string> {
+      if (cachedToken && clock.now() < expiresAt - 30_000) {
+        return cachedToken;
+      }
+      const result = await refreshAccessToken(
+        targetName,
+        target,
+        credentialStore,
+        acquireLock,
+        deps
+      );
+      cachedToken = result.accessToken;
+      expiresAt = clock.now() + result.expiresIn * 1000;
+      return result.accessToken;
+    },
+  };
+}
+
+export async function revokeAndCleanup(
+  target: TargetRecord,
+  credentialStore: TargetCredentialStore,
+  acquireLock: () => Promise<() => Promise<void>>,
+  deps: Pick<TargetSessionDeps, 'http' | 'discoveryEndpoints'>,
+  force: boolean
+): Promise<void> {
+  const { http, discoveryEndpoints } = deps;
+  const { revocationEndpoint, clientId } = discoveryEndpoints;
+  const serviceKey = targetServiceKey(target.id);
+
+  const release = await acquireLock();
+  try {
+    const refreshToken = await credentialStore.get(serviceKey, TARGET_ACCOUNT);
+    if (refreshToken && revocationEndpoint) {
+      const body = new URLSearchParams({
+        token: refreshToken,
+        client_id: clientId,
+        token_type_hint: 'refresh_token',
+      });
+      try {
+        const response = await http.fetch(revocationEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: body.toString(),
+          redirect: 'error',
+        });
+        if (!response.ok && !force) {
+          throw new Error(
+            `Remote revocation failed (${response.status}). Use --force to remove anyway.`
+          );
+        }
+      } catch (err) {
+        if (!force) throw err;
+      }
+    }
+    await credentialStore.delete(serviceKey, TARGET_ACCOUNT);
+  } finally {
+    await release();
+  }
+}