@augmentd-labs/canvas-edge 0.4.1 → 0.6.2

package/README.md

@@ -75,3 +75,12 @@ mirrors.json). `CANVAS_DIRECTION=pull` makes the container a backup target
 
 Protocol: canvas-server `docs/canvas-edge-protocol.md` (tunnel) and
 `docs/sync-protocol.md` (file plane).
+
+### Client certificates (0.5.0+)
+
+Hub remotes retain `tls: { certFile, keyFile }` from the shared client config.
+Workspace remotes can carry the same optional fields. Pairing, tunnel sockets,
+mirror status calls, and object transfers all use the identity. Container bootstrap
+accepts `CANVAS_TLS_CERT`/`CANVAS_TLS_KEY` as a complete pair of file paths; mount
+these files read-only. Use leaf-first PEM chains and protected unencrypted RSA/EC
+keys. Server verification is enabled. Restart the daemon/container after renewal.

package/node_modules/canvas-stored/package.json

@@ -1,25 +1,12 @@
 {
   "name": "canvas-stored",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "",
   "main": "./src/index.js",
   "type": "module",
   "author": "Jozef Melich <me@idnc.sk>",
   "license": "AGPL-3.0-or-later",
-  "dependencies": {
-    "cacache": "^20.0.4",
-    "chokidar": "^5.0.0",
-    "debug": "^4.4.3",
-    "eventemitter2": "^6.4.9",
-    "exifr": "^7.1.3",
-    "file-type": "^21.3.3",
-    "fs-extra": "^11.3.4",
-    "image-size": "^2.0.2",
-    "imap": "^0.8.19",
-    "lmdb": "^3.5.2",
-    "music-metadata": "^11.9.0",
-    "picomatch": "^2.3.1"
-  },
+  "dependencies": {},
   "engines": {
     "node": ">=20.0.0"
   }

package/node_modules/canvas-stored/src/backends/file/index.js

@@ -288,6 +288,29 @@ export default class FileBackend extends StorageBackend {
         return { key, size: stats.size };
     }
 
+    // Create-only placement: link(2) fails with EEXIST even for an unindexed
+    // file, directory or dangling symlink. Never use rename-over for this path.
+    async createFrom(key, srcPath) {
+        const dest = this.#resolvePath(key);
+        await fs.ensureDir(path.dirname(dest));
+        try {
+            await fs.link(srcPath, dest);
+        } catch (error) {
+            if (error.code !== 'EXDEV') throw error;
+            // Stage on the destination filesystem, then publish atomically.
+            const sibling = path.join(path.dirname(dest), `${TMP_DIR}-${process.pid}-${Math.random().toString(16).slice(2)}`);
+            try {
+                await fs.copyFile(srcPath, sibling);
+                await fs.link(sibling, dest);
+            } finally {
+                await fs.remove(sibling).catch(() => {});
+            }
+        }
+        const stat = await this.stat(key);
+        if (!stat) throw new Error(`Upload destination disappeared: ${key}`);
+        return stat;
+    }
+
     // ── Retention ─────────────────────────────────────────────────────────
     //
     // Bytes an overwrite or delete is about to displace are kept for a while
@@ -399,8 +422,11 @@ export default class FileBackend extends StorageBackend {
 
     async stat(key) {
         const filePath = this.#resolvePath(key);
-        if (!await fs.pathExists(filePath)) return null;
-        const stats = await fs.stat(filePath);
+        let stats;
+        try { stats = await fs.stat(filePath); } catch (error) {
+            if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+            throw error;
+        }
         if (!stats.isFile()) return null;
         // dev/ino feed rename matching (same inode at a new path) and the
         // liveness checks — stored keeps them in location metadata.
@@ -413,7 +439,6 @@ export default class FileBackend extends StorageBackend {
     async *list(options = {}) {
         const { prefix = '', recursive = true, onError = null } = options;
         const searchPath = this.#resolvePath(prefix);
-        if (!await fs.pathExists(searchPath)) return;
 
         let entries;
         try {
@@ -426,7 +451,13 @@ export default class FileBackend extends StorageBackend {
             const relativePath = path.join(prefix, entry.name);
             if (this.#isIgnored(relativePath)) continue;
             if (entry.isFile()) {
-                yield { key: relativePath, ...(await this.stat(relativePath)) };
+                try {
+                    const stat = await this.stat(relativePath);
+                    if (stat) yield stat;
+                } catch (error) {
+                    if (typeof onError !== 'function') throw error;
+                    onError(relativePath, error);
+                }
             } else if (entry.isDirectory() && recursive) {
                 yield* this.list({ ...options, prefix: relativePath });
             }

package/node_modules/canvas-stored/src/index.js

@@ -417,7 +417,14 @@ export default class Stored extends EventEmitter2 {
             try {
                 if (current) await this.#retain(backendName, destKey, current);
                 let placed = null;
-                if (typeof backend.renameFrom === 'function') {
+                if (String(options.ifNoneMatch || '').trim() === '*') {
+                    if (typeof backend.createFrom !== 'function') return { ok: false, reason: 'unsupported-backend' };
+                    try { placed = await backend.createFrom(destKey, tempPath); }
+                    catch (error) {
+                        if (error.code === 'EEXIST') return { ok: false, reason: 'precondition-failed', current: null };
+                        throw error;
+                    }
+                } else if (typeof backend.renameFrom === 'function') {
                     try { placed = await backend.renameFrom(destKey, tempPath); }
                     catch (err) { if (err.code !== 'EXDEV') throw err; }
                 }
@@ -968,6 +975,11 @@ export default class Stored extends EventEmitter2 {
                 const existing = this.#index.get(id);
                 const locations = existing?.locations || [];
                 const match = locations.find(l => l.backend === file.backend && l.key === file.key);
+                // Avoid LMDB/index/change-feed churn on warm scans. Still emit
+                // the row to consumers: their document index may need repair.
+                if (match && match.synced === true && match.size === file.size && match.mtime === file.modified
+                    && (file.ino == null || (match.ino === file.ino && match.dev === file.dev))
+                    && existing.size === file.size && existing.mimeType === file.mimeType) return;
                 if (match) {
                     match.size = file.size;
                     match.mtime = file.modified;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augmentd-labs/canvas-edge",
-  "version": "0.4.1",
+  "version": "0.6.2",
   "description": "Canvas device runtime: folder mirrors (canvas-stored Mirror engine) + edge tunnel client (dist artifact)",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -20,8 +20,8 @@
     "node": ">=20.18.0"
   },
   "dependencies": {
-    "@augmentd-labs/canvas-protocol": "^0.4.0",
-    "canvas-stored": "1.9.1",
+    "@augmentd-labs/canvas-protocol": "^0.5.0",
+    "canvas-stored": "1.9.3",
     "cacache": "^20.0.4",
     "chokidar": "^5.0.0",
     "debug": "^4.4.3",
@@ -36,7 +36,8 @@
     "picomatch": "^2.3.1",
     "fastify": "^4.29.1",
     "pino": "^10.3.1",
-    "socket.io-client": "^4.8.3"
+    "socket.io-client": "^4.8.3",
+    "@augmentd-labs/canvas-api-client": "^0.4.1"
   },
   "repository": {
     "type": "git",
@@ -46,6 +47,6 @@
   "bundleDependencies": [
     "canvas-stored"
   ],
-  "canvasRev": "0dbc541",
+  "canvasRev": "52fc07d",
   "canvasSource": "runtimes/edge"
 }

package/src/EdgeClient.js

@@ -1,129 +1 @@
-'use strict';
-
-import { io } from 'socket.io-client';
-
-const CHUNK_SIZE = 256 * 1024;
-
-/**
- * canvas-edge tunnel client.
- *
- * Dials out to a canvas-server instance, announces what this runtime hosts,
- * and replays proxied requests into the local fastify app (`app.inject()`),
- * so the tunnel and localhost serve identical APIs by construction.
- * Reconnection/backoff and heartbeat come from socket.io.
- *
- * See docs/canvas-edge-protocol.md for the frame protocol.
- */
-export default class EdgeClient {
-    #serverUrl;
-    #token;
-    #localApp;
-    #announce;
-    #socket = null;
-    #announced = false;
-    #forwarded = [];
-
-    constructor({ serverUrl, token, localApp, announce }) {
-        if (!serverUrl || !token || !localApp?.inject || !announce?.instanceId) {
-            throw new Error('EdgeClient requires serverUrl, token, localApp (fastify) and announce.instanceId');
-        }
-        this.#serverUrl = serverUrl.replace(/\/+$/, '');
-        this.#token = token;
-        this.#localApp = localApp;
-        this.#announce = announce;
-    }
-
-    /**
-   * One-time pairing: exchange a user API token for a device token via the
-   * existing device registration endpoint. Persist the result locally and
-   * never touch the user token again.
-   */
-    static async pair({ serverUrl, userToken, name, type = 'edge', ...deviceInfo }) {
-        const res = await fetch(`${serverUrl.replace(/\/+$/, '')}/rest/v2/auth/devices/register`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${userToken}` },
-            body: JSON.stringify({ name, type, ...deviceInfo }),
-        });
-        const json = await res.json().catch(() => null);
-        if (!res.ok || !json?.payload?.token) {
-            throw new Error(`Edge pairing failed: ${json?.message || res.statusText}`);
-        }
-        return { token: json.payload.token, deviceId: json.payload.deviceId || json.payload.id };
-    }
-
-    get connected() {
-        return this.#socket?.connected === true;
-    }
-
-    connect() {
-        if (this.#socket) return this;
-        this.#socket = io(this.#serverUrl, {
-            auth: { token: this.#token },
-            transports: ['websocket'],
-        });
-        // Announce on every (re)connect — announce is idempotent full state.
-        this.#socket.on('connect', () => this.#socket.emit('edge:announce', this.#announce));
-        this.#socket.on('edge:announced', () => { this.#announced = true; });
-        this.#socket.on('disconnect', () => { this.#announced = false; });
-        this.#socket.on('edge:req', (frame) => this.handleRequest(frame));
-        return this;
-    }
-
-    /** Resolves once the server has acked the announce; rejects on timeout. */
-    waitForAnnounce(timeoutMs = 10_000) {
-        if (this.#announced) return Promise.resolve();
-        if (!this.#socket) return Promise.reject(new Error('not connected — call connect() first'));
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.#socket?.off('edge:announced', onAck);
-                reject(new Error(`edge announce not acked within ${timeoutMs}ms`));
-            }, timeoutMs);
-            const onAck = () => { clearTimeout(timer); resolve(); };
-            this.#socket.once('edge:announced', onAck);
-        });
-    }
-
-    /**
-   * Dispatch a proxied request into the local app and stream the answer back.
-   * `socket` is injectable for tests.
-   */
-    async handleRequest(frame = {}, socket = this.#socket) {
-        const { id, method, path, headers = {}, body, bodyEncoding } = frame;
-        if (!id || !method || !path) return;
-        try {
-            const payload = body == null
-                ? undefined
-                : (bodyEncoding === 'base64' ? Buffer.from(body, 'base64') : body);
-            const res = await this.#localApp.inject({ method, url: path, headers, payload });
-            socket.emit('edge:res', { id, status: res.statusCode, headers: res.headers });
-            const buf = res.rawPayload;
-            for (let offset = 0, seq = 0; offset < buf.length; offset += CHUNK_SIZE, seq++) {
-                socket.emit('edge:chunk', { id, seq, data: buf.subarray(offset, offset + CHUNK_SIZE).toString('base64') });
-            }
-            socket.emit('edge:end', { id });
-        } catch (err) {
-            socket.emit('edge:err', { id, code: 'EDGE_DISPATCH_FAILED', message: err.message });
-        }
-    }
-
-    /**
-   * Relay all events from a local wildcard emitter (EventEmitter2) up the
-   * tunnel; the server re-emits them through its WorkspaceManager.
-   */
-    forwardEvents(emitter) {
-        const socket = () => this.#socket;
-        const listener = function (payload) {
-            socket()?.emit('edge:event', { name: this.event, payload });
-        };
-        emitter.on('**', listener);
-        this.#forwarded.push([emitter, listener]);
-        return this;
-    }
-
-    close() {
-        for (const [emitter, listener] of this.#forwarded) emitter.off('**', listener);
-        this.#forwarded = [];
-        this.#socket?.disconnect();
-        this.#socket = null;
-    }
-}
+export { default } from '@augmentd-labs/canvas-api-client/edge';

package/src/env.js

@@ -1,5 +1,6 @@
 'use strict';
 
+import { resolveTls } from '@augmentd-labs/canvas-api-client/tls';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -81,7 +82,7 @@ export function ensureEnvConfig(env = process.env) {
     const prior = remotes[hubId] || {};
     // A device token minted for this remote stays authoritative; env only
     // seeds the user/API token it started from.
-    remotes[hubId] = { ...prior, url, apiBase: prior.apiBase || '/rest/v2', auth: { ...(prior.auth || {}), token }, source: 'env' };
+    remotes[hubId] = { ...prior, url, apiBase: prior.apiBase || '/rest/v2', auth: { ...(prior.auth || {}), token }, source: 'env', ...(resolveTls(prior.url && new URL(prior.url).origin !== new URL(url).origin ? undefined : prior.tls, env) ? { tls: resolveTls(prior.url && new URL(prior.url).origin !== new URL(url).origin ? undefined : prior.tls, env) } : { tls: undefined }) };
     writeJson(EDGE_PATHS.remotes, remotes);
 
     const cfg = readJson(EDGE_PATHS.mirrors, { version: 1, mirrors: [] }) || { version: 1, mirrors: [] };
@@ -142,7 +143,7 @@ export async function ensureDeviceToken(remoteId, { logger = null } = {}) {
     if (!r?.url || r.source !== 'env' || r.device?.token || !r.auth?.token) return hubFor(remoteId);
     const identity = deviceIdentity(null);
     const paired = await EdgeClient.pair({
-        serverUrl: r.url, userToken: r.auth.token, name: identity.deviceName, type: 'edge',
+        serverUrl: r.url, tls: resolveTls(r.tls), userToken: r.auth.token, name: identity.deviceName, type: 'edge',
         deviceId: identity.deviceId, hostname: os.hostname(), platform: process.platform, arch: process.arch,
     });
     remotes[remoteId] = { ...r, device: { deviceId: paired.deviceId || identity.deviceId, token: paired.token, registeredAt: new Date().toISOString() } };
@@ -161,6 +162,7 @@ export function hubFor(remoteId) {
     return {
         id: remoteId,
         url: String(r.url).replace(/\/+$/, ''),
+        tls: resolveTls(r.tls),
         apiBase: r.apiBase || '/rest/v2',
         token,
         deviceId: deviceToken && r.device?.deviceId ? String(r.device.deviceId) : null,

package/src/mirror-runtime.js

@@ -1,5 +1,6 @@
 'use strict';
 
+import { createTlsTransport } from '@augmentd-labs/canvas-api-client/tls';
 import fs from 'fs';
 import path from 'path';
 import { io } from 'socket.io-client';
@@ -29,6 +30,7 @@ const STATUS_HEARTBEAT_MS = 60000;
  * ledger as `full` so a hub that lost its replica table rebuilds it.
  */
 export class MirrorRuntime {
+    #transport;
     #mirror;
     #hub;
     #identity;
@@ -45,6 +47,7 @@ export class MirrorRuntime {
     constructor({ mirror, hub, identity, logger }) {
         this.#mirror = mirror;
         this.#hub = hub;
+        this.#transport = createTlsTransport(hub.url, hub.tls);
         this.#identity = identity;
         this.#logger = logger;
     }
@@ -87,6 +90,7 @@ export class MirrorRuntime {
         this.#stored.addBackend('trash', { driver: 'file', root: path.join(internal, 'trash'), watch: false });
         this.#stored.addBackend('conflicts', { driver: 'file', root: path.join(internal, 'conflicts'), watch: false });
         this.#stored.addBackend('canvas:hub', {
+            fetch: this.#transport.fetch,
             driver: 'canvas', url: this.#hub.url, apiBase: this.#hub.apiBase, token: this.#hub.token,
             workspaceId: this.#mirror.workspaceId || this.#mirror.workspaceName, backend: 'workspace:home',
             deviceId: this.#identity.deviceId, deviceName: this.#identity.deviceName, prefixes: this.#mirror.pins || [], pollInterval: 30000,
@@ -113,6 +117,7 @@ export class MirrorRuntime {
     }
 
     async stop() {
+        // Close pooled TLS connections after stopping mirror activity below.
         clearInterval(this.#reporter);
         clearTimeout(this.#reportTimer);
         this.#socket?.close();
@@ -121,6 +126,7 @@ export class MirrorRuntime {
         await this.#stored?.stop().catch(() => {});
         this.#engine = null;
         this.#stored = null;
+        await this.#transport.dispose();
     }
 
     status() {
@@ -133,7 +139,7 @@ export class MirrorRuntime {
 
     async #fetchHubExclusions() {
         try {
-            const res = await fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${encodeURIComponent(this.#mirror.workspaceName)}/backends/file/workspace%3Ahome`, {
+            const res = await this.#transport.fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${encodeURIComponent(this.#mirror.workspaceName)}/backends/file/workspace%3Ahome`, {
                 headers: { authorization: `Bearer ${this.#hub.token}` },
             });
             const json = await res.json();
@@ -147,7 +153,7 @@ export class MirrorRuntime {
     async #resolveWorkspaceId() {
         if (this.#mirror.workspaceId && /^[0-9a-f-]{36}$/i.test(this.#mirror.workspaceId)) return this.#mirror.workspaceId;
         try {
-            const res = await fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${encodeURIComponent(this.#mirror.workspaceName)}`, { headers: { authorization: `Bearer ${this.#hub.token}` } });
+            const res = await this.#transport.fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${encodeURIComponent(this.#mirror.workspaceName)}`, { headers: { authorization: `Bearer ${this.#hub.token}` } });
             const json = await res.json();
             return json?.payload?.workspace?.id || json?.payload?.id || this.#mirror.workspaceId || this.#mirror.workspaceName;
         } catch { return this.#mirror.workspaceId || this.#mirror.workspaceName; }
@@ -156,7 +162,7 @@ export class MirrorRuntime {
     async #connectSocket() {
         try {
             const wsId = await this.#resolveWorkspaceId();
-            const socket = io(this.#hub.url, { auth: { token: this.#hub.token }, transports: ['websocket'], reconnection: true, reconnectionDelay: 1000, reconnectionDelayMax: 30000 });
+            const socket = io(this.#hub.url, { ...this.#transport.socketOptions, auth: { token: this.#hub.token }, transports: this.#transport.socketOptions.transports || ['websocket'], reconnection: true, reconnectionDelay: 1000, reconnectionDelayMax: 30000 });
             this.#socket = socket;
             socket.on('connect', () => { socket.emit('subscribe', { channel: `workspace:${wsId}` }); this.resync().catch(() => {}); });
             socket.on('backend.changed', (e) => { if (!e?.backend || e.backend === 'workspace:home') this.nudge(); });
@@ -188,7 +194,7 @@ export class MirrorRuntime {
         this.#pendingApplied = full ? [] : mergePairs(this.#pendingApplied, delta);
         const applied = full ? (typeof engine.appliedSnapshot === 'function' ? engine.appliedSnapshot() : []) : this.#pendingApplied;
         try {
-            const res = await fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${ws}/mirrors/${encodeURIComponent(this.#identity.deviceId)}/status`, {
+            const res = await this.#transport.fetch(`${this.#hub.url}${this.#hub.apiBase}/workspaces/${ws}/mirrors/${encodeURIComponent(this.#identity.deviceId)}/status`, {
                 method: 'POST',
                 headers: { authorization: `Bearer ${this.#hub.token}`, 'content-type': 'application/json' },
                 body: JSON.stringify({

package/src/remote-config.js

@@ -1,5 +1,6 @@
 'use strict';
 
+import { normalizeTls } from '@augmentd-labs/canvas-api-client/tls';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -18,7 +19,8 @@ import path from 'node:path';
  */
 
 export function workspaceConfigPath(dir) {
-    return path.join(dir, 'workspace.json');
+    const home = path.join(dir, '.workspace', 'workspace.json');
+    return fs.existsSync(home) ? home : path.join(dir, 'workspace.json');
 }
 
 export function readWorkspaceConfig(dir) {
@@ -35,11 +37,12 @@ export function listRemotes(config = {}) {
             url: remote.url.replace(/\/+$/, ''),
             token: remote.token,
             enabled: remote.enabled !== false,
+            ...(remote.tls ? { tls: normalizeTls(remote.tls) } : {}),
         }));
 }
 
 /** Add or update (matched by url) a remote entry, persisting workspace.json. */
-export function saveRemote(dir, { url, token, enabled = true }) {
+export function saveRemote(dir, { url, token, enabled = true, tls }) {
     if (!url || !token) throw new Error('remote requires url and token');
     const file = workspaceConfigPath(dir);
     const config = readWorkspaceConfig(dir);
@@ -50,8 +53,9 @@ export function saveRemote(dir, { url, token, enabled = true }) {
         existing.url = normalizedUrl;
         existing.token = token;
         existing.enabled = enabled;
+        if (tls !== undefined) existing.tls = normalizeTls(tls);
     } else {
-        remotes.push({ url: normalizedUrl, token, enabled });
+        remotes.push({ url: normalizedUrl, token, enabled, ...(tls ? { tls: normalizeTls(tls) } : {}) });
     }
     config.remotes = remotes;
     fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');

package/src/runtime.js

@@ -45,6 +45,7 @@ export function connectRemotes({ dir, localApp, events, clientFactory } = {}) {
             const client = createClient({
                 serverUrl: remote.url,
                 token: remote.token,
+                tls: remote.tls,
                 localApp,
                 announce,
             });