pipane 0.1.6 → 0.1.7

package/dist/server/shared/backend-api.js

@@ -0,0 +1 @@
+export const MAX_UPLOAD_FILE_BYTES = 20 * 1024 * 1024;

package/dist/server/shared/backend-protocol.js

@@ -0,0 +1,164 @@
+/** Semantic hidden-backend request protocol carried beside application v1 frames. */
+export const BACKEND_PROTOCOL_VERSION = 2;
+export const BACKEND_PROTOCOL_MAX_FRAME_BYTES = 3 * 1024 * 1024;
+export function encodeBackendFrame(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeBackendRequest(raw) {
+    const envelope = parseEnvelope(raw);
+    if (!envelope.ok)
+        return envelope;
+    const value = envelope.value;
+    const requestId = typeof value.id === "string" ? value.id : null;
+    const method = typeof value.method === "string" ? value.method : "";
+    if (value.kind !== "request" || !isNonEmptyString(value.id) || !isNonEmptyString(value.method) || !isRecord(value.params)) {
+        return invalid("invalid_request", "Backend request envelope is malformed", requestId, method);
+    }
+    if (!isBackendMethod(value.method)) {
+        return invalid("unknown_method", `Unknown backend method: ${value.method}`, value.id, value.method);
+    }
+    if (!validateParams(value.method, value.params)) {
+        return invalid("invalid_request", `Invalid parameters for ${value.method}`, value.id, value.method);
+    }
+    return { ok: true, value: value };
+}
+export function decodeBackendResponse(raw) {
+    const envelope = parseEnvelope(raw);
+    if (!envelope.ok)
+        return envelope;
+    const value = envelope.value;
+    const requestId = typeof value.id === "string" ? value.id : null;
+    const method = typeof value.method === "string" ? value.method : "";
+    if (value.kind !== "response" || !isNonEmptyString(value.id) || !isNonEmptyString(value.method) || typeof value.success !== "boolean") {
+        return invalid("invalid_request", "Backend response envelope is malformed", requestId, method);
+    }
+    if (value.success) {
+        if (!("result" in value))
+            return invalid("invalid_request", "Successful response is missing result", value.id, value.method);
+    }
+    else if (!isApiError(value.error)) {
+        return invalid("invalid_request", "Failed response is missing a valid error", value.id, value.method);
+    }
+    return { ok: true, value: value };
+}
+export function isBackendProtocolFrame(raw) {
+    // `encodeBackendFrame` emits the version first. Keep v1 streaming frames on
+    // their hot path without parsing large snapshots twice.
+    const prefix = raw.slice(0, 128);
+    return /"v"\s*:\s*2(?:\s*[,}])/u.test(prefix)
+        && /"kind"\s*:\s*"(?:request|response|event)"/u.test(prefix);
+}
+function parseEnvelope(raw) {
+    if (new TextEncoder().encode(raw).byteLength > BACKEND_PROTOCOL_MAX_FRAME_BYTES) {
+        return invalid("invalid_request", "Backend frame exceeds the size limit", null, "");
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return invalid("invalid_json", "Backend frame is not valid JSON", null, "");
+    }
+    if (!isRecord(value))
+        return invalid("invalid_request", "Backend frame must be an object", null, "");
+    if (value.v !== BACKEND_PROTOCOL_VERSION) {
+        return invalid("unsupported_version", `Unsupported backend protocol version: ${String(value.v)}`, null, "");
+    }
+    return { ok: true, value };
+}
+function validateParams(method, params) {
+    switch (method) {
+        case "backend.capabilities":
+        case "sessions.list":
+        case "settings.get":
+        case "updates.get":
+            return hasOnlyKeys(params, []);
+        case "sessions.delete":
+        case "sessions.forkMessages":
+        case "sessions.raw":
+            return hasOnlyKeys(params, ["sessionPath"]) && isNonEmptyString(params.sessionPath);
+        case "files.read":
+            return hasOnlyKeys(params, ["sessionPath", "path"])
+                && isNonEmptyString(params.sessionPath)
+                && isNonEmptyString(params.path);
+        case "files.upload.create":
+            return hasOnlyKeys(params, ["fileName", "mimeType", "size"])
+                && isNonEmptyString(params.fileName)
+                && isNonEmptyString(params.mimeType)
+                && Number.isSafeInteger(params.size)
+                && params.size >= 0;
+        case "files.upload.append":
+            return hasOnlyKeys(params, ["uploadId", "offset", "data"])
+                && isNonEmptyString(params.uploadId)
+                && Number.isSafeInteger(params.offset)
+                && params.offset >= 0
+                && isNonEmptyString(params.data);
+        case "files.upload.complete":
+            return hasOnlyKeys(params, ["uploadId"]) && isNonEmptyString(params.uploadId);
+        case "host.browse":
+            return hasOnlyKeys(params, ["path"]) && typeof params.path === "string";
+        case "host.mkdir":
+            return hasOnlyKeys(params, ["parentPath", "name"])
+                && isNonEmptyString(params.parentPath)
+                && isNonEmptyString(params.name);
+        case "settings.validate":
+        case "settings.save":
+            return hasOnlyKeys(params, ["content"]) && typeof params.content === "string";
+        case "settings.patch":
+            return hasOnlyKeys(params, ["patch"]) && isRecord(params.patch);
+        case "updates.run":
+            return hasOnlyKeys(params, ["target"])
+                && (params.target === "pipane" || params.target === "pi" || params.target === "extensions");
+    }
+}
+function isBackendMethod(value) {
+    return [
+        "backend.capabilities",
+        "sessions.list",
+        "sessions.delete",
+        "sessions.forkMessages",
+        "sessions.raw",
+        "files.read",
+        "files.upload.create",
+        "files.upload.append",
+        "files.upload.complete",
+        "host.browse",
+        "host.mkdir",
+        "settings.get",
+        "settings.validate",
+        "settings.patch",
+        "settings.save",
+        "updates.get",
+        "updates.run",
+    ].includes(value);
+}
+function isApiError(value) {
+    return isRecord(value)
+        && isBackendErrorCode(value.code)
+        && isNonEmptyString(value.message);
+}
+function isBackendErrorCode(value) {
+    return typeof value === "string" && [
+        "invalid_json",
+        "invalid_request",
+        "unsupported_version",
+        "unknown_method",
+        "not_found",
+        "forbidden",
+        "conflict",
+        "internal_error",
+    ].includes(value);
+}
+function invalid(code, message, requestId, method) {
+    return { ok: false, error: { code, message }, requestId, method };
+}
+function hasOnlyKeys(value, keys) {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}

package/dist/server/shared/node-trust-crypto.js

@@ -0,0 +1,61 @@
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { connectionTicketSignaturePayload, parseConnectionTicketClaims, } from "./trust-protocol.js";
+const DEVICE_ID_PREFIX = "d_";
+export function deriveDeviceId(publicKey) {
+    const bytes = decodeP256PublicKey(publicKey);
+    return `${DEVICE_ID_PREFIX}${createHash("sha256").update(bytes).digest("base64url")}`;
+}
+export function verifyDeviceSignature(publicKey, payload, signature) {
+    try {
+        const key = createPublicKey({ key: decodeP256PublicKey(publicKey), format: "der", type: "spki" });
+        return verify("sha256", Buffer.from(payload), { key, dsaEncoding: "ieee-p1363" }, Buffer.from(signature, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+export function verifyConnectionTicket(ticket, publicKey, now = Date.now()) {
+    const parts = ticket.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        throw new Error("Malformed connection ticket");
+    const [encodedClaims, encodedSignature] = parts;
+    let claims;
+    try {
+        const bytes = Buffer.from(encodedClaims, "base64url");
+        if (bytes.toString("base64url") !== encodedClaims)
+            throw new Error("non-canonical payload");
+        claims = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("Malformed connection ticket claims");
+    }
+    const parsed = parseConnectionTicketClaims(claims);
+    if (!parsed)
+        throw new Error("Invalid connection ticket claims");
+    if (!verifyDeviceSignature(publicKey, connectionTicketSignaturePayload(encodedClaims), encodedSignature)) {
+        throw new Error("Invalid connection ticket signature");
+    }
+    if (parsed.expiresAt <= now)
+        throw new Error("Connection ticket expired");
+    if (parsed.issuedAt > now + 30_000)
+        throw new Error("Connection ticket was issued in the future");
+    return parsed;
+}
+export function decodeP256PublicKey(publicKey) {
+    if (!/^[A-Za-z0-9_-]+$/.test(publicKey))
+        throw new Error("Invalid public key encoding");
+    const bytes = Buffer.from(publicKey, "base64url");
+    if (bytes.length === 0 || bytes.toString("base64url") !== publicKey)
+        throw new Error("Invalid public key encoding");
+    const key = createPublicKey({ key: bytes, format: "der", type: "spki" });
+    assertP256Key(key);
+    const canonical = Buffer.from(key.export({ type: "spki", format: "der" }));
+    if (!canonical.equals(bytes))
+        throw new Error("Public key is not canonical");
+    return bytes;
+}
+export function assertP256Key(key) {
+    if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+        throw new Error("Identity must use P-256");
+    }
+}

package/dist/server/shared/rendezvous-protocol.js

@@ -0,0 +1,243 @@
+export const RENDEZVOUS_PROTOCOL_VERSION = 2;
+export function rendezvousWebSocketUrl(baseUrl, role) {
+    const url = new URL(baseUrl);
+    if (url.protocol === "http:")
+        url.protocol = "ws:";
+    else if (url.protocol === "https:")
+        url.protocol = "wss:";
+    else if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+        throw new Error(`Unsupported rendezvous URL protocol: ${url.protocol}`);
+    }
+    url.pathname = `/v${RENDEZVOUS_PROTOCOL_VERSION}/rendezvous/${role}`;
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+export function backendRegistrationPayload(nonce) {
+    return `pipane-rendezvous-v${RENDEZVOUS_PROTOCOL_VERSION}\n${nonce}`;
+}
+export function encodeRendezvousMessage(message) {
+    return JSON.stringify(message);
+}
+export function decodeBackendCommand(raw) {
+    return decodeCommand(raw, "backend");
+}
+export function decodeBrowserCommand(raw) {
+    return decodeCommand(raw, "browser");
+}
+export function decodeBackendMessage(raw) {
+    return decodeServerMessage(raw, "backend");
+}
+export function decodeBrowserMessage(raw) {
+    return decodeServerMessage(raw, "browser");
+}
+function decodeCommand(raw, role) {
+    const envelope = parseEnvelope(raw);
+    if (!envelope.ok)
+        return envelope;
+    const value = envelope.value;
+    switch (value.type) {
+        case "register_backend":
+            if (role !== "backend")
+                return unknownMessage(value.type);
+            if (!isString(value.publicKey) || !isString(value.signature) || !isBackendMetadata(value.metadata)) {
+                return invalidMessage("register_backend requires publicKey, signature, and valid metadata");
+            }
+            break;
+        case "open_pairing":
+            if (role !== "backend")
+                return unknownMessage(value.type);
+            if (!isString(value.pairId) || !isPositiveInteger(value.expiresAt)) {
+                return invalidMessage("open_pairing requires pairId and expiresAt");
+            }
+            break;
+        case "confirm_pairing":
+            if (role !== "backend")
+                return unknownMessage(value.type);
+            if (!isString(value.connectionId))
+                return invalidMessage("confirm_pairing requires connectionId");
+            break;
+        case "connect_backend":
+            if (role !== "browser")
+                return unknownMessage(value.type);
+            if (!isString(value.backendId) || !isString(value.ticket)) {
+                return invalidMessage("connect_backend requires backendId and ticket");
+            }
+            break;
+        case "signal":
+            if (!isString(value.connectionId) || !isIceSignal(value.signal)) {
+                return invalidMessage("signal requires connectionId and a valid ICE signal");
+            }
+            break;
+        case "connection_binding":
+            if (role !== "backend")
+                return unknownMessage(value.type);
+            if (!isString(value.connectionId) || !isBackendIdentityBinding(value.binding)) {
+                return invalidMessage("connection_binding requires connectionId and a valid binding");
+            }
+            break;
+        case "close_connection":
+            if (!isString(value.connectionId) || !isOptionalString(value.reason)) {
+                return invalidMessage("close_connection requires connectionId and an optional reason");
+            }
+            break;
+        default:
+            return unknownMessage(value.type);
+    }
+    return { ok: true, value: value };
+}
+function decodeServerMessage(raw, role) {
+    const envelope = parseEnvelope(raw);
+    if (!envelope.ok)
+        return envelope;
+    const value = envelope.value;
+    switch (value.type) {
+        case "challenge":
+            if (role !== "backend" || !isString(value.nonce))
+                return invalidMessage("invalid backend challenge");
+            break;
+        case "registered":
+            if (role !== "backend" || !isString(value.backendId) || !isString(value.ticketPublicKey) || !isIceServers(value.iceServers)) {
+                return invalidMessage("invalid backend registration");
+            }
+            break;
+        case "pairing_opened":
+            if (role !== "backend" || !isString(value.pairId) || !isPositiveInteger(value.expiresAt)) {
+                return invalidMessage("invalid pairing acknowledgement");
+            }
+            break;
+        case "pairing_confirmed":
+            if (role !== "backend"
+                || !isString(value.connectionId)
+                || !isString(value.pairId)
+                || !isString(value.accountId)
+                || !isString(value.deviceId)) {
+                return invalidMessage("invalid pairing confirmation");
+            }
+            break;
+        case "connection_request":
+            if (role !== "backend" || !isString(value.connectionId) || !isString(value.ticket) || !isIceServers(value.iceServers)) {
+                return invalidMessage("invalid connection request");
+            }
+            break;
+        case "backend_connected":
+            if (role !== "browser" || !isString(value.backendId) || !isString(value.connectionId)) {
+                return invalidMessage("invalid browser connection acknowledgement");
+            }
+            break;
+        case "signal":
+            if (!isString(value.connectionId) || !isIceSignal(value.signal))
+                return invalidMessage("invalid ICE signal");
+            break;
+        case "connection_binding":
+            if (role !== "browser" || !isString(value.connectionId) || !isBackendIdentityBinding(value.binding)) {
+                return invalidMessage("invalid backend identity binding");
+            }
+            break;
+        case "connection_closed":
+            if (!isString(value.connectionId) || !isString(value.reason))
+                return invalidMessage("invalid connection closure");
+            break;
+        case "authorization_revoked":
+            if (role !== "backend" || !isString(value.accountId) || !isOptionalString(value.deviceId)) {
+                return invalidMessage("invalid authorization revocation");
+            }
+            break;
+        case "error":
+            if (!isErrorCode(value.code) || !isString(value.message) || !isOptionalString(value.connectionId)) {
+                return invalidMessage("invalid rendezvous error");
+            }
+            break;
+        default:
+            return unknownMessage(value.type);
+    }
+    return { ok: true, value: value };
+}
+function parseEnvelope(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: { code: "invalid_json", message: "Message is not valid JSON" } };
+    }
+    if (!isRecord(value) || !isString(value.type))
+        return invalidMessage("Message must be an object with a type");
+    if (value.protocolVersion !== RENDEZVOUS_PROTOCOL_VERSION) {
+        return {
+            ok: false,
+            error: {
+                code: "unsupported_version",
+                message: `Unsupported rendezvous protocol version: ${String(value.protocolVersion)}`,
+            },
+        };
+    }
+    return { ok: true, value };
+}
+function isBackendMetadata(value) {
+    return isRecord(value)
+        && isOptionalString(value.name)
+        && isString(value.softwareVersion)
+        && Array.isArray(value.protocolVersions)
+        && value.protocolVersions.length > 0
+        && value.protocolVersions.every((version) => Number.isSafeInteger(version) && version > 0);
+}
+function isIceSignal(value) {
+    if (!isRecord(value) || !isString(value.kind))
+        return false;
+    if (value.kind === "description") {
+        return (value.type === "offer" || value.type === "answer") && isString(value.sdp);
+    }
+    if (value.kind === "candidate") {
+        return isString(value.candidate)
+            && (value.sdpMid === null || isString(value.sdpMid))
+            && (value.sdpMLineIndex === null || (Number.isSafeInteger(value.sdpMLineIndex) && value.sdpMLineIndex >= 0));
+    }
+    return false;
+}
+function isBackendIdentityBinding(value) {
+    return isRecord(value)
+        && value.version === 1
+        && isString(value.backendId)
+        && isString(value.publicKey)
+        && isString(value.connectionId)
+        && isString(value.offerSha256)
+        && isString(value.answerSha256)
+        && isString(value.dtlsFingerprint)
+        && isPositiveInteger(value.expiresAt)
+        && isString(value.signature);
+}
+function isIceServers(value) {
+    return Array.isArray(value) && value.every((server) => isRecord(server)
+        && (isString(server.urls) || (Array.isArray(server.urls) && server.urls.length > 0 && server.urls.every(isString)))
+        && isOptionalString(server.username)
+        && isOptionalString(server.credential));
+}
+function isErrorCode(value) {
+    return value === "invalid_json"
+        || value === "invalid_message"
+        || value === "unsupported_version"
+        || value === "unknown_message"
+        || value === "backend_offline"
+        || value === "unauthorized_connection"
+        || value === "invalid_ticket"
+        || value === "invalid_pairing";
+}
+function invalidMessage(message) {
+    return { ok: false, error: { code: "invalid_message", message } };
+}
+function unknownMessage(type) {
+    return { ok: false, error: { code: "unknown_message", message: `Unknown rendezvous message: ${String(type)}` } };
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isOptionalString(value) {
+    return value === undefined || isString(value);
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}

package/dist/server/shared/tool-runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/server/shared/trust-protocol.js

@@ -0,0 +1,97 @@
+export const TRUST_PROTOCOL_VERSION = 1;
+export const CONNECTION_TICKET_VERSION = 1;
+export const PIPANE_DATA_CHANNEL_LABEL = "pipane";
+export const PIPANE_DATA_CHANNEL_PROTOCOL = "pipane.v1";
+export function deviceChallengePayload(challenge) {
+    return [
+        `pipane-device-challenge-v${TRUST_PROTOCOL_VERSION}`,
+        challenge.challengeId,
+        challenge.nonce,
+        challenge.purpose,
+        challenge.deviceId,
+        challenge.devicePublicKey,
+        challenge.backendId ?? "",
+        challenge.connectionId ?? "",
+        challenge.pairId ?? "",
+        challenge.targetDeviceId ?? "",
+        String(challenge.expiresAt),
+    ].join("\n");
+}
+export function connectionTicketSignaturePayload(encodedClaims) {
+    return `pipane-connection-ticket-v${CONNECTION_TICKET_VERSION}\n${encodedClaims}`;
+}
+export function backendIdentityBindingPayload(binding) {
+    return [
+        `pipane-backend-binding-v${TRUST_PROTOCOL_VERSION}`,
+        binding.backendId,
+        binding.publicKey,
+        binding.connectionId,
+        binding.offerSha256,
+        binding.answerSha256,
+        binding.dtlsFingerprint,
+        String(binding.expiresAt),
+    ].join("\n");
+}
+export function deviceConnectionProofPayload(ticket, bindingSignature) {
+    return [
+        `pipane-device-connection-v${TRUST_PROTOCOL_VERSION}`,
+        ticket,
+        bindingSignature,
+    ].join("\n");
+}
+export function decodeDataChannelAuthenticateFrame(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value)
+        || value.protocolVersion !== TRUST_PROTOCOL_VERSION
+        || value.type !== "authenticate"
+        || !isNonEmptyString(value.ticket)
+        || !isNonEmptyString(value.bindingSignature)
+        || !isNonEmptyString(value.deviceSignature)
+        || !isOptionalString(value.pairingSecret)) {
+        return undefined;
+    }
+    return value;
+}
+export function parseConnectionTicketClaims(value) {
+    if (!isRecord(value)
+        || value.version !== CONNECTION_TICKET_VERSION
+        || (value.kind !== "pairing" && value.kind !== "connection")
+        || !isNonEmptyString(value.ticketId)
+        || !isNonEmptyString(value.backendId)
+        || !isNonEmptyString(value.connectionId)
+        || !isNonEmptyString(value.deviceId)
+        || !isNonEmptyString(value.devicePublicKey)
+        || !isOptionalString(value.accountId)
+        || !isOptionalString(value.pairId)
+        || !isNonNegativeInteger(value.issuedAt)
+        || !isPositiveInteger(value.expiresAt)
+        || value.expiresAt <= value.issuedAt) {
+        return undefined;
+    }
+    if (value.kind === "pairing" && !isNonEmptyString(value.pairId))
+        return undefined;
+    if (value.kind === "connection" && !isNonEmptyString(value.accountId))
+        return undefined;
+    return value;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isOptionalString(value) {
+    return value === undefined || isNonEmptyString(value);
+}
+function isNonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}

package/dist/server/shared/updates.js

@@ -0,0 +1,4 @@
+export const UPDATE_TARGETS = ["pipane", "pi", "extensions"];
+export function isUpdateTarget(value) {
+    return typeof value === "string" && UPDATE_TARGETS.includes(value);
+}