@undefineds.co/xpod 0.4.19 → 0.4.25

package/dist/http/agent-directory/AgentDirectoryHttpHandler.js

@@ -0,0 +1,717 @@
+"use strict";
+/**
+ * AgentDirectoryHttpHandler - authenticated directory enumeration and exact
+ * content query for agent shell adapters (rg/grep wrappers).
+ *
+ * Endpoints (sidecar path, default `/-/agent-directory`):
+ * - GET  `.../list?root=<containerUrl>[&pathPrefix=][&limit=][&cursor=]`
+ * - GET  `.../search?root=<containerUrl>&q=<literal>[&pathPrefix=][&limit=][&cursor=][&maxFileBytes=]`
+ * - GET  `.../read?url=<resourceUrl>`
+ *
+ * Design notes:
+ * - The `root` URI is only a scope selector. Every container and every result
+ *   is authorized individually through the CSS credentials/permission/authorizer
+ *   chain, so a readable root never implies readable descendants.
+ * - Child URIs returned by the accessor are validated (same origin, canonical
+ *   root scope, no query/hash/userinfo, direct child) before use.
+ * - Search is a server-side exact literal scan of authorized content. Only
+ *   matches/metadata cross the wire; the full directory body is never returned
+ *   to the client for it to grep. Regex/ignore-case/unknown modes are rejected
+ *   so the caller falls back to the native binary instead of changing semantics.
+ * - Denied resources are silently excluded. Their count is never reported, so
+ *   the response cannot leak the existence of inaccessible resources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDirectoryHttpHandler = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const community_server_1 = require("@solid/community-server");
+const community_server_2 = require("@solid/community-server");
+const policy_engine_1 = require("@solidlab/policy-engine");
+const ResourceReadContext_1 = require("../../storage/ResourceReadContext");
+const protocol_1 = require("../../agent-directory/protocol");
+const ALLOWED_METHODS = ['GET', 'OPTIONS'];
+const DEFAULT_LIMIT = 1000;
+const MAX_LIMIT = 5000;
+const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_SCAN_ENTRIES = 50_000;
+const INTERNAL_QUADS = 'internal/quads';
+const TEXTUAL_CONTENT_TYPES = [
+    'text/',
+    'application/json',
+    'application/ld+json',
+    'application/xml',
+    'application/x-ndjson',
+    'application/yaml',
+    'application/x-yaml',
+    'application/toml',
+    'application/javascript',
+    'application/x-sh',
+    'application/sql',
+    'application/sparql-query',
+    'application/sparql-update',
+];
+class AgentDirectoryHttpHandler extends community_server_1.HttpHandler {
+    constructor(accessor, credentialsExtractor, permissionReader, authorizer, auxiliaryStrategy, identifierStrategy, options = {}) {
+        super();
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.accessor = accessor;
+        this.credentialsExtractor = credentialsExtractor;
+        this.permissionReader = permissionReader;
+        this.authorizer = authorizer;
+        this.auxiliaryStrategy = auxiliaryStrategy;
+        this.identifierStrategy = identifierStrategy;
+        this.sidecarPath = options.sidecarPath ?? protocol_1.AGENT_DIRECTORY_SIDECAR;
+        this.defaultLimit = this.normalizeLimit(options.defaultLimit, DEFAULT_LIMIT);
+        this.maxFileBytes = this.normalizeLimit(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES);
+    }
+    async canHandle({ request }) {
+        const path = this.parseUrl(request).pathname;
+        if (!path.includes(this.sidecarPath)) {
+            throw new community_server_2.NotImplementedHttpError('Request is not targeting the agent directory endpoint.');
+        }
+    }
+    async handle({ request, response }) {
+        const method = (request.method ?? 'GET').toUpperCase();
+        if (method === 'OPTIONS') {
+            this.writeOptions(response);
+            return;
+        }
+        if (!ALLOWED_METHODS.includes(method)) {
+            throw new community_server_2.MethodNotAllowedHttpError(ALLOWED_METHODS);
+        }
+        try {
+            const url = this.parseUrl(request);
+            const operation = this.parseOperation(url.pathname);
+            const credentials = await this.credentialsExtractor.handleSafe(request);
+            switch (operation) {
+                case 'list':
+                    await this.handleList(url, credentials, response);
+                    break;
+                case 'search':
+                    await this.handleSearch(url, credentials, response);
+                    break;
+                case 'read':
+                    await this.handleRead(url, credentials, response);
+                    break;
+                default:
+                    throw new community_server_2.BadRequestHttpError(`Unsupported agent directory operation: ${operation}`);
+            }
+        }
+        catch (error) {
+            this.handleError(response, error);
+        }
+    }
+    // ============================================
+    // list
+    // ============================================
+    async handleList(url, credentials, response) {
+        const root = await this.resolveRoot(url, credentials);
+        const pathPrefix = this.parsePathPrefix(url.searchParams.get('pathPrefix'));
+        const limit = this.clampLimit(url.searchParams.get('limit'));
+        const cursor = this.decodeListCursor(url.searchParams.get('cursor'));
+        // Collect one extra entry so truncation is detectable without an extra scan.
+        const collected = await this.collectEntries(root, credentials, pathPrefix, cursor.offset + limit + 1);
+        const page = collected.entries.slice(cursor.offset, cursor.offset + limit);
+        const truncated = collected.limitReached || collected.entries.length > cursor.offset + limit;
+        const payload = {
+            root,
+            entries: page,
+            truncated,
+            // `complete` is about coverage, not about whether this page is the last one.
+            complete: collected.complete,
+            scanned: collected.scanned,
+            ...(truncated ? { nextCursor: this.encodeCursor({ offset: cursor.offset + page.length }) } : {}),
+        };
+        this.sendJsonResponse(response, payload);
+    }
+    // ============================================
+    // search
+    // ============================================
+    async handleSearch(url, credentials, response) {
+        const root = await this.resolveRoot(url, credentials);
+        const query = url.searchParams.get('q');
+        if (!query) {
+            throw new community_server_2.BadRequestHttpError('Missing query parameter "q".');
+        }
+        const mode = url.searchParams.get('mode') ?? 'literal';
+        if (mode !== 'literal') {
+            throw new community_server_2.NotImplementedHttpError(`Agent directory search mode "${mode}" is not supported; use the native search binary instead.`);
+        }
+        if (this.parseBoolean(url.searchParams.get('ignoreCase'))) {
+            // JavaScript case folding is not equivalent to ripgrep's Unicode simple
+            // folding and can shift byte/column offsets; refuse rather than mislead.
+            throw new community_server_2.NotImplementedHttpError('Case-insensitive search is not supported; use the native search binary instead.');
+        }
+        const pathPrefix = this.parsePathPrefix(url.searchParams.get('pathPrefix'));
+        const limit = this.clampLimit(url.searchParams.get('limit'));
+        const cursor = this.decodeSearchCursor(url.searchParams.get('cursor'));
+        const maxFileBytes = this.clampLimit(url.searchParams.get('maxFileBytes'), this.maxFileBytes);
+        const collected = await this.collectEntries(root, credentials, pathPrefix, MAX_SCAN_ENTRIES);
+        const files = collected.entries.filter((entry) => entry.type === 'file');
+        const matches = [];
+        let scannedFiles = 0;
+        let skippedUnsupported = 0;
+        let truncated = false;
+        let nextCursor;
+        let hasUnscannedScope = !collected.complete || collected.failed > 0 || collected.limitReached;
+        for (let fileIndex = cursor.file; fileIndex < files.length; fileIndex += 1) {
+            if (matches.length >= limit) {
+                truncated = true;
+                nextCursor = { file: fileIndex, line: 0 };
+                break;
+            }
+            const file = files[fileIndex];
+            scannedFiles += 1;
+            const content = await this.readSearchableText(file.url, maxFileBytes);
+            if (!content) {
+                skippedUnsupported += 1;
+                hasUnscannedScope = true;
+                continue;
+            }
+            const fromLine = fileIndex === cursor.file ? cursor.line : 0;
+            for (const match of this.findLiteralMatches(content.text, query, file, fromLine)) {
+                matches.push(match);
+                if (matches.length >= limit) {
+                    // Resume inside this same file so no later match is dropped.
+                    truncated = true;
+                    nextCursor = { file: fileIndex, line: match.line };
+                    break;
+                }
+            }
+            if (truncated) {
+                break;
+            }
+        }
+        // Coverage only: pagination (`truncated`/`nextCursor`) is not an omission.
+        const complete = collected.complete && collected.failed === 0 && !collected.limitReached && skippedUnsupported === 0;
+        const payload = {
+            root,
+            query,
+            mode: 'literal',
+            ignoreCase: false,
+            matches,
+            truncated,
+            complete,
+            scannedFiles,
+            skippedUnsupported,
+            hasUnscannedScope,
+            ...(nextCursor ? { nextCursor: this.encodeCursor(nextCursor) } : {}),
+        };
+        this.sendJsonResponse(response, payload);
+    }
+    // ============================================
+    // read
+    // ============================================
+    async handleRead(url, credentials, response) {
+        const rawUrl = url.searchParams.get('url');
+        if (!rawUrl) {
+            throw new community_server_2.BadRequestHttpError('Missing query parameter "url".');
+        }
+        const resourceUrl = this.validateSameOriginUrl(rawUrl, `${url.protocol}//${url.host}`);
+        const identifier = { path: resourceUrl };
+        if (this.auxiliaryStrategy.isAuxiliaryIdentifier(identifier)) {
+            throw new community_server_2.ForbiddenHttpError('Auxiliary resources are not exposed through the agent directory endpoint.');
+        }
+        if (!this.identifierStrategy.supportsIdentifier(identifier)) {
+            throw new community_server_2.ForbiddenHttpError('Resource is outside the server identifier scope.');
+        }
+        await this.authorizeIdentifier(resourceUrl, credentials, [policy_engine_1.PERMISSIONS.Read]);
+        const content = await this.readSearchableText(resourceUrl, this.maxFileBytes);
+        if (!content) {
+            throw new community_server_2.BadRequestHttpError('Resource is not a supported text resource.');
+        }
+        const metadata = await this.accessor.getMetadata(identifier);
+        this.sendJsonResponse(response, {
+            url: resourceUrl,
+            contentType: metadata.contentType,
+            size: Buffer.byteLength(content.text, 'utf8'),
+            bodyBase64: Buffer.from(content.text, 'utf8').toString('base64'),
+        });
+    }
+    // ============================================
+    // enumeration + authorization
+    // ============================================
+    async collectEntries(root, credentials, pathPrefix, maxEntries) {
+        const entries = [];
+        let denied = 0;
+        let failed = 0;
+        let complete = true;
+        let limitReached = false;
+        let aborted = false;
+        // Iterative DFS with deterministic sibling ordering so cursors are stable.
+        const stack = [root];
+        const visited = new Set();
+        while (stack.length > 0 && !aborted) {
+            const container = stack.pop();
+            if (visited.has(container)) {
+                continue;
+            }
+            visited.add(container);
+            let children;
+            try {
+                children = await this.listAuthorizedChildren(container, credentials);
+            }
+            catch (error) {
+                // Read/enumeration failure must make the result explicitly incomplete,
+                // never silently "complete".
+                failed += 1;
+                complete = false;
+                if (error instanceof community_server_2.HttpError) {
+                    continue;
+                }
+                throw error;
+            }
+            children.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+            const childContainers = [];
+            for (const childUrl of children) {
+                if (entries.length >= maxEntries) {
+                    limitReached = true;
+                    aborted = true;
+                    break;
+                }
+                if (!this.isValidChild(container, childUrl, root)) {
+                    failed += 1;
+                    complete = false;
+                    continue;
+                }
+                const relativePath = this.decodeRelativePath(childUrl.slice(root.length));
+                if (relativePath === undefined) {
+                    failed += 1;
+                    complete = false;
+                    continue;
+                }
+                if (pathPrefix && !relativePath.startsWith(pathPrefix)) {
+                    continue;
+                }
+                const identifier = { path: childUrl };
+                if (this.auxiliaryStrategy.isAuxiliaryIdentifier(identifier)) {
+                    continue;
+                }
+                let metadata;
+                try {
+                    metadata = await this.accessor.getMetadata(identifier);
+                }
+                catch (error) {
+                    if (community_server_2.NotFoundHttpError.isInstance(error)) {
+                        failed += 1;
+                        complete = false;
+                        continue;
+                    }
+                    throw error;
+                }
+                const isContainer = childUrl.endsWith('/');
+                const authorized = await this.canAuthorizeIdentifier(childUrl, credentials, [policy_engine_1.PERMISSIONS.Read]);
+                if (!authorized) {
+                    denied += 1;
+                    continue;
+                }
+                if (isContainer) {
+                    childContainers.push(childUrl);
+                }
+                entries.push({
+                    path: relativePath,
+                    url: childUrl,
+                    type: isContainer ? 'container' : 'file',
+                    ...(metadata.contentType && metadata.contentType !== INTERNAL_QUADS
+                        ? { contentType: metadata.contentType }
+                        : {}),
+                    ...(metadata.contentLength !== undefined ? { size: metadata.contentLength } : {}),
+                });
+            }
+            // Only recurse into containers that were validated and authorized.
+            for (let index = childContainers.length - 1; index >= 0; index -= 1) {
+                stack.push(childContainers[index]);
+            }
+        }
+        return { entries, complete, limitReached, scanned: entries.length, denied, failed };
+    }
+    async listAuthorizedChildren(containerUrl, credentials) {
+        await this.authorizeIdentifier(containerUrl, credentials, [policy_engine_1.PERMISSIONS.Read]);
+        const children = [];
+        for await (const child of this.accessor.getChildren({ path: containerUrl })) {
+            const value = child.identifier?.value;
+            if (value) {
+                children.push(value);
+            }
+        }
+        return children;
+    }
+    isValidChild(containerUrl, childUrl, root) {
+        let parsed;
+        try {
+            parsed = new URL(childUrl);
+        }
+        catch {
+            return false;
+        }
+        const container = new URL(containerUrl);
+        if (parsed.origin !== container.origin || parsed.origin !== new URL(root).origin) {
+            return false;
+        }
+        if (parsed.search !== '' || parsed.hash !== '' || parsed.username !== '' || parsed.password !== '') {
+            return false;
+        }
+        if (!childUrl.startsWith(root) || childUrl === root) {
+            return false;
+        }
+        if (!childUrl.startsWith(containerUrl)) {
+            return false;
+        }
+        const segment = childUrl.slice(containerUrl.length);
+        if (segment.length === 0) {
+            return false;
+        }
+        const bare = segment.endsWith('/') ? segment.slice(0, -1) : segment;
+        return bare.length > 0 && !bare.includes('/');
+    }
+    decodeRelativePath(raw) {
+        const segments = raw.split('/').filter((segment) => segment.length > 0);
+        const decoded = [];
+        for (const segment of segments) {
+            let value;
+            try {
+                value = decodeURIComponent(segment);
+            }
+            catch {
+                return undefined;
+            }
+            if (value.length === 0 || value === '.' || value === '..' || value.includes('/')) {
+                return undefined;
+            }
+            decoded.push(value);
+        }
+        const joined = decoded.join('/');
+        return raw.endsWith('/') && joined.length > 0 ? `${joined}/` : joined;
+    }
+    // ============================================
+    // content reading
+    // ============================================
+    async readSearchableText(resourceUrl, maxFileBytes) {
+        const identifier = { path: resourceUrl };
+        let metadata;
+        try {
+            metadata = await this.accessor.getMetadata(identifier);
+        }
+        catch (error) {
+            if (community_server_2.NotFoundHttpError.isInstance(error)) {
+                return undefined;
+            }
+            throw error;
+        }
+        let stream;
+        if (metadata.contentType === INTERNAL_QUADS) {
+            const localRdf = await this.tryReadLocalRdfDocument(identifier);
+            if (!localRdf) {
+                return undefined;
+            }
+            stream = localRdf;
+        }
+        else {
+            if (!this.isTextualContentType(metadata.contentType)) {
+                return undefined;
+            }
+            stream = await (0, ResourceReadContext_1.withDirectDataRead)(async () => this.accessor.getData(identifier));
+        }
+        const bounded = await this.readStreamLimited(stream, maxFileBytes);
+        if (bounded.truncated || bounded.buffer.includes(0)) {
+            return undefined;
+        }
+        const text = bounded.buffer.toString('utf8');
+        if (text.includes('\uFFFD')) {
+            return undefined;
+        }
+        return { text };
+    }
+    async tryReadLocalRdfDocument(identifier) {
+        const accessor = this.accessor;
+        if (typeof accessor.getLocalRdfDocument !== 'function') {
+            return undefined;
+        }
+        try {
+            const document = await accessor.getLocalRdfDocument(identifier);
+            return document.data;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isTextualContentType(contentType) {
+        if (!contentType) {
+            return true;
+        }
+        const normalized = contentType.toLowerCase();
+        return TEXTUAL_CONTENT_TYPES.some((prefix) => normalized.startsWith(prefix));
+    }
+    async readStreamLimited(stream, maxFileBytes) {
+        const chunks = [];
+        let total = 0;
+        let truncated = false;
+        try {
+            for await (const chunk of stream) {
+                const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk);
+                total += buffer.length;
+                if (total > maxFileBytes) {
+                    truncated = true;
+                    break;
+                }
+                chunks.push(buffer);
+            }
+        }
+        finally {
+            const destroyable = stream;
+            if (typeof destroyable.destroy === 'function') {
+                destroyable.destroy();
+            }
+        }
+        return { buffer: Buffer.concat(chunks), truncated };
+    }
+    /**
+     * Line-oriented literal matching.
+     *
+     * ripgrep's default output prints a matching line once, even when the pattern
+     * occurs multiple times on that line, and `-c` counts matching lines rather
+     * than occurrences. `fromLineExclusive` lets an in-file cursor resume without
+     * dropping later matches. Case-insensitive matching is deliberately absent:
+     * the server rejects it before reaching this method.
+     */
+    findLiteralMatches(text, query, file, fromLineExclusive) {
+        const matches = [];
+        if (query.length === 0) {
+            return matches;
+        }
+        let lineStart = 0;
+        let lineNumber = 1;
+        while (lineStart <= text.length) {
+            const newlineIndex = text.indexOf('\n', lineStart);
+            const lineEnd = newlineIndex === -1 ? text.length : newlineIndex;
+            if (lineNumber > fromLineExclusive) {
+                const line = text.slice(lineStart, lineEnd);
+                const found = line.indexOf(query);
+                if (found !== -1) {
+                    matches.push({
+                        path: file.path,
+                        url: file.url,
+                        line: lineNumber,
+                        column: found + 1,
+                        text: line,
+                        matched: line.slice(found, found + query.length),
+                        ...(file.version ? { version: file.version } : {}),
+                    });
+                }
+            }
+            if (newlineIndex === -1) {
+                break;
+            }
+            lineStart = newlineIndex + 1;
+            lineNumber += 1;
+        }
+        return matches;
+    }
+    // ============================================
+    // validation helpers
+    // ============================================
+    async resolveRoot(url, credentials) {
+        const rawRoot = url.searchParams.get('root');
+        if (!rawRoot) {
+            throw new community_server_2.BadRequestHttpError('Missing query parameter "root".');
+        }
+        const origin = `${url.protocol}//${url.host}`;
+        let parsed;
+        try {
+            parsed = new URL(rawRoot);
+        }
+        catch {
+            throw new community_server_2.BadRequestHttpError('Parameter "root" must be an absolute URL.');
+        }
+        if (parsed.origin !== origin) {
+            throw new community_server_2.ForbiddenHttpError('Parameter "root" must point at this server origin.');
+        }
+        if (parsed.search !== '' || parsed.hash !== '' || parsed.username !== '' || parsed.password !== '') {
+            throw new community_server_2.ForbiddenHttpError('Parameter "root" must not carry query, hash or userinfo.');
+        }
+        if (!parsed.pathname.endsWith('/')) {
+            throw new community_server_2.BadRequestHttpError('Parameter "root" must be a container URL ending with "/".');
+        }
+        const normalized = parsed.href;
+        const identifier = { path: normalized };
+        if (!this.identifierStrategy.supportsIdentifier(identifier)) {
+            throw new community_server_2.ForbiddenHttpError('Parameter "root" is outside the server identifier scope.');
+        }
+        await this.authorizeIdentifier(normalized, credentials, [policy_engine_1.PERMISSIONS.Read]);
+        return normalized;
+    }
+    parsePathPrefix(value) {
+        if (!value) {
+            return undefined;
+        }
+        const stripped = value.replace(/^\/+/, '');
+        if (stripped.length === 0) {
+            return undefined;
+        }
+        // A trailing slash is the directory marker the caller uses; interior empty
+        // segments and ".." are still rejected.
+        const segments = stripped.split('/');
+        if (segments[segments.length - 1] === '') {
+            segments.pop();
+        }
+        if (segments.length === 0 || segments.some((segment) => segment === '..' || segment.length === 0)) {
+            throw new community_server_2.BadRequestHttpError('Parameter "pathPrefix" must be a relative path without "..".');
+        }
+        return `${segments.join('/')}/`;
+    }
+    clampLimit(value, fallback = this.defaultLimit) {
+        if (!value) {
+            return fallback;
+        }
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new community_server_2.BadRequestHttpError('Limit must be a positive integer.');
+        }
+        return Math.min(parsed, MAX_LIMIT);
+    }
+    normalizeLimit(value, fallback) {
+        if (value === undefined || !Number.isFinite(value) || value <= 0) {
+            return fallback;
+        }
+        return Math.min(Math.trunc(value), MAX_LIMIT);
+    }
+    parseBoolean(value) {
+        return value === '1' || value === 'true' || value === 'yes';
+    }
+    decodeListCursor(value) {
+        if (!value) {
+            return { offset: 0 };
+        }
+        try {
+            const decoded = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+            const offset = Number(decoded.offset);
+            if (!Number.isFinite(offset) || offset < 0) {
+                throw new Error('invalid offset');
+            }
+            return { offset: Math.trunc(offset) };
+        }
+        catch {
+            throw new community_server_2.BadRequestHttpError('Invalid pagination cursor.');
+        }
+    }
+    decodeSearchCursor(value) {
+        if (!value) {
+            return { file: 0, line: 0 };
+        }
+        try {
+            const decoded = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+            const file = Number(decoded.file);
+            const line = Number(decoded.line);
+            if (!Number.isFinite(file) || file < 0 || !Number.isFinite(line) || line < 0) {
+                throw new Error('invalid cursor');
+            }
+            return { file: Math.trunc(file), line: Math.trunc(line) };
+        }
+        catch {
+            throw new community_server_2.BadRequestHttpError('Invalid pagination cursor.');
+        }
+    }
+    encodeCursor(cursor) {
+        return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+    }
+    parseOperation(pathname) {
+        const index = pathname.indexOf(this.sidecarPath);
+        if (index === -1) {
+            throw new community_server_2.NotImplementedHttpError('Request is not targeting the agent directory endpoint.');
+        }
+        const suffix = pathname.slice(index + this.sidecarPath.length).replace(/^\/+/, '');
+        return suffix.split('/')[0] ?? '';
+    }
+    validateSameOriginUrl(value, origin) {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            throw new community_server_2.BadRequestHttpError('URL parameter must be an absolute URL.');
+        }
+        if (parsed.origin !== origin) {
+            throw new community_server_2.ForbiddenHttpError('URL parameter must point at this server origin.');
+        }
+        if (parsed.search !== '' || parsed.hash !== '' || parsed.username !== '' || parsed.password !== '') {
+            throw new community_server_2.ForbiddenHttpError('URL parameter must not carry query, hash or userinfo.');
+        }
+        if (!this.identifierStrategy.supportsIdentifier({ path: parsed.href })) {
+            throw new community_server_2.ForbiddenHttpError('URL parameter is outside the server identifier scope.');
+        }
+        return parsed.href;
+    }
+    async authorizeIdentifier(basePath, credentials, modes) {
+        const identifier = { path: basePath };
+        const requestedModes = new community_server_2.IdentifierSetMultiMap();
+        for (const mode of modes) {
+            requestedModes.add(identifier, mode);
+        }
+        const availablePermissions = await this.permissionReader.handleSafe({ credentials, requestedModes });
+        await this.authorizer.handleSafe({ credentials, requestedModes, availablePermissions });
+    }
+    async canAuthorizeIdentifier(basePath, credentials, modes) {
+        try {
+            await this.authorizeIdentifier(basePath, credentials, modes);
+            return true;
+        }
+        catch (error) {
+            this.logger.debug(`Agent directory denied ${basePath}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    // ============================================
+    // HTTP helpers
+    // ============================================
+    parseUrl(request) {
+        // Gateway xfwd appends each hop; use the first forwarded origin value.
+        const protocol = this.firstForwardedValue(request.headers['x-forwarded-proto'])
+            ?? this.firstForwardedValue(request.headers['X-Forwarded-Proto'])
+            ?? 'http';
+        const host = this.firstForwardedValue(request.headers['x-forwarded-host'])
+            ?? this.firstForwardedValue(request.headers['X-Forwarded-Host'])
+            ?? this.firstForwardedValue(request.headers.host)
+            ?? this.firstForwardedValue(request.headers.Host)
+            ?? 'localhost';
+        return new URL(request.url ?? '/', `${protocol}://${host}`);
+    }
+    firstForwardedValue(value) {
+        const first = Array.isArray(value) ? value[0] : value;
+        if (typeof first !== 'string') {
+            return undefined;
+        }
+        return first.split(',')[0]?.trim() || undefined;
+    }
+    sendJsonResponse(response, data, status = 200) {
+        response.writeHead(status, {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-store',
+        });
+        response.end(JSON.stringify(data));
+    }
+    handleError(response, error) {
+        if (error instanceof community_server_2.HttpError) {
+            this.sendError(response, error.statusCode, error.name || 'HttpError', error.message);
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Agent directory error: ${message}`);
+        this.sendError(response, 500, 'INTERNAL_ERROR', message);
+    }
+    sendError(response, status, code, message) {
+        response.writeHead(status, {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-store',
+        });
+        response.end(JSON.stringify({ error: true, code, message }));
+    }
+    writeOptions(response) {
+        response.writeHead(204, {
+            'Access-Control-Allow-Methods': ALLOWED_METHODS.join(', '),
+            'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        });
+        response.end();
+    }
+}
+exports.AgentDirectoryHttpHandler = AgentDirectoryHttpHandler;
+//# sourceMappingURL=AgentDirectoryHttpHandler.js.map