@undefineds.co/xpod 0.4.18 → 0.4.19

package/dist/api/handlers/readBoundedRequestBody.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBoundedRequestBody = readBoundedRequestBody;
+const MatrixError_1 = require("../matrix/MatrixError");
+/** Reject oversize bodies while draining the request, preserving its response socket. */
+function readBoundedRequestBody(request, maxBytes, message) {
+    return new Promise((resolve, reject) => {
+        const buffers = [];
+        let bytes = 0;
+        const cleanup = () => {
+            request.removeListener('data', onData);
+            request.removeListener('end', onEnd);
+            request.removeListener('error', onError);
+            request.removeListener('aborted', onAborted);
+        };
+        const onError = (error) => { cleanup(); reject(error); };
+        const onAborted = () => onError(new MatrixError_1.MatrixError(400, 'M_BAD_JSON', 'Request aborted'));
+        const onEnd = () => { cleanup(); resolve(buffers); };
+        const onData = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buffer.length;
+            if (bytes > maxBytes) {
+                // Drain without retaining the payload or destroying the response socket.
+                cleanup();
+                request.resume();
+                reject(new MatrixError_1.MatrixError(413, 'M_TOO_LARGE', message));
+                return;
+            }
+            buffers.push(buffer);
+        };
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('error', onError);
+        request.once('aborted', onAborted);
+    });
+}
+//# sourceMappingURL=readBoundedRequestBody.js.map

package/dist/api/matrix/MatrixError.d.ts

@@ -0,0 +1,6 @@
+/** A protocol error safe to expose to Matrix clients. Backend errors must remain private. */
+export declare class MatrixError extends Error {
+    readonly status: number;
+    readonly errcode: string;
+    constructor(status: number, errcode: string, message: string);
+}

package/dist/api/matrix/MatrixError.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatrixError = void 0;
+/** A protocol error safe to expose to Matrix clients. Backend errors must remain private. */
+class MatrixError extends Error {
+    constructor(status, errcode, message) {
+        super(message);
+        this.status = status;
+        this.errcode = errcode;
+        this.name = 'MatrixError';
+    }
+}
+exports.MatrixError = MatrixError;
+//# sourceMappingURL=MatrixError.js.map

package/dist/api/matrix/MatrixEventJournal.d.ts

@@ -0,0 +1,39 @@
+import { type IdentityDatabase } from '../../identity/drizzle/db';
+export interface MatrixTransactionReservation {
+    eventId: string;
+    createdAt: number;
+    contentHash: string;
+}
+/** Operational references only: event bodies and room state remain authoritative in the Pod. */
+export interface MatrixEventJournal {
+    reserveTransaction(scope: string, key: string, candidate: MatrixTransactionReservation): Promise<MatrixTransactionReservation>;
+    registerEvent(scope: string, roomId: string, eventId: string): Promise<number>;
+    getHighWatermark(scope: string): Promise<number>;
+    findReservation(scope: string, eventId: string): Promise<MatrixTransactionReservation | undefined>;
+}
+/** Isolated tests only. Production cursors and reservations must survive process restarts. */
+export declare class InMemoryMatrixEventJournal implements MatrixEventJournal {
+    private readonly transactions;
+    private readonly events;
+    private readonly highWatermarks;
+    private sequence;
+    reserveTransaction(scope: string, key: string, candidate: MatrixTransactionReservation): Promise<MatrixTransactionReservation>;
+    findReservation(scope: string, eventId: string): Promise<MatrixTransactionReservation | undefined>;
+    registerEvent(scope: string, roomId: string, eventId: string): Promise<number>;
+    getHighWatermark(scope: string): Promise<number>;
+}
+export declare class SqlMatrixEventJournal implements MatrixEventJournal {
+    private readonly db;
+    private initialization?;
+    constructor(db: IdentityDatabase);
+    reserveTransaction(scope: string, key: string, candidate: MatrixTransactionReservation): Promise<MatrixTransactionReservation>;
+    findReservation(scope: string, eventId: string): Promise<MatrixTransactionReservation | undefined>;
+    registerEvent(scope: string, roomId: string, eventId: string): Promise<number>;
+    getHighWatermark(scope: string): Promise<number>;
+    private insertEvent;
+    private findEventSequence;
+    private toSequence;
+    private ensureInitialized;
+    private initialize;
+    private createTables;
+}

package/dist/api/matrix/MatrixEventJournal.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlMatrixEventJournal = exports.InMemoryMatrixEventJournal = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const db_1 = require("../../identity/drizzle/db");
+/** Isolated tests only. Production cursors and reservations must survive process restarts. */
+class InMemoryMatrixEventJournal {
+    constructor() {
+        this.transactions = new Map();
+        this.events = new Map();
+        this.highWatermarks = new Map();
+        this.sequence = 0;
+    }
+    async reserveTransaction(scope, key, candidate) {
+        const identity = JSON.stringify([scope, key]);
+        const reservation = this.transactions.get(identity) ?? { ...candidate };
+        this.transactions.set(identity, reservation);
+        return { ...reservation };
+    }
+    async findReservation(scope, eventId) {
+        for (const [key, value] of this.transactions)
+            if (JSON.parse(key)[0] === scope && value.eventId === eventId)
+                return { ...value };
+        return undefined;
+    }
+    async registerEvent(scope, roomId, eventId) {
+        const identity = JSON.stringify([scope, roomId, eventId]);
+        const existing = this.events.get(identity);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const sequence = ++this.sequence;
+        this.events.set(identity, sequence);
+        this.highWatermarks.set(scope, sequence);
+        return sequence;
+    }
+    async getHighWatermark(scope) {
+        return this.highWatermarks.get(scope) ?? 0;
+    }
+}
+exports.InMemoryMatrixEventJournal = InMemoryMatrixEventJournal;
+class SqlMatrixEventJournal {
+    constructor(db) {
+        this.db = db;
+    }
+    async reserveTransaction(scope, key, candidate) {
+        await this.ensureInitialized();
+        await (0, db_1.executeStatement)(this.db, (0, drizzle_orm_1.sql) `
+      INSERT INTO xpod_matrix_transactions (scope, transaction_key, event_id, created_at, content_hash)
+      VALUES (${scope}, ${key}, ${candidate.eventId}, ${candidate.createdAt}, ${candidate.contentHash})
+      ON CONFLICT (scope, transaction_key) DO NOTHING
+    `);
+        const result = await (0, db_1.executeQuery)(this.db, (0, drizzle_orm_1.sql) `
+      SELECT event_id, created_at, content_hash FROM xpod_matrix_transactions
+      WHERE scope = ${scope} AND transaction_key = ${key}
+    `);
+        const row = result.rows[0];
+        if (!row) {
+            throw new Error('Matrix transaction reservation disappeared');
+        }
+        return { eventId: row.event_id, createdAt: Number(row.created_at), contentHash: row.content_hash };
+    }
+    async findReservation(scope, eventId) {
+        await this.ensureInitialized();
+        const result = await (0, db_1.executeQuery)(this.db, (0, drizzle_orm_1.sql) `
+      SELECT event_id,created_at,content_hash FROM xpod_matrix_transactions WHERE scope=${scope} AND event_id=${eventId}
+    `);
+        const row = result.rows[0];
+        return row ? { eventId: row.event_id, createdAt: Number(row.created_at), contentHash: row.content_hash } : undefined;
+    }
+    async registerEvent(scope, roomId, eventId) {
+        await this.ensureInitialized();
+        // Registered references are immutable. A committed hit needs no write lock;
+        // concurrent misses still converge through the unique constraint below.
+        const existing = await this.findEventSequence(this.db, scope, roomId, eventId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        if ((0, db_1.isDatabaseSqlite)(this.db)) {
+            return this.insertEvent(this.db, scope, roomId, eventId);
+        }
+        // BIGSERIAL allocation alone is insufficient: a later sequence could commit first,
+        // allowing readers to advance past an uncommitted event. Serialize writers until commit.
+        return this.db.transaction(async (transaction) => {
+            await (0, db_1.executeStatement)(transaction, (0, drizzle_orm_1.sql) `LOCK TABLE xpod_matrix_events IN SHARE ROW EXCLUSIVE MODE`);
+            return this.insertEvent(transaction, scope, roomId, eventId);
+        });
+    }
+    async getHighWatermark(scope) {
+        await this.ensureInitialized();
+        const result = await (0, db_1.executeQuery)(this.db, (0, drizzle_orm_1.sql) `
+      SELECT COALESCE(MAX(sequence), 0) AS sequence FROM xpod_matrix_events WHERE scope = ${scope}
+    `);
+        return this.toSequence(result.rows[0]?.sequence ?? 0);
+    }
+    async insertEvent(db, scope, roomId, eventId) {
+        await (0, db_1.executeStatement)(db, (0, drizzle_orm_1.sql) `
+      INSERT INTO xpod_matrix_events (scope, room_id, event_id) VALUES (${scope}, ${roomId}, ${eventId})
+      ON CONFLICT (scope, room_id, event_id) DO NOTHING
+    `);
+        const sequence = await this.findEventSequence(db, scope, roomId, eventId);
+        if (sequence === undefined) {
+            throw new Error('Matrix event registration disappeared');
+        }
+        return sequence;
+    }
+    async findEventSequence(db, scope, roomId, eventId) {
+        const result = await (0, db_1.executeQuery)(db, (0, drizzle_orm_1.sql) `
+      SELECT sequence FROM xpod_matrix_events WHERE scope = ${scope} AND room_id = ${roomId} AND event_id = ${eventId}
+    `);
+        return result.rows[0] ? this.toSequence(result.rows[0].sequence) : undefined;
+    }
+    toSequence(value) {
+        const sequence = Number(value);
+        if (!Number.isSafeInteger(sequence) || sequence < 0) {
+            throw new Error('Matrix event sequence exceeds the supported cursor range');
+        }
+        return sequence;
+    }
+    ensureInitialized() {
+        if (!this.initialization) {
+            this.initialization = this.initialize().catch((error) => {
+                this.initialization = undefined;
+                throw error;
+            });
+        }
+        return this.initialization;
+    }
+    async initialize() {
+        if ((0, db_1.isDatabaseSqlite)(this.db)) {
+            await this.createTables(this.db);
+            return;
+        }
+        // Honor the shared identity database's readiness before opening a transaction.
+        await (0, db_1.executeQuery)(this.db, (0, drizzle_orm_1.sql) `SELECT 1`);
+        await this.db.transaction(async (transaction) => {
+            // IF NOT EXISTS alone races on PostgreSQL catalog types during cold starts.
+            await (0, db_1.executeQuery)(transaction, (0, drizzle_orm_1.sql) `SELECT pg_advisory_xact_lock(hashtext('xpod_matrix_journal_schema'))`);
+            await this.createTables(transaction);
+        });
+    }
+    async createTables(db) {
+        await (0, db_1.executeStatement)(db, (0, drizzle_orm_1.sql) `
+      CREATE TABLE IF NOT EXISTS xpod_matrix_transactions (
+        scope TEXT NOT NULL,
+        transaction_key TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        created_at BIGINT NOT NULL,
+        content_hash TEXT NOT NULL,
+        PRIMARY KEY (scope, transaction_key)
+      )
+    `);
+        await (0, db_1.executeStatement)(db, (0, drizzle_orm_1.sql) `CREATE INDEX IF NOT EXISTS xpod_matrix_transaction_event ON xpod_matrix_transactions (scope, event_id)`);
+        const sequenceType = (0, db_1.isDatabaseSqlite)(db)
+            ? drizzle_orm_1.sql.raw('INTEGER PRIMARY KEY AUTOINCREMENT')
+            : drizzle_orm_1.sql.raw('BIGSERIAL PRIMARY KEY');
+        await (0, db_1.executeStatement)(db, (0, drizzle_orm_1.sql) `
+      CREATE TABLE IF NOT EXISTS xpod_matrix_events (
+        sequence ${sequenceType},
+        scope TEXT NOT NULL,
+        room_id TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        UNIQUE (scope, room_id, event_id)
+      )
+    `);
+    }
+}
+exports.SqlMatrixEventJournal = SqlMatrixEventJournal;
+//# sourceMappingURL=MatrixEventJournal.js.map

package/dist/api/matrix/MatrixPodResolver.d.ts

@@ -0,0 +1,12 @@
+import type { PodLookupRepository } from '../../identity/drizzle/PodLookupRepository';
+import type { AuthenticatedRequest } from '../middleware/AuthMiddleware';
+import type { MatrixStoreContext } from './types';
+export type MatrixPodResolver = (webId: string, requestedPodUrl?: string) => Promise<string>;
+/**
+ * Select only registered Pod roots, without dereferencing user-supplied URLs.
+ * Selection is not access authorization: shared Pod requests retain the caller's
+ * credentials, and membership plus Solid ACL checks enforce their access.
+ */
+export declare function createMatrixPodResolver(repository: Pick<PodLookupRepository, 'findAllByWebId' | 'findByResourceIdentifier'>): MatrixPodResolver;
+/** Preserve the authenticated caller; never borrow the selected Pod owner's credentials. */
+export declare function resolveMatrixContext(request: AuthenticatedRequest, resolver: MatrixPodResolver): Promise<MatrixStoreContext>;

package/dist/api/matrix/MatrixPodResolver.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMatrixPodResolver = createMatrixPodResolver;
+exports.resolveMatrixContext = resolveMatrixContext;
+const AuthContext_1 = require("../auth/AuthContext");
+const MatrixError_1 = require("./MatrixError");
+/**
+ * Select only registered Pod roots, without dereferencing user-supplied URLs.
+ * Selection is not access authorization: shared Pod requests retain the caller's
+ * credentials, and membership plus Solid ACL checks enforce their access.
+ */
+function createMatrixPodResolver(repository) {
+    return async (webId, requestedPodUrl) => {
+        if (requestedPodUrl === undefined) {
+            const pods = await repository.findAllByWebId(webId);
+            if (pods.length === 0) {
+                throw new MatrixError_1.MatrixError(404, 'M_NOT_FOUND', 'No Pod is registered for this WebID');
+            }
+            if (pods.length !== 1) {
+                throw new MatrixError_1.MatrixError(400, 'M_INVALID_PARAM', 'Multiple Pods are registered; select one with X-Xpod-Pod-Url');
+            }
+            return normalizeRoot(pods[0].baseUrl);
+        }
+        const requested = normalizeRoot(requestedPodUrl);
+        const pod = await repository.findByResourceIdentifier(requested);
+        if (!pod || ![pod.baseUrl, pod.storageUrl].some(root => root !== undefined && normalizeRoot(root) === requested)) {
+            throw new MatrixError_1.MatrixError(403, 'M_FORBIDDEN', 'Selected URL is not a registered Pod root');
+        }
+        return normalizeRoot(pod.baseUrl);
+    };
+}
+/** Preserve the authenticated caller; never borrow the selected Pod owner's credentials. */
+async function resolveMatrixContext(request, resolver) {
+    const auth = request.auth;
+    const webId = auth ? (0, AuthContext_1.getWebId)(auth) : undefined;
+    if (!webId) {
+        throw new MatrixError_1.MatrixError(401, 'M_UNAUTHORIZED', 'Matrix API requires Solid WebID authentication');
+    }
+    const selection = request.headers['x-xpod-pod-url'];
+    if (Array.isArray(selection)) {
+        throw new MatrixError_1.MatrixError(400, 'M_INVALID_PARAM', 'Provide exactly one X-Xpod-Pod-Url');
+    }
+    return { webId, auth, podUrl: await resolver(webId, selection) };
+}
+function normalizeRoot(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new MatrixError_1.MatrixError(400, 'M_INVALID_PARAM', 'Pod URL must be an absolute HTTP(S) URL');
+    }
+    if (!/^https?:\/\//i.test(value) || value !== value.trim() || /[\s\\?#]/u.test(value) ||
+        !['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+        throw new MatrixError_1.MatrixError(400, 'M_INVALID_PARAM', 'Pod URL must be HTTP(S) without credentials, query, or fragment');
+    }
+    if (!parsed.pathname.endsWith('/'))
+        parsed.pathname += '/';
+    return parsed.toString();
+}
+//# sourceMappingURL=MatrixPodResolver.js.map

package/dist/api/matrix/PodMatrixStore.d.ts

@@ -1,10 +1,24 @@
 import { type ServerGroupReconcilerService } from '../reconciler';
+import { type MatrixEventJournal } from './MatrixEventJournal';
+import type { PodAccessFetchProvider } from '../ai-gateway/pod/OwnerPodAccess';
+import type { SharedWakeAgentJob } from '../reconciler/coordination';
 import type { MatrixAccountInfo, MatrixClientEvent, MatrixCreateRoomRequest, MatrixEventRecord, MatrixRoomRecord, MatrixSendEventRequest, MatrixStoreContext, MatrixSyncResponse } from './types';
 export interface PodMatrixStoreOptions {
+    podAccess?: PodAccessFetchProvider;
+    journal?: MatrixEventJournal;
     serverName?: string;
     serverGroupReconcilerService?: ServerGroupReconcilerService;
 }
+export interface MatrixAgentGrant {
+    agent: string;
+    executor: string;
+    workspace: string;
+    allowedActors: string[];
+    handoffTo: string[];
+}
 export declare class PodMatrixStore {
+    private readonly podAccess?;
+    private readonly journal;
     private readonly logger;
     private readonly serverName?;
     private readonly serverGroupReconcilerService?;
@@ -21,7 +35,10 @@ export declare class PodMatrixStore {
     sync(context: MatrixStoreContext, options?: {
         since?: string;
         limit?: number;
+        timeout?: number;
+        signal?: AbortSignal;
     }): Promise<MatrixSyncResponse>;
+    private syncOnce;
     listJoinedRooms(context: MatrixStoreContext): Promise<string[]>;
     getMembers(roomId: string, context: MatrixStoreContext): Promise<MatrixClientEvent[]>;
     listMessages(roomId: string, context: MatrixStoreContext, options?: {
@@ -36,21 +53,57 @@ export declare class PodMatrixStore {
     getEvent(roomId: string, eventId: string, context: MatrixStoreContext): Promise<MatrixClientEvent>;
     getState(roomId: string, eventType: string, stateKey: string, context: MatrixStoreContext): Promise<Record<string, unknown>>;
     private getDb;
-    private createAccessTokenFetch;
-    private ensureRoomExists;
     private appendEvent;
     private appendMembershipEvent;
     private listRooms;
     private listJoinedRoomRecords;
     private resolveRoomId;
     private listEvents;
-    private findEventByTxnId;
     private findEventById;
-    private nextEventDepth;
     private findLatestStateEvent;
     private eventSourceToRecord;
     private chatSourceToRoomRecord;
     private toClientEvent;
+    private scope;
+    private hash;
+    private canonicalJson;
+    private chatIri;
+    private threadIri;
+    private roomSource;
+    private requireRoomOwner;
+    private requireJoined;
+    private latestState;
+    private validateAgentGrants;
+    private agentGrants;
+    private authorizeTargets;
+    private reconcileEvent;
+    /** Runtime principals must have both Pod access and an explicit room execution grant. */
+    authorize(roomId: string, agent: string, context: MatrixStoreContext): Promise<{
+        thread: string;
+    }>;
+    /** Rebuild operational work from Pod facts after an interrupted write or queue restart. */
+    recover(roomId: string, context: MatrixStoreContext): Promise<void>;
+    loadInput(roomId: string, job: SharedWakeAgentJob, context: MatrixStoreContext): Promise<{
+        content: string;
+        [key: string]: unknown;
+    }>;
+    commitResult(roomId: string, job: SharedWakeAgentJob, result: {
+        body: string;
+        handoffTo?: string;
+        evidence?: string[];
+    }, context: MatrixStoreContext): Promise<{
+        eventId: string;
+        run: string;
+    }>;
+    private validateTrigger;
+    recordFailure(roomId: string, job: SharedWakeAgentJob, failure: {
+        error?: string;
+        retry: boolean;
+    }, context: MatrixStoreContext): Promise<void>;
+    private runAttempts;
+    private reconcileHandoff;
+    private ensureDelivery;
+    private materializeRun;
     private parseJsonObject;
     private stringValue;
     private numberValue;
@@ -62,22 +115,15 @@ export declare class PodMatrixStore {
     private routeTargetAgentFromMatrixContent;
     private getMatrixUserId;
     private getServerName;
-    private localpartFromUserId;
     private displayNameFromUserId;
     private generateRoomId;
     private generateEventId;
-    private deviceIdFromUserId;
+    private deviceId;
     private randomId;
-    private slug;
     private surfaceIdFromRoomId;
     private chatResourceIdFromRoomId;
-    private messageParentResourceIdFromRoomId;
     private threadResourceIdFromRoomId;
-    private chatParentRefFromRoomId;
     private messageResourceIdFromEvent;
-    private resolveDataResourceUriFromId;
-    private derivePodBaseUrl;
-    private dateParts;
     private isoToMillis;
     private encodeSyncToken;
     private parseSyncToken;