@the-open-engine/zeroshot 6.28.0 → 6.29.1

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';

package/lib/target/index.js

@@ -1,38 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TargetDiscoveryError = exports.discoverTargetSessionEndpoints = exports.LoginRequiredError = exports.revokeAndCleanup = exports.getAccessTokenProvider = exports.refreshAccessToken = exports.targetLogin = exports.TargetUrlInvalidError = exports.TargetNotFoundError = exports.TargetNameExistsError = exports.TargetNameInvalidError = exports.normalizeAndValidateUrl = exports.validateTargetName = exports.updateTargetOrganization = exports.listTargets = exports.getTarget = exports.removeTarget = exports.addTarget = exports.UnboundSessionError = exports.DeviceFlowExpiredError = exports.DeviceFlowDeniedError = exports.pollForToken = exports.requestDeviceCode = exports.acquireTargetLock = exports.TARGET_ACCOUNT = exports.targetServiceKey = exports.FakeCredentialStore = exports.KeyringCredentialStore = exports.CredentialStoreUnavailableError = void 0;
-var credential_store_ts_1 = require("./credential-store.js");
-Object.defineProperty(exports, "CredentialStoreUnavailableError", { enumerable: true, get: function () { return credential_store_ts_1.CredentialStoreUnavailableError; } });
-Object.defineProperty(exports, "KeyringCredentialStore", { enumerable: true, get: function () { return credential_store_ts_1.KeyringCredentialStore; } });
-Object.defineProperty(exports, "FakeCredentialStore", { enumerable: true, get: function () { return credential_store_ts_1.FakeCredentialStore; } });
-Object.defineProperty(exports, "targetServiceKey", { enumerable: true, get: function () { return credential_store_ts_1.targetServiceKey; } });
-Object.defineProperty(exports, "TARGET_ACCOUNT", { enumerable: true, get: function () { return credential_store_ts_1.TARGET_ACCOUNT; } });
-var credential_lock_ts_1 = require("./credential-lock.js");
-Object.defineProperty(exports, "acquireTargetLock", { enumerable: true, get: function () { return credential_lock_ts_1.acquireTargetLock; } });
-var device_flow_ts_1 = require("./device-flow.js");
-Object.defineProperty(exports, "requestDeviceCode", { enumerable: true, get: function () { return device_flow_ts_1.requestDeviceCode; } });
-Object.defineProperty(exports, "pollForToken", { enumerable: true, get: function () { return device_flow_ts_1.pollForToken; } });
-Object.defineProperty(exports, "DeviceFlowDeniedError", { enumerable: true, get: function () { return device_flow_ts_1.DeviceFlowDeniedError; } });
-Object.defineProperty(exports, "DeviceFlowExpiredError", { enumerable: true, get: function () { return device_flow_ts_1.DeviceFlowExpiredError; } });
-Object.defineProperty(exports, "UnboundSessionError", { enumerable: true, get: function () { return device_flow_ts_1.UnboundSessionError; } });
-var target_registry_ts_1 = require("./target-registry.js");
-Object.defineProperty(exports, "addTarget", { enumerable: true, get: function () { return target_registry_ts_1.addTarget; } });
-Object.defineProperty(exports, "removeTarget", { enumerable: true, get: function () { return target_registry_ts_1.removeTarget; } });
-Object.defineProperty(exports, "getTarget", { enumerable: true, get: function () { return target_registry_ts_1.getTarget; } });
-Object.defineProperty(exports, "listTargets", { enumerable: true, get: function () { return target_registry_ts_1.listTargets; } });
-Object.defineProperty(exports, "updateTargetOrganization", { enumerable: true, get: function () { return target_registry_ts_1.updateTargetOrganization; } });
-Object.defineProperty(exports, "validateTargetName", { enumerable: true, get: function () { return target_registry_ts_1.validateTargetName; } });
-Object.defineProperty(exports, "normalizeAndValidateUrl", { enumerable: true, get: function () { return target_registry_ts_1.normalizeAndValidateUrl; } });
-Object.defineProperty(exports, "TargetNameInvalidError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNameInvalidError; } });
-Object.defineProperty(exports, "TargetNameExistsError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNameExistsError; } });
-Object.defineProperty(exports, "TargetNotFoundError", { enumerable: true, get: function () { return target_registry_ts_1.TargetNotFoundError; } });
-Object.defineProperty(exports, "TargetUrlInvalidError", { enumerable: true, get: function () { return target_registry_ts_1.TargetUrlInvalidError; } });
-var target_session_ts_1 = require("./target-session.js");
-Object.defineProperty(exports, "targetLogin", { enumerable: true, get: function () { return target_session_ts_1.targetLogin; } });
-Object.defineProperty(exports, "refreshAccessToken", { enumerable: true, get: function () { return target_session_ts_1.refreshAccessToken; } });
-Object.defineProperty(exports, "getAccessTokenProvider", { enumerable: true, get: function () { return target_session_ts_1.getAccessTokenProvider; } });
-Object.defineProperty(exports, "revokeAndCleanup", { enumerable: true, get: function () { return target_session_ts_1.revokeAndCleanup; } });
-Object.defineProperty(exports, "LoginRequiredError", { enumerable: true, get: function () { return target_session_ts_1.LoginRequiredError; } });
-var discovery_ts_1 = require("./discovery.js");
-Object.defineProperty(exports, "discoverTargetSessionEndpoints", { enumerable: true, get: function () { return discovery_ts_1.discoverTargetSessionEndpoints; } });
-Object.defineProperty(exports, "TargetDiscoveryError", { enumerable: true, get: function () { return discovery_ts_1.TargetDiscoveryError; } });
+exports.TargetDiscoveryError = exports.expandRoute = exports.discoverTargetSessionEndpoints = exports.discoverTarget = exports.LoginRequiredError = exports.TargetSessionManager = exports.TargetUrlInvalidError = exports.TargetNotFoundError = exports.TargetNameExistsError = exports.TargetNameInvalidError = exports.normalizeAndValidateUrl = exports.validateTargetName = exports.updateTargetOrganization = exports.listTargets = exports.getTarget = exports.removeTarget = exports.addTarget = exports.UnboundSessionError = exports.DeviceFlowExpiredError = exports.DeviceFlowDeniedError = exports.parseTokenResponse = exports.pollForToken = exports.requestDeviceCode = exports.acquireTargetLock = exports.TARGET_ACCOUNT = exports.targetServiceKey = exports.FakeCredentialStore = exports.KeyringCredentialStore = exports.CredentialStoreUnavailableError = void 0;
+var credential_store_js_1 = require("./credential-store.js");
+Object.defineProperty(exports, "CredentialStoreUnavailableError", { enumerable: true, get: function () { return credential_store_js_1.CredentialStoreUnavailableError; } });
+Object.defineProperty(exports, "KeyringCredentialStore", { enumerable: true, get: function () { return credential_store_js_1.KeyringCredentialStore; } });
+Object.defineProperty(exports, "FakeCredentialStore", { enumerable: true, get: function () { return credential_store_js_1.FakeCredentialStore; } });
+Object.defineProperty(exports, "targetServiceKey", { enumerable: true, get: function () { return credential_store_js_1.targetServiceKey; } });
+Object.defineProperty(exports, "TARGET_ACCOUNT", { enumerable: true, get: function () { return credential_store_js_1.TARGET_ACCOUNT; } });
+var credential_lock_js_1 = require("./credential-lock.js");
+Object.defineProperty(exports, "acquireTargetLock", { enumerable: true, get: function () { return credential_lock_js_1.acquireTargetLock; } });
+var device_flow_js_1 = require("./device-flow.js");
+Object.defineProperty(exports, "requestDeviceCode", { enumerable: true, get: function () { return device_flow_js_1.requestDeviceCode; } });
+Object.defineProperty(exports, "pollForToken", { enumerable: true, get: function () { return device_flow_js_1.pollForToken; } });
+Object.defineProperty(exports, "parseTokenResponse", { enumerable: true, get: function () { return device_flow_js_1.parseTokenResponse; } });
+Object.defineProperty(exports, "DeviceFlowDeniedError", { enumerable: true, get: function () { return device_flow_js_1.DeviceFlowDeniedError; } });
+Object.defineProperty(exports, "DeviceFlowExpiredError", { enumerable: true, get: function () { return device_flow_js_1.DeviceFlowExpiredError; } });
+Object.defineProperty(exports, "UnboundSessionError", { enumerable: true, get: function () { return device_flow_js_1.UnboundSessionError; } });
+var target_registry_js_1 = require("./target-registry.js");
+Object.defineProperty(exports, "addTarget", { enumerable: true, get: function () { return target_registry_js_1.addTarget; } });
+Object.defineProperty(exports, "removeTarget", { enumerable: true, get: function () { return target_registry_js_1.removeTarget; } });
+Object.defineProperty(exports, "getTarget", { enumerable: true, get: function () { return target_registry_js_1.getTarget; } });
+Object.defineProperty(exports, "listTargets", { enumerable: true, get: function () { return target_registry_js_1.listTargets; } });
+Object.defineProperty(exports, "updateTargetOrganization", { enumerable: true, get: function () { return target_registry_js_1.updateTargetOrganization; } });
+Object.defineProperty(exports, "validateTargetName", { enumerable: true, get: function () { return target_registry_js_1.validateTargetName; } });
+Object.defineProperty(exports, "normalizeAndValidateUrl", { enumerable: true, get: function () { return target_registry_js_1.normalizeAndValidateUrl; } });
+Object.defineProperty(exports, "TargetNameInvalidError", { enumerable: true, get: function () { return target_registry_js_1.TargetNameInvalidError; } });
+Object.defineProperty(exports, "TargetNameExistsError", { enumerable: true, get: function () { return target_registry_js_1.TargetNameExistsError; } });
+Object.defineProperty(exports, "TargetNotFoundError", { enumerable: true, get: function () { return target_registry_js_1.TargetNotFoundError; } });
+Object.defineProperty(exports, "TargetUrlInvalidError", { enumerable: true, get: function () { return target_registry_js_1.TargetUrlInvalidError; } });
+var target_session_js_1 = require("./target-session.js");
+Object.defineProperty(exports, "TargetSessionManager", { enumerable: true, get: function () { return target_session_js_1.TargetSessionManager; } });
+Object.defineProperty(exports, "LoginRequiredError", { enumerable: true, get: function () { return target_session_js_1.LoginRequiredError; } });
+var discovery_js_1 = require("./discovery.js");
+Object.defineProperty(exports, "discoverTarget", { enumerable: true, get: function () { return discovery_js_1.discoverTarget; } });
+Object.defineProperty(exports, "discoverTargetSessionEndpoints", { enumerable: true, get: function () { return discovery_js_1.discoverTargetSessionEndpoints; } });
+Object.defineProperty(exports, "expandRoute", { enumerable: true, get: function () { return discovery_js_1.expandRoute; } });
+Object.defineProperty(exports, "TargetDiscoveryError", { enumerable: true, get: function () { return discovery_js_1.TargetDiscoveryError; } });

package/lib/target/oauth-http.d.ts

@@ -0,0 +1,2 @@
+export declare function readTargetSessionJson(response: Response): Promise<unknown>;
+export declare function readOAuthError(response: Response): Promise<string | null>;

package/lib/target/oauth-http.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readTargetSessionJson = readTargetSessionJson;
+exports.readOAuthError = readOAuthError;
+const bounded_response_js_1 = require("./bounded-response.js");
+const MAX_SESSION_RESPONSE_BYTES = 64 * 1024;
+async function readTargetSessionJson(response) {
+    return (0, bounded_response_js_1.readBoundedResponseJson)(response, MAX_SESSION_RESPONSE_BYTES, (kind) => new Error(kind === 'size'
+        ? 'Target session response exceeds the size limit'
+        : 'Target session response is malformed'));
+}
+async function readOAuthError(response) {
+    try {
+        const value = await readTargetSessionJson(response);
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const record = value;
+        return Object.keys(record).length === 1 && typeof record.error === 'string'
+            ? record.error
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/lib/target/refresh-exchange.d.ts

@@ -0,0 +1,11 @@
+import { type HttpTransport } from './device-flow.js';
+import { 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 declare function exchangeRefreshToken(request: RefreshExchangeRequest): Promise<TokenResponse>;

package/lib/target/refresh-exchange.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeRefreshToken = exchangeRefreshToken;
+const device_flow_js_1 = require("./device-flow.js");
+const oauth_http_js_1 = require("./oauth-http.js");
+const token_response_js_1 = require("./token-response.js");
+async function exchangeRefreshToken(request) {
+    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, (0, device_flow_js_1.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 (0, oauth_http_js_1.readOAuthError)(response);
+        throw new Error('Target token exchange failed');
+    }
+    return (0, token_response_js_1.parseTokenResponse)(await (0, oauth_http_js_1.readTargetSessionJson)(response));
+}

package/lib/target/refresh-revocation.d.ts

@@ -0,0 +1,8 @@
+import { type HttpTransport } from './device-flow.js';
+import type { TargetSessionEndpoints } from './discovery.js';
+interface RevocationDeps {
+    readonly http: HttpTransport;
+    readonly discoveryEndpoints: TargetSessionEndpoints;
+}
+export declare function revokeRefreshToken(token: string, deps: RevocationDeps): Promise<Response>;
+export {};

package/lib/target/refresh-revocation.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revokeRefreshToken = revokeRefreshToken;
+const device_flow_js_1 = require("./device-flow.js");
+async function revokeRefreshToken(token, deps) {
+    const body = new URLSearchParams({
+        token,
+        client_id: deps.discoveryEndpoints.clientId,
+        token_type_hint: 'refresh_token',
+    });
+    const response = await deps.http.fetch(deps.discoveryEndpoints.revocationEndpoint, (0, device_flow_js_1.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/lib/target/route-template.cjs

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeTemplate = routeTemplate;
+exports.expandRoute = expandRoute;
+const discovery_errors_js_1 = require("./discovery-errors.cjs");
+function expandCompiled(template, variables, values) {
+    const supplied = Object.keys(values).filter((key) => values[key] !== undefined);
+    if (supplied.some((key) => !variables.includes(key))) {
+        throw new discovery_errors_js_1.TargetDiscoveryError('route expansion supplied an undeclared variable');
+    }
+    let expanded = template.replace(/\{\?([^}]+)\}/g, (_match, names) => {
+        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) => {
+        const value = values[name];
+        if (value === undefined)
+            throw new discovery_errors_js_1.TargetDiscoveryError(`route expansion is missing ${name}`);
+        const opaque = String(value);
+        if (opaque === '.' || opaque === '..') {
+            throw new discovery_errors_js_1.TargetDiscoveryError('route expansion contains a structural dot segment');
+        }
+        return encodeURIComponent(opaque);
+    });
+    if (/[{}]/.test(expanded)) {
+        throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError('route expansion changed during URL canonicalization');
+    }
+    return expanded;
+}
+function isUnsafeTemplate(value) {
+    return typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') ||
+        value.includes('\\') || value.includes('#') || /[\u0000-\u0020\u007f]/.test(value) ||
+        value.replace(/\{\?[^}]+\}/g, '').includes('?');
+}
+function expressionNames(expressions, field) {
+    const found = [];
+    for (const expression of expressions) {
+        const body = expression[1];
+        if (body === undefined)
+            throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError(`${field} contains an unsupported query expansion`);
+        }
+        found.push(...names);
+    }
+    return found;
+}
+function routeTemplate(value, field, variables) {
+    if (isUnsafeTemplate(value)) {
+        throw new discovery_errors_js_1.TargetDiscoveryError(`${field} must be a safe relative route template`);
+    }
+    const template = value;
+    const expressions = [...template.matchAll(/\{([^{}]+)\}/g)];
+    const stripped = template.replace(/\{[^{}]+\}/g, '');
+    if (stripped.includes('{') || stripped.includes('}') ||
+        /(^|\/)(?:\.|%2e){1,2}(?:\/|$)/i.test(stripped)) {
+        throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError(`${field} declares unsupported variables`);
+    }
+    const compiledVariables = Object.freeze([...variables]);
+    return Object.freeze({
+        template,
+        variables: compiledVariables,
+        expand: (values) => expandCompiled(template, compiledVariables, values),
+    });
+}
+function expandRoute(template, values) {
+    return template.expand(values);
+}

package/lib/target/route-template.d.cts

@@ -0,0 +1,7 @@
+export interface RouteTemplate {
+    readonly template: string;
+    readonly variables: readonly string[];
+    expand(values: Readonly<Record<string, string | number | undefined>>): string;
+}
+export declare function routeTemplate(value: unknown, field: string, variables: readonly string[]): RouteTemplate;
+export declare function expandRoute(template: RouteTemplate, values: Readonly<Record<string, string | number | undefined>>): string;

package/lib/target/route-template.d.mts

@@ -0,0 +1,7 @@
+export interface RouteTemplate {
+    readonly template: string;
+    readonly variables: readonly string[];
+    expand(values: Readonly<Record<string, string | number | undefined>>): string;
+}
+export declare function routeTemplate(value: unknown, field: string, variables: readonly string[]): RouteTemplate;
+export declare function expandRoute(template: RouteTemplate, values: Readonly<Record<string, string | number | undefined>>): string;

package/lib/target/route-template.d.ts

@@ -0,0 +1,7 @@
+export interface RouteTemplate {
+    readonly template: string;
+    readonly variables: readonly string[];
+    expand(values: Readonly<Record<string, string | number | undefined>>): string;
+}
+export declare function routeTemplate(value: unknown, field: string, variables: readonly string[]): RouteTemplate;
+export declare function expandRoute(template: RouteTemplate, values: Readonly<Record<string, string | number | undefined>>): string;

package/lib/target/route-template.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeTemplate = routeTemplate;
+exports.expandRoute = expandRoute;
+const discovery_errors_js_1 = require("./discovery-errors.js");
+function expandCompiled(template, variables, values) {
+    const supplied = Object.keys(values).filter((key) => values[key] !== undefined);
+    if (supplied.some((key) => !variables.includes(key))) {
+        throw new discovery_errors_js_1.TargetDiscoveryError('route expansion supplied an undeclared variable');
+    }
+    let expanded = template.replace(/\{\?([^}]+)\}/g, (_match, names) => {
+        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) => {
+        const value = values[name];
+        if (value === undefined)
+            throw new discovery_errors_js_1.TargetDiscoveryError(`route expansion is missing ${name}`);
+        const opaque = String(value);
+        if (opaque === '.' || opaque === '..') {
+            throw new discovery_errors_js_1.TargetDiscoveryError('route expansion contains a structural dot segment');
+        }
+        return encodeURIComponent(opaque);
+    });
+    if (/[{}]/.test(expanded)) {
+        throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError('route expansion changed during URL canonicalization');
+    }
+    return expanded;
+}
+function isUnsafeTemplate(value) {
+    return typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') ||
+        value.includes('\\') || value.includes('#') || /[\u0000-\u0020\u007f]/.test(value) ||
+        value.replace(/\{\?[^}]+\}/g, '').includes('?');
+}
+function expressionNames(expressions, field) {
+    const found = [];
+    for (const expression of expressions) {
+        const body = expression[1];
+        if (body === undefined)
+            throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError(`${field} contains an unsupported query expansion`);
+        }
+        found.push(...names);
+    }
+    return found;
+}
+function routeTemplate(value, field, variables) {
+    if (isUnsafeTemplate(value)) {
+        throw new discovery_errors_js_1.TargetDiscoveryError(`${field} must be a safe relative route template`);
+    }
+    const template = value;
+    const expressions = [...template.matchAll(/\{([^{}]+)\}/g)];
+    const stripped = template.replace(/\{[^{}]+\}/g, '');
+    if (stripped.includes('{') || stripped.includes('}') ||
+        /(^|\/)(?:\.|%2e){1,2}(?:\/|$)/i.test(stripped)) {
+        throw new discovery_errors_js_1.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 discovery_errors_js_1.TargetDiscoveryError(`${field} declares unsupported variables`);
+    }
+    const compiledVariables = Object.freeze([...variables]);
+    return Object.freeze({
+        template,
+        variables: compiledVariables,
+        expand: (values) => expandCompiled(template, compiledVariables, values),
+    });
+}
+function expandRoute(template, values) {
+    return template.expand(values);
+}

package/lib/target/route-template.mjs

@@ -0,0 +1,81 @@
+import { TargetDiscoveryError } from './discovery-errors.mjs';
+function expandCompiled(template, variables, values) {
+    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) => {
+        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) => {
+        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) {
+    return typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') ||
+        value.includes('\\') || value.includes('#') || /[\u0000-\u0020\u007f]/.test(value) ||
+        value.replace(/\{\?[^}]+\}/g, '').includes('?');
+}
+function expressionNames(expressions, field) {
+    const found = [];
+    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, field, variables) {
+    if (isUnsafeTemplate(value)) {
+        throw new TargetDiscoveryError(`${field} must be a safe relative route template`);
+    }
+    const template = value;
+    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) => expandCompiled(template, compiledVariables, values),
+    });
+}
+export function expandRoute(template, values) {
+    return template.expand(values);
+}

package/lib/target/session-errors.d.ts

@@ -0,0 +1,4 @@
+export declare class LoginRequiredError extends Error {
+    readonly targetName: string;
+    constructor(targetName: string);
+}

package/lib/target/session-errors.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoginRequiredError = void 0;
+class LoginRequiredError extends Error {
+    targetName;
+    constructor(targetName) {
+        super(`Login required. Run: zeroshot target login ${targetName}`);
+        this.name = 'LoginRequiredError';
+        this.targetName = targetName;
+    }
+}
+exports.LoginRequiredError = LoginRequiredError;

package/lib/target/session-verification.d.ts

@@ -0,0 +1,10 @@
+import type { HttpTransport } from './device-flow.js';
+import type { TargetSessionEndpoints } from './discovery.js';
+interface SessionVerificationDeps {
+    readonly http: HttpTransport;
+    readonly discoveryEndpoints: TargetSessionEndpoints;
+}
+export declare function readVerifiedOrganization(accessToken: string, signal: AbortSignal | undefined, deps: SessionVerificationDeps): Promise<{
+    readonly id: string;
+}>;
+export {};

package/lib/target/session-verification.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readVerifiedOrganization = readVerifiedOrganization;
+const oauth_http_js_1 = require("./oauth-http.js");
+function parseOrganization(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Target session response is malformed');
+    }
+    const body = value;
+    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 });
+}
+async function readVerifiedOrganization(accessToken, signal, deps) {
+    const init = {
+        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 (0, oauth_http_js_1.readTargetSessionJson)(response));
+}

package/lib/target/target-registry.d.ts

@@ -1,3 +1,4 @@
+import type { TargetDiscoveryDescriptor } from './discovery.js';
 export interface TargetRecord {
     readonly id: string;
     readonly url: string;
@@ -5,8 +6,9 @@ export interface TargetRecord {
     readonly deviceToken: string;
     readonly organization?: {
         readonly id: string;
-        readonly name: string;
+        readonly name?: string;
     };
+    readonly refreshInvalidated?: true;
     readonly createdAt: string;
 }
 export declare class TargetNameInvalidError extends Error {
@@ -31,7 +33,7 @@ export interface SettingsPort {
     load(): SettingsWithTargets;
     mutate(mutator: (settings: SettingsWithTargets) => void): void;
 }
-export declare function addTarget(name: string, rawUrl: string, settings: SettingsPort): TargetRecord;
+export declare function addTarget(name: string, rawUrl: string, settings: SettingsPort, descriptor: TargetDiscoveryDescriptor): TargetRecord;
 export declare function removeTarget(name: string, settings: SettingsPort): TargetRecord;
 export declare function getTarget(name: string, settings: SettingsPort): TargetRecord | null;
 export declare function listTargets(settings: SettingsPort): Array<{
@@ -40,6 +42,8 @@ export declare function listTargets(settings: SettingsPort): Array<{
 }>;
 export declare function updateTargetOrganization(name: string, organization: {
     id: string;
-    name: string;
+    name?: string;
 }, settings: SettingsPort): void;
+export declare function targetRefreshIsInvalidated(name: string, settings: SettingsPort): boolean;
+export declare function setTargetRefreshInvalidated(name: string, invalidated: boolean, settings: SettingsPort): void;
 export {};