@rynx-ai/remote-runtime-client 0.1.9

package/dist/credential.d.ts

@@ -0,0 +1,35 @@
+import { type KeyObject } from "node:crypto";
+import { type DirectRuntimeClientErrorCode } from "./errors.js";
+export interface DirectRuntimeClientIdentity {
+    clientId: string;
+    /** Canonical Ed25519 SubjectPublicKeyInfo DER, unpadded base64url. */
+    clientPublicKey: string;
+    /** Ed25519 PKCS#8 private key. Keep this value secret. */
+    clientPrivateKeyPem: string;
+}
+export interface GenerateDirectRuntimeClientIdentityOptions {
+    clientId?: string;
+}
+export interface DirectRuntimeCredential extends DirectRuntimeClientIdentity {
+    version: 2;
+    daemonId: string;
+    /** Pinned daemon Ed25519 SubjectPublicKeyInfo DER, unpadded base64url. */
+    identityPublicKey: string;
+    /** Pinned daemon X25519 SubjectPublicKeyInfo DER, unpadded base64url. */
+    serverEncryptionPublicKey: string;
+    directEndpoint: string;
+    grantId: string;
+}
+export interface ParsedDirectRuntimeClientIdentity {
+    value: DirectRuntimeClientIdentity;
+    privateKey: KeyObject;
+}
+/** Generate a durable client identity for one or more Direct Runtime grants. */
+export declare function generateDirectRuntimeClientIdentity(options?: GenerateDirectRuntimeClientIdentityOptions): DirectRuntimeClientIdentity;
+/** Validate persisted, untrusted credential JSON and return only known fields. */
+export declare function parseDirectRuntimeCredential(value: unknown): DirectRuntimeCredential;
+export declare function parseDirectRuntimeClientIdentity(value: unknown, code?: DirectRuntimeClientErrorCode): ParsedDirectRuntimeClientIdentity;
+export declare function parseEd25519PublicKey(value: unknown, field: string, code: DirectRuntimeClientErrorCode): string;
+export declare function parseDirectEndpoint(value: unknown, code: DirectRuntimeClientErrorCode): string;
+export declare function parseX25519PublicKey(value: unknown, field: string, code: DirectRuntimeClientErrorCode): string;
+export declare function opaqueId(value: unknown, field: string, code: DirectRuntimeClientErrorCode): string;

package/dist/credential.js

@@ -0,0 +1,163 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, } from "node:crypto";
+import { DIRECT_RUNTIME_CONTROL_PATH } from "@rynx-ai/protocol/direct-runtime";
+import { clientError, } from "./errors.js";
+const MAX_ID_CHARS = 256;
+const MAX_ENDPOINT_CHARS = 2_048;
+const MAX_PRIVATE_KEY_BYTES = 4 * 1024;
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** Generate a durable client identity for one or more Direct Runtime grants. */
+export function generateDirectRuntimeClientIdentity(options = {}) {
+    const clientId = options.clientId === undefined
+        ? `client_${randomBytes(18).toString("base64url")}`
+        : opaqueId(options.clientId, "clientId", "authentication_failed");
+    const pair = generateKeyPairSync("ed25519");
+    return {
+        clientId,
+        clientPublicKey: exportPublicKey(pair.publicKey),
+        clientPrivateKeyPem: pair.privateKey
+            .export({ type: "pkcs8", format: "pem" })
+            .toString(),
+    };
+}
+/** Validate persisted, untrusted credential JSON and return only known fields. */
+export function parseDirectRuntimeCredential(value) {
+    const record = requireRecord(value, "Direct Runtime credential", "authentication_failed");
+    if (record.version !== 2) {
+        throw clientError("authentication_failed", "Direct Runtime credential version must be 2");
+    }
+    const daemonId = opaqueId(record.daemonId, "daemonId", "authentication_failed");
+    const identityPublicKey = parseEd25519PublicKey(record.identityPublicKey, "identityPublicKey", "authentication_failed");
+    const serverEncryptionPublicKey = parseX25519PublicKey(record.serverEncryptionPublicKey, "serverEncryptionPublicKey", "authentication_failed");
+    const directEndpoint = parseDirectEndpoint(record.directEndpoint, "authentication_failed");
+    const identity = parseDirectRuntimeClientIdentity(record, "authentication_failed");
+    const grantId = opaqueId(record.grantId, "grantId", "authentication_failed");
+    return {
+        version: 2,
+        daemonId,
+        identityPublicKey,
+        serverEncryptionPublicKey,
+        directEndpoint,
+        ...identity.value,
+        grantId,
+    };
+}
+export function parseDirectRuntimeClientIdentity(value, code = "authentication_failed") {
+    const record = requireRecord(value, "Direct Runtime client identity", code);
+    const clientId = opaqueId(record.clientId, "clientId", code);
+    const clientPublicKey = parseEd25519PublicKey(record.clientPublicKey, "clientPublicKey", code);
+    const clientPrivateKeyPem = parsePrivateKeyPem(record.clientPrivateKeyPem, code);
+    let privateKey;
+    try {
+        privateKey = createPrivateKey({ key: clientPrivateKeyPem, format: "pem" });
+    }
+    catch (error) {
+        throw clientError(code, "clientPrivateKeyPem is not a valid private key", error);
+    }
+    if (privateKey.asymmetricKeyType !== "ed25519") {
+        throw clientError(code, "clientPrivateKeyPem must contain an Ed25519 key");
+    }
+    const derivedPublicKey = exportPublicKey(createPublicKey(privateKey));
+    if (derivedPublicKey !== clientPublicKey) {
+        throw clientError(code, "client private and public keys do not match");
+    }
+    return {
+        value: { clientId, clientPublicKey, clientPrivateKeyPem },
+        privateKey,
+    };
+}
+export function parseEd25519PublicKey(value, field, code) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 512 ||
+        !BASE64URL_PATTERN.test(value)) {
+        throw clientError(code, `${field} must be an Ed25519 SPKI DER base64url key`);
+    }
+    try {
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.toString("base64url") !== value)
+            throw new Error("non-canonical base64url");
+        const key = createPublicKey({ key: bytes, format: "der", type: "spki" });
+        if (key.asymmetricKeyType !== "ed25519")
+            throw new Error("not Ed25519");
+        const canonical = exportPublicKey(key);
+        if (canonical !== value)
+            throw new Error("non-canonical SPKI DER");
+        return canonical;
+    }
+    catch (error) {
+        throw clientError(code, `${field} must be an Ed25519 SPKI DER base64url key`, error);
+    }
+}
+export function parseDirectEndpoint(value, code) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_ENDPOINT_CHARS ||
+        !/^wss?:\/\/[^\s]+$/.test(value)) {
+        throw clientError(code, "directEndpoint must be a bounded ws: or wss: URL");
+    }
+    let endpoint;
+    try {
+        endpoint = new URL(value);
+    }
+    catch (error) {
+        throw clientError(code, "directEndpoint must be a valid ws: or wss: URL", error);
+    }
+    if ((endpoint.protocol !== "ws:" && endpoint.protocol !== "wss:") ||
+        endpoint.hostname.length === 0 ||
+        endpoint.username.length > 0 ||
+        endpoint.password.length > 0 ||
+        endpoint.hash.length > 0 ||
+        endpoint.search.length > 0 ||
+        endpoint.pathname !== DIRECT_RUNTIME_CONTROL_PATH) {
+        throw clientError(code, `directEndpoint must be a credential-free ws: or wss: URL at ${DIRECT_RUNTIME_CONTROL_PATH} without query or fragment`);
+    }
+    return value;
+}
+export function parseX25519PublicKey(value, field, code) {
+    if (typeof value !== "string" || !BASE64URL_PATTERN.test(value)) {
+        throw clientError(code, `${field} must be an X25519 SPKI DER base64url key`);
+    }
+    try {
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.byteLength !== 44 || bytes.toString("base64url") !== value) {
+            throw new Error("non-canonical base64url");
+        }
+        const key = createPublicKey({ key: bytes, format: "der", type: "spki" });
+        if (key.asymmetricKeyType !== "x25519")
+            throw new Error("not X25519");
+        return key.export({ type: "spki", format: "der" }).toString("base64url");
+    }
+    catch (error) {
+        throw clientError(code, `${field} must be an X25519 SPKI DER base64url key`, error);
+    }
+}
+export function opaqueId(value, field, code) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_ID_CHARS ||
+        !OPAQUE_ID_PATTERN.test(value)) {
+        throw clientError(code, `${field} must be an opaque ASCII token`);
+    }
+    return value;
+}
+function parsePrivateKeyPem(value, code) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        Buffer.byteLength(value, "utf8") > MAX_PRIVATE_KEY_BYTES ||
+        value.includes("\0") ||
+        !value.includes("-----BEGIN PRIVATE KEY-----") ||
+        !value.includes("-----END PRIVATE KEY-----")) {
+        throw clientError(code, "clientPrivateKeyPem must be a bounded PKCS#8 PEM key");
+    }
+    return value;
+}
+function exportPublicKey(key) {
+    return key.export({ type: "spki", format: "der" }).toString("base64url");
+}
+function requireRecord(value, field, code) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw clientError(code, `${field} must be an object`);
+    }
+    return value;
+}

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+import type { RemoteRuntimeRpcErrorCode, RemoteRuntimeRpcMethod, RemoteRuntimeSessionEventsCloseReason, RemoteRuntimeSessionTerminalCloseReason } from "@rynx-ai/protocol/remote-runtime-rpc";
+export type DirectRuntimeClientErrorCode = "invalid_offer" | "tls_error" | "identity_mismatch" | "incompatible" | "authentication_failed" | "protocol_error" | "deadline_exceeded" | "unreachable" | "closed";
+export type DirectRuntimeCallOutcome = "not_started" | "unknown";
+export declare class DirectRuntimeClientError extends Error {
+    readonly code: DirectRuntimeClientErrorCode;
+    readonly outcome?: DirectRuntimeCallOutcome;
+    /** Original application WebSocket close code, when the peer supplied one. */
+    readonly webSocketCloseCode?: number;
+    constructor(code: DirectRuntimeClientErrorCode, message: string, options?: ErrorOptions & {
+        webSocketCloseCode?: number;
+        outcome?: DirectRuntimeCallOutcome;
+    });
+}
+export { DirectRuntimeClientError as RemoteRuntimeClientError };
+export type DirectRuntimeClientCapacity = "pending_rpc" | "session_subscription" | "session_terminal" | "emulator_surface" | "outbound_frames" | "outbound_bytes";
+/** Local admission failure. The rejected operation was not written to the wire. */
+export declare class DirectRuntimeClientCapacityError extends DirectRuntimeClientError {
+    readonly capacity: DirectRuntimeClientCapacity;
+    readonly limit: number;
+    readonly outcome: "not_started";
+    constructor(capacity: DirectRuntimeClientCapacity, limit: number, message: string);
+}
+/** A valid application-level `rpc.error` returned by the authenticated daemon. */
+export declare class DirectRuntimeRpcError extends Error {
+    readonly code: RemoteRuntimeRpcErrorCode;
+    readonly method: RemoteRuntimeRpcMethod;
+    readonly requestId: string;
+    readonly outcome: "unknown" | undefined;
+    constructor(code: RemoteRuntimeRpcErrorCode, method: RemoteRuntimeRpcMethod, requestId: string, message: string);
+}
+export { DirectRuntimeRpcError as RemoteRuntimeRpcCallError };
+/** Transport failure correlated to one call, including delivery ambiguity. */
+export declare class DirectRuntimeCallTransportError extends DirectRuntimeClientError {
+    readonly method: RemoteRuntimeRpcMethod;
+    readonly requestId: string;
+    readonly outcome: DirectRuntimeCallOutcome;
+    constructor(code: DirectRuntimeClientErrorCode, method: RemoteRuntimeRpcMethod, requestId: string, outcome: DirectRuntimeCallOutcome, message: string, options?: ErrorOptions & {
+        webSocketCloseCode?: number;
+    });
+}
+/** A terminal error scoped to one accepted Remote Session event stream. */
+export declare class DirectRuntimeSessionEventsError extends DirectRuntimeClientError {
+    readonly reason: RemoteRuntimeSessionEventsCloseReason;
+    readonly subscriptionId: string;
+    readonly sessionId: string;
+    constructor(reason: RemoteRuntimeSessionEventsCloseReason, subscriptionId: string, sessionId: string, message: string, options?: ErrorOptions);
+}
+/** A terminal error scoped to one Remote Session terminal attachment. */
+export declare class DirectRuntimeSessionTerminalError extends DirectRuntimeClientError {
+    readonly reason: RemoteRuntimeSessionTerminalCloseReason;
+    readonly attachmentId: string;
+    readonly sessionId: string;
+    constructor(reason: RemoteRuntimeSessionTerminalCloseReason, attachmentId: string, sessionId: string, message: string, options?: ErrorOptions);
+}
+export declare function clientError(code: DirectRuntimeClientErrorCode, message: string, cause?: unknown, webSocketCloseCode?: number): DirectRuntimeClientError;

package/dist/errors.js

@@ -0,0 +1,112 @@
+export class DirectRuntimeClientError extends Error {
+    code;
+    outcome;
+    /** Original application WebSocket close code, when the peer supplied one. */
+    webSocketCloseCode;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "DirectRuntimeClientError";
+        this.code = code;
+        this.outcome = options?.outcome;
+        if (options?.webSocketCloseCode !== undefined) {
+            this.webSocketCloseCode = options.webSocketCloseCode;
+        }
+    }
+}
+export { DirectRuntimeClientError as RemoteRuntimeClientError };
+/** Local admission failure. The rejected operation was not written to the wire. */
+export class DirectRuntimeClientCapacityError extends DirectRuntimeClientError {
+    capacity;
+    limit;
+    outcome = "not_started";
+    constructor(capacity, limit, message) {
+        // Keep the stable public error-code surface aligned with peer-side capacity
+        // rejection while exposing a distinct class for local admission decisions.
+        super("unreachable", message);
+        this.capacity = capacity;
+        this.limit = limit;
+        this.name = "DirectRuntimeClientCapacityError";
+    }
+}
+/** A valid application-level `rpc.error` returned by the authenticated daemon. */
+export class DirectRuntimeRpcError extends Error {
+    code;
+    method;
+    requestId;
+    outcome;
+    constructor(code, method, requestId, message) {
+        super(message);
+        this.code = code;
+        this.method = method;
+        this.requestId = requestId;
+        this.name = "DirectRuntimeRpcError";
+        this.outcome = code === "outcome_unknown" ? "unknown" : undefined;
+    }
+}
+export { DirectRuntimeRpcError as RemoteRuntimeRpcCallError };
+/** Transport failure correlated to one call, including delivery ambiguity. */
+export class DirectRuntimeCallTransportError extends DirectRuntimeClientError {
+    method;
+    requestId;
+    outcome;
+    constructor(code, method, requestId, outcome, message, options) {
+        super(code, message, options);
+        this.method = method;
+        this.requestId = requestId;
+        this.outcome = outcome;
+        this.name = "DirectRuntimeCallTransportError";
+    }
+}
+/** A terminal error scoped to one accepted Remote Session event stream. */
+export class DirectRuntimeSessionEventsError extends DirectRuntimeClientError {
+    reason;
+    subscriptionId;
+    sessionId;
+    constructor(reason, subscriptionId, sessionId, message, options) {
+        super(sessionEventsErrorCode(reason), message, options);
+        this.reason = reason;
+        this.subscriptionId = subscriptionId;
+        this.sessionId = sessionId;
+        this.name = "DirectRuntimeSessionEventsError";
+    }
+}
+/** A terminal error scoped to one Remote Session terminal attachment. */
+export class DirectRuntimeSessionTerminalError extends DirectRuntimeClientError {
+    reason;
+    attachmentId;
+    sessionId;
+    constructor(reason, attachmentId, sessionId, message, options) {
+        super(sessionTerminalErrorCode(reason), message, options);
+        this.reason = reason;
+        this.attachmentId = attachmentId;
+        this.sessionId = sessionId;
+        this.name = "DirectRuntimeSessionTerminalError";
+    }
+}
+function sessionEventsErrorCode(reason) {
+    if (reason === "unauthorized")
+        return "authentication_failed";
+    if (reason === "capacity")
+        return "unreachable";
+    return "closed";
+}
+function sessionTerminalErrorCode(reason) {
+    if (reason === "unauthorized")
+        return "authentication_failed";
+    if (reason === "capacity" || reason === "backpressure")
+        return "unreachable";
+    return "closed";
+}
+export function clientError(code, message, cause, webSocketCloseCode) {
+    if (cause instanceof DirectRuntimeClientError &&
+        cause.code === code &&
+        webSocketCloseCode === undefined) {
+        return cause;
+    }
+    return new DirectRuntimeClientError(code, message, cause === undefined && webSocketCloseCode === undefined
+        ? undefined
+        : {
+            ...(cause === undefined ? {} : { cause }),
+            ...(webSocketCloseCode === undefined ? {} : { webSocketCloseCode }),
+        });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { connectDirectRuntime, pairDirectRuntime, type DirectRuntimeCallOptions, type DirectRuntimeClientOptions, type DirectRuntimeConnection, type DirectRuntimeSessionEventsOptions, type DirectRuntimeSessionEventsSubscription, type DirectRuntimeSessionTerminal, type DirectRuntimeSessionTerminalOptions, type DirectRuntimeEmulatorSurface, type DirectRuntimeEmulatorSurfaceOptions, type PairDirectRuntimeOptions, type PairDirectRuntimeResult, } from "./client.js";
+export { DirectRuntimeBrowserSurfaceError, openDirectRuntimeBrowserSurface, type DirectRuntimeBrowserSurfaceClientOptions, type DirectRuntimeBrowserSurfaceConnection, type DirectRuntimeBrowserSurfaceEvent, } from "./browser-surface-client.js";
+export { generateDirectRuntimeClientIdentity, parseDirectRuntimeCredential, type DirectRuntimeClientIdentity, type DirectRuntimeCredential, type GenerateDirectRuntimeClientIdentityOptions, } from "./credential.js";
+export { DirectRuntimeCallTransportError, DirectRuntimeClientCapacityError, DirectRuntimeClientError, DirectRuntimeRpcError, DirectRuntimeSessionEventsError, DirectRuntimeSessionTerminalError, RemoteRuntimeClientError, RemoteRuntimeRpcCallError, type DirectRuntimeCallOutcome, type DirectRuntimeClientCapacity, type DirectRuntimeClientErrorCode, } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { connectDirectRuntime, pairDirectRuntime, } from "./client.js";
+export { DirectRuntimeBrowserSurfaceError, openDirectRuntimeBrowserSurface, } from "./browser-surface-client.js";
+export { generateDirectRuntimeClientIdentity, parseDirectRuntimeCredential, } from "./credential.js";
+export { DirectRuntimeCallTransportError, DirectRuntimeClientCapacityError, DirectRuntimeClientError, DirectRuntimeRpcError, DirectRuntimeSessionEventsError, DirectRuntimeSessionTerminalError, RemoteRuntimeClientError, RemoteRuntimeRpcCallError, } from "./errors.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rynx-ai/remote-runtime-client",
+  "version": "0.1.9",
+  "description": "Authenticated Node.js client for a Rynx Direct Remote Runtime.",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.21.0",
+    "@rynx-ai/protocol": "0.1.9",
+    "@rynx-ai/remote-runtime-e2ee": "0.1.9"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  }
+}