@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/remote-runtime-target-control.d.ts

@@ -0,0 +1,47 @@
+import { type PairingOffer } from "@rynx-ai/protocol/direct-runtime";
+import type { DaemonStatus } from "@rynx-ai/protocol/remote-runtime";
+import { connectDirectRuntime, pairDirectRuntime, type DirectRuntimeCredential, type PairDirectRuntimeOptions } from "@rynx-ai/remote-runtime-client";
+import { type DaemonRuntimeHost, type RuntimeTargetControlHost, type RuntimeTargetView } from "@rynx-ai/server";
+import { DaemonRuntimeConnectionManager } from "./remote-runtime-connection-manager.js";
+import { FileRemoteRuntimeCredentialStore } from "./remote-runtime-credential-store.js";
+import { RemoteRuntimeTargetStore } from "./remote-runtime-target-store.js";
+export type RuntimeTargetControlErrorCode = "invalid_offer" | "invalid_target" | "not_found" | "conflict" | "tls_error" | "identity_mismatch" | "incompatible" | "authentication_failed" | "protocol_error" | "deadline_exceeded" | "outcome_unknown" | "unreachable";
+export declare class RuntimeTargetControlError extends Error {
+    readonly code: RuntimeTargetControlErrorCode;
+    constructor(code: RuntimeTargetControlErrorCode, message: string, options?: ErrorOptions);
+}
+interface PairInput {
+    offer: unknown;
+    displayName?: string;
+}
+interface RuntimeTargetClientAdapter {
+    pair(offer: PairingOffer, options: PairDirectRuntimeOptions): ReturnType<typeof pairDirectRuntime>;
+    connect(credential: DirectRuntimeCredential): ReturnType<typeof connectDirectRuntime>;
+}
+/** Local resident-daemon application service backing CLI and browser BFF target management. */
+export declare class DaemonRuntimeTargetControl implements RuntimeTargetControlHost {
+    private readonly localRuntime;
+    private readonly targets;
+    private readonly credentials;
+    private readonly connections;
+    private readonly client;
+    private pairing;
+    constructor(localRuntime: DaemonRuntimeHost, targets: RemoteRuntimeTargetStore, credentials: FileRemoteRuntimeCredentialStore, connections: DaemonRuntimeConnectionManager, client?: RuntimeTargetClientAdapter);
+    list(): RuntimeTargetView[];
+    pair(input: PairInput): Promise<{
+        target: RuntimeTargetView;
+        status: DaemonStatus;
+    }>;
+    private discardExpiredPending;
+    private resumePendingEnrollment;
+    private probe;
+    test(selector: string): Promise<{
+        target: RuntimeTargetView;
+        status: DaemonStatus;
+    }>;
+    forget(daemonId: string): Promise<{
+        forgotten: true;
+    }>;
+    private target;
+}
+export {};

package/dist/remote-runtime-target-control.js

@@ -0,0 +1,433 @@
+import { createHash } from "node:crypto";
+import { decodePairingCode, parsePairingOffer, } from "@rynx-ai/protocol/direct-runtime";
+import { connectDirectRuntime, DirectRuntimeClientError, DirectRuntimeRpcError, generateDirectRuntimeClientIdentity, pairDirectRuntime, } from "@rynx-ai/remote-runtime-client";
+import { RuntimeConnectionManagerError, } from "./remote-runtime-connection-manager.js";
+import { RemoteRuntimeTargetConflictError, } from "./remote-runtime-target-store.js";
+export class RuntimeTargetControlError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "RuntimeTargetControlError";
+    }
+}
+/** Local resident-daemon application service backing CLI and browser BFF target management. */
+export class DaemonRuntimeTargetControl {
+    localRuntime;
+    targets;
+    credentials;
+    connections;
+    client;
+    pairing = false;
+    constructor(localRuntime, targets, credentials, connections, client = {
+        pair: (offer, options) => pairDirectRuntime(offer, options),
+        connect: (credential) => connectDirectRuntime(credential),
+    }) {
+        this.localRuntime = localRuntime;
+        this.targets = targets;
+        this.credentials = credentials;
+        this.connections = connections;
+        this.client = client;
+    }
+    list() {
+        const localStatus = this.localRuntime.status();
+        return [
+            {
+                selector: "local",
+                daemonId: localStatus.daemonId,
+                displayName: "This device",
+                binding: "local",
+            },
+            ...this.targets.list().map(targetView),
+        ];
+    }
+    async pair(input) {
+        if (this.pairing)
+            throw controlError("conflict", "another Runtime pairing is in progress");
+        this.pairing = true;
+        try {
+            const parsed = parseOfferInput(input.offer);
+            const { offer } = parsed;
+            if (offer.daemonId === this.localRuntime.status().daemonId) {
+                throw controlError("conflict", "cannot pair the local daemon as a remote target");
+            }
+            // Validate all client-local metadata before any network enrollment.
+            const targetName = displayName(input.displayName, offer.daemonId);
+            const existing = this.targets.get(offer.daemonId);
+            if (existing) {
+                if (existing.identityPublicKey !== offer.identityPublicKey) {
+                    throw controlError("identity_mismatch", "a target with this daemonId has a different pinned identity key");
+                }
+                throw controlError("conflict", "this Runtime target is already paired");
+            }
+            const fingerprint = pairingOfferFingerprint(offer);
+            let pending = this.targets.getPendingEnrollment(offer.claimId);
+            const otherPending = this.targets.getPendingEnrollmentForDaemon(offer.daemonId);
+            if (!pending && otherPending) {
+                await this.discardExpiredPending(otherPending);
+                pending = this.targets.getPendingEnrollment(offer.claimId);
+            }
+            if (pending)
+                assertPendingOffer(pending, offer, fingerprint);
+            if (!pending && parsed.expired) {
+                throw controlError("invalid_offer", "pairing offer has expired");
+            }
+            if (!pending) {
+                const identity = generateDirectRuntimeClientIdentity();
+                const pendingCredential = pendingCredentialFrom(offer, identity);
+                let credentialRef;
+                try {
+                    credentialRef = await this.credentials.savePending(pendingCredential);
+                    pending = this.targets.addPendingEnrollment({
+                        claimId: offer.claimId,
+                        daemonId: offer.daemonId,
+                        identityPublicKey: offer.identityPublicKey,
+                        credentialRef,
+                        offerFingerprint: fingerprint,
+                        expiresAt: offer.expiresAt,
+                    });
+                }
+                catch (error) {
+                    if (credentialRef)
+                        await this.credentials.remove(credentialRef).catch(() => undefined);
+                    throw persistenceError("failed to prepare the Runtime enrollment", error);
+                }
+            }
+            return await this.resumePendingEnrollment(pending, offer, targetName, parsed.expired);
+        }
+        finally {
+            this.pairing = false;
+        }
+    }
+    async discardExpiredPending(pending) {
+        if (Date.parse(pending.expiresAt) > Date.now()) {
+            throw controlError("conflict", "a different unexpired enrollment is already pending for this Runtime");
+        }
+        try {
+            await this.credentials.remove(pending.credentialRef);
+            this.targets.removePendingEnrollment(pending.claimId);
+        }
+        catch (error) {
+            throw persistenceError("failed to discard an expired Runtime enrollment", error);
+        }
+    }
+    async resumePendingEnrollment(pending, offer, targetName, offerExpired) {
+        let enrollment;
+        try {
+            enrollment = await this.credentials.loadEnrollment(pending.credentialRef);
+        }
+        catch (error) {
+            throw controlError("authentication_failed", "pending Runtime enrollment credential is unavailable", error);
+        }
+        let accepted;
+        let status;
+        if (enrollment.state === "pending") {
+            assertPendingCredential(enrollment.credential, pending, offer);
+            let paired;
+            try {
+                paired = await this.client.pair(offer, {
+                    identity: clientIdentityFrom(enrollment.credential),
+                    ...(offerExpired ? { allowExpiredOffer: true } : {}),
+                });
+            }
+            catch (error) {
+                throw normalizeClientError(error);
+            }
+            assertPairResult(paired, offer, enrollment.credential);
+            accepted = secretCredentialFrom(paired.credential);
+            status = paired.status;
+            try {
+                await this.credentials.finalizePending(pending.credentialRef, pending.claimId, accepted);
+            }
+            catch (error) {
+                throw persistenceError("failed to finalize the Runtime enrollment credential", error);
+            }
+        }
+        else {
+            accepted = enrollment.credential;
+            assertCredentialTarget(accepted, pending.daemonId, pending.identityPublicKey);
+            status = await this.probe(directCredentialForOffer(accepted, offer));
+        }
+        let target;
+        try {
+            target = this.targets.commitPendingEnrollment(pending.claimId, {
+                daemonId: offer.daemonId,
+                displayName: targetName,
+                identityPublicKey: offer.identityPublicKey,
+                credentialRef: pending.credentialRef,
+                directEndpoint: offer.directEndpoint,
+            });
+        }
+        catch (error) {
+            throw persistenceError("failed to persist the paired Runtime target", error);
+        }
+        return { target: targetView(target), status };
+    }
+    async probe(credential) {
+        let connection;
+        try {
+            connection = await this.client.connect(credential);
+            const status = await connection.status();
+            if (status.daemonId !== credential.daemonId) {
+                throw controlError("identity_mismatch", "remote status belongs to a different daemon");
+            }
+            return status;
+        }
+        catch (error) {
+            if (error instanceof RuntimeTargetControlError)
+                throw error;
+            throw normalizeClientError(error);
+        }
+        finally {
+            await connection?.close().catch(() => undefined);
+        }
+    }
+    async test(selector) {
+        const target = selector === "local" ? this.list()[0] : targetView(this.target(selector));
+        let failure;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            let lease;
+            try {
+                lease = await this.connections.acquire(selector);
+                const status = await lease.call("status.get", {});
+                if (status.daemonId !== lease.target.daemonId) {
+                    throw controlError("identity_mismatch", "remote status belongs to a different daemon");
+                }
+                return { target, status };
+            }
+            catch (error) {
+                failure = error;
+                // status.get is read-only. Retry once only when a previously cached
+                // channel was already closed; mutations never use this path.
+                if (selector === "local" || attempt > 0 || !isClosedStatusChannel(error))
+                    break;
+            }
+            finally {
+                lease?.release();
+            }
+        }
+        if (failure instanceof RuntimeTargetControlError)
+            throw failure;
+        if (failure instanceof RuntimeConnectionManagerError) {
+            throw normalizeConnectionManagerError(failure);
+        }
+        if (failure instanceof DirectRuntimeRpcError)
+            throw normalizeRpcError(failure);
+        throw normalizeClientError(failure);
+    }
+    async forget(daemonId) {
+        if (daemonId === "local" || daemonId === this.localRuntime.status().daemonId) {
+            throw controlError("invalid_target", "the local Runtime target cannot be forgotten");
+        }
+        const existing = this.target(daemonId);
+        // invalidate() detaches the current generation synchronously. Removing the
+        // target immediately afterwards closes the acquire/forget race without
+        // exposing the credential or silently falling back to Local.
+        const invalidation = this.connections.invalidate(existing.daemonId);
+        const target = this.targets.remove(existing.daemonId);
+        if (!target)
+            throw controlError("conflict", "Runtime target disappeared while forgetting it");
+        let invalidationError;
+        try {
+            await invalidation;
+        }
+        catch (error) {
+            invalidationError = error;
+        }
+        try {
+            await this.credentials.remove(target.credentialRef);
+        }
+        catch (error) {
+            // The target is already unreachable from Rynx. Report cleanup failure so
+            // the operator knows an orphaned protected file may require attention.
+            throw controlError("conflict", "Runtime target was removed but credential cleanup failed", error);
+        }
+        if (invalidationError !== undefined) {
+            throw controlError("conflict", "Runtime target was removed but its cached connection did not close cleanly", invalidationError);
+        }
+        return { forgotten: true };
+    }
+    target(selector) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/.test(selector)) {
+            throw controlError("invalid_target", "Runtime target selector is invalid");
+        }
+        const target = this.targets.get(selector);
+        if (!target)
+            throw controlError("not_found", "Runtime target was not found");
+        return target;
+    }
+}
+function parseOfferInput(input) {
+    let value = input;
+    if (typeof input === "string") {
+        try {
+            value = input.trim().startsWith("rynx://")
+                ? decodePairingCode(input, { allowExpired: true })
+                : JSON.parse(input);
+        }
+        catch (error) {
+            throw controlError("invalid_offer", "pairing offer must be a valid Rynx pairing link or JSON", error);
+        }
+    }
+    try {
+        const offer = parsePairingOffer(value, { allowExpired: true });
+        return { offer, expired: Date.parse(offer.expiresAt) <= Date.now() };
+    }
+    catch (error) {
+        throw controlError("invalid_offer", "pairing offer is invalid", error);
+    }
+}
+function displayName(value, daemonId) {
+    if (value === undefined)
+        return `Runtime ${daemonId.slice(0, 8)}`;
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 128 ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        throw controlError("invalid_target", "Runtime target displayName is invalid");
+    }
+    return value;
+}
+function secretCredentialFrom(credential) {
+    return {
+        version: 2,
+        daemonId: credential.daemonId,
+        identityPublicKey: credential.identityPublicKey,
+        serverEncryptionPublicKey: credential.serverEncryptionPublicKey,
+        clientId: credential.clientId,
+        grantId: credential.grantId,
+        clientPublicKey: credential.clientPublicKey,
+        clientPrivateKeyPem: credential.clientPrivateKeyPem,
+    };
+}
+function pendingCredentialFrom(offer, identity) {
+    return {
+        version: 2,
+        state: "pending_enrollment",
+        daemonId: offer.daemonId,
+        identityPublicKey: offer.identityPublicKey,
+        serverEncryptionPublicKey: offer.serverEncryptionPublicKey,
+        claimId: offer.claimId,
+        ...identity,
+    };
+}
+function clientIdentityFrom(credential) {
+    return {
+        clientId: credential.clientId,
+        clientPublicKey: credential.clientPublicKey,
+        clientPrivateKeyPem: credential.clientPrivateKeyPem,
+    };
+}
+function directCredentialForOffer(credential, offer) {
+    return {
+        ...credential,
+        directEndpoint: offer.directEndpoint,
+    };
+}
+function assertPendingOffer(pending, offer, offerFingerprint) {
+    if (pending.daemonId !== offer.daemonId) {
+        throw controlError("conflict", "pairing claim belongs to a different Runtime");
+    }
+    if (pending.identityPublicKey !== offer.identityPublicKey) {
+        throw controlError("identity_mismatch", "pending enrollment has a different pinned Runtime identity");
+    }
+    if (pending.offerFingerprint !== offerFingerprint) {
+        throw controlError("conflict", "pairing offer differs from the pending enrollment");
+    }
+}
+function assertPendingCredential(credential, pending, offer) {
+    if (credential.claimId !== pending.claimId ||
+        credential.daemonId !== pending.daemonId ||
+        credential.daemonId !== offer.daemonId ||
+        credential.identityPublicKey !== pending.identityPublicKey ||
+        credential.identityPublicKey !== offer.identityPublicKey ||
+        credential.serverEncryptionPublicKey !== offer.serverEncryptionPublicKey) {
+        throw controlError("identity_mismatch", "pending Runtime metadata does not match its protected credential");
+    }
+}
+function assertCredentialTarget(credential, daemonId, identityPublicKey) {
+    if (credential.daemonId !== daemonId ||
+        credential.identityPublicKey !== identityPublicKey) {
+        throw controlError("identity_mismatch", "Runtime target metadata does not match its protected credential");
+    }
+}
+function assertPairResult(paired, offer, pending) {
+    const credential = paired.credential;
+    if (credential.daemonId !== offer.daemonId ||
+        credential.identityPublicKey !== offer.identityPublicKey ||
+        credential.serverEncryptionPublicKey !== offer.serverEncryptionPublicKey ||
+        paired.status.daemonId !== offer.daemonId) {
+        throw controlError("identity_mismatch", "enrollment result belongs to a different Runtime");
+    }
+    if (credential.directEndpoint !== offer.directEndpoint ||
+        credential.clientId !== pending.clientId ||
+        credential.clientPublicKey !== pending.clientPublicKey ||
+        credential.clientPrivateKeyPem !== pending.clientPrivateKeyPem) {
+        throw controlError("protocol_error", "enrollment result differs from the requested offer");
+    }
+}
+function pairingOfferFingerprint(offer) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        offer.type,
+        offer.enrollmentVersion,
+        offer.daemonId,
+        offer.identityAlgorithm,
+        offer.identityPublicKey,
+        offer.security,
+        offer.encryptionAlgorithm,
+        offer.serverEncryptionPublicKey,
+        offer.directEndpoint,
+        offer.claimId,
+        offer.claimSecret,
+        offer.expiresAt,
+    ]))
+        .digest("hex");
+}
+function targetView(target) {
+    return {
+        selector: target.daemonId,
+        daemonId: target.daemonId,
+        displayName: target.displayName,
+        binding: "direct",
+        endpoint: target.directRoute.endpoint,
+        identityKeyFingerprint: fingerprint(target.identityPublicKey),
+        createdAt: target.createdAt,
+    };
+}
+function fingerprint(publicKey) {
+    return `SHA256:${createHash("sha256")
+        .update(Buffer.from(publicKey, "base64url"))
+        .digest("base64url")}`;
+}
+function normalizeClientError(error) {
+    if (error instanceof DirectRuntimeClientError) {
+        const code = error.code === "closed" ? "unreachable" : error.code;
+        return controlError(code, error.message, error);
+    }
+    return controlError("unreachable", "remote Runtime connection failed", error);
+}
+function normalizeConnectionManagerError(error) {
+    const code = error.code === "closed" || error.code === "cancelled" ? "unreachable" : error.code;
+    return controlError(code, error.message, error);
+}
+function isClosedStatusChannel(error) {
+    return ((error instanceof DirectRuntimeClientError && error.code === "closed") ||
+        (error instanceof RuntimeConnectionManagerError && error.code === "closed"));
+}
+function normalizeRpcError(error) {
+    const code = error.code === "unauthorized" ? "authentication_failed" : "protocol_error";
+    return controlError(code, error.message, error);
+}
+function persistenceError(message, error) {
+    if (error instanceof RuntimeTargetControlError)
+        return error;
+    if (error instanceof RemoteRuntimeTargetConflictError) {
+        return controlError("conflict", error.message, error);
+    }
+    return controlError("conflict", message, error);
+}
+function controlError(code, message, cause) {
+    return new RuntimeTargetControlError(code, message, cause === undefined ? undefined : { cause });
+}

package/dist/remote-runtime-target-store.d.ts

@@ -0,0 +1,53 @@
+import Database from "better-sqlite3";
+export interface RemoteRuntimeTarget {
+    daemonId: string;
+    displayName: string;
+    identityPublicKey: string;
+    credentialRef: string;
+    directRoute: {
+        endpoint: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AddRemoteRuntimeTargetInput {
+    daemonId: string;
+    displayName: string;
+    identityPublicKey: string;
+    credentialRef: string;
+    directEndpoint: string;
+}
+export interface RemoteRuntimePendingEnrollment {
+    claimId: string;
+    daemonId: string;
+    identityPublicKey: string;
+    credentialRef: string;
+    offerFingerprint: string;
+    expiresAt: string;
+    createdAt: string;
+}
+export interface AddRemoteRuntimePendingEnrollmentInput {
+    claimId: string;
+    daemonId: string;
+    identityPublicKey: string;
+    credentialRef: string;
+    offerFingerprint: string;
+    expiresAt: string;
+}
+export declare class RemoteRuntimeTargetStore {
+    private readonly connection;
+    private readonly clock;
+    constructor(connection?: Database.Database, clock?: () => Date);
+    add(input: AddRemoteRuntimeTargetInput): RemoteRuntimeTarget;
+    addPendingEnrollment(input: AddRemoteRuntimePendingEnrollmentInput): RemoteRuntimePendingEnrollment;
+    getPendingEnrollment(claimIdInput: string): RemoteRuntimePendingEnrollment | undefined;
+    getPendingEnrollmentForDaemon(daemonIdInput: string): RemoteRuntimePendingEnrollment | undefined;
+    removePendingEnrollment(claimIdInput: string): RemoteRuntimePendingEnrollment | undefined;
+    commitPendingEnrollment(claimIdInput: string, input: AddRemoteRuntimeTargetInput): RemoteRuntimeTarget;
+    get(daemonIdInput: string): RemoteRuntimeTarget | undefined;
+    list(): RemoteRuntimeTarget[];
+    remove(daemonIdInput: string): RemoteRuntimeTarget | undefined;
+}
+export declare class RemoteRuntimeTargetConflictError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}