@tapicker/bridge 1.0.0

package/dist/bridge/daemon.js

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { BridgeError } from '../errors.js';
+const BridgeDaemonStateSchema = z
+    .object({
+    pid: z.number().int().positive(),
+    bridgeId: z.uuid(),
+    httpUrl: z.url(),
+    startedAt: z.number().int().positive(),
+})
+    .strict();
+export function getBridgeDaemonStatePath(dataDir) {
+    return join(dataDir, 'bridge.pid');
+}
+export function getBridgeDaemonLogPath(dataDir) {
+    return join(dataDir, 'bridge.log');
+}
+export async function readBridgeDaemonState(dataDir) {
+    const filePath = getBridgeDaemonStatePath(dataDir);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (cause) {
+        throw new BridgeError('InvalidDaemonState', 'Saved Bridge process state is not valid JSON', {
+            status: 500,
+            cause,
+        });
+    }
+    const parsed = BridgeDaemonStateSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new BridgeError('InvalidDaemonState', 'Saved Bridge process state has an unsupported format', {
+            status: 500,
+            details: parsed.error.issues,
+        });
+    }
+    return parsed.data;
+}
+export async function writeBridgeDaemonState(dataDir, state) {
+    const filePath = getBridgeDaemonStatePath(dataDir);
+    const directory = dirname(filePath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporaryPath = join(directory, `.bridge-${process.pid}-${randomUUID()}.tmp`);
+    const content = JSON.stringify(state, null, 2);
+    let file;
+    try {
+        file = await open(temporaryPath, 'wx', 0o600);
+        await file.writeFile(content, 'utf8');
+        await file.sync();
+        await file.close();
+        file = undefined;
+        await rename(temporaryPath, filePath);
+    }
+    catch (error) {
+        await file?.close().catch(() => undefined);
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+export async function removeBridgeDaemonState(dataDir, expectedPid) {
+    const state = await readBridgeDaemonState(dataDir);
+    if (state?.pid !== expectedPid)
+        return;
+    try {
+        await unlink(getBridgeDaemonStatePath(dataDir));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+export function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ESRCH')
+            return false;
+        if (code === 'EPERM')
+            return true;
+        throw error;
+    }
+}
+//# sourceMappingURL=daemon.js.map

package/dist/bridge/extension-session.d.ts

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'node:events';
+import type { WebSocket } from 'ws';
+import type { ExtensionPairInput } from '../protocol/schema.js';
+export type ExtensionSessionStatus = {
+    connected: boolean;
+    ready: boolean;
+    pairingRequired?: boolean;
+    clientId?: string;
+    clientName?: string;
+    capabilities: string[];
+};
+export type ExtensionSessionOptions = {
+    bridgeVersion: string;
+    protocolVersion: number;
+    capabilities: string[];
+    remoteAddress: string;
+    verifyCredential: (clientId: string, credential: string) => boolean;
+    pair: (input: ExtensionPairInput, remoteAddress: string) => Promise<string>;
+};
+export declare class ExtensionSession extends EventEmitter {
+    private readonly socket;
+    private readonly options;
+    private ready;
+    private pairingRequired;
+    private clientId;
+    private clientName;
+    private capabilities;
+    private pendingRequests;
+    constructor(socket: WebSocket, options: ExtensionSessionOptions);
+    start(): void;
+    getStatus(): ExtensionSessionStatus;
+    request<T>(type: string, data: unknown, timeout?: number): Promise<T>;
+    close(code?: number, reason?: string): void;
+    private handleMessage;
+    private handleHello;
+    private handlePair;
+    private authorize;
+    private respond;
+    private send;
+    private rejectPending;
+    private reportError;
+}
+//# sourceMappingURL=extension-session.d.ts.map

package/dist/bridge/extension-session.js

@@ -0,0 +1,204 @@
+import { EventEmitter } from 'node:events';
+import { DEFAULT_REQUEST_TIMEOUT } from '../constants.js';
+import { BridgeError, safeError, safeSuccess } from '../errors.js';
+import { BridgeHelloDataSchema, BridgePairDataSchema, ExtensionHelloInputSchema, ExtensionPairInputSchema, SafeResultSchema, createEnvelope, parseEnvelope, } from '../protocol/schema.js';
+export class ExtensionSession extends EventEmitter {
+    socket;
+    options;
+    ready = false;
+    pairingRequired = false;
+    clientId;
+    clientName;
+    capabilities = [];
+    pendingRequests = new Map();
+    constructor(socket, options) {
+        super();
+        this.socket = socket;
+        this.options = options;
+    }
+    start() {
+        this.socket.on('message', (data) => void this.handleMessage(data).catch((error) => this.reportError(error)));
+        this.socket.on('error', (error) => this.reportError(error));
+        this.socket.on('close', (code, reason) => {
+            this.rejectPending(new BridgeError('ExtensionDisconnected', 'Tapicker Extension disconnected', { status: 503 }));
+            this.emit('close', { code, reason: reason.toString() });
+        });
+    }
+    getStatus() {
+        return {
+            connected: this.socket.readyState === this.socket.OPEN,
+            ready: this.ready,
+            pairingRequired: this.pairingRequired,
+            clientId: this.clientId,
+            clientName: this.clientName,
+            capabilities: this.ready ? this.capabilities : [],
+        };
+    }
+    request(type, data, timeout = DEFAULT_REQUEST_TIMEOUT) {
+        if (!this.ready || this.socket.readyState !== this.socket.OPEN) {
+            return Promise.reject(new BridgeError('ExtensionUnavailable', 'No paired Tapicker Extension is connected', { status: 503 }));
+        }
+        const envelope = createEnvelope(type, data);
+        const responseType = `${type}:res`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(envelope.id);
+                reject(new BridgeError('ExtensionRequestTimeout', `Extension did not respond to ${type}`, {
+                    status: 504,
+                    details: { timeout },
+                }));
+            }, timeout);
+            this.pendingRequests.set(envelope.id, {
+                type: responseType,
+                timer,
+                resolve: (value) => resolve(value),
+                reject,
+            });
+            try {
+                this.send(envelope);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pendingRequests.delete(envelope.id);
+                reject(error);
+            }
+        });
+    }
+    close(code = 1000, reason = 'Bridge session closed') {
+        if (this.socket.readyState === this.socket.OPEN || this.socket.readyState === this.socket.CONNECTING) {
+            this.socket.close(code, reason);
+        }
+    }
+    async handleMessage(raw) {
+        const parsed = parseEnvelope(raw);
+        if (!parsed.success) {
+            this.reportError(parsed.error);
+            return;
+        }
+        const message = parsed.data;
+        if (message.type === 'pong')
+            return;
+        const pending = this.pendingRequests.get(message.id);
+        if (pending && pending.type === message.type) {
+            this.pendingRequests.delete(message.id);
+            clearTimeout(pending.timer);
+            const result = SafeResultSchema.safeParse(message.data);
+            if (!result.success) {
+                pending.reject(new BridgeError('InvalidExtensionResponse', 'Extension returned an invalid response', { status: 502 }));
+            }
+            else if (result.data.ok) {
+                pending.resolve(result.data.data);
+            }
+            else {
+                pending.reject(new BridgeError(result.data.error.code, result.data.error.message, {
+                    status: 502,
+                    details: result.data.error.details,
+                }));
+            }
+            return;
+        }
+        if (message.type === 'ping') {
+            this.respond(message, 'pong', undefined);
+            return;
+        }
+        if (message.type === 'extension.hello') {
+            await this.handleHello(message);
+            return;
+        }
+        if (message.type === 'extension.pair') {
+            await this.handlePair(message);
+            return;
+        }
+        this.emit('message', message);
+    }
+    async handleHello(message) {
+        const parsed = ExtensionHelloInputSchema.safeParse(message.data);
+        if (!parsed.success) {
+            this.respond(message, `${message.type}:res`, safeError(new BridgeError('InvalidHello', 'Invalid Extension hello', {
+                status: 400,
+                details: parsed.error.issues,
+            })));
+            return;
+        }
+        const hello = parsed.data;
+        this.clientId = hello.clientId;
+        this.clientName = hello.clientName;
+        this.capabilities = hello.capabilities;
+        const accepted = Boolean(hello.credential && this.options.verifyCredential(hello.clientId, hello.credential));
+        this.pairingRequired = !accepted;
+        const response = BridgeHelloDataSchema.parse({
+            accepted,
+            requiresPairing: !accepted,
+            bridgeVersion: this.options.bridgeVersion,
+            protocolVersion: this.options.protocolVersion,
+            capabilities: this.options.capabilities,
+        });
+        this.respond(message, `${message.type}:res`, safeSuccess(response));
+        if (accepted)
+            this.authorize(hello);
+    }
+    async handlePair(message) {
+        const parsed = ExtensionPairInputSchema.safeParse(message.data);
+        if (!parsed.success) {
+            this.respond(message, `${message.type}:res`, safeError(new BridgeError('InvalidPairingRequest', 'Invalid pairing request', {
+                status: 400,
+                details: parsed.error.issues,
+            })));
+            return;
+        }
+        const input = parsed.data;
+        if (!this.clientId || input.clientId !== this.clientId || input.clientName !== this.clientName) {
+            this.respond(message, `${message.type}:res`, safeError(new BridgeError('PairingSessionMismatch', 'Pairing request does not match the Extension hello', {
+                status: 400,
+            })));
+            return;
+        }
+        try {
+            const credential = await this.options.pair(input, this.options.remoteAddress);
+            const response = BridgePairDataSchema.parse({
+                accepted: true,
+                clientId: input.clientId,
+                credential,
+            });
+            this.respond(message, `${message.type}:res`, safeSuccess(response));
+            this.authorize({ ...input, capabilities: this.capabilities });
+        }
+        catch (error) {
+            this.respond(message, `${message.type}:res`, safeError(error));
+        }
+    }
+    authorize(hello) {
+        this.ready = true;
+        this.pairingRequired = false;
+        this.clientId = hello.clientId;
+        this.clientName = hello.clientName;
+        this.capabilities = hello.capabilities;
+        this.emit('ready', {
+            clientId: this.clientId,
+            clientName: this.clientName,
+            capabilities: this.capabilities,
+        });
+    }
+    respond(request, type, data) {
+        this.send(createEnvelope(type, data, { id: request.id, callback: false }));
+    }
+    send(envelope) {
+        if (this.socket.readyState !== this.socket.OPEN) {
+            throw new BridgeError('ExtensionUnavailable', 'Tapicker Extension WebSocket is not open', { status: 503 });
+        }
+        this.socket.send(JSON.stringify(envelope));
+    }
+    rejectPending(error) {
+        for (const pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pendingRequests.clear();
+    }
+    reportError(error) {
+        if (this.listenerCount('error') > 0) {
+            this.emit('error', error);
+        }
+    }
+}
+//# sourceMappingURL=extension-session.js.map

package/dist/bridge/pairing-state.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+declare const PairingStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    clients: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        clientId: z.ZodUUID;
+        credential: z.ZodUUID;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type PairedExtensionIdentity = z.infer<typeof PairingStateSchema>['clients'][number];
+export interface PairingStatePersistence {
+    load(): Promise<PairedExtensionIdentity[]>;
+    save(identities: PairedExtensionIdentity[]): Promise<void>;
+}
+export declare class PairingStateFile implements PairingStatePersistence {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): Promise<PairedExtensionIdentity[]>;
+    save(identities: PairedExtensionIdentity[]): Promise<void>;
+}
+export declare function getDefaultBridgeDataDir(home?: string): string;
+export {};
+//# sourceMappingURL=pairing-state.d.ts.map

package/dist/bridge/pairing-state.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { BridgeError } from '../errors.js';
+const PairingStateSchema = z
+    .object({
+    version: z.literal(1),
+    clients: z
+        .array(z
+        .object({
+        clientId: z.uuid(),
+        credential: z.uuid(),
+    })
+        .strict())
+        .default([]),
+})
+    .strict();
+export class PairingStateFile {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async load() {
+        await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        let content;
+        try {
+            content = await readFile(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(content);
+        }
+        catch (cause) {
+            throw new BridgeError('InvalidPairingState', 'Saved Bridge pairing state is not valid JSON', {
+                status: 500,
+                cause,
+            });
+        }
+        const parsed = PairingStateSchema.safeParse(value);
+        if (!parsed.success) {
+            throw new BridgeError('InvalidPairingState', `Saved Bridge pairing state at ${this.filePath} has an unsupported format. This pre-release version does not migrate old state automatically; update it to the version 1 clients-array format or remove it and pair Extensions again.`, { status: 500, details: parsed.error.issues });
+        }
+        return parsed.data.clients;
+    }
+    async save(identities) {
+        const directory = dirname(this.filePath);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const temporaryPath = join(directory, `.paired-clients-${process.pid}-${randomUUID()}.tmp`);
+        const content = JSON.stringify({ version: 1, clients: identities }, null, 2);
+        let file;
+        try {
+            file = await open(temporaryPath, 'wx', 0o600);
+            await file.writeFile(content, 'utf8');
+            await file.sync();
+            await file.close();
+            file = undefined;
+            await rename(temporaryPath, this.filePath);
+        }
+        catch (error) {
+            await file?.close().catch(() => undefined);
+            await unlink(temporaryPath).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+export function getDefaultBridgeDataDir(home = homedir()) {
+    return join(home, '.tapicker');
+}
+//# sourceMappingURL=pairing-state.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map