@decentrl/event-store 0.0.1

package/src/event-store.ts

@@ -0,0 +1,574 @@
+import {
+	base64Decode,
+	decryptString,
+	encryptString,
+	generateEncryptedTag,
+	multibaseDecode,
+	signJsonObject,
+	verifyJsonSignature,
+} from '@decentrl/crypto';
+import type { AcknowledgePendingEventsMediatorCommandResponse } from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/acknowledge-pending-events.schema';
+import {
+	generateDirectAuthenticatedMediatorCommand,
+	generateTwoWayPrivateMediatorCommand,
+} from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/command.service';
+import type { QueryEventsMediatorCommandResponse } from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/query-events.schema';
+import type { QueryPendingEventsMediatorCommandResponse } from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/query-pending-events.schema';
+import type { SaveEventsMediatorCommandResponse } from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/save-events.schema';
+import type { UpdateEventTagsMediatorCommandResponse } from '@decentrl/identity/communication-channels/mediator/direct-authenticated/command/update-event-tags.schema';
+import axiosModule from 'axios';
+import {
+	type EventStoreConfig,
+	EventStoreError,
+	type PaginatedResult,
+	type PublishOptions,
+	type QueryOptions,
+} from './types';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const axios = {
+	post: <T>(url: string, data: unknown) =>
+		axiosModule.post<T>(url, data, { timeout: DEFAULT_TIMEOUT_MS }),
+};
+
+export class DecentrlEventStore {
+	constructor(private config: EventStoreConfig) {}
+
+	/**
+	 * Publish an event - stores locally and optionally sends to recipient
+	 */
+	async publishEvent<T>(event: T, options: PublishOptions): Promise<void> {
+		try {
+			// 1. Handle recipient delivery (if specified)
+			if (options.recipient) {
+				await this.sendToRecipient(event, options.recipient);
+			}
+
+			// 2. Store locally for own queries (skip for ephemeral events)
+			if (!options.ephemeral) {
+				await this.storeLocally(event, options.tags, options.recipient);
+			}
+		} catch (error) {
+			throw new EventStoreError(
+				`Failed to publish event: ${error instanceof Error ? error.message : String(error)}`,
+				'PUBLISH_FAILED',
+				{ event, options, error },
+			);
+		}
+	}
+
+	/**
+	 * Query stored events from mediator
+	 */
+	async queryEvents<T>(options: QueryOptions = {}): Promise<PaginatedResult<T>> {
+		try {
+			const { identity } = this.config;
+			const identityKeys = identity.keys;
+
+			const encryptedTags = options.tags?.map((tag) =>
+				generateEncryptedTag(identityKeys.signing.privateKey, tag),
+			);
+
+			const page = options.pagination?.page ?? 0;
+			const pageSize = options.pagination?.pageSize ?? 100;
+
+			const queryCommand = generateDirectAuthenticatedMediatorCommand(
+				identity.did,
+				`${identity.did}#signing`,
+				identity.mediatorDid,
+				{
+					type: 'QUERY_EVENTS',
+					filter: {
+						encrypted_tags: encryptedTags,
+						participant_did: options.participantDid,
+						after_timestamp: options.afterTimestamp,
+						before_timestamp: options.beforeTimestamp,
+						unprocessed_only: options.unprocessedOnly,
+					},
+					pagination: { page, page_size: pageSize },
+				},
+				identityKeys,
+			);
+
+			const response = await axios.post<QueryEventsMediatorCommandResponse>(
+				identity.mediatorEndpoint,
+				queryCommand,
+			);
+
+			if (response.data.type !== 'SUCCESS') {
+				throw new EventStoreError('Query failed', 'QUERY_FAILED', response.data);
+			}
+
+			const storageKey = identityKeys.storageKey;
+
+			const data: T[] = [];
+
+			for (const event of response.data.payload.events) {
+				try {
+					const decrypted = decryptString(event.payload, storageKey);
+					data.push(JSON.parse(decrypted) as T);
+				} catch (error) {
+					console.warn(
+						`[EventStore] Decryption failure for event: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+
+			return {
+				data,
+				pagination: {
+					page: response.data.payload.pagination.page,
+					pageSize: response.data.payload.pagination.page_size,
+					total: response.data.payload.pagination.total,
+				},
+			};
+		} catch (error) {
+			if (error instanceof EventStoreError) {
+				throw error;
+			}
+
+			throw new EventStoreError(
+				`Failed to query events: ${error instanceof Error ? error.message : String(error)}`,
+				'QUERY_FAILED',
+				{ options, error },
+			);
+		}
+	}
+
+	/**
+	 * Process pending events from other participants
+	 */
+	async processPendingEvents<T>(): Promise<T[]> {
+		try {
+			const { identity, communicationContracts } = this.config;
+			const activeContracts = communicationContracts();
+
+			if (activeContracts.length === 0) {
+				return [];
+			}
+
+			// Query pending events
+			const queryCommand = generateDirectAuthenticatedMediatorCommand(
+				identity.did,
+				`${identity.did}#signing`,
+				identity.mediatorDid,
+				{
+					type: 'QUERY_PENDING_EVENTS',
+					filter: {},
+					pagination: { page: 0, page_size: 100 },
+				},
+				identity.keys,
+			);
+
+			const response = await axios.post<QueryPendingEventsMediatorCommandResponse>(
+				identity.mediatorEndpoint,
+				queryCommand,
+			);
+
+			if (response.data.type !== 'SUCCESS') {
+				throw new EventStoreError(
+					'Failed to query pending events',
+					'PENDING_QUERY_FAILED',
+					response.data,
+				);
+			}
+
+			return await this.decryptStoreAndAck<T>(response.data.payload.pending_events);
+		} catch (error) {
+			if (error instanceof EventStoreError) {
+				throw error;
+			}
+
+			throw new EventStoreError(
+				`Failed to process pending events: ${error instanceof Error ? error.message : String(error)}`,
+				'PENDING_PROCESS_FAILED',
+				{ error },
+			);
+		}
+	}
+
+	/**
+	 * Process pre-fetched pending events (e.g. from WebSocket push).
+	 * Same logic as processPendingEvents but skips the HTTP query.
+	 */
+	async processPreFetchedPendingEvents<T>(
+		rawEvents: Array<{ id: string; sender_did: string; payload: string }>,
+	): Promise<T[]> {
+		try {
+			return await this.decryptStoreAndAck<T>(rawEvents);
+		} catch (error) {
+			if (error instanceof EventStoreError) {
+				throw error;
+			}
+
+			throw new EventStoreError(
+				`Failed to process pre-fetched pending events: ${error instanceof Error ? error.message : String(error)}`,
+				'PENDING_PROCESS_FAILED',
+				{ error },
+			);
+		}
+	}
+
+	/**
+	 * Update event tags on the mediator (idempotent replace).
+	 */
+	async updateEventTags(
+		events: Array<{ eventId: string; encryptedTags: string[] }>,
+	): Promise<void> {
+		const { identity } = this.config;
+
+		const command = generateDirectAuthenticatedMediatorCommand(
+			identity.did,
+			`${identity.did}#signing`,
+			identity.mediatorDid,
+			{
+				type: 'UPDATE_EVENT_TAGS',
+				events: events.map((e) => ({
+					event_id: e.eventId,
+					encrypted_tags: e.encryptedTags,
+				})),
+			},
+			identity.keys,
+		);
+
+		await axios.post<UpdateEventTagsMediatorCommandResponse>(identity.mediatorEndpoint, command);
+	}
+
+	/**
+	 * Query events that haven't been processed by the app yet.
+	 * Returns mediator event IDs alongside decrypted data for tag updates.
+	 */
+	async queryUnprocessedEvents<T>(pagination?: {
+		page: number;
+		pageSize: number;
+	}): Promise<PaginatedResult<T & { _mediatorEventId?: string }>> {
+		try {
+			const { identity } = this.config;
+			const identityKeys = identity.keys;
+
+			const page = pagination?.page ?? 0;
+			const pageSize = pagination?.pageSize ?? 100;
+
+			const queryCommand = generateDirectAuthenticatedMediatorCommand(
+				identity.did,
+				`${identity.did}#signing`,
+				identity.mediatorDid,
+				{
+					type: 'QUERY_EVENTS',
+					filter: { unprocessed_only: true },
+					pagination: { page, page_size: pageSize },
+				},
+				identityKeys,
+			);
+
+			const response = await axios.post<QueryEventsMediatorCommandResponse>(
+				identity.mediatorEndpoint,
+				queryCommand,
+			);
+
+			if (response.data.type !== 'SUCCESS') {
+				throw new EventStoreError('Query failed', 'QUERY_FAILED', response.data);
+			}
+
+			const storageKey = identityKeys.storageKey;
+			const data: (T & { _mediatorEventId?: string })[] = [];
+
+			for (const event of response.data.payload.events) {
+				try {
+					const decrypted = decryptString(event.payload, storageKey);
+					const parsed = JSON.parse(decrypted) as T & { _mediatorEventId?: string };
+					parsed._mediatorEventId = event.id;
+					data.push(parsed);
+				} catch (error) {
+					console.warn(
+						`[EventStore] Decryption failure for event: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+
+			return {
+				data,
+				pagination: {
+					page: response.data.payload.pagination.page,
+					pageSize: response.data.payload.pagination.page_size,
+					total: response.data.payload.pagination.total,
+				},
+			};
+		} catch (error) {
+			if (error instanceof EventStoreError) {
+				throw error;
+			}
+
+			throw new EventStoreError(
+				`Failed to query unprocessed events: ${error instanceof Error ? error.message : String(error)}`,
+				'QUERY_FAILED',
+				{ error },
+			);
+		}
+	}
+
+	/**
+	 * Shared logic: filter by known senders, decrypt, store locally, acknowledge.
+	 */
+	private async decryptStoreAndAck<T>(
+		pendingEvents: Array<{ id: string; sender_did: string; payload: string }>,
+	): Promise<T[]> {
+		const { communicationContracts } = this.config;
+		const activeContracts = communicationContracts();
+
+		if (activeContracts.length === 0) {
+			return [];
+		}
+
+		const knownSenders = new Set(activeContracts.map((c) => c.participantDid));
+		const filtered = pendingEvents.filter((event) => knownSenders.has(event.sender_did));
+
+		const processedEvents: T[] = [];
+		const ackEventIds: string[] = [];
+
+		for (const pendingEvent of filtered) {
+			try {
+				const matchingContracts = activeContracts
+					.filter((c) => c.participantDid === pendingEvent.sender_did && c.rootSecret)
+					.sort(
+						(a, b) =>
+							b.signedCommunicationContract.communication_contract.expires_at -
+							a.signedCommunicationContract.communication_contract.expires_at,
+					);
+
+				let decrypted: string | null = null;
+				let contract: (typeof matchingContracts)[number] | null = null;
+
+				for (const candidate of matchingContracts) {
+					try {
+						decrypted = decryptString(pendingEvent.payload, base64Decode(candidate.rootSecret));
+						contract = candidate;
+						break;
+					} catch {}
+				}
+
+				if (!decrypted || !contract) {
+					console.warn(`[EventStore] No contract could decrypt event ${pendingEvent.id}`);
+					continue;
+				}
+
+				this.config.onContractUsed?.(contract.id, pendingEvent.sender_did);
+
+				const envelope = JSON.parse(decrypted);
+
+				const senderSigningKey = extractSigningKeyFromDid(pendingEvent.sender_did);
+
+				if (senderSigningKey && envelope.signature) {
+					const { signature, ...envelopeData } = envelope;
+					const isValid = verifyJsonSignature(envelopeData, signature, senderSigningKey);
+
+					if (!isValid) {
+						console.warn(`Invalid signature on event ${pendingEvent.id}, skipping`);
+						continue;
+					}
+				}
+
+				const event = JSON.parse(envelope.event) as T;
+
+				if (!(event as any)?.meta?.ephemeral) {
+					await this.storeReceivedEvent(event, pendingEvent.sender_did, contract.id);
+				}
+
+				processedEvents.push(event);
+				ackEventIds.push(pendingEvent.id);
+			} catch (error) {
+				console.warn(`Failed to process pending event ${pendingEvent.id}:`, error);
+			}
+		}
+
+		if (ackEventIds.length > 0) {
+			await this.acknowledgePendingEvents(ackEventIds);
+		}
+
+		return processedEvents;
+	}
+
+	/**
+	 * Send event to recipient via two-way private channel
+	 */
+	private async sendToRecipient<T>(event: T, recipientDid: string): Promise<void> {
+		const { identity, communicationContracts } = this.config;
+
+		const contract = communicationContracts()
+			.filter(
+				(c) => c.participantDid === recipientDid && c.rootSecret && c.signedCommunicationContract,
+			)
+			.sort(
+				(a, b) =>
+					b.signedCommunicationContract.communication_contract.expires_at -
+					a.signedCommunicationContract.communication_contract.expires_at,
+			)[0];
+
+		if (!contract) {
+			throw new EventStoreError(
+				`No communication contract found with ${recipientDid}`,
+				'CONTRACT_NOT_FOUND',
+				{ recipientDid },
+			);
+		}
+
+		const rootSecret = base64Decode(contract.rootSecret);
+		const timestamp = Math.floor(Date.now() / 1000);
+
+		const envelopeData = {
+			contract_id: contract.id,
+			event: JSON.stringify(event),
+			timestamp,
+		};
+
+		const signature = signJsonObject(envelopeData, identity.keys.signing.privateKey);
+
+		const envelope = {
+			...envelopeData,
+			signature,
+		};
+
+		const encryptedPayload = encryptString(JSON.stringify(envelope), rootSecret);
+
+		const twoWayPrivateCommand = generateTwoWayPrivateMediatorCommand(
+			identity.did,
+			`${identity.did}#signing`,
+			recipientDid,
+			encryptedPayload,
+			identity.keys,
+		);
+
+		await axios.post(identity.mediatorEndpoint, twoWayPrivateCommand);
+	}
+
+	/**
+	 * Store event locally with encrypted tags
+	 */
+	private async storeLocally<T>(event: T, tags: string[], recipientDid?: string): Promise<void> {
+		const { identity, communicationContracts } = this.config;
+
+		const storageKey = identity.keys.storageKey;
+		const encryptedEventForSelf = encryptString(JSON.stringify(event), storageKey);
+
+		const encryptedTags = tags.map((tag) =>
+			generateEncryptedTag(identity.keys.signing.privateKey, tag),
+		);
+
+		let contractId: string | undefined;
+
+		if (recipientDid) {
+			const contract = communicationContracts().find((c) => c.participantDid === recipientDid);
+			contractId = contract?.id;
+		}
+
+		const saveEventCommand = generateDirectAuthenticatedMediatorCommand(
+			identity.did,
+			`${identity.did}#signing`,
+			identity.mediatorDid,
+			{
+				type: 'SAVE_EVENTS',
+				events: [
+					{
+						sender_did: identity.did,
+						recipient_did: recipientDid || identity.did,
+						contract_id: contractId,
+						payload: encryptedEventForSelf,
+						timestamp: Math.floor(Date.now() / 1000),
+						encrypted_tags: encryptedTags,
+					},
+				],
+			},
+			identity.keys,
+		);
+
+		await axios.post<SaveEventsMediatorCommandResponse>(
+			identity.mediatorEndpoint,
+			saveEventCommand,
+		);
+	}
+
+	/**
+	 * Store received event with appropriate tags
+	 */
+	private async storeReceivedEvent<T>(
+		event: T,
+		senderDid: string,
+		contractId?: string,
+	): Promise<void> {
+		const { identity } = this.config;
+
+		const storageKey = identity.keys.storageKey;
+		const encryptedEventForSelf = encryptString(JSON.stringify(event), storageKey);
+
+		const participantTag = generateEncryptedTag(
+			identity.keys.signing.privateKey,
+			`participant.${senderDid}`,
+		);
+
+		const saveEventCommand = generateDirectAuthenticatedMediatorCommand(
+			identity.did,
+			`${identity.did}#signing`,
+			identity.mediatorDid,
+			{
+				type: 'SAVE_EVENTS',
+				events: [
+					{
+						sender_did: senderDid,
+						recipient_did: identity.did,
+						contract_id: contractId,
+						payload: encryptedEventForSelf,
+						timestamp: Math.floor(Date.now() / 1000),
+						encrypted_tags: [participantTag],
+					},
+				],
+			},
+			identity.keys,
+		);
+
+		await axios.post<SaveEventsMediatorCommandResponse>(
+			identity.mediatorEndpoint,
+			saveEventCommand,
+		);
+	}
+
+	/**
+	 * Acknowledge processed pending events
+	 */
+	private async acknowledgePendingEvents(eventIds: string[]): Promise<void> {
+		const { identity } = this.config;
+
+		const ackCommand = generateDirectAuthenticatedMediatorCommand(
+			identity.did,
+			`${identity.did}#signing`,
+			identity.mediatorDid,
+			{
+				type: 'ACKNOWLEDGE_PENDING_EVENTS',
+				event_ids: eventIds,
+			},
+			identity.keys,
+		);
+
+		await axios.post<AcknowledgePendingEventsMediatorCommandResponse>(
+			identity.mediatorEndpoint,
+			ackCommand,
+		);
+	}
+}
+
+const extractSigningKeyFromDid = (did: string): Uint8Array | null => {
+	if (!did.startsWith('did:decentrl:')) {
+		return null;
+	}
+
+	const parts = did.replace('did:decentrl:', '').split(':');
+
+	if (parts.length !== 4) {
+		return null;
+	}
+
+	try {
+		return multibaseDecode(parts[1]);
+	} catch {
+		return null;
+	}
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export { DecentrlEventStore } from './event-store';
+export type {
+	EventStoreConfig,
+	PaginatedResult,
+	PaginationMeta,
+	PublishOptions,
+	QueryOptions,
+	StoredSignedContract,
+} from './types';
+export { EventStoreError } from './types';

package/src/types.ts

@@ -0,0 +1,61 @@
+import type { DecentrlIdentityKeys } from '@decentrl/crypto';
+import type { SignedCommunicationContract } from '@decentrl/identity/communication-contract/communication-contract.schema';
+
+export interface EventStoreConfig {
+	identity: {
+		did: string;
+		keys: DecentrlIdentityKeys;
+		mediatorEndpoint: string;
+		mediatorDid: string;
+	};
+	communicationContracts: () => StoredSignedContract[];
+	onContractUsed?: (contractId: string, participantDid: string) => void;
+}
+
+/**
+ * Minimal contract shape needed by the event store.
+ * The canonical definition lives in @decentrl/sdk types.
+ */
+export interface StoredSignedContract {
+	id: string;
+	participantDid: string;
+	signedCommunicationContract: SignedCommunicationContract;
+	rootSecret: string;
+}
+
+export interface PublishOptions {
+	recipient?: string; // If provided, sends via two-way private
+	tags: string[]; // For querying later
+	ephemeral?: boolean; // If true, skip local storage
+}
+
+export interface QueryOptions {
+	tags?: string[];
+	participantDid?: string;
+	afterTimestamp?: number;
+	beforeTimestamp?: number;
+	pagination?: { page: number; pageSize: number };
+	unprocessedOnly?: boolean;
+}
+
+export interface PaginationMeta {
+	page: number;
+	pageSize: number;
+	total: number;
+}
+
+export interface PaginatedResult<T> {
+	data: T[];
+	pagination: PaginationMeta;
+}
+
+export class EventStoreError extends Error {
+	constructor(
+		message: string,
+		public code: string,
+		public details?: unknown,
+	) {
+		super(message);
+		this.name = 'EventStoreError';
+	}
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"extends": "../../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"declaration": true,
+		"declarationMap": true,
+		"noEmit": false,
+		"composite": false,
+		"allowImportingTsExtensions": false,
+		"moduleResolution": "bundler"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}