@enbox/dwn-server 0.0.2 → 0.0.4

package/dist/esm/src/admin/types.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Options for listing tenants with search, filter, and sort capabilities.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/390
+ */
+export type TenantListOptions = {
+    /** Cursor for keyset pagination. */
+    cursor?: string;
+    /** Maximum number of results per page. */
+    limit?: number;
+    /** Substring search across tenant DIDs. */
+    search?: string;
+    /** Filter by suspension status. */
+    status?: 'active' | 'suspended';
+    /** Sort field. Default: `did`. */
+    sort?: 'did' | 'storage' | 'messages';
+    /** Sort direction. Default: `asc`. */
+    order?: 'asc' | 'desc';
+};
+/**
+ * Summary of a tenant for list endpoints.
+ */
+export type AdminTenantSummary = {
+    did: string;
+    messageCount: number;
+    dataStorageBytes: number;
+};
+/**
+ * Detailed information about a single tenant.
+ */
+export type AdminTenantDetail = {
+    did: string;
+    isActive: boolean;
+    suspended: boolean;
+    registration: {
+        termsOfServiceHash?: string;
+    } | undefined;
+    storage: {
+        messageCount: number;
+        dataStorageBytes: number;
+        protocolCount: number;
+    };
+    protocols: string[];
+    quota?: {
+        maxMessages: number;
+        maxStorageBytes: number;
+        source: 'tenant' | 'global' | 'unlimited';
+    };
+};
+/**
+ * Per-tenant storage and usage statistics.
+ */
+export type TenantStats = {
+    messageCount: number;
+    dataStorageBytes: number;
+    protocolCount: number;
+    protocols: string[];
+};
+/**
+ * Global server statistics.
+ */
+export type GlobalStats = {
+    tenantCount: number;
+    totalMessages: number;
+    totalDataBytes: number;
+    totalProtocols: number;
+};
+/**
+ * Health check result for a single backend component.
+ */
+export type HealthCheckResult = {
+    status: 'healthy' | 'unhealthy';
+    latencyMs: number;
+    error?: string;
+};
+/**
+ * Full deep health check response.
+ */
+export type AdminHealthCheck = {
+    status: 'healthy' | 'unhealthy';
+    uptime: number;
+    version: string | undefined;
+    checks: Record<string, HealthCheckResult>;
+};
+/**
+ * Server statistics response.
+ */
+export type AdminServerStats = {
+    tenants: {
+        total: number;
+        suspended: number;
+    };
+    storage: {
+        totalMessages: number;
+        totalDataBytes: number;
+        totalProtocols: number;
+    };
+    connections: {
+        websocket: {
+            active: number;
+            subscriptions: number;
+        };
+    };
+    registration: {
+        proofOfWorkEnabled: boolean;
+    };
+    uptime: number;
+};
+/**
+ * Paginated response wrapper.
+ */
+export type PaginatedResponse<T> = {
+    data: T[];
+    cursor?: string;
+    totalCount: number;
+};
+/**
+ * A single DWN activity event captured by the in-memory ring buffer.
+ */
+export type AdminActivityEvent = {
+    /** Monotonically increasing event ID (used as cursor). */
+    id: number;
+    /** ISO-8601 timestamp of the event. */
+    timestamp: string;
+    /** The tenant DID the request targeted. */
+    tenant: string;
+    /** DWN interface (e.g. `Records`, `Protocols`, `Events`). */
+    interface: string;
+    /** DWN method (e.g. `Write`, `Query`, `Read`, `Subscribe`). */
+    method: string;
+    /** DWN status code returned (e.g. 200, 202, 401). */
+    statusCode: number;
+    /** Transport used (`http` or `ws`). */
+    transport: 'http' | 'ws';
+    /** Data size in bytes (if applicable). */
+    dataSizeBytes?: number;
+};
+/**
+ * Snapshot of a single subscription's flow control state.
+ */
+export type AdminSubscriptionSnapshot = {
+    /** Subscription JSON-RPC ID. */
+    id: string | number;
+    /** Number of events sent but not yet acknowledged. */
+    inflight: number;
+    /** Number of events buffered waiting for the window to open. */
+    buffered: number;
+};
+/**
+ * Snapshot of a single WebSocket connection for the admin inspector.
+ */
+export type AdminConnectionSnapshot = {
+    /** Unique connection identifier. */
+    id: string;
+    /** ISO-8601 timestamp when the connection was established. */
+    connectedAt: string;
+    /** Number of active subscriptions on this connection. */
+    subscriptionCount: number;
+    /** Per-subscription flow control state. */
+    subscriptions: AdminSubscriptionSnapshot[];
+};
+/**
+ * Per-tenant storage quota limits.
+ * A value of 0 (or `undefined`) means the global default applies.
+ */
+export type TenantQuota = {
+    /** Tenant DID this quota applies to. */
+    did: string;
+    /** Maximum number of messages the tenant may store (0 = use global default). */
+    maxMessages: number;
+    /** Maximum data storage in bytes (0 = use global default). */
+    maxStorageBytes: number;
+};
+/**
+ * Request body for setting a tenant quota via the admin API.
+ */
+export type TenantQuotaInput = {
+    maxMessages?: number;
+    maxStorageBytes?: number;
+};
+/**
+ * Current tenant usage relative to their quota.
+ */
+export type TenantQuotaStatus = {
+    quota: {
+        maxMessages: number;
+        maxStorageBytes: number;
+        source: 'tenant' | 'global' | 'unlimited';
+    };
+    usage: {
+        messageCount: number;
+        storageBytes: number;
+    };
+};
+/**
+ * Summary of rate limit state for a single key (IP or tenant DID).
+ */
+export type RateLimitEntry = {
+    key: string;
+    tokens: number;
+    maxTokens: number;
+    refillRate: number;
+};
+/**
+ * Admin response for the rate-limits endpoint.
+ */
+export type RateLimitStatus = {
+    config: {
+        perIp: {
+            requestsPerSecond: number;
+            burst: number;
+            enabled: boolean;
+        };
+        perTenant: {
+            requestsPerSecond: number;
+            burst: number;
+            enabled: boolean;
+        };
+    };
+    activeEntries: {
+        ip: number;
+        tenant: number;
+    };
+};
+/**
+ * Runtime-changeable server settings (subset of DwnServerConfig).
+ */
+export type RuntimeConfig = {
+    logLevel: string;
+    maxRecordDataSize: number;
+    maxInFlight: number;
+    quotaMaxMessages: number;
+    quotaMaxStorageBytes: number;
+    rateLimitRequestsPerSecond: number;
+    rateLimitBurst: number;
+    rateLimitTenantRequestsPerSecond: number;
+    rateLimitTenantBurst: number;
+};
+/**
+ * Input for PATCH /admin/api/config. All fields are optional.
+ */
+export type RuntimeConfigPatch = Partial<RuntimeConfig>;
+/**
+ * Metadata-only view of a DWN message for the tenant data browser.
+ * Does not include decrypted content or encoded message bytes.
+ */
+export type AdminMessageSummary = {
+    messageCid: string;
+    interface: string | null;
+    method: string | null;
+    protocol: string | null;
+    protocolPath: string | null;
+    schema: string | null;
+    dataFormat: string | null;
+    dataSize: number | null;
+    dateCreated: string | null;
+    messageTimestamp: string | null;
+};
+/**
+ * Protocol summary with record count per protocol.
+ */
+export type AdminProtocolSummary = {
+    protocol: string;
+    messageCount: number;
+};
+/**
+ * Complete tenant data export for backup/migration.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/391
+ */
+export type TenantExport = {
+    metadata: {
+        tenant: string;
+        exportedAt: string;
+        messageCount: number;
+        dataRecordCount: number;
+    };
+    messages: Record<string, unknown>[];
+    dataRecords: Record<string, unknown>[];
+};
+/**
+ * A registered webhook endpoint for admin event notifications.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/395
+ */
+export type AdminWebhook = {
+    /** Auto-generated webhook ID. */
+    id: string;
+    /** URL to POST events to. */
+    url: string;
+    /** Event patterns to subscribe to (e.g. `tenant.*`, `quota.warning`). Asterisk is wildcard. */
+    events: string[];
+    /** Optional shared secret for HMAC-SHA256 signature verification. */
+    secret?: string;
+    /** ISO-8601 timestamp of creation. */
+    createdAt: string;
+};
+/**
+ * Input for creating a webhook.
+ */
+export type AdminWebhookInput = {
+    url: string;
+    events: string[];
+    secret?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/src/admin/types.d.ts.map

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

package/dist/esm/src/admin/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/src/admin/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/admin/types.ts"],"names":[],"mappings":""}

package/dist/esm/src/admin/webhook-manager.d.ts

@@ -0,0 +1,55 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+import type { AdminWebhook, AdminWebhookInput } from './types.js';
+/**
+ * Payload delivered to webhook endpoints.
+ */
+export type WebhookPayload = {
+    /** Unique delivery ID. */
+    id: string;
+    /** ISO-8601 timestamp. */
+    timestamp: string;
+    /** Event type (e.g. `tenant.suspend`, `quota.warning`). */
+    event: string;
+    /** Optional target (e.g. tenant DID). */
+    target?: string;
+    /** Additional event data. */
+    data?: Record<string, unknown>;
+};
+/**
+ * Manages webhook registrations and event delivery.
+ *
+ * Webhooks are stored in a SQL table and fire asynchronously when matching
+ * events occur. Delivery includes retry logic and optional HMAC-SHA256 signatures.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/395
+ */
+export declare class WebhookManager {
+    #private;
+    private constructor();
+    /**
+     * Creates and initializes a `WebhookManager` instance.
+     */
+    static create(dialect: Dialect): Promise<WebhookManager>;
+    /**
+     * Registers a new webhook. Returns the created webhook (without secret echoed).
+     */
+    register(input: AdminWebhookInput): Promise<AdminWebhook>;
+    /**
+     * Lists all registered webhooks. Secrets are redacted.
+     */
+    list(): Promise<AdminWebhook[]>;
+    /**
+     * Deletes a webhook by ID. Returns `true` if found and deleted.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Fires matching webhooks for a given event. Non-blocking — delivery happens
+     * asynchronously and errors are logged but never propagated.
+     */
+    fire(event: string, target?: string, data?: Record<string, unknown>): void;
+    /**
+     * Closes the underlying database connection.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=webhook-manager.d.ts.map

package/dist/esm/src/admin/webhook-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-manager.d.ts","sourceRoot":"","sources":["../../../../src/admin/webhook-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAOlE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,0BAA0B;IAC1B,EAAE,EAAG,MAAM,CAAC;IACZ,0BAA0B;IAC1B,SAAS,EAAG,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAG,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAG,MAAM,CAAC;IACjB,6BAA6B;IAC7B,IAAI,CAAC,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,cAAc;;IAOzB,OAAO;IAIP;;OAEG;WACiB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBrE;;OAEG;IACU,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsBtE;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB5C;;OAEG;IACU,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAajD;;;OAGG;IACI,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA0FjF;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGpC"}

package/dist/esm/src/admin/webhook-manager.js

@@ -0,0 +1,184 @@
+import { createHmac } from 'crypto';
+import { Kysely } from 'kysely';
+import log from 'loglevel';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Manages webhook registrations and event delivery.
+ *
+ * Webhooks are stored in a SQL table and fire asynchronously when matching
+ * events occur. Delivery includes retry logic and optional HMAC-SHA256 signatures.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/395
+ */
+export class WebhookManager {
+    static #tableName = 'adminWebhooks';
+    static #maxRetries = 3;
+    static #retryDelaysMs = [1000, 5000, 15000];
+    #db;
+    constructor(dialect) {
+        this.#db = new Kysely({ dialect });
+    }
+    /**
+     * Creates and initializes a `WebhookManager` instance.
+     */
+    static async create(dialect) {
+        const manager = new WebhookManager(dialect);
+        await manager.#initialize();
+        return manager;
+    }
+    async #initialize() {
+        await this.#db.schema
+            .createTable(WebhookManager.#tableName)
+            .ifNotExists()
+            .addColumn('id', 'text', (col) => col.primaryKey())
+            .addColumn('url', 'text', (col) => col.notNull())
+            .addColumn('events', 'text', (col) => col.notNull()) // JSON array
+            .addColumn('secret', 'text')
+            .addColumn('createdAt', 'text', (col) => col.notNull())
+            .execute();
+    }
+    // ---------------------------------------------------------------------------
+    // CRUD
+    // ---------------------------------------------------------------------------
+    /**
+     * Registers a new webhook. Returns the created webhook (without secret echoed).
+     */
+    async register(input) {
+        const webhook = {
+            id: uuidv4(),
+            url: input.url,
+            events: input.events,
+            createdAt: new Date().toISOString(),
+        };
+        await this.#db
+            .insertInto(WebhookManager.#tableName)
+            .values({
+            id: webhook.id,
+            url: webhook.url,
+            events: JSON.stringify(webhook.events),
+            secret: input.secret ?? null,
+            createdAt: webhook.createdAt,
+        })
+            .execute();
+        return webhook;
+    }
+    /**
+     * Lists all registered webhooks. Secrets are redacted.
+     */
+    async list() {
+        const rows = await this.#db
+            .selectFrom(WebhookManager.#tableName)
+            .select(['id', 'url', 'events', 'secret', 'createdAt'])
+            .orderBy('createdAt', 'asc')
+            .execute();
+        return rows.map((row) => ({
+            id: row.id,
+            url: row.url,
+            events: JSON.parse(row.events),
+            secret: row.secret ? '***' : undefined,
+            createdAt: row.createdAt,
+        }));
+    }
+    /**
+     * Deletes a webhook by ID. Returns `true` if found and deleted.
+     */
+    async delete(id) {
+        const result = await this.#db
+            .deleteFrom(WebhookManager.#tableName)
+            .where('id', '=', id)
+            .executeTakeFirstOrThrow();
+        return Number(result.numDeletedRows) > 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Event dispatch
+    // ---------------------------------------------------------------------------
+    /**
+     * Fires matching webhooks for a given event. Non-blocking — delivery happens
+     * asynchronously and errors are logged but never propagated.
+     */
+    fire(event, target, data) {
+        // Fire-and-forget.
+        this.#dispatchAll(event, target, data).catch((err) => {
+            log.error('Webhook dispatch error:', err);
+        });
+    }
+    async #dispatchAll(event, target, data) {
+        const rows = await this.#db
+            .selectFrom(WebhookManager.#tableName)
+            .select(['id', 'url', 'events', 'secret'])
+            .execute();
+        const payload = {
+            id: uuidv4(),
+            timestamp: new Date().toISOString(),
+            event,
+            target,
+            data,
+        };
+        const body = JSON.stringify(payload);
+        for (const row of rows) {
+            const patterns = JSON.parse(row.events);
+            if (this.#matchesEvent(event, patterns)) {
+                this.#deliver(row.url, body, row.secret).catch((err) => {
+                    log.warn(`Webhook delivery failed for ${row.url}:`, err);
+                });
+            }
+        }
+    }
+    /**
+     * Checks if an event matches any of the subscription patterns.
+     * Supports wildcard patterns like `tenant.*`.
+     */
+    #matchesEvent(event, patterns) {
+        for (const pattern of patterns) {
+            if (pattern === '*') {
+                return true;
+            }
+            if (pattern === event) {
+                return true;
+            }
+            if (pattern.endsWith('.*')) {
+                const prefix = pattern.slice(0, -2);
+                if (event.startsWith(prefix + '.') || event === prefix) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Delivers a webhook payload with retry logic and optional HMAC signature.
+     */
+    async #deliver(url, body, secret) {
+        const headers = {
+            'content-type': 'application/json',
+        };
+        if (secret) {
+            const signature = createHmac('sha256', secret).update(body).digest('hex');
+            headers['x-webhook-signature'] = `sha256=${signature}`;
+        }
+        for (let attempt = 0; attempt <= WebhookManager.#maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, { method: 'POST', headers, body, signal: AbortSignal.timeout(10_000) });
+                if (response.ok) {
+                    return;
+                }
+                log.warn(`Webhook ${url} returned ${response.status} (attempt ${attempt + 1})`);
+            }
+            catch (err) {
+                log.warn(`Webhook ${url} fetch error (attempt ${attempt + 1}):`, err);
+            }
+            // Wait before retry (skip wait on last attempt).
+            if (attempt < WebhookManager.#maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, WebhookManager.#retryDelaysMs[attempt]));
+            }
+        }
+        log.error(`Webhook delivery to ${url} failed after ${WebhookManager.#maxRetries + 1} attempts`);
+    }
+    /**
+     * Closes the underlying database connection.
+     */
+    async close() {
+        await this.#db.destroy();
+    }
+}
+//# sourceMappingURL=webhook-manager.js.map

package/dist/esm/src/admin/webhook-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-manager.js","sourceRoot":"","sources":["../../../../src/admin/webhook-manager.ts"],"names":[],"mappings":"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"}