@zhanguym/chatroom 1.0.0

package/dist/plugins/cloud/api-client.js

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import { CLOUD_ENTITLEMENT_SCHEMA, CLOUD_HTTP_URL_SCHEMA, CLOUD_LEASE_SCHEMA, } from "./types.js";
+import { signDeviceProof } from "./device-proof.js";
+const customerSchema = z.object({ id: z.string().min(1) }).strict();
+const recoveryCredentialSchema = z
+    .object({
+    recoveryKey: z.string().regex(/^crr\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/),
+})
+    .strict();
+const sessionSchema = z
+    .object({
+    purchaseToken: z.string().min(24),
+    managementUrl: CLOUD_HTTP_URL_SCHEMA,
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+const statusSchema = z
+    .object({
+    managementSessionActive: z.boolean(),
+    entitlements: z.array(CLOUD_ENTITLEMENT_SCHEMA),
+    customer: customerSchema.nullable(),
+    publicPrefix: z.string().min(1).nullable(),
+})
+    .strict();
+const restoreSchema = z
+    .object({
+    entitlements: z.array(CLOUD_ENTITLEMENT_SCHEMA),
+    customer: customerSchema,
+    publicPrefix: z.string().min(1).nullable(),
+    recoveryKey: z.string().regex(/^crr\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/),
+})
+    .strict();
+export class CloudApiClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async createManagementSession(identity) {
+        const payload = { devicePublicKey: identity.devicePublicKey };
+        return sessionSchema.parse(await this.devicePost("/v1/device/session", "session", identity, payload));
+    }
+    async status(identity, purchaseToken) {
+        const payload = {
+            devicePublicKey: identity.devicePublicKey,
+            purchaseToken,
+        };
+        return statusSchema.parse(await this.devicePost("/v1/device/status", "status", identity, payload));
+    }
+    async restore(identity, recoveryKey) {
+        const payload = { devicePublicKey: identity.devicePublicKey, recoveryKey };
+        return restoreSchema.parse(await this.devicePost("/v1/device/restore", "restore", identity, payload));
+    }
+    async replaceRecoveryKey(identity) {
+        const payload = { devicePublicKey: identity.devicePublicKey };
+        return recoveryCredentialSchema.parse(await this.devicePost("/v1/device/recovery-key", "recovery-key", identity, payload));
+    }
+    async lease(identity, requestedServices) {
+        const payload = {
+            devicePublicKey: identity.devicePublicKey,
+            requestedServices,
+        };
+        return CLOUD_LEASE_SCHEMA.parse(await this.devicePost("/v1/device/lease", "lease", identity, payload));
+    }
+    async devicePost(path, operation, identity, payload) {
+        const proof = signDeviceProof({
+            operation,
+            installationId: identity.installationId,
+            devicePrivateKey: identity.devicePrivateKey,
+            payload,
+        });
+        const response = await fetch(new URL(path, `${this.baseUrl}/`), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify({
+                installationId: identity.installationId,
+                ...payload,
+                ...proof,
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const body = (await response.json().catch(() => null));
+        if (!response.ok) {
+            const message = typeof body === "object" &&
+                body &&
+                "message" in body &&
+                typeof body.message === "string"
+                ? body.message
+                : `ChatRoom Cloud request failed (${response.status})`;
+            const issues = typeof body === "object" &&
+                body &&
+                "issues" in body &&
+                Array.isArray(body.issues)
+                ? body.issues.flatMap((issue) => {
+                    if (!issue || typeof issue !== "object")
+                        return [];
+                    const path = "path" in issue && Array.isArray(issue.path)
+                        ? issue.path.join(".")
+                        : "";
+                    const detail = "message" in issue && typeof issue.message === "string"
+                        ? issue.message
+                        : "";
+                    return detail ? [`${path || "request"}: ${detail}`] : [];
+                })
+                : [];
+            throw new Error(issues.length ? `${message}: ${issues.join("; ")}` : message);
+        }
+        return body;
+    }
+}

package/dist/plugins/cloud/controller.d.ts

@@ -0,0 +1,58 @@
+import type { ChatRoomConfig } from "#config/types";
+import type { LogWriter } from "#core/logging/types";
+import { type CloudServiceId, type CloudStatus } from "./types.js";
+interface ExternalAccessSink {
+    setCloud(state: {
+        mcpBaseUrl: string | null;
+        webBaseUrl: string | null;
+    }): void;
+    clearCloud(): void;
+}
+export declare class CloudController {
+    private readonly config;
+    private readonly logs;
+    private readonly externalAccess;
+    private readonly store;
+    private readonly api;
+    private state;
+    private tunnel;
+    private connection;
+    private lastError;
+    private managementTimer;
+    private renewalTimer;
+    private statusRetryTimer;
+    private stopped;
+    private mutationQueue;
+    private constructor();
+    static create(config: ChatRoomConfig, logs: LogWriter, externalAccess: ExternalAccessSink): Promise<CloudController>;
+    status(): CloudStatus;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    managementUrl(): Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+    syncStatus(): Promise<CloudStatus>;
+    restore(recoveryKey: string): Promise<{
+        status: CloudStatus;
+        recoveryKey: string;
+    }>;
+    replaceRecoveryKey(): Promise<string>;
+    setService(service: CloudServiceId, enabled: boolean): Promise<CloudStatus>;
+    private syncStatusInternal;
+    private refreshLeaseIfNeeded;
+    private connectTunnel;
+    private recoverRejectedLease;
+    private publishExternalAccess;
+    private scheduleStatusRetry;
+    private scheduleManagementSync;
+    private scheduleRenewal;
+    private clearTimers;
+    private serial;
+    private validManagementSession;
+    private identity;
+    private ensureState;
+    private requireState;
+    private setError;
+}
+export {};

package/dist/plugins/cloud/controller.js

@@ -0,0 +1,425 @@
+import { ChatRoomError } from "#core/errors/chatroom-error";
+import { CloudApiClient } from "./api-client.js";
+import { CloudStateStore } from "./state-store.js";
+import { CloudTunnelClient } from "./tunnel-client.js";
+import { CLOUD_SERVICES, } from "./types.js";
+export class CloudController {
+    config;
+    logs;
+    externalAccess;
+    store;
+    api;
+    state = null;
+    tunnel = null;
+    connection = "inactive";
+    lastError = null;
+    managementTimer = null;
+    renewalTimer = null;
+    statusRetryTimer = null;
+    stopped = true;
+    mutationQueue = Promise.resolve();
+    constructor(config, cloudApi, logs, externalAccess) {
+        this.config = config;
+        this.logs = logs;
+        this.externalAccess = externalAccess;
+        this.store = new CloudStateStore(config.dataDir);
+        this.api = new CloudApiClient(cloudApi);
+    }
+    static async create(config, logs, externalAccess) {
+        const apiBaseUrl = (process.env.CHATROOM_CLOUD_API ?? "https://chatroomcp.com").replace(/\/$/, "");
+        const controller = new CloudController(config, apiBaseUrl, logs, externalAccess);
+        await controller.ensureState().catch(() => undefined);
+        return controller;
+    }
+    status() {
+        const state = this.state;
+        if (!state) {
+            return {
+                installationId: null,
+                customerId: null,
+                publicPrefix: null,
+                desiredServices: { remote_mcp: false, remote_web: false },
+                entitlements: [],
+                managementSessionActive: false,
+                connection: "error",
+                mcpUrl: null,
+                webUrl: null,
+                lastError: this.lastError ?? "ChatRoom Cloud is unavailable",
+            };
+        }
+        const lease = state.lease && Date.parse(state.lease.expiresAt) > Date.now()
+            ? state.lease
+            : null;
+        return {
+            installationId: state.installationId,
+            customerId: state.customerId,
+            publicPrefix: state.publicPrefix,
+            desiredServices: { ...state.desiredServices },
+            entitlements: [...state.entitlements],
+            managementSessionActive: Boolean(state.managementSession &&
+                Date.parse(state.managementSession.expiresAt) > Date.now()),
+            connection: this.connection,
+            mcpUrl: lease?.mcpBaseUrl ? `${lease.mcpBaseUrl}/mcp` : null,
+            webUrl: lease?.webBaseUrl ?? null,
+            lastError: this.lastError,
+        };
+    }
+    start() {
+        return this.serial(async () => {
+            if (!this.stopped)
+                return;
+            this.stopped = false;
+            if (!this.state)
+                return;
+            await this.syncStatusInternal().catch((error) => {
+                this.setError(error);
+                this.scheduleStatusRetry();
+            });
+            this.scheduleManagementSync();
+        });
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        return this.serial(async () => {
+            this.tunnel?.stop();
+            this.tunnel = null;
+            this.externalAccess.clearCloud();
+            if (this.state?.lease)
+                this.connection = "disconnected";
+        });
+    }
+    managementUrl() {
+        return this.serial(async () => {
+            const state = await this.ensureState();
+            const current = state.managementSession;
+            if (current && Date.parse(current.expiresAt) > Date.now()) {
+                return { url: current.managementUrl, expiresAt: current.expiresAt };
+            }
+            const session = await this.api.createManagementSession(this.identity());
+            this.state = {
+                ...state,
+                managementSession: {
+                    purchaseToken: session.purchaseToken,
+                    managementUrl: session.managementUrl,
+                    expiresAt: session.expiresAt,
+                },
+            };
+            await this.store.save(this.state);
+            this.scheduleManagementSync(0);
+            return { url: session.managementUrl, expiresAt: session.expiresAt };
+        });
+    }
+    syncStatus() {
+        return this.serial(() => this.syncStatusInternal());
+    }
+    restore(recoveryKey) {
+        return this.serial(async () => {
+            const state = await this.ensureState();
+            const previousEntitlements = state.entitlements;
+            const result = await this.api.restore(this.identity(), recoveryKey);
+            this.state = {
+                ...state,
+                customerId: result.customer.id,
+                publicPrefix: result.publicPrefix,
+                desiredServices: enableNewlyPurchasedServices(state.desiredServices, previousEntitlements.map((entry) => entry.service), result.entitlements.map((entry) => entry.service)),
+                entitlements: result.entitlements,
+                lease: null,
+            };
+            await this.store.save(this.state);
+            this.tunnel?.stop();
+            this.tunnel = null;
+            if (!this.stopped) {
+                await this.refreshLeaseIfNeeded(true);
+                this.connectTunnel();
+                this.scheduleRenewal();
+            }
+            this.lastError = null;
+            return { status: this.status(), recoveryKey: result.recoveryKey };
+        });
+    }
+    async replaceRecoveryKey() {
+        await this.ensureState();
+        const result = await this.api.replaceRecoveryKey(this.identity());
+        return result.recoveryKey;
+    }
+    setService(service, enabled) {
+        return this.serial(async () => {
+            const state = await this.ensureState();
+            if (!CLOUD_SERVICES.includes(service))
+                throw new Error(`Unknown Cloud service: ${service}`);
+            this.state = {
+                ...state,
+                desiredServices: { ...state.desiredServices, [service]: enabled },
+            };
+            await this.store.save(this.state);
+            if (!this.stopped) {
+                await this.refreshLeaseIfNeeded(true);
+                this.connectTunnel();
+                this.scheduleRenewal();
+            }
+            this.lastError = null;
+            return this.status();
+        });
+    }
+    async syncStatusInternal() {
+        const state = await this.ensureState();
+        const managementSession = this.validManagementSession();
+        const previousEntitlements = state.entitlements;
+        const previousPrefix = state.publicPrefix;
+        const result = await this.api.status(this.identity(), managementSession?.purchaseToken ?? null);
+        this.state = {
+            ...state,
+            customerId: result.customer?.id ?? null,
+            publicPrefix: result.publicPrefix,
+            desiredServices: enableNewlyPurchasedServices(state.desiredServices, previousEntitlements.map((entry) => entry.service), result.entitlements.map((entry) => entry.service)),
+            entitlements: result.entitlements,
+            managementSession: result.managementSessionActive
+                ? managementSession
+                : null,
+        };
+        await this.store.save(this.state);
+        if (!this.stopped) {
+            await this.refreshLeaseIfNeeded(previousPrefix !== null && previousPrefix !== result.publicPrefix);
+            this.connectTunnel();
+            this.scheduleRenewal();
+        }
+        this.lastError = null;
+        if (this.statusRetryTimer)
+            clearTimeout(this.statusRetryTimer);
+        this.statusRetryTimer = null;
+        return this.status();
+    }
+    async refreshLeaseIfNeeded(force) {
+        const state = this.requireState();
+        const entitled = new Set(state.entitlements.map((entry) => entry.service));
+        const requested = CLOUD_SERVICES.filter((service) => state.desiredServices[service] && entitled.has(service));
+        if (requested.length === 0) {
+            if (state.lease) {
+                this.state = { ...state, lease: null };
+                await this.store.save(this.state);
+            }
+            this.tunnel?.drainAndStop();
+            this.tunnel = null;
+            this.connection = "inactive";
+            this.publishExternalAccess();
+            return;
+        }
+        if (!state.publicPrefix) {
+            if (state.lease) {
+                this.state = { ...state, lease: null };
+                await this.store.save(this.state);
+            }
+            this.tunnel?.drainAndStop();
+            this.tunnel = null;
+            this.connection = "inactive";
+            this.publishExternalAccess();
+            return;
+        }
+        const current = state.lease;
+        const sameServices = current &&
+            requested.length === current.services.length &&
+            requested.every((service) => current.services.includes(service));
+        const fresh = current && Date.parse(current.expiresAt) - Date.now() > 15 * 60 * 1000;
+        if (!force && sameServices && fresh) {
+            this.publishExternalAccess();
+            return;
+        }
+        const lease = await this.api.lease(this.identity(), requested);
+        this.state = { ...state, lease };
+        await this.store.save(this.state);
+        this.publishExternalAccess();
+        this.tunnel?.updateLease(lease);
+    }
+    connectTunnel() {
+        const state = this.state;
+        if (this.stopped ||
+            this.tunnel ||
+            !state?.lease ||
+            state.lease.services.length === 0)
+            return;
+        this.connection = "connecting";
+        this.logs.info("cloud", "cloud.connecting", "Cloud tunnel is connecting", {
+            services: state.lease.services,
+        });
+        let tunnel;
+        tunnel = new CloudTunnelClient(state.lease, { devicePrivateKey: state.devicePrivateKey }, this.config.server, {
+            onConnected: () => {
+                this.lastError = null;
+                this.connection = "connected";
+                this.logs.info("cloud", "cloud.connected", "Cloud tunnel connected", {
+                    services: this.state?.lease?.services ?? [],
+                });
+            },
+            onDisconnected: () => {
+                if (!this.stopped && this.state?.lease) {
+                    this.connection = "disconnected";
+                    this.logs.warn("cloud", "cloud.disconnected", "Cloud tunnel disconnected");
+                }
+            },
+            onLeaseRejected: () => {
+                void this.recoverRejectedLease(tunnel);
+            },
+            onError: (error) => this.setError(error),
+        });
+        this.tunnel = tunnel;
+        tunnel.start();
+    }
+    recoverRejectedLease(tunnel) {
+        return this.serial(async () => {
+            if (this.stopped || this.tunnel !== tunnel || !this.state)
+                return;
+            tunnel.stop();
+            this.tunnel = null;
+            this.state = { ...this.state, lease: null };
+            await this.store.save(this.state);
+            this.connection = "connecting";
+            this.publishExternalAccess();
+            this.logs.warn("cloud", "cloud.lease-rejected", "Cloud lease was rejected; requesting a replacement");
+            try {
+                await this.refreshLeaseIfNeeded(true);
+                this.connectTunnel();
+                this.scheduleRenewal();
+            }
+            catch (error) {
+                this.setError(error);
+                this.scheduleStatusRetry();
+            }
+        });
+    }
+    publishExternalAccess() {
+        const state = this.state;
+        if (!state) {
+            this.externalAccess.clearCloud();
+            return;
+        }
+        const lease = state.lease;
+        const activeLease = lease && Date.parse(lease.expiresAt) > Date.now() ? lease : null;
+        this.externalAccess.setCloud({
+            mcpBaseUrl: activeLease?.services.includes("remote_mcp")
+                ? activeLease.mcpBaseUrl
+                : null,
+            webBaseUrl: activeLease?.services.includes("remote_web")
+                ? activeLease.webBaseUrl
+                : null,
+        });
+    }
+    scheduleStatusRetry(delayMs = 30_000) {
+        if (this.stopped || !this.state || this.statusRetryTimer)
+            return;
+        this.statusRetryTimer = setTimeout(() => {
+            this.statusRetryTimer = null;
+            void this.syncStatus().catch((error) => {
+                this.setError(error);
+                this.scheduleStatusRetry();
+            });
+        }, delayMs);
+        this.statusRetryTimer.unref();
+    }
+    scheduleManagementSync(delayMs = 3_000) {
+        if (this.managementTimer)
+            clearTimeout(this.managementTimer);
+        this.managementTimer = null;
+        if (this.stopped || !this.validManagementSession())
+            return;
+        this.managementTimer = setTimeout(() => {
+            this.managementTimer = null;
+            void this.syncStatus()
+                .catch((error) => this.setError(error))
+                .finally(() => this.scheduleManagementSync());
+        }, delayMs);
+        this.managementTimer.unref();
+    }
+    scheduleRenewal() {
+        if (this.renewalTimer)
+            clearTimeout(this.renewalTimer);
+        this.renewalTimer = null;
+        const lease = this.state?.lease;
+        if (this.stopped || !lease)
+            return;
+        const remaining = Date.parse(lease.expiresAt) - Date.now();
+        const delay = Math.max(60_000, remaining - (10 + Math.random() * 10) * 60_000);
+        this.renewalTimer = setTimeout(() => {
+            this.renewalTimer = null;
+            void this.serial(async () => {
+                if (this.stopped)
+                    return;
+                await this.refreshLeaseIfNeeded(true);
+                this.connectTunnel();
+            })
+                .catch((error) => this.setError(error))
+                .finally(() => this.scheduleRenewal());
+        }, delay);
+        this.renewalTimer.unref();
+    }
+    clearTimers() {
+        if (this.managementTimer)
+            clearTimeout(this.managementTimer);
+        if (this.renewalTimer)
+            clearTimeout(this.renewalTimer);
+        if (this.statusRetryTimer)
+            clearTimeout(this.statusRetryTimer);
+        this.managementTimer = null;
+        this.renewalTimer = null;
+        this.statusRetryTimer = null;
+    }
+    serial(action) {
+        const next = this.mutationQueue.then(action, action);
+        this.mutationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    validManagementSession() {
+        const value = this.state?.managementSession;
+        return value && Date.parse(value.expiresAt) > Date.now() ? value : null;
+    }
+    identity() {
+        const state = this.requireState();
+        return {
+            installationId: state.installationId,
+            devicePublicKey: state.devicePublicKey,
+            devicePrivateKey: state.devicePrivateKey,
+        };
+    }
+    async ensureState() {
+        if (this.state)
+            return this.state;
+        try {
+            this.state = await this.store.loadOrCreate();
+            this.lastError = null;
+            this.connection = "inactive";
+            this.publishExternalAccess();
+            return this.state;
+        }
+        catch (error) {
+            this.externalAccess.clearCloud();
+            const detail = error instanceof Error ? error.message : String(error);
+            this.lastError = `Cloud state unavailable: ${detail}`;
+            this.connection = "error";
+            this.logs.error("cloud", "cloud.state_unavailable", "Cloud state is unavailable", { error });
+            throw new ChatRoomError("INTERNAL", "ChatRoom Cloud is unavailable", { reason: "cloud_state_unavailable" }, error instanceof Error ? { cause: error } : undefined);
+        }
+    }
+    requireState() {
+        if (!this.state)
+            throw new ChatRoomError("INTERNAL", "ChatRoom Cloud is unavailable", {
+                reason: "cloud_state_unavailable",
+            });
+        return this.state;
+    }
+    setError(error) {
+        this.lastError = error instanceof Error ? error.message : String(error);
+        this.connection = "error";
+        this.logs.error("cloud", "cloud.error", "Cloud operation failed", {
+            error,
+        });
+    }
+}
+function enableNewlyPurchasedServices(desiredServices, previousEntitlements, currentEntitlements) {
+    const previous = new Set(previousEntitlements);
+    const current = new Set(currentEntitlements);
+    const next = { ...desiredServices };
+    for (const service of CLOUD_SERVICES)
+        if (!previous.has(service) && current.has(service))
+            next[service] = true;
+    return next;
+}

package/dist/plugins/cloud/device-proof.d.ts

@@ -0,0 +1,9 @@
+export declare function signDeviceProof(input: {
+    operation: string;
+    installationId: string;
+    devicePrivateKey: string;
+    payload: unknown;
+}): {
+    timestamp: string;
+    signature: string;
+};

package/dist/plugins/cloud/device-proof.js

@@ -0,0 +1,17 @@
+import { createHash, createPrivateKey, sign } from "node:crypto";
+export function signDeviceProof(input) {
+    const timestamp = new Date().toISOString();
+    const payloadHash = createHash("sha256")
+        .update(JSON.stringify(input.payload))
+        .digest("base64url");
+    const message = Buffer.from(`chatroom-cloud-device-v1\n${input.operation}\n${input.installationId}\n${timestamp}\n${payloadHash}`);
+    const key = createPrivateKey({
+        key: Buffer.from(input.devicePrivateKey, "base64url"),
+        format: "der",
+        type: "pkcs8",
+    });
+    return {
+        timestamp,
+        signature: sign(null, message, key).toString("base64url"),
+    };
+}

package/dist/plugins/cloud/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { InternalPlugin } from "#plugins/types";
+import { CloudController } from "./controller.js";
+export declare const CloudService: import("#plugins/types").ServiceToken<CloudController>;
+export declare function createCloudPlugin(): InternalPlugin;

package/dist/plugins/cloud/plugin.js

@@ -0,0 +1,17 @@
+import { createServiceToken } from "#plugins/types";
+import { CloudController } from "./controller.js";
+export const CloudService = createServiceToken("cloud");
+export function createCloudPlugin() {
+    let controller = null;
+    return {
+        id: "cloud",
+        async activate(context) {
+            controller = await CloudController.create(context.config, context.logs, context.externalAccess);
+            context.services.provide(CloudService, controller);
+        },
+        async deactivate() {
+            await controller?.stop();
+            controller = null;
+        },
+    };
+}

package/dist/plugins/cloud/state-store.d.ts

@@ -0,0 +1,7 @@
+import { type CloudPersistedState } from "./types.js";
+export declare class CloudStateStore {
+    readonly filePath: string;
+    constructor(dataDir: string);
+    loadOrCreate(): Promise<CloudPersistedState>;
+    save(state: CloudPersistedState): Promise<void>;
+}