mindoodb 0.0.51 → 0.0.54

package/dist/node/server/MindooDBServer.js

@@ -59,19 +59,31 @@ const cors_1 = __importDefault(require("cors"));
 const express_rate_limit_1 = __importStar(require("express-rate-limit"));
 const compressionMiddleware_1 = require("./compressionMiddleware");
 const binaryEntryFraming_1 = require("../../core/appendonlystores/network/binaryEntryFraming");
+const entryWireCodec_1 = require("../../core/appendonlystores/network/entryWireCodec");
 const SyncEventBus_1 = require("./SyncEventBus");
-const types_1 = require("../../core/appendonlystores/types");
-const types_2 = require("../../core/appendonlystores/network/types");
+const ClusterManager_1 = require("./peer/ClusterManager");
+const routes_1 = require("./peer/routes");
+const types_1 = require("./peer/types");
+const types_2 = require("../../core/appendonlystores/types");
+const types_3 = require("../../core/appendonlystores/network/types");
 const TenantManager_1 = require("./TenantManager");
 const CapabilityMatcher_1 = require("./CapabilityMatcher");
 const SystemAdminAuth_1 = require("./SystemAdminAuth");
+const DeviceDiscoveryService_1 = require("./DeviceDiscoveryService");
 const config_1 = require("./config");
 const SystemIpAllowlist_1 = require("./SystemIpAllowlist");
 const validation_1 = require("./validation");
 const urlSafety_1 = require("../../core/utils/urlSafety");
-const types_3 = require("./types");
+const types_4 = require("./types");
 const timestampProxy_1 = require("./timestampProxy");
 const rateLimits_1 = require("./rateLimits");
+/**
+ * Wire-format types for the sync HTTP API live in
+ * {@link ../../core/appendonlystores/network/entryWireCodec}: binary fields
+ * (signature, encryptedData, rsaEncryptedPayload) are base64 strings in
+ * transit. Client and server share that codec so signed trailing blocks
+ * cannot drift off the wire.
+ */
 /**
  * Rate-limit defaults. Auth and sync have separate tiers because a single
  * challenge/authenticate handshake is two requests; with multiple tenants,
@@ -114,24 +126,6 @@ const DEFAULT_TIMESTAMP_RATE_LIMIT_MAX = 10;
 const DEFAULT_TIMESTAMP_DAILY_LIMIT_MAX = 500;
 const TIMESTAMP_DAILY_WINDOW_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_SERVER_SOCKET_TIMEOUT_MS = 120000;
-/**
- * The effective max number of database ids per sync-server registration. Reads
- * the `MINDOODB_MAX_SYNC_SERVER_DATABASES` env override and falls back to
- * {@link DEFAULT_MAX_SYNC_SERVER_DATABASES} when unset or invalid (non-integer
- * or non-positive), so a typo can never silently disable the bound.
- */
-function resolveMaxSyncServerDatabases() {
-    const raw = process.env[types_3.ENV_VARS.MAX_SYNC_SERVER_DATABASES]?.trim();
-    if (!raw)
-        return validation_1.DEFAULT_MAX_SYNC_SERVER_DATABASES;
-    const parsed = Number(raw);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        console.warn(`[MindooDBServer] Ignoring invalid ${types_3.ENV_VARS.MAX_SYNC_SERVER_DATABASES}="${raw}" ` +
-            `(expected a positive integer); using default ${validation_1.DEFAULT_MAX_SYNC_SERVER_DATABASES}`);
-        return validation_1.DEFAULT_MAX_SYNC_SERVER_DATABASES;
-    }
-    return parsed;
-}
 /** Parse a human-readable size string ("5mb", "1024", "100kb") into bytes. */
 function parseBodySizeLimitToBytes(limit) {
     const normalized = limit.trim().toLowerCase();
@@ -174,8 +168,8 @@ class MindooDBServer {
         this.configPath = configPath ?? path_1.default.join(dataDir, "config.json");
         this.jsonBodyLimit = process.env.MINDOODB_JSON_BODY_LIMIT?.trim() || "5mb";
         this.jsonBodyLimitBytes = parseBodySizeLimitToBytes(this.jsonBodyLimit);
-        this.tsaProviders = (0, timestampProxy_1.parseTsaProviders)(process.env[types_3.ENV_VARS.TSA_PROVIDERS], {
-            allowInsecureUrls: /^(1|true)$/i.test(process.env[types_3.ENV_VARS.ALLOW_INSECURE_SYNC_URLS] ?? ""),
+        this.tsaProviders = (0, timestampProxy_1.parseTsaProviders)(process.env[types_4.ENV_VARS.TSA_PROVIDERS], {
+            allowInsecureUrls: /^(1|true)$/i.test(process.env[types_4.ENV_VARS.ALLOW_INSECURE_SYNC_URLS] ?? ""),
         });
         if (this.tsaProviders.length > 0) {
             console.log(`[MindooDBServer] RFC 3161 timestamp proxy enabled with providers: ${this.tsaProviders
@@ -187,7 +181,43 @@ class MindooDBServer {
         // SystemAdminAuthService generates a random HMAC-SHA256 secret for JWTs
         // on each server start — existing tokens become invalid after restart.
         const cryptoAdapter = this.tenantManager.getCryptoAdapter();
-        this.systemAdminAuth = new SystemAdminAuth_1.SystemAdminAuthService(cryptoAdapter, this.serverConfig);
+        this.systemAdminAuth = new SystemAdminAuth_1.SystemAdminAuthService(cryptoAdapter, this.serverConfig, {
+            isTenantAdminSigningKey: (publicsignkey) => this.tenantManager.isRegisteredTenantAdminSigningKey(publicsignkey),
+        });
+        this.deviceDiscovery = new DeviceDiscoveryService_1.DeviceDiscoveryService(this.tenantManager, cryptoAdapter);
+        this.cluster = new ClusterManager_1.ClusterManager({
+            cryptoAdapter,
+            dataDir,
+            eventBus: this.syncEventBus,
+            listTrustedServers: () => this.tenantManager.listTrustedServers(),
+            localServerName: () => this.tenantManager.getServerPublicInfo()?.name ?? null,
+            localSigningPublicKey: () => this.tenantManager.getServerPublicInfo()?.signingPublicKey ?? null,
+            getSigningKey: async () => (await this.tenantManager.getWitnessSigner())?.signingPrivateKey,
+            getEncryptionKey: () => this.tenantManager.getServerEncryptionPrivateKey(),
+            listTenants: () => this.tenantManager.listTenants(),
+            listDatabases: (tenantId) => this.tenantManager.listDatabases(tenantId),
+            getLocalStore: (tenantId, dbId, storeKind) => this.tenantManager.getStore(tenantId, dbId, storeKind),
+            localRole: this.serverConfig.cluster?.role,
+        });
+        // Peer tokens are accepted by the tenant sync routes so a peer can mirror
+        // the encrypted stores through the ordinary protocol; the store bypasses
+        // per-user access control for them (see ServerNetworkContentAddressedStore).
+        this.tenantManager.setPeerAccessControl({
+            peerTokenResolver: async (token) => {
+                const payload = await this.cluster.auth.validateToken(token);
+                if (!payload)
+                    return null;
+                const trusted = this.cluster.auth.findTrustedServerByKey(payload.publicsignkey);
+                if (!trusted)
+                    return null;
+                return {
+                    name: trusted.name,
+                    signingPublicKey: trusted.signingPublicKey,
+                    encryptionPublicKey: trusted.encryptionPublicKey,
+                };
+            },
+            trustedWitnessResolver: (receivedByPublicKey) => this.cluster.auth.findTrustedServerByKey(receivedByPublicKey) !== null,
+        });
         const principalCount = Object.values(this.serverConfig.capabilities).reduce((sum, arr) => sum + arr.length, 0);
         if (principalCount === 0) {
             console.log(`[MindooDBServer] WARNING: No system admin principals configured. All /system/* endpoints are locked down.`);
@@ -207,6 +237,23 @@ class MindooDBServer {
     getSystemAdminAuth() {
         return this.systemAdminAuth;
     }
+    getClusterManager() {
+        return this.cluster;
+    }
+    /**
+     * Begin replicating with every trusted server that has a `url`.
+     *
+     * Separate from the constructor so a server can serve the peer and cluster
+     * endpoints — answering handshakes, status and admin actions — without
+     * dialling out itself. That is what `--auto-sync` toggles, and it is what
+     * makes a passive mirror or a test harness possible.
+     */
+    startCluster() {
+        this.cluster.start();
+    }
+    async stopCluster() {
+        await this.cluster.stop();
+    }
     getServerConfig() {
         return this.serverConfig;
     }
@@ -307,7 +354,7 @@ class MindooDBServer {
      * list over `true`, which trusts the whole chain.
      */
     applyTrustProxySetting() {
-        const raw = process.env[types_3.ENV_VARS.TRUST_PROXY]?.trim();
+        const raw = process.env[types_4.ENV_VARS.TRUST_PROXY]?.trim();
         if (!raw || /^(0|false)$/i.test(raw)) {
             return;
         }
@@ -362,6 +409,17 @@ class MindooDBServer {
         this.app.get("/health", (req, res) => {
             res.json({ status: "ok", timestamp: Date.now() });
         });
+        // Server-wide device discovery (before /:tenantId so "device" is not a tenant id).
+        // Aggressive rate limit: challenge+discover scans every local tenant.
+        const deviceDiscoveryRateLimit = (0, express_rate_limit_1.default)({
+            windowMs: 60000,
+            max: 10,
+            standardHeaders: true,
+            legacyHeaders: false,
+            message: { error: "Too many device discovery requests, please try again later" },
+        });
+        this.app.post("/device/challenge", deviceDiscoveryRateLimit, this.handleDeviceChallenge.bind(this));
+        this.app.post("/device/discover", deviceDiscoveryRateLimit, this.handleDeviceDiscover.bind(this));
         // .well-known endpoints are unauthenticated so clients can discover
         // server identity and tenant availability before attempting to authenticate.
         this.app.get("/.well-known/mindoodb-server-info", (req, res) => {
@@ -372,6 +430,10 @@ class MindooDBServer {
             }
             res.json({
                 ...info,
+                // Its own mesh role, so `add-to-network` can propagate it into the
+                // other side's trusted-servers entry instead of asking the operator to
+                // repeat it on every node.
+                clusterRole: this.serverConfig.cluster?.role ?? "peer",
                 maxJsonRequestBodyLimit: this.jsonBodyLimit,
                 maxJsonRequestBodyBytes: this.jsonBodyLimitBytes ?? undefined,
                 // Lets a client decide between calling a browser-reachable TSA directly
@@ -382,6 +444,33 @@ class MindooDBServer {
                 },
             });
         });
+        /**
+         * Mirrors of one tenant, for client failover.
+         *
+         * Scoped to the tenant in the query on purpose: a client asking about
+         * tenant A must not learn which other tenants this server replicates, or
+         * to whom. Unauthenticated like the other discovery endpoints — a client
+         * needs it precisely when it cannot reach a server to authenticate with.
+         */
+        this.app.get("/.well-known/mindoodb-cluster", (req, res) => {
+            const tenantId = typeof req.query.tenantId === "string" ? req.query.tenantId.toLowerCase() : "";
+            if (!tenantId) {
+                res.status(400).json({ error: "tenantId query parameter is required" });
+                return;
+            }
+            try {
+                (0, validation_1.validateTenantId)(tenantId);
+            }
+            catch {
+                res.status(400).json({ error: "Invalid tenantId format" });
+                return;
+            }
+            if (!this.tenantManager.tenantExists(tenantId)) {
+                res.status(404).json({ error: "Tenant not found on server" });
+                return;
+            }
+            res.json({ tenantId, mirrors: this.cluster.mirrorsForTenant(tenantId) });
+        });
         this.app.get("/.well-known/mindoodb-tenants/:tenantId/publicinfos-fingerprints", async (req, res) => {
             const tenantId = req.params.tenantId.toLowerCase();
             try {
@@ -431,12 +520,29 @@ class MindooDBServer {
             console.log(`[MindooDBServer] MINDOODB_ADMIN_ALLOWED_IPS is set — /system/* limited to: ${systemIpRaw}`);
         }
         const systemRateLimit = (0, express_rate_limit_1.default)({
-            windowMs: 60000,
-            max: 30,
+            windowMs: this.serverConfig.rateLimits?.system?.windowMs ?? 60000,
+            max: this.serverConfig.rateLimits?.system?.max ?? 30,
             standardHeaders: true,
             legacyHeaders: false,
             message: { error: "Too many system requests, please try again later" },
         });
+        // Peer routes are mounted before the /system chain on purpose. They are
+        // server-to-server traffic, not administration: the admin IP allowlist
+        // would lock out the operator's own cluster, and 30 req/min would throttle
+        // replication to a crawl. They are protected by the peer JWT, which is only
+        // issued to a key in trusted-servers.json.
+        this.app.use("/system/peer", (0, express_rate_limit_1.default)({
+            windowMs: 60000,
+            max: 600,
+            standardHeaders: true,
+            legacyHeaders: false,
+            message: { error: "Too many peer requests, please try again later" },
+        }), (0, routes_1.createPeerRouter)({
+            cluster: this.cluster,
+            eventBus: this.syncEventBus,
+            listTenants: () => this.tenantManager.listTenants(),
+            listDatabases: (tenantId) => this.tenantManager.listDatabases(tenantId),
+        }));
         const systemRouter = (0, express_1.Router)();
         this.setupSystemRoutes(systemRouter);
         this.app.use("/system", SystemIpAllowlist_1.systemIpAllowlistMiddleware, systemRateLimit, systemRouter);
@@ -451,6 +557,10 @@ class MindooDBServer {
      * JWT-based middleware for /system/* routes (excluding /system/auth/*).
      * Extracts and validates the bearer token, then checks capabilities
      * for the current (method, path, username, publicsignkey).
+     *
+     * `DELETE /system/tenants/:tenantId` is also allowed when the JWT signing
+     * key is that tenant's registered `adminSigningPublicKey` (own-tenant
+     * delete). Sub-resources and other tenants stay capability-gated.
      */
     async systemAdminMiddleware(req, res, next) {
         const auth = req.headers.authorization;
@@ -468,7 +578,10 @@ class MindooDBServer {
         // but we need the full path for capability matching.
         const fullPath = `/system${req.path}`;
         const method = req.method.toUpperCase();
-        if (!this.capabilityMatcher.isAuthorized(method, fullPath, payload.sub, payload.publicsignkey)) {
+        const capabilityAuthorized = this.capabilityMatcher.isAuthorized(method, fullPath, payload.sub, payload.publicsignkey);
+        const ownerDeleteAuthorized = !capabilityAuthorized &&
+            this.isOwnTenantDeleteAuthorized(method, fullPath, payload.publicsignkey);
+        if (!capabilityAuthorized && !ownerDeleteAuthorized) {
             res.status(403).json({ error: "Forbidden: insufficient capabilities" });
             return;
         }
@@ -478,6 +591,27 @@ class MindooDBServer {
         };
         next();
     }
+    /**
+     * Owner bypass for deleting the caller's own tenant. Matches only
+     * `DELETE /system/tenants/:tenantId` (no sub-resource) and requires the
+     * JWT public key to equal that tenant's stored admin signing key.
+     */
+    isOwnTenantDeleteAuthorized(method, fullPath, publicsignkey) {
+        if (method !== "DELETE") {
+            return false;
+        }
+        const tenantId = (0, CapabilityMatcher_1.parseSystemTenantItemPath)(fullPath);
+        if (!tenantId) {
+            return false;
+        }
+        try {
+            (0, validation_1.validateTenantIdFormat)(tenantId);
+        }
+        catch {
+            return false;
+        }
+        return this.tenantManager.isTenantAdminSigningKeyFor(tenantId, publicsignkey);
+    }
     // ==================== Tenant Middleware ====================
     tenantMiddleware(req, res, next) {
         const rawTenantId = req.params.tenantId?.toLowerCase();
@@ -512,6 +646,15 @@ class MindooDBServer {
         router.post("/auth/challenge", challengeRateLimit, this.handleSystemChallenge.bind(this));
         router.post("/auth/authenticate", authenticateRateLimit, this.handleSystemAuthenticate.bind(this));
         const authMiddleware = this.systemAdminMiddleware.bind(this);
+        // Cluster administration. Behind the same JWT + capability middleware as
+        // the rest of /system, so config.json can grant an auditor principal the
+        // GET routes without granting the POST/PATCH/DELETE ones.
+        router.use("/cluster", authMiddleware, (0, routes_1.createClusterRouter)({
+            cluster: this.cluster,
+            listTrustedServers: () => this.tenantManager.listTrustedServers(),
+            saveTrustedServer: (peer) => this.tenantManager.saveTrustedServer(peer),
+            removeTrustedServer: (name) => this.tenantManager.removeTrustedServer(name),
+        }));
         // Tenant CRUD
         router.get("/tenants", authMiddleware, (req, res) => {
             try {
@@ -651,7 +794,7 @@ class MindooDBServer {
         });
         router.post("/trusted-servers", authMiddleware, (req, res) => {
             try {
-                const { name, signingPublicKey, encryptionPublicKey } = req.body;
+                const { name, signingPublicKey, encryptionPublicKey, url, direction, role, attachments } = req.body;
                 if (!name || !signingPublicKey || !encryptionPublicKey) {
                     res.status(400).json({ error: "name, signingPublicKey, and encryptionPublicKey are required" });
                     return;
@@ -660,7 +803,41 @@ class MindooDBServer {
                 (0, validation_1.validateStringLength)(signingPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "signingPublicKey");
                 (0, validation_1.validateStringLength)(encryptionPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "encryptionPublicKey");
                 const server = { name, signingPublicKey, encryptionPublicKey };
+                // Replication settings are optional: an entry without a url is a trust
+                // relationship only (inbound peers may authenticate, we never dial).
+                if (url !== undefined) {
+                    (0, validation_1.validateStringLength)(url, 2048, "url");
+                    const allowInsecure = /^(1|true)$/i.test(process.env[types_4.ENV_VARS.ALLOW_INSECURE_SYNC_URLS] ?? "");
+                    try {
+                        (0, urlSafety_1.assertSafeSyncUrl)(url, {
+                            requireHttps: !allowInsecure,
+                            allowPrivate: allowInsecure,
+                        });
+                    }
+                    catch (e) {
+                        if (e instanceof urlSafety_1.UnsafeUrlError) {
+                            res.status(400).json({ error: e.message });
+                            return;
+                        }
+                        throw e;
+                    }
+                    server.url = url;
+                }
+                for (const [field, value, guard] of [
+                    ["direction", direction, types_1.isPeerSyncDirection],
+                    ["role", role, types_1.isPeerRole],
+                    ["attachments", attachments, types_1.isPeerAttachmentMode],
+                ]) {
+                    if (value === undefined)
+                        continue;
+                    if (!guard(value)) {
+                        res.status(400).json({ error: `Invalid ${field}: ${String(value)}` });
+                        return;
+                    }
+                    Object.assign(server, { [field]: value });
+                }
                 this.tenantManager.addTrustedServer(server);
+                this.cluster.syncReplicators();
                 res.status(201).json({ success: true, message: `Trusted server "${name}" added` });
             }
             catch (error) {
@@ -685,6 +862,8 @@ class MindooDBServer {
                     res.status(404).json({ error: "Trusted server not found" });
                     return;
                 }
+                // Revoking trust must also stop replicating with that server.
+                this.cluster.syncReplicators();
                 res.json({ success: true, message: `Trusted server "${serverName}" removed` });
             }
             catch (error) {
@@ -696,128 +875,6 @@ class MindooDBServer {
                 res.status(500).json({ error: "Failed to remove trusted server" });
             }
         });
-        // Per-tenant sync server management
-        router.get("/tenants/:tenantId/sync-servers", authMiddleware, (req, res) => {
-            try {
-                const tenantId = req.params.tenantId.toLowerCase();
-                try {
-                    (0, validation_1.validateTenantId)(tenantId);
-                }
-                catch {
-                    res.status(400).json({ error: "Invalid tenantId format" });
-                    return;
-                }
-                if (!this.tenantManager.tenantExists(tenantId)) {
-                    res.status(404).json({ error: "Tenant not found" });
-                    return;
-                }
-                const servers = this.tenantManager.getTenantSyncServers(tenantId);
-                res.json({ servers });
-            }
-            catch (error) {
-                console.error("[MindooDBServer] Error listing sync servers:", error);
-                res.status(500).json({ error: "Failed to list sync servers" });
-            }
-        });
-        router.post("/tenants/:tenantId/sync-servers", authMiddleware, (req, res) => {
-            try {
-                const tenantId = req.params.tenantId.toLowerCase();
-                try {
-                    (0, validation_1.validateTenantId)(tenantId);
-                }
-                catch {
-                    res.status(400).json({ error: "Invalid tenantId format" });
-                    return;
-                }
-                if (!this.tenantManager.tenantExists(tenantId)) {
-                    res.status(404).json({ error: "Tenant not found" });
-                    return;
-                }
-                const { name, url, syncIntervalMs, databases } = req.body;
-                if (!name || !url) {
-                    res.status(400).json({ error: "name and url are required" });
-                    return;
-                }
-                if (!databases || !Array.isArray(databases) || databases.length === 0) {
-                    res.status(400).json({ error: "databases array is required and must not be empty" });
-                    return;
-                }
-                // Bound and format-validate each database id (audit, Low): these are
-                // used to scope sync and must be safe identifiers, not arbitrary input.
-                // The bound is overridable per deployment via
-                // MINDOODB_MAX_SYNC_SERVER_DATABASES.
-                (0, validation_1.validateArraySize)(databases, resolveMaxSyncServerDatabases(), "databases");
-                for (const db of databases) {
-                    (0, validation_1.validateIdentifier)(db, "databases[]");
-                }
-                (0, validation_1.validateStringLength)(name, 256, "name");
-                (0, validation_1.validateStringLength)(url, 2048, "url");
-                // SSRF guard: an admin-supplied sync URL is fetched server-side, so
-                // reject plaintext/internal targets unless explicitly allowed for dev.
-                const allowInsecure = /^(1|true)$/i.test(process.env[types_3.ENV_VARS.ALLOW_INSECURE_SYNC_URLS] ?? "");
-                try {
-                    (0, urlSafety_1.assertSafeSyncUrl)(url, {
-                        requireHttps: !allowInsecure,
-                        allowPrivate: allowInsecure,
-                    });
-                }
-                catch (e) {
-                    if (e instanceof urlSafety_1.UnsafeUrlError) {
-                        res.status(400).json({ error: e.message });
-                        return;
-                    }
-                    throw e;
-                }
-                const config = { name, url, databases };
-                if (syncIntervalMs !== undefined) {
-                    config.syncIntervalMs = syncIntervalMs;
-                }
-                this.tenantManager.addTenantSyncServer(tenantId, config);
-                res.status(201).json({ success: true, message: `Sync server "${name}" configured for tenant ${tenantId}` });
-            }
-            catch (error) {
-                if (error instanceof validation_1.ValidationError) {
-                    res.status(400).json({ error: error.message });
-                    return;
-                }
-                console.error("[MindooDBServer] Error adding sync server:", error);
-                res.status(500).json({ error: "Failed to add sync server" });
-            }
-        });
-        router.delete("/tenants/:tenantId/sync-servers/:serverName", authMiddleware, (req, res) => {
-            try {
-                const tenantId = req.params.tenantId.toLowerCase();
-                try {
-                    (0, validation_1.validateTenantId)(tenantId);
-                }
-                catch {
-                    res.status(400).json({ error: "Invalid tenantId format" });
-                    return;
-                }
-                if (!this.tenantManager.tenantExists(tenantId)) {
-                    res.status(404).json({ error: "Tenant not found" });
-                    return;
-                }
-                const serverName = decodeURIComponent(req.params.serverName);
-                (0, validation_1.validateStringLength)(serverName, 256, "serverName");
-                const removed = this.tenantManager.removeTenantSyncServer(tenantId, serverName);
-                if (!removed) {
-                    res.status(404).json({ error: "Sync server not found" });
-                    return;
-                }
-                res.json({ success: true, message: `Sync server "${serverName}" removed from tenant ${tenantId}` });
-            }
-            catch (error) {
-                if (error instanceof validation_1.ValidationError) {
-                    res.status(400).json({ error: error.message });
-                    return;
-                }
-                console.error("[MindooDBServer] Error removing sync server:", error);
-                res.status(500).json({ error: "Failed to remove sync server" });
-            }
-        });
-        // Per-tenant trigger-sync (moved from /:tenantId/admin/trigger-sync)
-        router.post("/tenants/:tenantId/trigger-sync", authMiddleware, this.handleTriggerSync.bind(this));
         // Runtime config management
         router.get("/config/backups", authMiddleware, (req, res) => {
             try {
@@ -1298,6 +1355,47 @@ class MindooDBServer {
         const serverName = this.tenantManager.getServerPublicInfo()?.name ?? "unknown";
         return `Tenant ${tenantId} not found on server ${serverName}`;
     }
+    // ==================== Device Discovery (server-wide) ====================
+    async handleDeviceChallenge(req, res) {
+        try {
+            const { signingPublicKey } = req.body ?? {};
+            if (typeof signingPublicKey !== "string" || !signingPublicKey.trim()) {
+                res.status(400).json({ error: "signingPublicKey is required" });
+                return;
+            }
+            (0, validation_1.validateStringLength)(signingPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "signingPublicKey");
+            const challenge = this.deviceDiscovery.createChallenge(signingPublicKey);
+            res.json({ challenge });
+        }
+        catch (error) {
+            this.handleRequestError(error, res);
+        }
+    }
+    async handleDeviceDiscover(req, res) {
+        try {
+            const { challenge, signature } = req.body ?? {};
+            if (typeof challenge !== "string" || !challenge.trim()) {
+                res.status(400).json({ error: "challenge is required" });
+                return;
+            }
+            if (typeof signature !== "string" || !signature.trim()) {
+                res.status(400).json({ error: "signature is required" });
+                return;
+            }
+            (0, validation_1.validateStringLength)(challenge, validation_1.MAX_CHALLENGE_LENGTH, "challenge");
+            (0, validation_1.validateStringLength)(signature, validation_1.MAX_SIGNATURE_LENGTH, "signature");
+            const signatureBytes = this.base64ToUint8Array(signature);
+            const result = await this.deviceDiscovery.discover(challenge, signatureBytes);
+            res.json(result);
+        }
+        catch (error) {
+            if (error instanceof DeviceDiscoveryService_1.DeviceDiscoveryAuthError) {
+                res.status(401).json({ error: error.message });
+                return;
+            }
+            this.handleRequestError(error, res);
+        }
+    }
     // ==================== Tenant Auth Handlers ====================
     // Two-step challenge-response flow:
     //  1. POST /auth/challenge  → client sends username, server returns a random nonce
@@ -1533,16 +1631,20 @@ class MindooDBServer {
         if (this.syncEventBus.listenerCount === 0) {
             return;
         }
-        void serverStore
-            .handleGetStoreHead(token)
-            .catch(() => null)
-            .then((head) => {
+        // Peer replicators subscribe to this bus, so a write that arrived from a
+        // peer has to be labelled: without the label it would be pushed straight
+        // back to its origin, and two bidirectional peers would ping-pong.
+        const originPeer = this.cluster?.auth
+            ? this.cluster.auth.validateToken(token).then((payload) => payload?.sub)
+            : Promise.resolve(undefined);
+        void Promise.all([serverStore.handleGetStoreHead(token).catch(() => null), originPeer]).then(([head, peerName]) => {
             this.syncEventBus.publish({
                 tenantId,
                 dbId,
                 storeKind,
                 epoch: head?.epoch,
                 maxReceiptOrder: head?.maxReceiptOrder,
+                originPeer: peerName,
             });
         });
     }
@@ -1907,9 +2009,6 @@ class MindooDBServer {
         }
     }
     // ==================== Management Handlers ====================
-    async handleTriggerSync(req, res) {
-        res.json({ success: true, message: "Sync triggered (not yet implemented)" });
-    }
     // ==================== Helper Methods ====================
     /**
      * Derive the StoreKind from the request path. Both "docs" and
@@ -1919,17 +2018,17 @@ class MindooDBServer {
     getStoreKindFromRequest(req) {
         const trimmedPath = req.path.replace(/\/$/, "");
         if (trimmedPath.startsWith("/sync/docs/") || trimmedPath === "/sync/docs/capabilities" || trimmedPath === "/sync/docs/getAllIds") {
-            return types_1.StoreKind.docs;
+            return types_2.StoreKind.docs;
         }
         if (trimmedPath.startsWith("/sync/attachments/") || trimmedPath === "/sync/attachments/capabilities" || trimmedPath === "/sync/attachments/getAllIds") {
-            return types_1.StoreKind.attachments;
+            return types_2.StoreKind.attachments;
         }
         throw new Error(`Unsupported sync store kind for path: ${req.path}`);
     }
     extractToken(req) {
         const auth = req.headers.authorization;
         if (!auth || !auth.startsWith("Bearer ")) {
-            throw new types_2.NetworkError("INVALID_TOKEN", "Missing or invalid Authorization header");
+            throw new types_3.NetworkError("INVALID_TOKEN", "Missing or invalid Authorization header");
         }
         return auth.substring(7);
     }
@@ -2007,70 +2106,16 @@ class MindooDBServer {
     }
     // ==================== Serialization ====================
     // Entries are stored with binary fields (Uint8Array) internally but
-    // transmitted as base64 strings over JSON. These methods handle the
-    // conversion in both directions.
+    // transmitted as base64 strings over JSON. Shared with the client
+    // (entryWireCodec) so signed trailing blocks cannot drift off the wire.
     serializeEntryMetadata(metadata) {
-        return {
-            entryType: metadata.entryType,
-            id: metadata.id,
-            contentHash: metadata.contentHash,
-            docId: metadata.docId,
-            dependencyIds: metadata.dependencyIds,
-            createdAt: metadata.createdAt,
-            receiptOrder: metadata.receiptOrder,
-            createdByPublicKey: metadata.createdByPublicKey,
-            decryptionKeyId: metadata.decryptionKeyId,
-            signature: this.uint8ArrayToBase64(metadata.signature),
-            metadataSignature: metadata.metadataSignature
-                ? this.uint8ArrayToBase64(metadata.metadataSignature)
-                : undefined,
-            originalSize: metadata.originalSize,
-            encryptedSize: metadata.encryptedSize,
-            receivedAt: metadata.receivedAt,
-            receivedByPublicKey: metadata.receivedByPublicKey,
-            receivedDateSignature: metadata.receivedDateSignature
-                ? this.uint8ArrayToBase64(metadata.receivedDateSignature)
-                : undefined,
-            attachmentRefs: metadata.attachmentRefs,
-            // Bound into metadataSignature, so it must survive the round-trip.
-            provenance: metadata.provenance,
-            entryVersion: metadata.entryVersion,
-        };
+        return (0, entryWireCodec_1.serializeEntryMetadata)(metadata);
     }
     deserializeEntryMetadata(serialized) {
-        return {
-            entryType: serialized.entryType,
-            id: serialized.id,
-            contentHash: serialized.contentHash,
-            docId: serialized.docId,
-            dependencyIds: serialized.dependencyIds,
-            createdAt: serialized.createdAt,
-            receiptOrder: serialized.receiptOrder,
-            createdByPublicKey: serialized.createdByPublicKey,
-            decryptionKeyId: serialized.decryptionKeyId,
-            signature: this.base64ToUint8Array(serialized.signature),
-            metadataSignature: serialized.metadataSignature
-                ? this.base64ToUint8Array(serialized.metadataSignature)
-                : undefined,
-            originalSize: serialized.originalSize,
-            encryptedSize: serialized.encryptedSize,
-            // Preserve any pre-existing witness receipt (e.g. on re-sync or
-            // server-to-server forwarding); a fresh local push has none.
-            receivedAt: serialized.receivedAt,
-            receivedByPublicKey: serialized.receivedByPublicKey,
-            receivedDateSignature: serialized.receivedDateSignature
-                ? this.base64ToUint8Array(serialized.receivedDateSignature)
-                : undefined,
-            attachmentRefs: serialized.attachmentRefs,
-            provenance: serialized.provenance,
-            entryVersion: serialized.entryVersion,
-        };
+        return (0, entryWireCodec_1.deserializeEntryMetadata)(serialized);
     }
     deserializeEntry(serialized) {
-        return {
-            ...this.deserializeEntryMetadata(serialized),
-            encryptedData: this.base64ToUint8Array(serialized.encryptedData),
-        };
+        return (0, entryWireCodec_1.deserializeStoreEntry)(serialized);
     }
     uint8ArrayToBase64(bytes) {
         return Buffer.from(bytes).toString("base64");