@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/http/SubgraphSparqlHttpHandler.d.ts

@@ -3,6 +3,7 @@ import type { HttpHandlerInput } from '@solid/community-server';
 import type { ActivityEmitter, CredentialsExtractor, PermissionReader, Authorizer } from '@solid/community-server';
 import { SubgraphQueryEngine } from '../storage/sparql/SubgraphQueryEngine';
 import { MixDataAccessor } from '../storage/accessors/MixDataAccessor';
+import type { HierarchyLockingResourceStore } from '../storage/HierarchyLockingResourceStore';
 interface SubgraphSparqlHttpHandlerOptions {
     /** @deprecated Use sidecarPath instead */
     resourceSuffix?: string;
@@ -15,6 +16,7 @@ interface SubgraphSparqlHttpHandlerOptions {
     defaultAccountBandwidthLimitBps?: number | null;
 }
 export declare class SubgraphSparqlHttpHandler extends HttpHandler {
+    private readonly mutationStore?;
     protected readonly logger: import("global-logger-factory").Logger<unknown>;
     private readonly engine;
     private readonly credentialsExtractor;
@@ -28,7 +30,7 @@ export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     private readonly emitter?;
     private readonly generator;
     private static readonly XSD_STRING;
-    constructor(queryEngine: SubgraphQueryEngine, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, options?: SubgraphSparqlHttpHandlerOptions, updateAuthority?: MixDataAccessor, emitter?: ActivityEmitter);
+    constructor(queryEngine: SubgraphQueryEngine, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, options?: SubgraphSparqlHttpHandlerOptions, updateAuthority?: MixDataAccessor, emitter?: ActivityEmitter, mutationStore?: HierarchyLockingResourceStore | undefined);
     canHandle({ request }: HttpHandlerInput): Promise<void>;
     handle({ request, response }: HttpHandlerInput): Promise<void>;
     private sendErrorResponse;

package/dist/http/SubgraphSparqlHttpHandler.js

@@ -14,12 +14,38 @@ const db_1 = require("../identity/drizzle/db");
 const PodLookupRepository_1 = require("../identity/drizzle/PodLookupRepository");
 const UsageRepository_1 = require("../storage/quota/UsageRepository");
 const BandwidthThrottleTransform_1 = require("../util/stream/BandwidthThrottleTransform");
+/** Independent authorization reads are latency-bound; bound their in-flight count per request. */
+const GRAPH_AUTHORIZATION_CONCURRENCY = 8;
+/**
+ * Runs `worker` over `items` with at most `limit` in flight, preserving input order.
+ *
+ * Contract: `worker` must not reject. This helper intentionally has no cancellation —
+ * it is only used for read-only authorization checks whose call site (`canAuthorizeFor`)
+ * already converts denials into `false`. If a throwing worker is ever wired in, the
+ * first rejection surfaces while sibling runners finish; add an AbortSignal then.
+ */
+async function mapBounded(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
 const ALLOWED_METHODS = ['GET', 'POST', 'OPTIONS'];
 const MODEL_COLLECTION_SUFFIX = '/settings/providers/-/sparql';
 const SETTINGS_COLLECTION_SUFFIX = '/settings/-/sparql';
 class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
-    constructor(queryEngine, credentialsExtractor, permissionReader, authorizer, options = {}, updateAuthority, emitter) {
+    constructor(queryEngine, credentialsExtractor, permissionReader, authorizer, options = {}, updateAuthority, emitter, mutationStore) {
         super();
+        this.mutationStore = mutationStore;
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         this.generator = new sparqljs_1.Generator();
         this.engine = queryEngine;
@@ -231,26 +257,27 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         if (accessPlan.hasDelete) {
             modes.push(policy_engine_1.PERMISSIONS.Delete);
         }
-        const credentials = trusted ? undefined : await this.authorizeFor(queryRequest.baseUrl, request, modes);
+        const authMemo = new Map();
+        const credentials = trusted ? undefined : await this.authorizeFor(queryRequest.baseUrl, request, modes, authMemo);
         if (!trusted && credentials) {
             for (const source of accessPlan.readTargets) {
                 if (source === queryRequest.baseUrl) {
                     continue;
                 }
-                await this.authorizeIdentifier(source, credentials, [policy_engine_1.PERMISSIONS.Read]);
+                await this.authorizeIdentifier(source, credentials, [policy_engine_1.PERMISSIONS.Read], authMemo);
             }
             for (const [graph, graphModes] of accessPlan.writeTargets) {
                 const resourceUrl = this.resourceUrlForGraphValue(graph);
                 if (resourceUrl === queryRequest.baseUrl) {
                     continue;
                 }
-                await this.authorizeIdentifier(resourceUrl, credentials, [...graphModes]);
+                await this.authorizeIdentifier(resourceUrl, credentials, [...graphModes], authMemo);
             }
         }
         const readAccessScope = accessPlan.needsReadScope
             ? trusted
                 ? this.trustedReadAccessScope(queryRequest.baseUrl)
-                : await this.resolveReadAccessScopeForCredentials(queryRequest.baseUrl, credentials)
+                : await this.resolveReadAccessScopeForCredentials(queryRequest.baseUrl, credentials, authMemo)
             : undefined;
         const loadDocumentPlan = accessPlan.loadDocuments[0];
         const clearGraph = accessPlan.clearGraphs[0];
@@ -283,17 +310,24 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         const emitActivities = Boolean(this.emitter) && !emptyAuthorityLoad;
         // Existence has to be captured before the write because the activity term depends on it
         // (`Create` for a document the update brings into existence, `Update` otherwise).
-        const pendingActivities = emitActivities ? await this.resolvePendingActivities(accessPlan) : [];
-        if (!skippedSilentAuthorityLoad) {
-            if (this.updateAuthority) {
-                await this.updateAuthority.executeSparqlUpdate(rewritten, queryRequest.baseUrl, readAccessScope);
-            }
-            else {
-                await this.engine.queryVoid(rewritten, queryRequest.baseUrl, readAccessScope, nativeOptions);
+        const write = async () => {
+            const pendingActivities = emitActivities ? await this.resolvePendingActivities(accessPlan) : [];
+            if (!skippedSilentAuthorityLoad) {
+                if (this.updateAuthority) {
+                    await this.updateAuthority.executeSparqlUpdate(rewritten, queryRequest.baseUrl, readAccessScope);
+                }
+                else {
+                    await this.engine.queryVoid(rewritten, queryRequest.baseUrl, readAccessScope, nativeOptions);
+                }
+                // Only a successful write notifies; a throwing write skips this line entirely.
+                this.emitActivities(pendingActivities);
             }
-            // Only a successful write notifies; a throwing write skips this line entirely.
-            this.emitActivities(pendingActivities);
-        }
+        };
+        // ACL authorization can read through ResourceStore; complete it before taking non-reentrant write locks.
+        if (this.mutationStore)
+            await this.mutationStore.withMutationLocks({ path: queryRequest.baseUrl }, write);
+        else
+            await write();
         await this.refreshUsage(queryRequest.baseUrl);
         response.statusCode = 204;
         response.setHeader('Cache-Control', 'no-store');
@@ -497,22 +531,46 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         return Math.trunc(value);
     }
     async resolveReadAccessScope(baseUrl, request) {
-        const credentials = await this.authorizeFor(baseUrl, request, [policy_engine_1.PERMISSIONS.Read]);
-        return this.resolveReadAccessScopeForCredentials(baseUrl, credentials);
+        const memo = new Map();
+        const credentials = await this.authorizeFor(baseUrl, request, [policy_engine_1.PERMISSIONS.Read], memo);
+        return this.resolveReadAccessScopeForCredentials(baseUrl, credentials, memo);
     }
-    async resolveReadAccessScopeForCredentials(baseUrl, credentials) {
+    async resolveReadAccessScopeForCredentials(baseUrl, credentials, memo) {
+        const listStartedAt = Date.now();
         const graphs = await this.engine.listGraphs(baseUrl);
-        const deniedGraphUrls = [];
+        const listMs = Date.now() - listStartedAt;
+        // Credentials and ACLs are fixed within one request, so several graph IRIs that
+        // resolve to the same resource share one decision (metadata graphs use a scheme
+        // prefix that resourceUrlForGraphValue strips). Authorize each distinct resource
+        // once, then map the decision back to every graph that resolves to it.
+        const graphsByResource = new Map();
         for (const graph of graphs) {
             const resourceUrl = this.resourceUrlForGraphValue(graph);
             if (!resourceUrl.startsWith(baseUrl)) {
                 continue;
             }
-            const allowed = await this.canAuthorizeFor(resourceUrl, credentials, [policy_engine_1.PERMISSIONS.Read]);
-            if (!allowed) {
-                deniedGraphUrls.push(graph);
+            const mapped = graphsByResource.get(resourceUrl);
+            if (mapped) {
+                mapped.push(graph);
+            }
+            else {
+                graphsByResource.set(resourceUrl, [graph]);
             }
         }
+        const entries = [...graphsByResource.entries()];
+        // These authorizations are independent and latency-bound; run them concurrently (bounded)
+        // instead of serially so a room's graph count does not multiply each read's latency.
+        const authStartedAt = Date.now();
+        const allowed = await mapBounded(entries, GRAPH_AUTHORIZATION_CONCURRENCY, ([resourceUrl]) => this.canAuthorizeFor(resourceUrl, credentials, [policy_engine_1.PERMISSIONS.Read], memo));
+        // Existing debug logging only: lets an operator attribute a slow read to graph listing vs the
+        // authorization phase without any new config or caller parameter.
+        this.logger.debug(`Subgraph read access scope for ${baseUrl}: graphs=${graphs.size} checked=${entries.length} listMs=${listMs} checkMs=${Date.now() - authStartedAt}`);
+        const deniedGraphUrls = [];
+        entries.forEach(([, resourceGraphs], index) => {
+            if (!allowed[index]) {
+                deniedGraphUrls.push(...resourceGraphs);
+            }
+        });
         deniedGraphUrls.sort();
         return {
             basePath: baseUrl,
@@ -532,17 +590,17 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             version: `trusted-owner:${baseUrl}`,
         };
     }
-    async authorizeFor(basePath, request, modes) {
+    async authorizeFor(basePath, request, modes, memo) {
         if (modes.length === 0) {
             return this.credentialsExtractor.handleSafe(request);
         }
         const credentials = await this.credentialsExtractor.handleSafe(request);
-        await this.authorizeIdentifier(basePath, credentials, modes);
+        await this.authorizeIdentifier(basePath, credentials, modes, memo);
         return credentials;
     }
-    async canAuthorizeFor(basePath, credentials, modes) {
+    async canAuthorizeFor(basePath, credentials, modes, memo) {
         try {
-            await this.authorizeIdentifier(basePath, credentials, modes);
+            await this.authorizeIdentifier(basePath, credentials, modes, memo);
             return true;
         }
         catch (error) {
@@ -550,14 +608,30 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             return false;
         }
     }
-    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);
+    async authorizeIdentifier(basePath, credentials, modes, memo) {
+        const key = JSON.stringify([basePath, [...new Set(modes)].sort()]);
+        let pending = memo?.get(key);
+        if (!pending) {
+            pending = (async () => {
+                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 });
+            })();
+            memo?.set(key, pending);
+        }
+        try {
+            await pending;
+        }
+        catch (error) {
+            if (memo?.get(key) === pending) {
+                memo.delete(key);
+            }
+            throw error;
         }
-        const availablePermissions = await this.permissionReader.handleSafe({ credentials, requestedModes });
-        await this.authorizer.handleSafe({ credentials, requestedModes, availablePermissions });
     }
     inspectUpdateGraphs(update, basePath) {
         const plan = {

package/dist/http/SubgraphSparqlHttpHandler.jsonld

@@ -55,6 +55,18 @@
             ]
           }
         },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_mutationStore",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "undefineds:dist/storage/HierarchyLockingResourceStore.jsonld#HierarchyLockingResourceStore",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_options_containerSuffix",
           "range": {
@@ -133,6 +145,10 @@
         }
       ],
       "memberFields": [
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_mutationStore",
+          "memberFieldName": "mutationStore"
+        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_logger",
           "memberFieldName": "logger",
@@ -488,6 +504,9 @@
         },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_emitter"
+        },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_mutationStore"
         }
       ]
     }

package/dist/http/agent-directory/AgentDirectoryHttpHandler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+import { HttpHandler } from '@solid/community-server';
+import type { Authorizer, AuxiliaryStrategy, CredentialsExtractor, HttpHandlerInput, IdentifierStrategy, PermissionReader } from '@solid/community-server';
+import { MixDataAccessor } from '../../storage/accessors/MixDataAccessor';
+export interface AgentDirectoryHttpHandlerOptions {
+    /** Sidecar path segment, default `/-/agent-directory`. */
+    sidecarPath?: string;
+    /** Default page size for list/search. */
+    defaultLimit?: number;
+    /** Hard cap for a single resource read during search. */
+    maxFileBytes?: number;
+}
+export declare class AgentDirectoryHttpHandler extends HttpHandler {
+    protected readonly logger: import("global-logger-factory").Logger<unknown>;
+    private readonly accessor;
+    private readonly credentialsExtractor;
+    private readonly permissionReader;
+    private readonly authorizer;
+    private readonly auxiliaryStrategy;
+    private readonly identifierStrategy;
+    private readonly sidecarPath;
+    private readonly defaultLimit;
+    private readonly maxFileBytes;
+    constructor(accessor: MixDataAccessor, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, auxiliaryStrategy: AuxiliaryStrategy, identifierStrategy: IdentifierStrategy, options?: AgentDirectoryHttpHandlerOptions);
+    canHandle({ request }: HttpHandlerInput): Promise<void>;
+    handle({ request, response }: HttpHandlerInput): Promise<void>;
+    private handleList;
+    private handleSearch;
+    private handleRead;
+    private collectEntries;
+    private listAuthorizedChildren;
+    private isValidChild;
+    private decodeRelativePath;
+    private readSearchableText;
+    private tryReadLocalRdfDocument;
+    private isTextualContentType;
+    private readStreamLimited;
+    /**
+     * 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.
+     */
+    private findLiteralMatches;
+    private resolveRoot;
+    private parsePathPrefix;
+    private clampLimit;
+    private normalizeLimit;
+    private parseBoolean;
+    private decodeListCursor;
+    private decodeSearchCursor;
+    private encodeCursor;
+    private parseOperation;
+    private validateSameOriginUrl;
+    private authorizeIdentifier;
+    private canAuthorizeIdentifier;
+    private parseUrl;
+    private firstForwardedValue;
+    private sendJsonResponse;
+    private handleError;
+    private sendError;
+    private writeOptions;
+}