@privateclaw/privateclaw-relay 0.1.0

package/.env.example

@@ -0,0 +1,13 @@
+PRIVATECLAW_RELAY_HOST=127.0.0.1
+PRIVATECLAW_RELAY_PORT=8787
+PRIVATECLAW_SESSION_TTL_MS=900000
+PRIVATECLAW_FRAME_CACHE_SIZE=25
+# Optional: enable background wake through Firebase Cloud Messaging.
+# Use either the full service-account JSON...
+# PRIVATECLAW_FCM_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"your-project","client_email":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"}
+# ...or the split fields below.
+# PRIVATECLAW_FCM_PROJECT_ID=
+# PRIVATECLAW_FCM_CLIENT_EMAIL=
+# PRIVATECLAW_FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+# Optional: encrypted frame cache only
+# PRIVATECLAW_REDIS_URL=redis://127.0.0.1:6379

package/README.md

@@ -0,0 +1,86 @@
+# `@privateclaw/privateclaw-relay`
+
+`@privateclaw/privateclaw-relay` is the standalone relay package for PrivateClaw.
+
+It starts the local blind WebSocket relay used by the PrivateClaw provider and app, and it can optionally expose that local relay to the public internet with one command through:
+
+- Tailscale Funnel
+- Cloudflare quick tunnels
+
+## Install
+
+```bash
+npm install -g @privateclaw/privateclaw-relay
+```
+
+Or run it directly without a global install:
+
+```bash
+npx @privateclaw/privateclaw-relay
+```
+
+## Usage
+
+Start a local relay with the default `127.0.0.1:8787` binding:
+
+```bash
+privateclaw-relay
+```
+
+If the default local port `8787` is already occupied, the CLI automatically retries the next free port and prints the final listening URL.
+
+Override the bind address or Redis URL:
+
+```bash
+privateclaw-relay --host 0.0.0.0 --port 8787
+privateclaw-relay --redis-url redis://127.0.0.1:6379
+```
+
+Expose the local relay to the internet through Tailscale Funnel:
+
+```bash
+privateclaw-relay --public tailscale
+```
+
+Expose the local relay through a temporary Cloudflare quick tunnel:
+
+```bash
+privateclaw-relay --public cloudflare
+```
+
+If the required `tailscale` or `cloudflared` CLI is missing, `privateclaw-relay` prints platform-aware install commands. In an interactive terminal it can also offer to run the supported install/setup commands for you before retrying the tunnel startup.
+
+## Tunnel notes
+
+### Tailscale Funnel
+
+- Requires the `tailscale` CLI to be installed and authenticated locally.
+- Requires Funnel to be enabled for your tailnet.
+- The CLI uses `tailscale funnel --bg <port>` and prints the detected public URL when available.
+- If this CLI created the Funnel endpoint itself, it will try to disable it again on shutdown with `tailscale funnel off`.
+- If `tailscale` is missing, the CLI can offer Homebrew / winget / Linux installer guidance and, on supported setups, run the install flow interactively before retrying Funnel startup.
+
+### Cloudflare Tunnel
+
+- Requires the `cloudflared` CLI to be installed locally.
+- Uses a temporary quick tunnel with `cloudflared tunnel --url http://127.0.0.1:<port>`.
+- Quick tunnels use a random `trycloudflare.com` URL and are intended for temporary sharing and testing.
+- If `cloudflared` is missing, the CLI prints platform-aware install guidance and can offer an interactive install on supported setups such as Homebrew or winget.
+
+## Environment variables
+
+The relay still reads its runtime config from the process environment:
+
+- `PRIVATECLAW_RELAY_HOST`
+- `PRIVATECLAW_RELAY_PORT`
+- `PRIVATECLAW_SESSION_TTL_MS`
+- `PRIVATECLAW_FRAME_CACHE_SIZE`
+- `PRIVATECLAW_RELAY_INSTANCE_ID`
+- `PRIVATECLAW_REDIS_URL`
+- `REDIS_URL`
+- `PRIVATECLAW_FCM_SERVICE_ACCOUNT_JSON`
+- `PRIVATECLAW_FCM_PROJECT_ID`
+- `PRIVATECLAW_FCM_CLIENT_EMAIL`
+- `PRIVATECLAW_FCM_PRIVATE_KEY`
+
+See the repository root `README.md` for the larger deployment story, Docker images, Railway configs, and Redis-backed HA notes.

package/dist/cli-error.d.ts

@@ -0,0 +1,3 @@
+export declare class RelayCliUserError extends Error {
+    constructor(message: string);
+}

package/dist/cli-error.js

@@ -0,0 +1,7 @@
+export class RelayCliUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RelayCliUserError";
+    }
+}
+//# sourceMappingURL=cli-error.js.map

package/dist/cli-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-error.js","sourceRoot":"","sources":["../src/cli-error.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { RelayCliUserError } from "./cli-error.js";
+import { runRelayCli } from "./relay-cli.js";
+try {
+    await runRelayCli(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof RelayCliUserError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    throw error;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,IAAI,CAAC;IACH,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;QACvC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface RelayServerConfig {
+    host: string;
+    port: number;
+    sessionTtlMs: number;
+    frameCacheSize: number;
+    instanceId?: string;
+    redisUrl?: string;
+    fcmServiceAccountJson?: string;
+    fcmProjectId?: string;
+    fcmClientEmail?: string;
+    fcmPrivateKey?: string;
+}
+export declare function loadRelayConfig(env?: NodeJS.ProcessEnv): RelayServerConfig;

package/dist/config.js

@@ -0,0 +1,36 @@
+function parsePositiveInteger(value, fallback, label) {
+    if (!value || value.trim() === "") {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return parsed;
+}
+export function loadRelayConfig(env = process.env) {
+    const host = env.PRIVATECLAW_RELAY_HOST?.trim() || "127.0.0.1";
+    const port = parsePositiveInteger(env.PRIVATECLAW_RELAY_PORT?.trim() || env.PORT?.trim(), 8787, "PRIVATECLAW_RELAY_PORT");
+    const sessionTtlMs = parsePositiveInteger(env.PRIVATECLAW_SESSION_TTL_MS, 15 * 60 * 1000, "PRIVATECLAW_SESSION_TTL_MS");
+    const frameCacheSize = parsePositiveInteger(env.PRIVATECLAW_FRAME_CACHE_SIZE, 25, "PRIVATECLAW_FRAME_CACHE_SIZE");
+    const instanceId = env.PRIVATECLAW_RELAY_INSTANCE_ID?.trim() ||
+        env.RAILWAY_REPLICA_ID?.trim();
+    const redisUrl = env.PRIVATECLAW_REDIS_URL?.trim() || env.REDIS_URL?.trim();
+    const fcmServiceAccountJson = env.PRIVATECLAW_FCM_SERVICE_ACCOUNT_JSON?.trim();
+    const fcmProjectId = env.PRIVATECLAW_FCM_PROJECT_ID?.trim();
+    const fcmClientEmail = env.PRIVATECLAW_FCM_CLIENT_EMAIL?.trim();
+    const fcmPrivateKey = env.PRIVATECLAW_FCM_PRIVATE_KEY?.trim();
+    return {
+        host,
+        port,
+        sessionTtlMs,
+        frameCacheSize,
+        ...(instanceId ? { instanceId } : {}),
+        ...(redisUrl ? { redisUrl } : {}),
+        ...(fcmServiceAccountJson ? { fcmServiceAccountJson } : {}),
+        ...(fcmProjectId ? { fcmProjectId } : {}),
+        ...(fcmClientEmail ? { fcmClientEmail } : {}),
+        ...(fcmPrivateKey ? { fcmPrivateKey } : {}),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAaA,SAAS,oBAAoB,CAC3B,KAAyB,EACzB,QAAgB,EAChB,KAAa;IAEb,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAClC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,IAAI,GAAG,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC;IAC/D,MAAM,IAAI,GAAG,oBAAoB,CAC/B,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,EACtD,IAAI,EACJ,wBAAwB,CACzB,CAAC;IACF,MAAM,YAAY,GAAG,oBAAoB,CACvC,GAAG,CAAC,0BAA0B,EAC9B,EAAE,GAAG,EAAE,GAAG,IAAI,EACd,4BAA4B,CAC7B,CAAC;IACF,MAAM,cAAc,GAAG,oBAAoB,CACzC,GAAG,CAAC,4BAA4B,EAChC,EAAE,EACF,8BAA8B,CAC/B,CAAC;IACF,MAAM,UAAU,GACd,GAAG,CAAC,6BAA6B,EAAE,IAAI,EAAE;QACzC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC;IAC5E,MAAM,qBAAqB,GACzB,GAAG,CAAC,oCAAoC,EAAE,IAAI,EAAE,CAAC;IACnD,MAAM,YAAY,GAAG,GAAG,CAAC,0BAA0B,EAAE,IAAI,EAAE,CAAC;IAC5D,MAAM,cAAc,GAAG,GAAG,CAAC,4BAA4B,EAAE,IAAI,EAAE,CAAC;IAChE,MAAM,aAAa,GAAG,GAAG,CAAC,2BAA2B,EAAE,IAAI,EAAE,CAAC;IAE9D,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,YAAY;QACZ,cAAc;QACd,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/dist/frame-cache.d.ts

@@ -0,0 +1,77 @@
+import type { CachedRelayFrameTarget, EncryptedEnvelope } from "@privateclaw/protocol";
+export interface EncryptedFrameCache {
+    push(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        envelope: EncryptedEnvelope;
+        appId?: string;
+    }): Promise<void>;
+    drain(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        appId?: string;
+    }): Promise<EncryptedEnvelope[]>;
+    clearApp(sessionId: string, appId: string): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface RedisFrameCacheMultiLike {
+    lpush(key: string, value: string): RedisFrameCacheMultiLike;
+    ltrim(key: string, start: number, stop: number): RedisFrameCacheMultiLike;
+    expire(key: string, seconds: number): RedisFrameCacheMultiLike;
+    exec(): Promise<unknown>;
+}
+export interface RedisFrameCacheClientLike {
+    multi(): RedisFrameCacheMultiLike;
+    eval(script: string, numKeys: number, ...keysAndArgs: string[]): Promise<unknown>;
+    scan(cursor: string, matchToken: string, pattern: string, countToken: string, count: number): Promise<[string, string[]]>;
+    del(...keys: string[]): Promise<number>;
+    quit(): Promise<unknown>;
+}
+export declare class InMemoryEncryptedFrameCache implements EncryptedFrameCache {
+    private readonly maxFrames;
+    private readonly frames;
+    constructor(maxFrames: number);
+    private key;
+    push(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        envelope: EncryptedEnvelope;
+        appId?: string;
+    }): Promise<void>;
+    drain(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        appId?: string;
+    }): Promise<EncryptedEnvelope[]>;
+    clear(sessionId: string): Promise<void>;
+    clearApp(sessionId: string, appId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class RedisEncryptedFrameCache implements EncryptedFrameCache {
+    private readonly maxFrames;
+    private readonly redis;
+    constructor(redisUrl: string, maxFrames: number, redisClient?: RedisFrameCacheClientLike);
+    private key;
+    private normalizeRawFrameValue;
+    private drainSerializedFrames;
+    push(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        envelope: EncryptedEnvelope;
+        appId?: string;
+    }): Promise<void>;
+    drain(params: {
+        sessionId: string;
+        target: CachedRelayFrameTarget;
+        appId?: string;
+    }): Promise<EncryptedEnvelope[]>;
+    clear(sessionId: string): Promise<void>;
+    clearApp(sessionId: string, appId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createEncryptedFrameCache(params: {
+    redisUrl?: string;
+    maxFrames: number;
+}): EncryptedFrameCache;
+export declare function createInMemoryEncryptedFrameCache(maxFrames: number): EncryptedFrameCache;

package/dist/frame-cache.js

@@ -0,0 +1,127 @@
+import { Redis } from "ioredis";
+export class InMemoryEncryptedFrameCache {
+    maxFrames;
+    frames = new Map();
+    constructor(maxFrames) {
+        this.maxFrames = maxFrames;
+    }
+    key(sessionId, target, appId) {
+        return `${sessionId}:${target}:${appId ?? "*"}`;
+    }
+    async push(params) {
+        const key = this.key(params.sessionId, params.target, params.appId);
+        const next = [...(this.frames.get(key) ?? []), params.envelope];
+        const bounded = next.slice(-this.maxFrames);
+        this.frames.set(key, bounded);
+    }
+    async drain(params) {
+        const globalKey = this.key(params.sessionId, params.target);
+        if (params.target !== "app" || !params.appId) {
+            const frames = this.frames.get(globalKey) ?? [];
+            this.frames.delete(globalKey);
+            return frames;
+        }
+        const targetedKey = this.key(params.sessionId, params.target, params.appId);
+        const globalFrames = this.frames.get(globalKey) ?? [];
+        const targetedFrames = this.frames.get(targetedKey) ?? [];
+        this.frames.delete(globalKey);
+        this.frames.delete(targetedKey);
+        return [...globalFrames, ...targetedFrames];
+    }
+    async clear(sessionId) {
+        const prefix = `${sessionId}:`;
+        for (const key of this.frames.keys()) {
+            if (key.startsWith(prefix)) {
+                this.frames.delete(key);
+            }
+        }
+    }
+    async clearApp(sessionId, appId) {
+        this.frames.delete(this.key(sessionId, "app", appId));
+    }
+    async close() {
+        this.frames.clear();
+    }
+}
+export class RedisEncryptedFrameCache {
+    maxFrames;
+    redis;
+    constructor(redisUrl, maxFrames, redisClient) {
+        this.maxFrames = maxFrames;
+        this.redis =
+            redisClient ??
+                new Redis(redisUrl, { lazyConnect: false, maxRetriesPerRequest: 1 });
+    }
+    key(sessionId, target, appId) {
+        return `privateclaw:frames:${sessionId}:${target}:${appId ?? "*"}`;
+    }
+    normalizeRawFrameValue(value) {
+        if (typeof value === "string") {
+            return value;
+        }
+        if (value instanceof Uint8Array) {
+            return Buffer.from(value).toString("utf8");
+        }
+        return String(value);
+    }
+    async drainSerializedFrames(key) {
+        const values = await this.redis.eval(`
+        local values = redis.call("lrange", KEYS[1], 0, -1)
+        redis.call("del", KEYS[1])
+        return values
+      `, 1, key);
+        if (!Array.isArray(values)) {
+            return [];
+        }
+        return values.map((value) => this.normalizeRawFrameValue(value)).reverse();
+    }
+    async push(params) {
+        const key = this.key(params.sessionId, params.target, params.appId);
+        await this.redis
+            .multi()
+            .lpush(key, JSON.stringify(params.envelope))
+            .ltrim(key, 0, this.maxFrames - 1)
+            .expire(key, 3600)
+            .exec();
+    }
+    async drain(params) {
+        const globalKey = this.key(params.sessionId, params.target);
+        if (params.target !== "app" || !params.appId) {
+            return (await this.drainSerializedFrames(globalKey))
+                .map((value) => JSON.parse(value));
+        }
+        const targetedKey = this.key(params.sessionId, params.target, params.appId);
+        const [globalValues, targetedValues] = await Promise.all([
+            this.drainSerializedFrames(globalKey),
+            this.drainSerializedFrames(targetedKey),
+        ]);
+        return [...globalValues, ...targetedValues].map((value) => JSON.parse(value));
+    }
+    async clear(sessionId) {
+        const match = `privateclaw:frames:${sessionId}:*`;
+        let cursor = "0";
+        do {
+            const [nextCursor, keys] = await this.redis.scan(cursor, "MATCH", match, "COUNT", 100);
+            if (keys.length > 0) {
+                await this.redis.del(...keys);
+            }
+            cursor = nextCursor;
+        } while (cursor !== "0");
+    }
+    async clearApp(sessionId, appId) {
+        await this.redis.del(this.key(sessionId, "app", appId));
+    }
+    async close() {
+        await this.redis.quit();
+    }
+}
+export function createEncryptedFrameCache(params) {
+    if (params.redisUrl) {
+        return new RedisEncryptedFrameCache(params.redisUrl, params.maxFrames);
+    }
+    return new InMemoryEncryptedFrameCache(params.maxFrames);
+}
+export function createInMemoryEncryptedFrameCache(maxFrames) {
+    return new InMemoryEncryptedFrameCache(maxFrames);
+}
+//# sourceMappingURL=frame-cache.js.map

package/dist/frame-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-cache.js","sourceRoot":"","sources":["../src/frame-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAyChC,MAAM,OAAO,2BAA2B;IAGT;IAFZ,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEjE,YAA6B,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;IAE1C,GAAG,CACT,SAAiB,EACjB,MAA8B,EAC9B,KAAc;QAEd,OAAO,GAAG,SAAS,IAAI,MAAM,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAKV;QACC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAIX;QACC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACtD,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,YAAY,EAAE,GAAG,cAAc,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACrC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,KAAa;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF;AAED,MAAM,OAAO,wBAAwB;IAKhB;IAJF,KAAK,CAA4B;IAElD,YACE,QAAgB,EACC,SAAiB,EAClC,WAAuC;QADtB,cAAS,GAAT,SAAS,CAAQ;QAGlC,IAAI,CAAC,KAAK;YACR,WAAW;gBACX,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAEO,GAAG,CACT,SAAiB,EACjB,MAA8B,EAC9B,KAAc;QAEd,OAAO,sBAAsB,SAAS,IAAI,MAAM,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;IACrE,CAAC;IAEO,sBAAsB,CAAC,KAAc;QAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,qBAAqB,CAAC,GAAW;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAClC;;;;OAIC,EACD,CAAC,EACD,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAKV;QACC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,IAAI,CAAC,KAAK;aACb,KAAK,EAAE;aACP,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;aAC3C,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;aACjC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC;aACjB,IAAI,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAIX;QACC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC7C,OAAO,CAAC,MAAM,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;iBACjD,GAAG,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAsB,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACvD,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC;YACrC,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC;SACxC,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,YAAY,EAAE,GAAG,cAAc,CAAC,CAAC,GAAG,CAC7C,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAsB,CAC1D,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,KAAK,GAAG,sBAAsB,SAAS,IAAI,CAAC;QAClD,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,GAAG,CAAC;YACF,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;YACvF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YAChC,CAAC;YACD,MAAM,GAAG,UAAU,CAAC;QACtB,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,KAAa;QAC7C,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CAAC,MAGzC;IACC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,2BAA2B,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,SAAiB;IACjE,OAAO,IAAI,2BAA2B,CAAC,SAAS,CAAC,CAAC;AACpD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./config.js";
+export * from "./relay-server.js";
+export * from "./tunnel.js";
+export * from "./tunnel-installer.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./config.js";
+export * from "./relay-server.js";
+export * from "./tunnel.js";
+export * from "./tunnel-installer.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dist/push-notifier.d.ts

@@ -0,0 +1,36 @@
+import type { RelayPushRegistrationRecord } from "./push-registration-store.js";
+interface FcmServiceAccountCredentials {
+    projectId: string;
+    clientEmail: string;
+    privateKey: string;
+}
+export interface RelayPushSendResult {
+    unregisterToken: boolean;
+}
+export interface RelayPushNotifier {
+    readonly enabled: boolean;
+    sendWake(registration: RelayPushRegistrationRecord): Promise<RelayPushSendResult>;
+    close(): Promise<void>;
+}
+export declare class NoopRelayPushNotifier implements RelayPushNotifier {
+    readonly enabled = false;
+    sendWake(): Promise<RelayPushSendResult>;
+    close(): Promise<void>;
+}
+export declare class FcmRelayPushNotifier implements RelayPushNotifier {
+    private readonly credentials;
+    readonly enabled = true;
+    private accessToken;
+    private accessTokenExpiresAt;
+    constructor(credentials: FcmServiceAccountCredentials);
+    private getAccessToken;
+    sendWake(registration: RelayPushRegistrationRecord): Promise<RelayPushSendResult>;
+    close(): Promise<void>;
+}
+export declare function createRelayPushNotifier(params: {
+    fcmServiceAccountJson?: string | undefined;
+    fcmProjectId?: string | undefined;
+    fcmClientEmail?: string | undefined;
+    fcmPrivateKey?: string | undefined;
+}): RelayPushNotifier;
+export {};

package/dist/push-notifier.js

@@ -0,0 +1,198 @@
+import { createSign } from "node:crypto";
+const GOOGLE_FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+const GOOGLE_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+export class NoopRelayPushNotifier {
+    enabled = false;
+    async sendWake() {
+        return { unregisterToken: false };
+    }
+    async close() { }
+}
+function encodeBase64Url(value) {
+    return Buffer.from(value, "utf8")
+        .toString("base64")
+        .replaceAll("=", "")
+        .replaceAll("+", "-")
+        .replaceAll("/", "_");
+}
+function createJwtAssertion(credentials) {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const header = encodeBase64Url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+    const payload = encodeBase64Url(JSON.stringify({
+        iss: credentials.clientEmail,
+        scope: GOOGLE_FCM_SCOPE,
+        aud: GOOGLE_OAUTH_TOKEN_URL,
+        iat: nowSeconds,
+        exp: nowSeconds + 3600,
+    }));
+    const unsigned = `${header}.${payload}`;
+    const signer = createSign("RSA-SHA256");
+    signer.update(unsigned);
+    signer.end();
+    const signature = signer
+        .sign(credentials.privateKey, "base64")
+        .replaceAll("=", "")
+        .replaceAll("+", "-")
+        .replaceAll("/", "_");
+    return `${unsigned}.${signature}`;
+}
+function parseJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+    }
+    catch { }
+    return undefined;
+}
+function parseServiceAccountFromJson(rawValue) {
+    if (!rawValue) {
+        return undefined;
+    }
+    const parsed = parseJsonObject(rawValue);
+    const projectId = parsed?.project_id;
+    const clientEmail = parsed?.client_email;
+    const privateKey = parsed?.private_key;
+    if (typeof projectId !== "string" ||
+        projectId.trim() === "" ||
+        typeof clientEmail !== "string" ||
+        clientEmail.trim() === "" ||
+        typeof privateKey !== "string" ||
+        privateKey.trim() === "") {
+        throw new Error("PRIVATECLAW_FCM_SERVICE_ACCOUNT_JSON must include project_id, client_email, and private_key.");
+    }
+    return {
+        projectId: projectId.trim(),
+        clientEmail: clientEmail.trim(),
+        privateKey: privateKey.replaceAll("\\n", "\n"),
+    };
+}
+function readFcmCredentials(params) {
+    const fromJson = parseServiceAccountFromJson(params.fcmServiceAccountJson);
+    if (fromJson) {
+        return fromJson;
+    }
+    const projectId = params.fcmProjectId?.trim();
+    const clientEmail = params.fcmClientEmail?.trim();
+    const privateKey = params.fcmPrivateKey?.trim();
+    if (!projectId && !clientEmail && !privateKey) {
+        return undefined;
+    }
+    if (!projectId || !clientEmail || !privateKey) {
+        throw new Error("PRIVATECLAW_FCM_PROJECT_ID, PRIVATECLAW_FCM_CLIENT_EMAIL, and PRIVATECLAW_FCM_PRIVATE_KEY must be provided together.");
+    }
+    return {
+        projectId,
+        clientEmail,
+        privateKey: privateKey.replaceAll("\\n", "\n"),
+    };
+}
+function toErrorMessage(status, payload) {
+    const remoteMessage = payload?.error?.message;
+    if (typeof remoteMessage === "string" && remoteMessage.trim() !== "") {
+        return `FCM request failed (${status}): ${remoteMessage}`;
+    }
+    return `FCM request failed with HTTP ${status}.`;
+}
+function shouldUnregisterToken(payload) {
+    const details = payload?.error?.details;
+    if (!Array.isArray(details)) {
+        return false;
+    }
+    return details.some((detail) => detail?.errorCode === "UNREGISTERED");
+}
+export class FcmRelayPushNotifier {
+    credentials;
+    enabled = true;
+    accessToken;
+    accessTokenExpiresAt = 0;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    async getAccessToken() {
+        if (this.accessToken &&
+            this.accessTokenExpiresAt > Date.now() + 60_000) {
+            return this.accessToken;
+        }
+        const assertion = createJwtAssertion(this.credentials);
+        const response = await fetch(GOOGLE_OAUTH_TOKEN_URL, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                assertion,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to obtain Google OAuth token (${response.status}).`);
+        }
+        const payload = (await response.json());
+        if (typeof payload.access_token !== "string" ||
+            typeof payload.expires_in !== "number") {
+            throw new Error("Google OAuth token response is missing access token data.");
+        }
+        this.accessToken = payload.access_token;
+        this.accessTokenExpiresAt =
+            Date.now() + Math.max(payload.expires_in * 1000, 60_000);
+        return this.accessToken;
+    }
+    async sendWake(registration) {
+        const accessToken = await this.getAccessToken();
+        const response = await fetch(`https://fcm.googleapis.com/v1/projects/${this.credentials.projectId}/messages:send`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                message: {
+                    token: registration.token,
+                    data: {
+                        type: "privateclaw.wake",
+                        sessionId: registration.sessionId,
+                        appId: registration.appId,
+                    },
+                    android: {
+                        priority: "high",
+                        ttl: "30s",
+                        collapseKey: registration.sessionId,
+                    },
+                    apns: {
+                        headers: {
+                            "apns-push-type": "background",
+                            "apns-priority": "5",
+                            "apns-collapse-id": registration.sessionId,
+                        },
+                        payload: {
+                            aps: {
+                                "content-available": 1,
+                            },
+                        },
+                    },
+                },
+            }),
+        });
+        if (response.ok) {
+            return { unregisterToken: false };
+        }
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch { }
+        if (shouldUnregisterToken(payload)) {
+            return { unregisterToken: true };
+        }
+        throw new Error(toErrorMessage(response.status, payload));
+    }
+    async close() { }
+}
+export function createRelayPushNotifier(params) {
+    const credentials = readFcmCredentials(params);
+    if (!credentials) {
+        return new NoopRelayPushNotifier();
+    }
+    return new FcmRelayPushNotifier(credentials);
+}
+//# sourceMappingURL=push-notifier.js.map