@the-open-engine/zeroshot 6.29.0 → 6.30.0

package/lib/target/discovery.cjs

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandRoute = exports.TargetDiscoveryError = void 0;
+exports.discoverTarget = discoverTarget;
+exports.discoverTargetSessionEndpoints = discoverTargetSessionEndpoints;
+const bounded_response_js_1 = require("./bounded-response.cjs");
+const discovery_errors_js_1 = require("./discovery-errors.cjs");
+const discovery_validation_js_1 = require("./discovery-validation.cjs");
+const discovery_sections_js_1 = require("./discovery-sections.cjs");
+var discovery_errors_js_2 = require("./discovery-errors.cjs");
+Object.defineProperty(exports, "TargetDiscoveryError", { enumerable: true, get: function () { return discovery_errors_js_2.TargetDiscoveryError; } });
+var route_template_js_1 = require("./route-template.cjs");
+Object.defineProperty(exports, "expandRoute", { enumerable: true, get: function () { return route_template_js_1.expandRoute; } });
+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',
+];
+async function readBoundedJson(response) {
+    return (0, bounded_response_js_1.readBoundedResponseJson)(response, MAX_DISCOVERY_BYTES, (kind) => new discovery_errors_js_1.TargetDiscoveryError(kind === 'size' ? 'response exceeds the size limit' : 'response is not valid UTF-8 JSON'));
+}
+async function fetchDocument(http, url) {
+    const response = await http.fetch(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        redirect: 'error',
+    });
+    if (response.url && new URL(response.url).href !== url) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new discovery_errors_js_1.TargetDiscoveryError('request changed target route or authority');
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new discovery_errors_js_1.TargetDiscoveryError(`request failed with status ${response.status}`);
+    }
+    return (0, discovery_validation_js_1.record)(await readBoundedJson(response), 'response');
+}
+async function discoverTarget(targetUrl, http) {
+    const target = new URL(targetUrl);
+    const origin = target.origin;
+    const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+    (0, discovery_validation_js_1.exact)(discovery.kind, 'openengine.hosted-target/v1', 'kind');
+    const adapter = (0, discovery_sections_js_1.parseAdapter)(discovery);
+    const endpoint = (0, discovery_sections_js_1.parseEndpoint)(discovery, origin);
+    const capsule = (0, discovery_sections_js_1.parseCapsule)(discovery, origin);
+    const oauth = (0, discovery_sections_js_1.parseOAuth)(discovery, origin);
+    (0, discovery_validation_js_1.exact)(discovery.organization_binding, 'device_approval', 'organization_binding');
+    const capabilityFlags = (0, discovery_validation_js_1.exactStringSet)(discovery.capability_flags, 'capability_flags', [
+        'capsule_allocate',
+        'capsule_read',
+        'capsule_terminate',
+        'capsule_access',
+        'connections_onboarding',
+    ]);
+    const sizes = (0, discovery_sections_js_1.parseSizes)(discovery);
+    const session = (0, discovery_sections_js_1.parseSession)(discovery);
+    const transport = (0, discovery_sections_js_1.parseTransport)(discovery);
+    const credentialInstall = (0, discovery_sections_js_1.parseExtensions)(discovery, origin);
+    const metadata = await fetchDocument(http, oauth.metadataUrl);
+    (0, discovery_sections_js_1.validateOAuthMetadata)(metadata, origin, [
+        oauth.deviceAuthorizationEndpoint,
+        oauth.tokenEndpoint,
+        oauth.revocationEndpoint,
+    ]);
+    const additional = Object.freeze(Object.fromEntries(Object.entries(discovery).filter(([key]) => !ROOT_FIELDS.includes(key))));
+    return Object.freeze({
+        origin,
+        adapter,
+        endpoint: endpoint.url,
+        endpointCapabilities: endpoint.capabilities,
+        pagination: endpoint.pagination,
+        sizes,
+        oauth,
+        session,
+        capsule,
+        transport,
+        capabilityFlags,
+        credentialInstall,
+        additional,
+    });
+}
+async function discoverTargetSessionEndpoints(targetUrl, http) {
+    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/lib/target/discovery.d.cts

@@ -0,0 +1,74 @@
+import type { HttpTransport } from './device-flow.js';
+import type { RouteTemplate } from './route-template.js';
+import { type CredentialInstallDescriptor } from './discovery-validation.js';
+export type { CredentialInstallDescriptor } from './discovery-validation.js';
+export { TargetDiscoveryError } from './discovery-errors.js';
+export { expandRoute, type RouteTemplate } from './route-template.js';
+declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+declare const CAPSULE_AUDIENCE = "capsule";
+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 clientId: string;
+    readonly capsuleApiBaseUrl: string;
+    readonly deviceGrantType: typeof DEVICE_GRANT;
+    readonly audience: typeof CAPSULE_AUDIENCE;
+    readonly sessionEndpoint: string;
+    readonly descriptor: TargetDiscoveryDescriptor;
+}
+export declare function discoverTarget(targetUrl: string, http: HttpTransport): Promise<TargetDiscoveryDescriptor>;
+export declare function discoverTargetSessionEndpoints(targetUrl: string, http: HttpTransport): Promise<TargetSessionEndpoints>;

package/lib/target/discovery.d.mts

@@ -0,0 +1,74 @@
+import type { HttpTransport } from './device-flow.js';
+import type { RouteTemplate } from './route-template.js';
+import { type CredentialInstallDescriptor } from './discovery-validation.js';
+export type { CredentialInstallDescriptor } from './discovery-validation.js';
+export { TargetDiscoveryError } from './discovery-errors.js';
+export { expandRoute, type RouteTemplate } from './route-template.js';
+declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+declare const CAPSULE_AUDIENCE = "capsule";
+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 clientId: string;
+    readonly capsuleApiBaseUrl: string;
+    readonly deviceGrantType: typeof DEVICE_GRANT;
+    readonly audience: typeof CAPSULE_AUDIENCE;
+    readonly sessionEndpoint: string;
+    readonly descriptor: TargetDiscoveryDescriptor;
+}
+export declare function discoverTarget(targetUrl: string, http: HttpTransport): Promise<TargetDiscoveryDescriptor>;
+export declare function discoverTargetSessionEndpoints(targetUrl: string, http: HttpTransport): Promise<TargetSessionEndpoints>;

package/lib/target/discovery.d.ts

@@ -1,12 +1,74 @@
-import type { HttpTransport } from './device-flow.ts';
+import type { HttpTransport } from './device-flow.js';
+import type { RouteTemplate } from './route-template.js';
+import { type CredentialInstallDescriptor } from './discovery-validation.js';
+export type { CredentialInstallDescriptor } from './discovery-validation.js';
+export { TargetDiscoveryError } from './discovery-errors.js';
+export { expandRoute, type RouteTemplate } from './route-template.js';
+declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+declare const CAPSULE_AUDIENCE = "capsule";
+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 declare class TargetDiscoveryError extends Error {
-    constructor(message: string);
-}
+export declare function discoverTarget(targetUrl: string, http: HttpTransport): Promise<TargetDiscoveryDescriptor>;
 export declare function discoverTargetSessionEndpoints(targetUrl: string, http: HttpTransport): Promise<TargetSessionEndpoints>;

package/lib/target/discovery.js

@@ -1,48 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TargetDiscoveryError = void 0;
+exports.expandRoute = exports.TargetDiscoveryError = void 0;
+exports.discoverTarget = discoverTarget;
 exports.discoverTargetSessionEndpoints = discoverTargetSessionEndpoints;
-const bounded_json_ts_1 = require("./bounded-json.js");
+const bounded_response_js_1 = require("./bounded-response.js");
+const discovery_errors_js_1 = require("./discovery-errors.js");
+const discovery_validation_js_1 = require("./discovery-validation.js");
+const discovery_sections_js_1 = require("./discovery-sections.js");
+var discovery_errors_js_2 = require("./discovery-errors.js");
+Object.defineProperty(exports, "TargetDiscoveryError", { enumerable: true, get: function () { return discovery_errors_js_2.TargetDiscoveryError; } });
+var route_template_js_1 = require("./route-template.js");
+Object.defineProperty(exports, "expandRoute", { enumerable: true, get: function () { return route_template_js_1.expandRoute; } });
 const DISCOVERY_PATH = '/.well-known/openengine-hosted-target';
 const MAX_DISCOVERY_BYTES = 64 * 1024;
-class TargetDiscoveryError extends Error {
-    constructor(message) {
-        super(`Target discovery failed: ${message}`);
-        this.name = 'TargetDiscoveryError';
-    }
-}
-exports.TargetDiscoveryError = TargetDiscoveryError;
-function record(value, field) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new TargetDiscoveryError(`${field} must be an object`);
-    }
-    return value;
-}
-function stringField(source, field) {
-    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, field, serviceOrigin) {
-    if (typeof value !== 'string') {
-        throw new TargetDiscoveryError(`${field} must be an absolute URL`);
-    }
-    let endpoint;
-    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;
+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',
+];
+async function readBoundedJson(response) {
+    return (0, bounded_response_js_1.readBoundedResponseJson)(response, MAX_DISCOVERY_BYTES, (kind) => new discovery_errors_js_1.TargetDiscoveryError(kind === 'size' ? 'response exceeds the size limit' : 'response is not valid UTF-8 JSON'));
 }
 async function fetchDocument(http, url) {
     const response = await http.fetch(url, {
@@ -50,48 +42,71 @@ async function fetchDocument(http, url) {
         headers: { Accept: 'application/json' },
         redirect: 'error',
     });
+    if (response.url && new URL(response.url).href !== url) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new discovery_errors_js_1.TargetDiscoveryError('request changed target route or authority');
+    }
     if (!response.ok) {
-        throw new TargetDiscoveryError(`request failed with status ${response.status}`);
+        await response.body?.cancel().catch(() => undefined);
+        throw new discovery_errors_js_1.TargetDiscoveryError(`request failed with status ${response.status}`);
     }
-    const body = await (0, bounded_json_ts_1.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 (0, discovery_validation_js_1.record)(await readBoundedJson(response), 'response');
 }
-async function discoverTargetSessionEndpoints(targetUrl, http) {
+async function discoverTarget(targetUrl, http) {
     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');
-    }
-    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 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,
-        capsuleApiBaseUrl,
-    };
+    (0, discovery_validation_js_1.exact)(discovery.kind, 'openengine.hosted-target/v1', 'kind');
+    const adapter = (0, discovery_sections_js_1.parseAdapter)(discovery);
+    const endpoint = (0, discovery_sections_js_1.parseEndpoint)(discovery, origin);
+    const capsule = (0, discovery_sections_js_1.parseCapsule)(discovery, origin);
+    const oauth = (0, discovery_sections_js_1.parseOAuth)(discovery, origin);
+    (0, discovery_validation_js_1.exact)(discovery.organization_binding, 'device_approval', 'organization_binding');
+    const capabilityFlags = (0, discovery_validation_js_1.exactStringSet)(discovery.capability_flags, 'capability_flags', [
+        'capsule_allocate',
+        'capsule_read',
+        'capsule_terminate',
+        'capsule_access',
+        'connections_onboarding',
+    ]);
+    const sizes = (0, discovery_sections_js_1.parseSizes)(discovery);
+    const session = (0, discovery_sections_js_1.parseSession)(discovery);
+    const transport = (0, discovery_sections_js_1.parseTransport)(discovery);
+    const credentialInstall = (0, discovery_sections_js_1.parseExtensions)(discovery, origin);
+    const metadata = await fetchDocument(http, oauth.metadataUrl);
+    (0, discovery_sections_js_1.validateOAuthMetadata)(metadata, origin, [
+        oauth.deviceAuthorizationEndpoint,
+        oauth.tokenEndpoint,
+        oauth.revocationEndpoint,
+    ]);
+    const additional = Object.freeze(Object.fromEntries(Object.entries(discovery).filter(([key]) => !ROOT_FIELDS.includes(key))));
+    return Object.freeze({
+        origin,
+        adapter,
+        endpoint: endpoint.url,
+        endpointCapabilities: endpoint.capabilities,
+        pagination: endpoint.pagination,
+        sizes,
+        oauth,
+        session,
+        capsule,
+        transport,
+        capabilityFlags,
+        credentialInstall,
+        additional,
+    });
+}
+async function discoverTargetSessionEndpoints(targetUrl, http) {
+    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/lib/target/discovery.mjs

@@ -0,0 +1,105 @@
+import { readBoundedResponseJson } from './bounded-response.mjs';
+import { TargetDiscoveryError } from './discovery-errors.mjs';
+import { exact, exactStringSet, record, } from './discovery-validation.mjs';
+import { parseAdapter, parseCapsule, parseEndpoint, parseExtensions, parseOAuth, parseSession, parseSizes, parseTransport, validateOAuthMetadata, } from './discovery-sections.mjs';
+export { TargetDiscoveryError } from './discovery-errors.mjs';
+export { expandRoute } from './route-template.mjs';
+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',
+];
+async function readBoundedJson(response) {
+    return readBoundedResponseJson(response, MAX_DISCOVERY_BYTES, (kind) => new TargetDiscoveryError(kind === 'size' ? 'response exceeds the size limit' : 'response is not valid UTF-8 JSON'));
+}
+async function fetchDocument(http, url) {
+    const response = await http.fetch(url, {
+        method: 'GET',
+        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}`);
+    }
+    return record(await readBoundedJson(response), 'response');
+}
+export async function discoverTarget(targetUrl, http) {
+    const target = new URL(targetUrl);
+    const origin = target.origin;
+    const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+    exact(discovery.kind, 'openengine.hosted-target/v1', 'kind');
+    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, oauth.metadataUrl);
+    validateOAuthMetadata(metadata, origin, [
+        oauth.deviceAuthorizationEndpoint,
+        oauth.tokenEndpoint,
+        oauth.revocationEndpoint,
+    ]);
+    const additional = Object.freeze(Object.fromEntries(Object.entries(discovery).filter(([key]) => !ROOT_FIELDS.includes(key))));
+    return Object.freeze({
+        origin,
+        adapter,
+        endpoint: endpoint.url,
+        endpointCapabilities: endpoint.capabilities,
+        pagination: endpoint.pagination,
+        sizes,
+        oauth,
+        session,
+        capsule,
+        transport,
+        capabilityFlags,
+        credentialInstall,
+        additional,
+    });
+}
+export async function discoverTargetSessionEndpoints(targetUrl, http) {
+    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/lib/target/index.d.ts

@@ -1,6 +1,6 @@
-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';
+export { CredentialStoreUnavailableError, KeyringCredentialStore, FakeCredentialStore, targetServiceKey, TARGET_ACCOUNT, type TargetCredentialStore, } from './credential-store.js';
+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.js';
+export { addTarget, removeTarget, getTarget, listTargets, updateTargetOrganization, validateTargetName, normalizeAndValidateUrl, TargetNameInvalidError, TargetNameExistsError, TargetNotFoundError, TargetUrlInvalidError, type TargetRecord, type SettingsPort, } from './target-registry.js';
+export { TargetSessionManager, LoginRequiredError, type BrowserOpener, type TargetSessionDeps, type TargetSessionManagerInit, } from './target-session.js';
+export { discoverTarget, discoverTargetSessionEndpoints, expandRoute, TargetDiscoveryError, type CredentialInstallDescriptor, type RouteTemplate, type TargetDiscoveryDescriptor, type TargetSessionEndpoints, } from './discovery.js';