@the-open-engine/zeroshot 6.29.0 → 6.30.0

package/src/target/discovery-sections.ts

@@ -0,0 +1,251 @@
+import { TargetDiscoveryError } from './discovery-errors.js';
+import {
+  closedRecord,
+  exact,
+  exactStringSet,
+  integer,
+  parseCredentialInstall,
+  sameOriginUrl,
+  stringField,
+  type CredentialInstallDescriptor,
+} from './discovery-validation.js';
+import { routeTemplate } from './route-template.js';
+
+export function parseAdapter(discovery: Record<string, unknown>): {
+  readonly name: 'fargate' | 'docker' | 'local';
+  readonly majorVersion: 1;
+} {
+  const adapter = closedRecord(discovery.adapter, 'adapter', ['name', 'major_version']);
+  if (!['fargate', 'docker', 'local'].includes(String(adapter.name))) {
+    throw new TargetDiscoveryError('adapter.name is not supported');
+  }
+  exact(adapter.major_version, 1, 'adapter.major_version');
+  return Object.freeze({
+    name: adapter.name as 'fargate' | 'docker' | 'local',
+    majorVersion: 1 as const,
+  });
+}
+
+export function validateCachePolicy(discovery: Record<string, unknown>): void {
+  const cache = closedRecord(discovery.cache_policy, 'cache_policy', ['control', 'discovery']);
+  exact(cache.control, 'no-store', 'cache_policy.control');
+  if (cache.discovery !== undefined && cache.discovery !== null &&
+      typeof cache.discovery !== 'string') {
+    throw new TargetDiscoveryError('cache_policy.discovery must be a string or null');
+  }
+}
+
+export function parseSizes(discovery: Record<string, unknown>): {
+  readonly catalog: readonly ('tiny' | 'small' | 'standard' | 'large')[];
+  readonly default: 'tiny' | 'small' | 'standard' | 'large';
+} {
+  const sizes = closedRecord(discovery.sizes, 'sizes', ['catalog', 'default']);
+  if (!Array.isArray(sizes.catalog) || sizes.catalog.length === 0 ||
+      new Set(sizes.catalog).size !== sizes.catalog.length ||
+      sizes.catalog.some((size) => !['tiny', 'small', 'standard', 'large'].includes(String(size)))) {
+    throw new TargetDiscoveryError('sizes.catalog contains an unsupported size');
+  }
+  if (!sizes.catalog.includes(sizes.default)) {
+    throw new TargetDiscoveryError('sizes.default is not in sizes.catalog');
+  }
+  return Object.freeze({
+    catalog: Object.freeze([...(sizes.catalog as Array<'tiny' | 'small' | 'standard' | 'large'>)]),
+    default: sizes.default as 'tiny' | 'small' | 'standard' | 'large',
+  });
+}
+
+export function parseExtensions(
+  discovery: Record<string, unknown>,
+  origin: string,
+): CredentialInstallDescriptor | null {
+  if (discovery.extensions === undefined || discovery.extensions === null) return null;
+  const extensions = closedRecord(discovery.extensions, 'extensions', [
+    'connections', 'credential_install',
+  ]);
+  if (extensions.connections === undefined) {
+    throw new TargetDiscoveryError('extensions.connections is required');
+  }
+  const connections = closedRecord(extensions.connections, 'extensions.connections', [
+    'kind', 'base_url', 'route_templates',
+  ]);
+  exact(connections.kind, 'zerocloud.connections/v1', 'extensions.connections.kind');
+  sameOriginUrl(connections.base_url, 'extensions.connections.base_url', origin);
+  const routes = closedRecord(connections.route_templates, 'extensions.connections.route_templates', [
+    'list', 'create', 'update',
+  ]);
+  routeTemplate(routes.list, 'extensions.connections.route_templates.list', []);
+  routeTemplate(routes.create, 'extensions.connections.route_templates.create', []);
+  routeTemplate(routes.update, 'extensions.connections.route_templates.update', ['connection_id']);
+  return parseCredentialInstall(extensions.credential_install);
+}
+
+export function validateOAuthMetadata(
+  metadata: Record<string, unknown>,
+  origin: string,
+  expected: readonly [string, string, string],
+): void {
+  const device = sameOriginUrl(
+    metadata.device_authorization_endpoint,
+    'OAuth metadata device_authorization_endpoint',
+    origin,
+  );
+  const token = sameOriginUrl(metadata.token_endpoint, 'OAuth metadata token_endpoint', origin);
+  const revoke = sameOriginUrl(
+    metadata.revocation_endpoint,
+    'OAuth metadata revocation_endpoint',
+    origin,
+  );
+  if (device !== expected[0] || token !== expected[1] || revoke !== expected[2]) {
+    throw new TargetDiscoveryError('OAuth metadata does not match hosted-target discovery');
+  }
+}
+
+export function parseEndpoint(discovery: Record<string, unknown>, origin: string) {
+  const protocol = closedRecord(discovery.protocol, 'protocol', ['name', 'major_version']);
+  exact(protocol.name, 'openengine.cluster/v1', 'protocol.name');
+  exact(protocol.major_version, 1, 'protocol.major_version');
+  const binding = closedRecord(discovery.binding, 'binding', ['scope', 'auth_location']);
+  exact(binding.scope, 'organization', 'binding.scope');
+  exact(binding.auth_location, 'authorization_header', 'binding.auth_location');
+  const endpoint = closedRecord(discovery.endpoint, 'endpoint', ['url', 'capabilities']);
+  const capabilities = exactStringSet(
+    endpoint.capabilities,
+    'endpoint.capabilities',
+    ['exec', 'log_stream'],
+  ) as readonly ['exec', 'log_stream'];
+  const pagination = closedRecord(discovery.pagination, 'pagination', [
+    'default_page_size',
+    'max_page_size',
+  ]);
+  const defaultPageSize = integer(
+    pagination.default_page_size,
+    'pagination.default_page_size',
+    1,
+  );
+  const maxPageSize = integer(pagination.max_page_size, 'pagination.max_page_size', 1);
+  if (defaultPageSize > maxPageSize) {
+    throw new TargetDiscoveryError('pagination.default_page_size exceeds maximum');
+  }
+  validateCachePolicy(discovery);
+  const schemaLinks = closedRecord(discovery.schema_links, 'schema_links', [
+    'self',
+    'problem',
+    'errors',
+  ]);
+  sameOriginUrl(schemaLinks.self, 'schema_links.self', origin);
+  sameOriginUrl(schemaLinks.problem, 'schema_links.problem', origin);
+  sameOriginUrl(schemaLinks.errors, 'schema_links.errors', origin);
+  return Object.freeze({
+    url: sameOriginUrl(endpoint.url, 'endpoint.url', origin),
+    capabilities,
+    pagination: Object.freeze({ defaultPageSize, maxPageSize }),
+  });
+}
+
+export function parseCapsule(discovery: Record<string, unknown>, origin: string) {
+  const capsule = closedRecord(discovery.capsule_protocol, 'capsule_protocol', [
+    'name',
+    'major_version',
+    'base_url',
+    'route_templates',
+  ]);
+  exact(capsule.name, 'openengine.capsules/v1', 'capsule_protocol.name');
+  exact(capsule.major_version, 1, 'capsule_protocol.major_version');
+  const routes = closedRecord(
+    capsule.route_templates,
+    'capsule_protocol.route_templates',
+    ['allocate', 'list', 'inspect', 'terminate', 'limits', 'access'],
+  );
+  const route = (name: string, variables: readonly string[]) =>
+    routeTemplate(routes[name], `capsule_protocol.route_templates.${name}`, variables);
+  return Object.freeze({
+    baseUrl: sameOriginUrl(capsule.base_url, 'capsule_protocol.base_url', origin),
+    routes: Object.freeze({
+      allocate: route('allocate', ['org_id']),
+      list: route('list', ['org_id', 'cursor', 'limit']),
+      inspect: route('inspect', ['org_id', 'capsule_id']),
+      terminate: route('terminate', ['org_id', 'capsule_id']),
+      limits: route('limits', ['org_id']),
+      access: route('access', ['capsule_id']),
+    }),
+  });
+}
+
+export function parseOAuth(discovery: Record<string, unknown>, origin: string) {
+  const oauth = closedRecord(discovery.oauth, 'oauth', [
+    'metadata_url',
+    'device_authorization_endpoint',
+    'token_endpoint',
+    'revocation_endpoint',
+    'client_id',
+    'device_grant_type',
+    'device_exchange_fields',
+    'audience',
+  ]);
+  exact(
+    oauth.device_grant_type,
+    'urn:ietf:params:oauth:grant-type:device_code',
+    'oauth.device_grant_type',
+  );
+  exactStringSet(
+    oauth.device_exchange_fields,
+    'oauth.device_exchange_fields',
+    ['device_token', 'device_label'],
+  );
+  exact(oauth.audience, 'capsule', 'oauth.audience');
+  return Object.freeze({
+    metadataUrl: sameOriginUrl(oauth.metadata_url, 'oauth.metadata_url', origin),
+    deviceAuthorizationEndpoint: sameOriginUrl(
+      oauth.device_authorization_endpoint,
+      'oauth.device_authorization_endpoint',
+      origin,
+    ),
+    tokenEndpoint: sameOriginUrl(oauth.token_endpoint, 'oauth.token_endpoint', origin),
+    revocationEndpoint: sameOriginUrl(
+      oauth.revocation_endpoint,
+      'oauth.revocation_endpoint',
+      origin,
+    ),
+    clientId: stringField(oauth, 'client_id', 'oauth.'),
+    deviceGrantType: 'urn:ietf:params:oauth:grant-type:device_code' as const,
+    audience: 'capsule' as const,
+  });
+}
+
+export function parseSession(discovery: Record<string, unknown>) {
+  const session = closedRecord(discovery.session, 'session', [
+    'route_template',
+    'method',
+    'cache_policy',
+  ]);
+  exact(session.method, 'GET', 'session.method');
+  exact(session.cache_policy, 'no-store', 'session.cache_policy');
+  return Object.freeze({
+    routeTemplate: routeTemplate(session.route_template, 'session.route_template', []),
+    method: 'GET' as const,
+  });
+}
+
+export function parseTransport(discovery: Record<string, unknown>) {
+  const transport = closedRecord(discovery.transport, 'transport', [
+    'websocket_route_template',
+    'unauthorized_status',
+    'close_codes',
+  ]);
+  exact(transport.unauthorized_status, 401, 'transport.unauthorized_status');
+  const closeCodes = closedRecord(transport.close_codes, 'transport.close_codes', [
+    'expired',
+    'revoked',
+  ]);
+  exact(closeCodes.expired, 4401, 'transport.close_codes.expired');
+  exact(closeCodes.revoked, 4403, 'transport.close_codes.revoked');
+  return Object.freeze({
+    websocketRouteTemplate: routeTemplate(
+      transport.websocket_route_template,
+      'transport.websocket_route_template',
+      ['capsule_id'],
+    ),
+    unauthorizedStatus: 401 as const,
+    closeCodes: Object.freeze({ expired: 4401 as const, revoked: 4403 as const }),
+  });
+}

package/src/target/discovery-validation.ts

@@ -0,0 +1,144 @@
+import { TargetDiscoveryError } from './discovery-errors.js';
+import { routeTemplate, type RouteTemplate } from './route-template.js';
+
+export interface CredentialInstallDescriptor {
+  readonly kind: 'openengine.capsule-credential-install/v1';
+  readonly grant: { readonly routeTemplate: RouteTemplate; readonly method: 'POST' };
+  readonly install: { readonly routeTemplate: RouteTemplate; readonly method: 'PUT' };
+  readonly uploadUrlOrigin: 'same_origin';
+  readonly sealedEnvelopeAlgorithms: readonly ['RSA-OAEP-3072-SHA256'];
+  readonly bounds: {
+    readonly maxEnvelopeBytes: number;
+    readonly maxBodyBytes: number;
+    readonly grantTtlSeconds: number;
+    readonly maxClockSkewSeconds: number;
+  };
+}
+
+export 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>;
+}
+
+export function closedRecord(
+  value: unknown,
+  field: string,
+  fields: readonly string[],
+): Record<string, unknown> {
+  const result = record(value, field);
+  const unknown = Object.keys(result).find((key) => !fields.includes(key));
+  if (unknown !== undefined) throw new TargetDiscoveryError(`${field}.${unknown} is not supported`);
+  return result;
+}
+
+export function stringField(
+  source: Record<string, unknown>,
+  field: string,
+  parent = '',
+): string {
+  const value = source[field];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TargetDiscoveryError(`${parent}${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+export function exact(value: unknown, expected: unknown, field: string): void {
+  if (value !== expected) throw new TargetDiscoveryError(`${field} is not supported`);
+}
+
+export function integer(
+  value: unknown,
+  field: string,
+  min: number,
+  max = Number.MAX_SAFE_INTEGER,
+): number {
+  if (!Number.isSafeInteger(value) || (value as number) < min || (value as number) > max) {
+    throw new TargetDiscoveryError(`${field} is outside the supported bounds`);
+  }
+  return value as number;
+}
+
+export function exactStringSet(
+  value: unknown,
+  field: string,
+  expected: readonly string[],
+): readonly string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new TargetDiscoveryError(`${field} must be an array of strings`);
+  }
+  if (value.length !== expected.length || new Set(value).size !== value.length ||
+      expected.some((item) => !value.includes(item))) {
+    throw new TargetDiscoveryError(`${field} does not match the supported contract`);
+  }
+  return Object.freeze([...value]) as readonly string[];
+}
+
+function hasForbiddenUrlComponent(
+  url: URL,
+  value: string,
+  protocols: readonly string[],
+): boolean {
+  return !protocols.includes(url.protocol) ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.search !== '' ||
+    url.hash !== '' ||
+    url.href !== value;
+}
+
+export function sameOriginUrl(
+  value: unknown,
+  field: string,
+  origin: string,
+  protocols: readonly string[] = ['https:', 'http:'],
+): string {
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f]|\s/u.test(value)) {
+    throw new TargetDiscoveryError(`${field} must be a canonical absolute URL`);
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TargetDiscoveryError(`${field} must be an absolute URL`);
+  }
+  if (hasForbiddenUrlComponent(url, value, protocols)) {
+    throw new TargetDiscoveryError(`${field} contains forbidden URL components`);
+  }
+  if (url.origin !== origin) {
+    throw new TargetDiscoveryError(`${field} must remain on the target origin`);
+  }
+  return url.href;
+}
+
+export function parseCredentialInstall(value: unknown): CredentialInstallDescriptor | null {
+  if (value === undefined || value === null) return null;
+  const extension = closedRecord(value, 'extensions.credential_install', [
+    'kind', 'grant', 'install', 'upload_url_origin', 'sealed_envelope_algorithms', 'bounds',
+  ]);
+  exact(extension.kind, 'openengine.capsule-credential-install/v1', 'extensions.credential_install.kind');
+  const grant = closedRecord(extension.grant, 'extensions.credential_install.grant', ['route_template', 'method']);
+  const install = closedRecord(extension.install, 'extensions.credential_install.install', ['route_template', 'method']);
+  exact(grant.method, 'POST', 'extensions.credential_install.grant.method');
+  exact(install.method, 'PUT', 'extensions.credential_install.install.method');
+  exact(extension.upload_url_origin, 'same_origin', 'extensions.credential_install.upload_url_origin');
+  exactStringSet(extension.sealed_envelope_algorithms, 'extensions.credential_install.sealed_envelope_algorithms', ['RSA-OAEP-3072-SHA256']);
+  const bounds = closedRecord(extension.bounds, 'extensions.credential_install.bounds', [
+    'max_envelope_bytes', 'max_body_bytes', 'grant_ttl_seconds', 'max_clock_skew_seconds',
+  ]);
+  return Object.freeze({
+    kind: 'openengine.capsule-credential-install/v1' as const,
+    grant: Object.freeze({ routeTemplate: routeTemplate(grant.route_template, 'extensions.credential_install.grant.route_template', ['capsule_id']), method: 'POST' as const }),
+    install: Object.freeze({ routeTemplate: routeTemplate(install.route_template, 'extensions.credential_install.install.route_template', ['capsule_id']), method: 'PUT' as const }),
+    uploadUrlOrigin: 'same_origin' as const,
+    sealedEnvelopeAlgorithms: Object.freeze(['RSA-OAEP-3072-SHA256'] as const),
+    bounds: Object.freeze({
+      maxEnvelopeBytes: integer(bounds.max_envelope_bytes, 'extensions.credential_install.bounds.max_envelope_bytes', 1, 1_048_576),
+      maxBodyBytes: integer(bounds.max_body_bytes, 'extensions.credential_install.bounds.max_body_bytes', 1, 1_048_576),
+      grantTtlSeconds: integer(bounds.grant_ttl_seconds, 'extensions.credential_install.bounds.grant_ttl_seconds', 1, 3_600),
+      maxClockSkewSeconds: integer(bounds.max_clock_skew_seconds, 'extensions.credential_install.bounds.max_clock_skew_seconds', 0, 300),
+    }),
+  });
+}