@qduc/term2 0.14.0 → 0.16.0

package/dist/gateway/contracts.d.ts

@@ -0,0 +1,141 @@
+import type { SessionRuntime } from '../core/index.js';
+export declare const ASSERTION_PURPOSES: readonly ['workspace_list', 'workspace_candidate_validate', 'workspace_candidate_browse', 'workspace_candidate_select', 'settings_read', 'settings_write', 'credential_write', 'credential_delete', 'oauth_login', 'oauth_select', 'oauth_delete', 'session_update', 'session_list', 'model_list', 'session_create', 'session_read', 'message_submit', 'interaction_resolve', 'abort', 'events_connect'];
+export type AssertionPurpose = (typeof ASSERTION_PURPOSES)[number];
+export type GatewayAssertionClaims = {
+    iss: string;
+    aud: string;
+    sub: string;
+    purpose: AssertionPurpose;
+    iat: number;
+    nbf: number;
+    exp: number;
+    jti: string;
+    ver: 1;
+    workspaceId?: string;
+    sessionId?: string;
+};
+export type WorkspaceAlias = {
+    workspaceId: string;
+    label: string;
+    access: 'read' | 'read_write';
+};
+export type WorkspaceGrantBffRecord = {
+    workspaceId: string;
+    ownerUserId: string;
+    label: string;
+    access: 'read' | 'read_write';
+};
+export type WorkspaceGrant = {
+    workspaceId: string;
+    ownerUserId: string;
+    label: string;
+    kind: 'local' | 'ssh';
+    localRoot?: string;
+    sshTargetId?: string;
+    remoteRoot?: string;
+    access: 'read' | 'read_write';
+    enabled: boolean;
+};
+export type SshTarget = {
+    sshTargetId: string;
+    host: string;
+    port: number;
+    username: string;
+    remoteRootAllowlist: string[];
+    knownHostsProfile: string;
+    agentProfileId: string;
+    enabled: boolean;
+};
+export type GatewayManifest = {
+    version: number;
+    grants: WorkspaceGrant[];
+    sshTargets?: SshTarget[];
+    sha256?: string;
+};
+export type SessionBinding = {
+    sessionId: string;
+    ownerUserId: string;
+    workspaceId: string;
+    grantVersion: number;
+    canonicalRoot: string;
+    access: 'read' | 'read_write';
+};
+export type SecretFreeWorkerSettings = {
+    providerId: string;
+    modelId: string;
+    /** Present for the legacy fixture broker; absent for the real provider stack. */
+    brokerCapabilityId?: string;
+    /** Canonical real path used by both the settings snapshot and execution context. */
+    executionRoot: string;
+    envPolicyVersion: 1;
+    reasoningEffort?: string;
+    mode?: string;
+    toolPolicy?: Readonly<Record<string, boolean>>;
+    defaultsRevision?: string | number;
+};
+/** Secret-free settings captured when a gateway session is admitted. */
+export type SessionSettingsSnapshot = Readonly<{
+    providerId: string;
+    modelId: string;
+    reasoningEffort: string;
+    mode: string;
+    effectiveToolPolicy: Readonly<Record<string, boolean>>;
+    defaultsRevision?: string | number;
+}>;
+export type NormalizedProviderRequest = {
+    messages: readonly Record<string, unknown>[];
+    tools?: readonly Record<string, unknown>[];
+};
+export type NormalizedProviderResponse = {
+    text?: string;
+    finishReason?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+};
+export type NormalizedProviderChunk = {
+    type: 'text' | 'reasoning' | 'tool_call' | 'usage' | 'done' | 'error';
+    value?: string;
+};
+export type ProviderBrokerCapability = {
+    capabilityId: string;
+    providerId: string;
+    modelId: string;
+    request(input: NormalizedProviderRequest): Promise<NormalizedProviderResponse>;
+    stream(input: NormalizedProviderRequest): AsyncIterable<NormalizedProviderChunk>;
+};
+export type GatewaySafeLogMetadata = {
+    schemaVersion: 1;
+    sessionId?: string;
+    workspaceId?: string;
+    grantVersion?: number;
+    access?: 'read' | 'read_write';
+    principalRef?: string;
+    providerId?: string;
+    modelId?: string;
+    correlationId: string;
+    operation: 'startup' | 'workspace_list' | 'workspace_candidate_validate' | 'workspace_candidate_browse' | 'workspace_candidate_select' | 'settings_read' | 'settings_write' | 'credential_write' | 'credential_delete' | 'oauth_login' | 'oauth_select' | 'oauth_delete' | 'session_update' | 'session_list' | 'model_list' | 'session_create' | 'session_read' | 'message_submit' | 'interaction_resolve' | 'abort' | 'events_connect' | 'shutdown';
+    outcome: 'allowed' | 'denied' | 'failed' | 'interrupted';
+    reasonCode?: string;
+};
+export type GatewaySessionComposition = {
+    sessionId: string;
+    binding: SessionBinding;
+    executionContext: import('../services/execution-context.js').ExecutionContext;
+    settings: SecretFreeWorkerSettings;
+    /** Session-owned mutable settings service; never serialized across the worker boundary. */
+    sessionSettingsService?: import('../services/service-interfaces.js').ISettingsService;
+    providerBroker?: ProviderBrokerCapability;
+    sessionSettingsSnapshot?: SessionSettingsSnapshot;
+    env: Readonly<Record<string, string>>;
+    spawnOptions: {
+        cwd: string;
+        env: Readonly<Record<string, string>>;
+        gatewayMode: true;
+    };
+    runtime?: SessionRuntime;
+    dispose(): Promise<void> | void;
+};
+export declare const isAssertionPurpose: (value: unknown) => value is AssertionPurpose;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/gateway/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../source/gateway/contracts.ts"],"names":[],"mappings":"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"}

package/dist/gateway/contracts.js

@@ -0,0 +1,24 @@
+export const ASSERTION_PURPOSES = [
+    'workspace_list',
+    'workspace_candidate_validate',
+    'workspace_candidate_browse',
+    'workspace_candidate_select',
+    'settings_read',
+    'settings_write',
+    'credential_write',
+    'credential_delete',
+    'oauth_login',
+    'oauth_select',
+    'oauth_delete',
+    'session_update',
+    'session_list',
+    'model_list',
+    'session_create',
+    'session_read',
+    'message_submit',
+    'interaction_resolve',
+    'abort',
+    'events_connect',
+];
+export const isAssertionPurpose = (value) => typeof value === 'string' && ASSERTION_PURPOSES.includes(value);
+//# sourceMappingURL=contracts.js.map

package/dist/gateway/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../source/gateway/contracts.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gBAAgB;IAChB,8BAA8B;IAC9B,4BAA4B;IAC5B,4BAA4B;IAC5B,eAAe;IACf,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,cAAc;IACd,YAAY;IACZ,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,qBAAqB;IACrB,OAAO;IACP,gBAAgB;CACR,CAAC;AA2KX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAA6B,EAAE,CAC9E,OAAO,KAAK,KAAK,QAAQ,IAAK,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC"}

package/dist/gateway/dynamic-workspace-registry.d.ts

@@ -0,0 +1,76 @@
+import { ExecutionContext } from '../services/execution-context.js';
+import type { SessionBinding } from './contracts.js';
+import { WorkspaceAdmission } from './workspace-admission.js';
+export type WorkspaceValidationCheck = {
+    name: 'absolute' | 'exists' | 'directory' | 'readable' | 'canonical' | 'contained';
+    status: 'ok' | 'error' | 'pending';
+};
+export type WorkspaceCandidateValidation = {
+    valid: true;
+    candidateId: string;
+    displayName: string;
+    expiresAt: number;
+    checks: readonly WorkspaceValidationCheck[];
+} | {
+    valid: false;
+    checks: readonly WorkspaceValidationCheck[];
+    reasonCode: 'workspace_root_unavailable' | 'workspace_root_not_canonical' | 'workspace_path_escape' | 'workspace_not_readable' | 'candidate_registry_full';
+    reason: string;
+};
+export type WorkspaceBrowseEntry = {
+    name: string;
+    type: 'directory' | 'file' | 'symlink' | 'other';
+    selectable: boolean;
+    rejectionReason?: 'workspace_path_escape' | 'workspace_root_unavailable' | 'workspace_not_directory';
+    targetDisplay?: string;
+    childToken?: string;
+};
+export type WorkspaceBrowseResult = {
+    candidateId: string;
+    entries: readonly WorkspaceBrowseEntry[];
+    truncated: boolean;
+};
+export type DynamicWorkspaceRegistryFs = {
+    realpathSync(path: string): string;
+    statSync(path: string): {
+        isDirectory(): boolean;
+    };
+    accessSync(path: string, mode: number): void;
+    readdirSync(path: string, options: {
+        withFileTypes: true;
+    }): import('node:fs').Dirent[];
+};
+export type DynamicWorkspaceSelection = {
+    workspaceId: string;
+    displayName: string;
+    binding: SessionBinding;
+};
+export declare class DynamicWorkspaceRegistryError extends Error {
+    readonly code: 'candidate_not_found' | 'candidate_expired' | 'workspace_owner_mismatch' | 'workspace_root_unavailable' | 'workspace_not_readable' | 'workspace_not_directory' | 'workspace_path_escape' | 'candidate_registry_full';
+    constructor(code: DynamicWorkspaceRegistryError['code']);
+}
+export declare class DynamicWorkspaceRegistry {
+    #private;
+    constructor(options: {
+        admission: WorkspaceAdmission;
+        allowedRoots: readonly string[];
+        candidateTtlMs?: number;
+        maxCandidates?: number;
+        maxCandidatesPerOwner?: number;
+        /** Total candidate + browse-token budget. Tokens are not unbounded side state. */
+        maxRegistryEntries?: number;
+        browseTokenTtlMs?: number;
+        maxBrowseEntries?: number;
+        now?: () => number;
+        fs?: DynamicWorkspaceRegistryFs;
+    });
+    get admission(): WorkspaceAdmission;
+    get candidateCount(): number;
+    get browseTokenCount(): number;
+    validateCandidate(candidatePath: string, ownerUserId?: string): WorkspaceCandidateValidation;
+    browse(candidateId: string, childToken?: string, ownerUserId?: string): WorkspaceBrowseResult;
+    select(candidateId: string, access: 'read' | 'read_write', ownerUserId?: string): DynamicWorkspaceSelection;
+    expire(candidateId: string): void;
+    pin(binding: SessionBinding): ExecutionContext;
+}
+//# sourceMappingURL=dynamic-workspace-registry.d.ts.map

package/dist/gateway/dynamic-workspace-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-workspace-registry.d.ts","sourceRoot":"","sources":["../../source/gateway/dynamic-workspace-registry.ts"],"names":[],"mappings":"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"}

package/dist/gateway/dynamic-workspace-registry.js

@@ -0,0 +1,403 @@
+import { constants, accessSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ExecutionContext } from '../services/execution-context.js';
+import { WorkspaceAdmissionError } from './workspace-admission.js';
+export class DynamicWorkspaceRegistryError extends Error {
+    code;
+    constructor(code) {
+        super('dynamic workspace registry rejected the request');
+        this.name = 'DynamicWorkspaceRegistryError';
+        this.code = code;
+    }
+}
+const OPAQUE_ID = /^[A-Za-z0-9_-]{1,256}$/;
+const DEFAULT_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_CANDIDATES = 128;
+const DEFAULT_MAX_CANDIDATES_PER_OWNER = 16;
+const DEFAULT_MAX_BROWSE_ENTRIES = 256;
+export class DynamicWorkspaceRegistry {
+    #admission;
+    #allowedRoots;
+    #candidateTtlMs;
+    #maxCandidates;
+    #maxCandidatesPerOwner;
+    #maxRegistryEntries;
+    #browseTokenTtlMs;
+    #maxBrowseEntries;
+    #now;
+    #fs;
+    #candidates = new Map();
+    #browseTokens = new Map();
+    constructor(options) {
+        this.#admission = options.admission;
+        this.#allowedRoots = Object.freeze(options.allowedRoots.map((root) => canonicalRoot(root)));
+        this.#candidateTtlMs = positiveBound(options.candidateTtlMs ?? DEFAULT_TTL_MS, 'candidateTtlMs');
+        this.#maxCandidates = positiveBound(options.maxCandidates ?? DEFAULT_MAX_CANDIDATES, 'maxCandidates');
+        this.#maxCandidatesPerOwner = positiveBound(options.maxCandidatesPerOwner ?? Math.min(DEFAULT_MAX_CANDIDATES_PER_OWNER, this.#maxCandidates), 'maxCandidatesPerOwner');
+        this.#maxRegistryEntries = positiveBound(options.maxRegistryEntries ?? Math.max(this.#maxCandidates, this.#maxCandidates * 8), 'maxRegistryEntries');
+        this.#browseTokenTtlMs = positiveBound(options.browseTokenTtlMs ?? this.#candidateTtlMs, 'browseTokenTtlMs');
+        this.#maxBrowseEntries = positiveBound(options.maxBrowseEntries ?? DEFAULT_MAX_BROWSE_ENTRIES, 'maxBrowseEntries');
+        this.#now = options.now ?? Date.now;
+        this.#fs = options.fs ?? { realpathSync, statSync, accessSync, readdirSync };
+    }
+    get admission() {
+        return this.#admission;
+    }
+    get candidateCount() {
+        this.#pruneExpired();
+        return this.#candidates.size;
+    }
+    get browseTokenCount() {
+        this.#pruneExpired();
+        return this.#browseTokens.size;
+    }
+    validateCandidate(candidatePath, ownerUserId = 'local-owner') {
+        const checks = [];
+        if (!ownerUserId || typeof candidatePath !== 'string' || !candidatePath || candidatePath.includes('\u0000')) {
+            return invalid(checks, 'workspace_root_unavailable', 'The workspace path is invalid.');
+        }
+        if (!path.isAbsolute(candidatePath)) {
+            checks.push({ name: 'absolute', status: 'error' });
+            return invalid(checks, 'workspace_root_unavailable', 'The workspace path must be absolute.');
+        }
+        checks.push({ name: 'absolute', status: 'ok' });
+        let canonical;
+        try {
+            const initialStat = this.#fs.statSync(candidatePath);
+            checks.push({ name: 'exists', status: 'ok' });
+            if (!initialStat.isDirectory()) {
+                checks.push({ name: 'directory', status: 'error' });
+                return invalid(checks, 'workspace_root_unavailable', 'The selected path is not a directory.');
+            }
+            checks.push({ name: 'directory', status: 'ok' });
+        }
+        catch {
+            checks.push({ name: 'exists', status: 'error' });
+            return invalid(checks, 'workspace_root_unavailable', 'The workspace folder is unavailable.');
+        }
+        try {
+            canonical = this.#fs.realpathSync(candidatePath);
+            checks.push({ name: 'canonical', status: 'ok' });
+        }
+        catch {
+            checks.push({ name: 'canonical', status: 'error' });
+            return invalid(checks, 'workspace_root_not_canonical', 'The workspace path could not be canonicalized.');
+        }
+        try {
+            this.#fs.accessSync(canonical, constants.R_OK | constants.X_OK);
+            checks.push({ name: 'readable', status: 'ok' });
+        }
+        catch {
+            checks.push({ name: 'readable', status: 'error' });
+            return invalid(checks, 'workspace_not_readable', 'The local user cannot read this folder.');
+        }
+        if (!this.#isContainedByAllowedRoot(canonical)) {
+            checks.push({ name: 'contained', status: 'error' });
+            return invalid(checks, 'workspace_path_escape', 'The selected folder is outside the allowed workspace roots.');
+        }
+        checks.push({ name: 'contained', status: 'ok' });
+        this.#pruneExpired();
+        const ownerCandidates = [...this.#candidates.values()].filter((candidate) => candidate.ownerUserId === ownerUserId);
+        if (this.#candidates.size >= this.#maxCandidates ||
+            ownerCandidates.length >= this.#maxCandidatesPerOwner ||
+            this.#registryEntryCount() >= this.#maxRegistryEntries) {
+            return invalid(checks, 'candidate_registry_full', 'Too many workspace selections are pending.');
+        }
+        const candidateId = opaqueId();
+        const record = {
+            candidateId,
+            ownerUserId,
+            canonicalRoot: canonical,
+            displayName: path.basename(canonical) || canonical,
+            expiresAt: this.#now() + this.#candidateTtlMs,
+        };
+        this.#candidates.set(candidateId, record);
+        return {
+            valid: true,
+            candidateId,
+            displayName: record.displayName,
+            expiresAt: record.expiresAt,
+            checks,
+        };
+    }
+    browse(candidateId, childToken, ownerUserId = 'local-owner') {
+        const candidate = this.#candidateFor(candidateId, ownerUserId);
+        const parent = childToken ? this.#browsePath(childToken, candidate) : this.#revalidate(candidate);
+        this.#assertReadableDirectory(parent);
+        let entries;
+        try {
+            entries = this.#fs
+                .readdirSync(parent, { withFileTypes: true })
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((entry) => this.#browseEntry(candidate, parent, entry));
+        }
+        catch {
+            throw new DynamicWorkspaceRegistryError('workspace_not_readable');
+        }
+        return {
+            candidateId,
+            entries: entries.slice(0, this.#maxBrowseEntries),
+            truncated: entries.length > this.#maxBrowseEntries,
+        };
+    }
+    select(candidateId, access, ownerUserId = 'local-owner') {
+        if (access !== 'read' && access !== 'read_write')
+            throw new DynamicWorkspaceRegistryError('workspace_root_unavailable');
+        const candidate = this.#candidateFor(candidateId, ownerUserId);
+        let canonical;
+        try {
+            canonical = this.#revalidate(candidate);
+        }
+        catch (error) {
+            this.expire(candidateId);
+            throw error;
+        }
+        const workspaceId = `ws_${opaqueId()}`;
+        const grant = {
+            workspaceId,
+            ownerUserId,
+            label: candidate.displayName,
+            kind: 'local',
+            localRoot: canonical,
+            access,
+            enabled: true,
+        };
+        this.#admission.registerDynamicLocalGrant(grant);
+        try {
+            const binding = this.#admission.prepare({
+                iss: 'term2-local-owner',
+                aud: 'term2-local-owner',
+                sub: ownerUserId,
+                purpose: 'session_create',
+                iat: 0,
+                nbf: 0,
+                exp: Number.MAX_SAFE_INTEGER,
+                jti: opaqueId(),
+                ver: 1,
+                workspaceId,
+            });
+            this.#candidates.delete(candidateId);
+            for (const [token, value] of this.#browseTokens) {
+                if (value.candidateId === candidateId)
+                    this.#browseTokens.delete(token);
+            }
+            return { workspaceId, displayName: candidate.displayName, binding };
+        }
+        catch (error) {
+            this.#admission.removeDynamicLocalGrant(workspaceId);
+            if (error instanceof WorkspaceAdmissionError)
+                throw error;
+            throw new DynamicWorkspaceRegistryError('workspace_root_unavailable');
+        }
+    }
+    expire(candidateId) {
+        this.#candidates.delete(candidateId);
+        for (const [token, value] of this.#browseTokens) {
+            if (value.candidateId === candidateId)
+                this.#browseTokens.delete(token);
+        }
+    }
+    pin(binding) {
+        return ExecutionContext.pin(binding.canonicalRoot);
+    }
+    #candidateFor(candidateId, ownerUserId) {
+        if (!OPAQUE_ID.test(candidateId))
+            throw new DynamicWorkspaceRegistryError('candidate_not_found');
+        const candidate = this.#candidates.get(candidateId);
+        if (!candidate)
+            throw new DynamicWorkspaceRegistryError('candidate_not_found');
+        if (candidate.ownerUserId !== ownerUserId)
+            throw new DynamicWorkspaceRegistryError('workspace_owner_mismatch');
+        if (candidate.expiresAt <= this.#now()) {
+            this.expire(candidateId);
+            throw new DynamicWorkspaceRegistryError('candidate_expired');
+        }
+        this.#pruneExpired();
+        return candidate;
+    }
+    #browsePath(token, candidate) {
+        if (!OPAQUE_ID.test(token))
+            throw new DynamicWorkspaceRegistryError('candidate_not_found');
+        const value = this.#browseTokens.get(token);
+        if (!value || value.candidateId !== candidate.candidateId || value.ownerUserId !== candidate.ownerUserId)
+            throw new DynamicWorkspaceRegistryError('candidate_not_found');
+        if (value.expiresAt <= this.#now()) {
+            this.#browseTokens.delete(token);
+            throw new DynamicWorkspaceRegistryError('candidate_expired');
+        }
+        let canonical;
+        try {
+            canonical = this.#revalidate(candidate);
+        }
+        catch (error) {
+            this.#browseTokens.delete(token);
+            throw error;
+        }
+        let currentPath;
+        try {
+            currentPath = this.#fs.realpathSync(value.canonicalPath);
+        }
+        catch {
+            this.#browseTokens.delete(token);
+            throw new DynamicWorkspaceRegistryError('workspace_path_escape');
+        }
+        if (currentPath !== value.canonicalPath || !isContained(canonical, currentPath)) {
+            this.#browseTokens.delete(token);
+            throw new DynamicWorkspaceRegistryError('workspace_path_escape');
+        }
+        this.#assertReadableDirectory(currentPath);
+        return currentPath;
+    }
+    #browseEntry(candidate, parent, entry) {
+        const fullPath = path.join(parent, entry.name);
+        if (entry.isSymbolicLink()) {
+            try {
+                const target = this.#fs.realpathSync(fullPath);
+                const inside = isContained(candidate.canonicalRoot, target);
+                if (!inside) {
+                    return {
+                        name: entry.name,
+                        type: 'symlink',
+                        selectable: false,
+                        rejectionReason: 'workspace_path_escape',
+                        targetDisplay: 'outside-candidate-root',
+                    };
+                }
+                if (!this.#fs.statSync(target).isDirectory()) {
+                    return { name: entry.name, type: 'symlink', selectable: false, rejectionReason: 'workspace_not_directory' };
+                }
+                return {
+                    name: entry.name,
+                    type: 'symlink',
+                    selectable: true,
+                    targetDisplay: path.relative(candidate.canonicalRoot, target) || '.',
+                    childToken: this.#tokenFor(candidate, target),
+                };
+            }
+            catch {
+                return { name: entry.name, type: 'symlink', selectable: false, rejectionReason: 'workspace_root_unavailable' };
+            }
+        }
+        if (entry.isDirectory()) {
+            try {
+                const target = this.#fs.realpathSync(fullPath);
+                if (!isContained(candidate.canonicalRoot, target))
+                    return { name: entry.name, type: 'directory', selectable: false, rejectionReason: 'workspace_path_escape' };
+                if (!this.#fs.statSync(target).isDirectory())
+                    return { name: entry.name, type: 'directory', selectable: false, rejectionReason: 'workspace_not_directory' };
+                return { name: entry.name, type: 'directory', selectable: true, childToken: this.#tokenFor(candidate, target) };
+            }
+            catch {
+                return {
+                    name: entry.name,
+                    type: 'directory',
+                    selectable: false,
+                    rejectionReason: 'workspace_root_unavailable',
+                };
+            }
+        }
+        if (entry.isFile())
+            return { name: entry.name, type: 'file', selectable: false, rejectionReason: 'workspace_not_directory' };
+        return { name: entry.name, type: 'other', selectable: false, rejectionReason: 'workspace_not_directory' };
+    }
+    #tokenFor(candidate, directory) {
+        this.#pruneExpired();
+        if (this.#registryEntryCount() >= this.#maxRegistryEntries) {
+            this.#evictBrowseToken();
+            if (this.#registryEntryCount() >= this.#maxRegistryEntries)
+                return undefined;
+        }
+        const token = opaqueId();
+        const now = this.#now();
+        this.#browseTokens.set(token, {
+            candidateId: candidate.candidateId,
+            ownerUserId: candidate.ownerUserId,
+            canonicalPath: directory,
+            expiresAt: Math.min(candidate.expiresAt, now + this.#browseTokenTtlMs),
+            createdAt: now,
+        });
+        return token;
+    }
+    #revalidate(candidate) {
+        let canonical;
+        try {
+            canonical = this.#fs.realpathSync(candidate.canonicalRoot);
+            if (!this.#fs.statSync(canonical).isDirectory())
+                throw new Error();
+            this.#fs.accessSync(canonical, constants.R_OK | constants.X_OK);
+        }
+        catch {
+            throw new DynamicWorkspaceRegistryError('workspace_root_unavailable');
+        }
+        if (canonical !== candidate.canonicalRoot || !this.#isContainedByAllowedRoot(canonical)) {
+            throw new DynamicWorkspaceRegistryError('workspace_path_escape');
+        }
+        return canonical;
+    }
+    #assertReadableDirectory(directory) {
+        try {
+            if (!this.#fs.statSync(directory).isDirectory())
+                throw new Error();
+            this.#fs.accessSync(directory, constants.R_OK | constants.X_OK);
+        }
+        catch {
+            throw new DynamicWorkspaceRegistryError('workspace_not_readable');
+        }
+    }
+    #isContainedByAllowedRoot(candidate) {
+        return this.#allowedRoots.some((root) => isContained(root, candidate));
+    }
+    #pruneExpired() {
+        const now = this.#now();
+        for (const [id, candidate] of this.#candidates) {
+            if (candidate.expiresAt <= now)
+                this.expire(id);
+        }
+        for (const [token, browse] of this.#browseTokens) {
+            if (browse.expiresAt <= now || !this.#candidates.has(browse.candidateId))
+                this.#browseTokens.delete(token);
+        }
+    }
+    #registryEntryCount() {
+        return this.#candidates.size + this.#browseTokens.size;
+    }
+    #evictBrowseToken() {
+        let oldest;
+        for (const item of this.#browseTokens.entries()) {
+            if (!oldest || item[1].createdAt < oldest[1].createdAt)
+                oldest = item;
+        }
+        if (oldest)
+            this.#browseTokens.delete(oldest[0]);
+    }
+}
+function canonicalRoot(root) {
+    if (!path.isAbsolute(root))
+        throw new Error('dynamic workspace allowed roots must be absolute');
+    try {
+        const resolved = realpathSync(root);
+        if (!statSync(resolved).isDirectory())
+            throw new Error();
+        return resolved;
+    }
+    catch {
+        throw new Error('dynamic workspace allowed root is unavailable');
+    }
+}
+function positiveBound(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+}
+function opaqueId() {
+    return randomUUID().replaceAll('-', '');
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+function invalid(checks, reasonCode, reason) {
+    return { valid: false, checks, reasonCode, reason };
+}
+//# sourceMappingURL=dynamic-workspace-registry.js.map