@the-open-engine/zeroshot 6.29.0 → 6.30.0

package/src/target/discovery.ts

@@ -1,57 +1,115 @@
-import type { HttpTransport } from './device-flow.ts';
-import { readBoundedJson } from './bounded-json.ts';
+import type { HttpTransport } from './device-flow.js';
+import { readBoundedResponseJson } from './bounded-response.js';
+import { TargetDiscoveryError } from './discovery-errors.js';
+import type { RouteTemplate } from './route-template.js';
+import {
+  exact,
+  exactStringSet,
+  record,
+  type CredentialInstallDescriptor,
+} from './discovery-validation.js';
+import {
+  parseAdapter,
+  parseCapsule,
+  parseEndpoint,
+  parseExtensions,
+  parseOAuth,
+  parseSession,
+  parseSizes,
+  parseTransport,
+  validateOAuthMetadata,
+} from './discovery-sections.js';
+export type { CredentialInstallDescriptor } from './discovery-validation.js';
+export { TargetDiscoveryError } from './discovery-errors.js';
+export { expandRoute, type RouteTemplate } from './route-template.js';
 
 const DISCOVERY_PATH = '/.well-known/openengine-hosted-target';
 const MAX_DISCOVERY_BYTES = 64 * 1024;
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const CAPSULE_AUDIENCE = 'capsule';
 
+const ROOT_FIELDS = [
+  'kind',
+  'adapter',
+  'protocol',
+  'binding',
+  'endpoint',
+  'pagination',
+  'cache_policy',
+  'schema_links',
+  'capsule_protocol',
+  'oauth',
+  'organization_binding',
+  'capability_flags',
+  'sizes',
+  'session',
+  'transport',
+  'extensions',
+] as const;
+export interface TargetDiscoveryDescriptor {
+  readonly origin: string;
+  readonly adapter: { readonly name: 'fargate' | 'docker' | 'local'; readonly majorVersion: 1 };
+  readonly endpoint: string;
+  readonly endpointCapabilities: readonly ['exec', 'log_stream'];
+  readonly pagination: { readonly defaultPageSize: number; readonly maxPageSize: number };
+  readonly sizes: {
+    readonly catalog: readonly ('tiny' | 'small' | 'standard' | 'large')[];
+    readonly default: 'tiny' | 'small' | 'standard' | 'large';
+  };
+  readonly oauth: {
+    readonly metadataUrl: string;
+    readonly deviceAuthorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly revocationEndpoint: string;
+    readonly clientId: string;
+    readonly deviceGrantType: typeof DEVICE_GRANT;
+    readonly audience: typeof CAPSULE_AUDIENCE;
+  };
+  readonly session: { readonly routeTemplate: RouteTemplate; readonly method: 'GET' };
+  readonly capsule: {
+    readonly baseUrl: string;
+    readonly routes: {
+      readonly allocate: RouteTemplate;
+      readonly list: RouteTemplate;
+      readonly inspect: RouteTemplate;
+      readonly terminate: RouteTemplate;
+      readonly limits: RouteTemplate;
+      readonly access: RouteTemplate;
+    };
+  };
+  readonly transport: {
+    readonly websocketRouteTemplate: RouteTemplate;
+    readonly unauthorizedStatus: 401;
+    readonly closeCodes: { readonly expired: 4401; readonly revoked: 4403 };
+  };
+  readonly capabilityFlags: readonly string[];
+  readonly credentialInstall: CredentialInstallDescriptor | null;
+  readonly additional: Readonly<Record<string, unknown>>;
+}
+
+/** Compatibility projection. New callers should retain the complete descriptor. */
 export interface TargetSessionEndpoints {
   readonly deviceAuthorizationEndpoint: string;
   readonly tokenEndpoint: string;
-  readonly revocationEndpoint?: string;
+  readonly revocationEndpoint: string;
   readonly clientId: string;
   readonly capsuleApiBaseUrl: string;
+  readonly deviceGrantType: typeof DEVICE_GRANT;
+  readonly audience: typeof CAPSULE_AUDIENCE;
+  readonly sessionEndpoint: string;
+  readonly descriptor: TargetDiscoveryDescriptor;
 }
 
-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;
+async function readBoundedJson(response: Response): Promise<unknown> {
+  return readBoundedResponseJson(response, MAX_DISCOVERY_BYTES, (kind) =>
+    new TargetDiscoveryError(
+      kind === 'size' ? 'response exceeds the size limit' : 'response is not valid UTF-8 JSON',
+    ),
+  );
 }
 
-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 fetchDocument(http: HttpTransport, url: string): Promise<Record<string, unknown>> {
   const response = await http.fetch(url, {
@@ -59,73 +117,81 @@ async function fetchDocument(http: HttpTransport, url: string): Promise<Record<s
     headers: { Accept: 'application/json' },
     redirect: 'error',
   });
+  if (response.url && new URL(response.url).href !== url) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new TargetDiscoveryError('request changed target route or authority');
+  }
   if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
     throw new TargetDiscoveryError(`request failed with status ${response.status}`);
   }
-  const body = await readBoundedJson(response, MAX_DISCOVERY_BYTES, {
-    tooLarge: () => new TargetDiscoveryError('response exceeds the size limit'),
-    invalid: () => new TargetDiscoveryError('response is not valid JSON'),
-  });
-  return record(body, 'response');
+  return record(await readBoundedJson(response), 'response');
 }
 
-export async function discoverTargetSessionEndpoints(
-  targetUrl: string,
-  http: HttpTransport
-): Promise<TargetSessionEndpoints> {
+
+export async function discoverTarget(targetUrl: string, http: HttpTransport): Promise<TargetDiscoveryDescriptor> {
   const target = new URL(targetUrl);
+  const origin = target.origin;
   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');
-  }
+  exact(discovery.kind, 'openengine.hosted-target/v1', 'kind');
 
-  const oauth = record(discovery.oauth, 'oauth');
-  const capsuleProtocol = record(discovery.capsule_protocol, 'capsule_protocol');
-  if (capsuleProtocol.name !== 'openengine.capsules/v1' || capsuleProtocol.major_version !== 1) {
-    throw new TargetDiscoveryError('unsupported capsule protocol');
-  }
-  const capsuleApiBaseUrl = safeEndpoint(
-    capsuleProtocol.base_url,
-    'capsule_protocol.base_url',
-    target.origin
-  ).replace(/\/$/, '');
-  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 adapter = parseAdapter(discovery);
+  const endpoint = parseEndpoint(discovery, origin);
+  const capsule = parseCapsule(discovery, origin);
+  const oauth = parseOAuth(discovery, origin);
+  exact(discovery.organization_binding, 'device_approval', 'organization_binding');
+  const capabilityFlags = exactStringSet(discovery.capability_flags, 'capability_flags', [
+    'capsule_allocate',
+    'capsule_read',
+    'capsule_terminate',
+    'capsule_access',
+    'connections_onboarding',
+  ]);
+  const sizes = parseSizes(discovery);
+  const session = parseSession(discovery);
+  const transport = parseTransport(discovery);
+  const credentialInstall = parseExtensions(discovery, origin);
 
-  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 metadata = await fetchDocument(http, oauth.metadataUrl);
+  validateOAuthMetadata(metadata, origin, [
+    oauth.deviceAuthorizationEndpoint,
+    oauth.tokenEndpoint,
+    oauth.revocationEndpoint,
+  ]);
 
-  const revocationEndpoint =
-    metadata.revocation_endpoint === undefined
-      ? undefined
-      : safeEndpoint(metadata.revocation_endpoint, 'revocation_endpoint', target.origin);
+  const additional = Object.freeze(
+    Object.fromEntries(Object.entries(discovery).filter(([key]) =>
+      !ROOT_FIELDS.includes(key as (typeof ROOT_FIELDS)[number]),
+    )),
+  );
+  return Object.freeze({
+    origin,
+    adapter,
+    endpoint: endpoint.url,
+    endpointCapabilities: endpoint.capabilities,
+    pagination: endpoint.pagination,
+    sizes,
+    oauth,
+    session,
+    capsule,
+    transport,
+    capabilityFlags,
+    credentialInstall,
+    additional,
+  });
+}
 
-  return {
-    deviceAuthorizationEndpoint: deviceEndpoint,
-    tokenEndpoint,
-    ...(revocationEndpoint === undefined ? {} : { revocationEndpoint }),
-    clientId,
-    capsuleApiBaseUrl,
-  };
+export async function discoverTargetSessionEndpoints(targetUrl: string, http: HttpTransport): Promise<TargetSessionEndpoints> {
+  const descriptor = await discoverTarget(targetUrl, http);
+  return Object.freeze({
+    deviceAuthorizationEndpoint: descriptor.oauth.deviceAuthorizationEndpoint,
+    tokenEndpoint: descriptor.oauth.tokenEndpoint,
+    revocationEndpoint: descriptor.oauth.revocationEndpoint,
+    clientId: descriptor.oauth.clientId,
+    capsuleApiBaseUrl: descriptor.capsule.baseUrl.replace(/\/$/, ''),
+    deviceGrantType: descriptor.oauth.deviceGrantType,
+    audience: descriptor.oauth.audience,
+    sessionEndpoint: new URL(descriptor.session.routeTemplate.template, descriptor.origin).href,
+    descriptor,
+  });
 }

package/src/target/index.ts

@@ -5,21 +5,23 @@ export {
   targetServiceKey,
   TARGET_ACCOUNT,
   type TargetCredentialStore,
-} from './credential-store.ts';
+} from './credential-store.js';
 
-export { acquireTargetLock } from './credential-lock.ts';
+export { acquireTargetLock } from './credential-lock.js';
 
 export {
   requestDeviceCode,
   pollForToken,
+  parseTokenResponse,
   DeviceFlowDeniedError,
   DeviceFlowExpiredError,
   UnboundSessionError,
   type DeviceCodeResponse,
+  type DeviceExchangeContext,
   type TokenResponse,
   type HttpTransport,
   type Clock,
-} from './device-flow.ts';
+} from './device-flow.js';
 
 export {
   addTarget,
@@ -35,21 +37,23 @@ export {
   TargetUrlInvalidError,
   type TargetRecord,
   type SettingsPort,
-} from './target-registry.ts';
+} from './target-registry.js';
 
 export {
-  targetLogin,
-  refreshAccessToken,
-  getAccessTokenProvider,
-  revokeAndCleanup,
+  TargetSessionManager,
   LoginRequiredError,
   type BrowserOpener,
   type TargetSessionDeps,
-  type TargetAccessTokenProvider,
-} from './target-session.ts';
+  type TargetSessionManagerInit,
+} from './target-session.js';
 
 export {
+  discoverTarget,
   discoverTargetSessionEndpoints,
+  expandRoute,
   TargetDiscoveryError,
+  type CredentialInstallDescriptor,
+  type RouteTemplate,
+  type TargetDiscoveryDescriptor,
   type TargetSessionEndpoints,
-} from './discovery.ts';
+} from './discovery.js';

package/src/target/oauth-http.ts

@@ -0,0 +1,27 @@
+import { readBoundedResponseJson } from './bounded-response.js';
+
+const MAX_SESSION_RESPONSE_BYTES = 64 * 1024;
+
+
+export async function readTargetSessionJson(response: Response): Promise<unknown> {
+  return readBoundedResponseJson(response, MAX_SESSION_RESPONSE_BYTES, (kind) =>
+    new Error(
+      kind === 'size'
+        ? 'Target session response exceeds the size limit'
+        : 'Target session response is malformed',
+    ),
+  );
+}
+
+export async function readOAuthError(response: Response): Promise<string | null> {
+  try {
+    const value = await readTargetSessionJson(response);
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+    const record = value as Record<string, unknown>;
+    return Object.keys(record).length === 1 && typeof record.error === 'string'
+      ? record.error
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/target/refresh-exchange.ts

@@ -0,0 +1,36 @@
+import { oauthFormRequest, type HttpTransport } from './device-flow.js';
+import { readOAuthError, readTargetSessionJson } from './oauth-http.js';
+import { parseTokenResponse, type TokenResponse } from './token-response.js';
+
+export interface RefreshExchangeRequest {
+  readonly tokenEndpoint: string;
+  readonly clientId: string;
+  readonly refreshToken: string;
+  readonly audience: string;
+  readonly http: HttpTransport;
+  readonly signal?: AbortSignal;
+}
+
+export async function exchangeRefreshToken(
+  request: RefreshExchangeRequest,
+): Promise<TokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    client_id: request.clientId,
+    refresh_token: request.refreshToken,
+    audience: request.audience,
+  });
+  const response = await request.http.fetch(
+    request.tokenEndpoint,
+    oauthFormRequest(body, request.signal),
+  );
+  if (response.url && new URL(response.url).href !== request.tokenEndpoint) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error('Target token response changed route or authority');
+  }
+  if (!response.ok) {
+    await readOAuthError(response);
+    throw new Error('Target token exchange failed');
+  }
+  return parseTokenResponse(await readTargetSessionJson(response));
+}

package/src/target/refresh-revocation.ts

@@ -0,0 +1,29 @@
+import { oauthFormRequest, type HttpTransport } from './device-flow.js';
+import type { TargetSessionEndpoints } from './discovery.js';
+
+interface RevocationDeps {
+  readonly http: HttpTransport;
+  readonly discoveryEndpoints: TargetSessionEndpoints;
+}
+
+export async function revokeRefreshToken(
+  token: string,
+  deps: RevocationDeps,
+): Promise<Response> {
+  const body = new URLSearchParams({
+    token,
+    client_id: deps.discoveryEndpoints.clientId,
+    token_type_hint: 'refresh_token',
+  });
+  const response = await deps.http.fetch(
+    deps.discoveryEndpoints.revocationEndpoint,
+    oauthFormRequest(body),
+  );
+  if (response.url &&
+      new URL(response.url).href !== deps.discoveryEndpoints.revocationEndpoint) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error('Target revocation response changed route or authority');
+  }
+  await response.body?.cancel().catch(() => undefined);
+  return response;
+}

package/src/target/route-template.ts

@@ -0,0 +1,105 @@
+import { TargetDiscoveryError } from './discovery-errors.js';
+
+export interface RouteTemplate {
+  readonly template: string;
+  readonly variables: readonly string[];
+  expand(values: Readonly<Record<string, string | number | undefined>>): string;
+}
+
+function expandCompiled(
+  template: string,
+  variables: readonly string[],
+  values: Readonly<Record<string, string | number | undefined>>,
+): string {
+  const supplied = Object.keys(values).filter((key) => values[key] !== undefined);
+  if (supplied.some((key) => !variables.includes(key))) {
+    throw new TargetDiscoveryError('route expansion supplied an undeclared variable');
+  }
+  let expanded = template.replace(/\{\?([^}]+)\}/g, (_match, names: string) => {
+    const params = names.split(',').flatMap((name) => {
+      const value = values[name];
+      return value === undefined
+        ? []
+        : [`${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`];
+    });
+    return params.length === 0 ? '' : `?${params.join('&')}`;
+  });
+  expanded = expanded.replace(/\{([^}?][^}]*)\}/g, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) throw new TargetDiscoveryError(`route expansion is missing ${name}`);
+    const opaque = String(value);
+    if (opaque === '.' || opaque === '..') {
+      throw new TargetDiscoveryError('route expansion contains a structural dot segment');
+    }
+    return encodeURIComponent(opaque);
+  });
+  if (/[{}]/.test(expanded)) {
+    throw new TargetDiscoveryError('route expansion left an unexpanded variable');
+  }
+  const canonical = new URL(expanded, 'https://route-validation.invalid');
+  if (canonical.origin !== 'https://route-validation.invalid' ||
+      `${canonical.pathname}${canonical.search}` !== expanded) {
+    throw new TargetDiscoveryError('route expansion changed during URL canonicalization');
+  }
+  return expanded;
+}
+
+function isUnsafeTemplate(value: unknown): boolean {
+  return typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') ||
+    value.includes('\\') || value.includes('#') || /[\u0000-\u0020\u007f]/.test(value) ||
+    value.replace(/\{\?[^}]+\}/g, '').includes('?');
+}
+
+function expressionNames(
+  expressions: RegExpMatchArray[],
+  field: string,
+): string[] {
+  const found: string[] = [];
+  for (const expression of expressions) {
+    const body = expression[1];
+    if (body === undefined) throw new TargetDiscoveryError(`${field} contains an invalid expression`);
+    const query = body.startsWith('?');
+    const names = body.replace(/^\?/, '').split(',');
+    if (query && field !== 'capsule_protocol.route_templates.list') {
+      throw new TargetDiscoveryError(`${field} contains an unsupported query expansion`);
+    }
+    found.push(...names);
+  }
+  return found;
+}
+
+export function routeTemplate(
+  value: unknown,
+  field: string,
+  variables: readonly string[],
+): RouteTemplate {
+  if (isUnsafeTemplate(value)) {
+    throw new TargetDiscoveryError(`${field} must be a safe relative route template`);
+  }
+  const template = value as string;
+  const expressions = [...template.matchAll(/\{([^{}]+)\}/g)];
+  const stripped = template.replace(/\{[^{}]+\}/g, '');
+  if (stripped.includes('{') || stripped.includes('}') ||
+      /(^|\/)(?:\.|%2e){1,2}(?:\/|$)/i.test(stripped)) {
+    throw new TargetDiscoveryError(`${field} contains an unsafe template expression`);
+  }
+  const found = expressionNames(expressions, field);
+  if (found.length !== variables.length || new Set(found).size !== found.length ||
+      variables.some((name) => !found.includes(name))) {
+    throw new TargetDiscoveryError(`${field} declares unsupported variables`);
+  }
+  const compiledVariables = Object.freeze([...variables]);
+  return Object.freeze({
+    template,
+    variables: compiledVariables,
+    expand: (values: Readonly<Record<string, string | number | undefined>>) =>
+      expandCompiled(template, compiledVariables, values),
+  });
+}
+
+export function expandRoute(
+  template: RouteTemplate,
+  values: Readonly<Record<string, string | number | undefined>>,
+): string {
+  return template.expand(values);
+}

package/src/target/session-errors.ts

@@ -0,0 +1,9 @@
+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;
+  }
+}

package/src/target/session-verification.ts

@@ -0,0 +1,51 @@
+import type { HttpTransport } from './device-flow.js';
+import type { TargetSessionEndpoints } from './discovery.js';
+import { readTargetSessionJson } from './oauth-http.js';
+
+interface SessionVerificationDeps {
+  readonly http: HttpTransport;
+  readonly discoveryEndpoints: TargetSessionEndpoints;
+}
+
+function parseOrganization(value: unknown): { readonly id: string } {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Target session response is malformed');
+  }
+  const body = value as Record<string, unknown>;
+  const fields = Object.keys(body);
+  if (fields.length !== 2 || !fields.includes('kind') ||
+      !fields.includes('organization_id') ||
+      body.kind !== 'openengine.target-session/v1' ||
+      typeof body.organization_id !== 'string' ||
+      body.organization_id.length === 0 || body.organization_id.length > 256) {
+    throw new Error('Target session response is malformed');
+  }
+  return Object.freeze({ id: body.organization_id });
+}
+
+export async function readVerifiedOrganization(
+  accessToken: string,
+  signal: AbortSignal | undefined,
+  deps: SessionVerificationDeps,
+): Promise<{ readonly id: string }> {
+  const init: RequestInit & { redirect: 'error' } = {
+    method: deps.discoveryEndpoints.descriptor.session.method,
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Bearer ${accessToken}`,
+      'Cache-Control': 'no-store',
+    },
+    redirect: 'error',
+  };
+  if (signal !== undefined) init.signal = signal;
+  const response = await deps.http.fetch(deps.discoveryEndpoints.sessionEndpoint, init);
+  if (response.url && new URL(response.url).href !== deps.discoveryEndpoints.sessionEndpoint) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error('Target session response changed route or authority');
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error('Target session verification failed');
+  }
+  return parseOrganization(await readTargetSessionJson(response));
+}