@rynx-ai/daemon 0.1.0 → 0.1.9

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

@@ -0,0 +1,307 @@
+import { createPublicKey } from "node:crypto";
+import { db } from "./db.js";
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
+const CREDENTIAL_REF_PATTERN = /^credential_[A-Za-z0-9_-]{24}$/;
+const MAX_DISPLAY_NAME_CHARS = 128;
+export class RemoteRuntimeTargetStore {
+    connection;
+    clock;
+    constructor(connection = db(), clock = () => new Date()) {
+        this.connection = connection;
+        this.clock = clock;
+    }
+    add(input) {
+        const normalized = normalizeTargetInput(input);
+        const now = validNow(this.clock()).toISOString();
+        const insert = this.connection.transaction(() => {
+            this.connection.prepare(`INSERT INTO runtime_targets
+           (daemon_id, display_name, identity_public_key, credential_ref, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)`).run(normalized.daemonId, normalized.displayName, normalized.identityPublicKey, normalized.credentialRef, now, now);
+            this.connection.prepare(`INSERT INTO runtime_direct_routes
+           (daemon_id, endpoint, updated_at)
+         VALUES (?, ?, ?)`).run(normalized.daemonId, normalized.directEndpoint, now);
+        });
+        try {
+            insert.immediate();
+        }
+        catch (error) {
+            if (isSqliteConstraint(error)) {
+                throw new RemoteRuntimeTargetConflictError("a Runtime target with this daemon identity or credential already exists", { cause: error });
+            }
+            throw error;
+        }
+        return this.get(normalized.daemonId);
+    }
+    addPendingEnrollment(input) {
+        const normalized = normalizePendingEnrollmentInput(input);
+        const createdAt = validNow(this.clock()).toISOString();
+        try {
+            this.connection.prepare(`INSERT INTO runtime_pending_enrollments
+           (claim_id, daemon_id, identity_public_key, credential_ref,
+            offer_fingerprint, expires_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`).run(normalized.claimId, normalized.daemonId, normalized.identityPublicKey, normalized.credentialRef, normalized.offerFingerprint, normalized.expiresAt, createdAt);
+        }
+        catch (error) {
+            if (isSqliteConstraint(error)) {
+                throw new RemoteRuntimeTargetConflictError("a pending Runtime enrollment already exists for this claim, daemon, or credential", { cause: error });
+            }
+            throw error;
+        }
+        return this.getPendingEnrollment(normalized.claimId);
+    }
+    getPendingEnrollment(claimIdInput) {
+        const claimId = validId(claimIdInput, "claimId");
+        const row = this.connection.prepare(`SELECT claim_id, daemon_id, identity_public_key, credential_ref,
+              offer_fingerprint, expires_at, created_at
+       FROM runtime_pending_enrollments
+       WHERE claim_id = ?`).get(claimId);
+        return row ? pendingEnrollmentFromRow(row) : undefined;
+    }
+    getPendingEnrollmentForDaemon(daemonIdInput) {
+        const daemonId = validId(daemonIdInput, "daemonId");
+        const row = this.connection.prepare(`SELECT claim_id, daemon_id, identity_public_key, credential_ref,
+              offer_fingerprint, expires_at, created_at
+       FROM runtime_pending_enrollments
+       WHERE daemon_id = ?`).get(daemonId);
+        return row ? pendingEnrollmentFromRow(row) : undefined;
+    }
+    removePendingEnrollment(claimIdInput) {
+        const claimId = validId(claimIdInput, "claimId");
+        const remove = this.connection.transaction(() => {
+            const pending = this.getPendingEnrollment(claimId);
+            if (!pending)
+                return undefined;
+            const result = this.connection.prepare("DELETE FROM runtime_pending_enrollments WHERE claim_id = ?").run(claimId);
+            if (result.changes !== 1)
+                throw new Error("pending Runtime enrollment changed concurrently");
+            return pending;
+        });
+        return remove.immediate();
+    }
+    commitPendingEnrollment(claimIdInput, input) {
+        const claimId = validId(claimIdInput, "claimId");
+        const normalized = normalizeTargetInput(input);
+        const now = validNow(this.clock()).toISOString();
+        const commit = this.connection.transaction(() => {
+            const pending = this.getPendingEnrollment(claimId);
+            if (!pending)
+                throw new Error("pending Runtime enrollment was not found");
+            if (pending.daemonId !== normalized.daemonId ||
+                pending.identityPublicKey !== normalized.identityPublicKey ||
+                pending.credentialRef !== normalized.credentialRef) {
+                throw new Error("pending Runtime enrollment does not match the accepted credential");
+            }
+            insertTarget(this.connection, normalized, now);
+            const deleted = this.connection.prepare("DELETE FROM runtime_pending_enrollments WHERE claim_id = ?").run(claimId);
+            if (deleted.changes !== 1) {
+                throw new Error("pending Runtime enrollment changed concurrently");
+            }
+        });
+        try {
+            commit.immediate();
+        }
+        catch (error) {
+            if (error instanceof RemoteRuntimeTargetConflictError)
+                throw error;
+            if (isSqliteConstraint(error)) {
+                throw new RemoteRuntimeTargetConflictError("a Runtime target with this daemon identity or credential already exists", { cause: error });
+            }
+            throw error;
+        }
+        return this.get(normalized.daemonId);
+    }
+    get(daemonIdInput) {
+        const daemonId = validId(daemonIdInput, "daemonId");
+        const row = this.connection.prepare(`SELECT t.daemon_id, t.display_name, t.identity_public_key, t.credential_ref,
+              t.created_at, t.updated_at, r.endpoint
+       FROM runtime_targets t
+       JOIN runtime_direct_routes r ON r.daemon_id = t.daemon_id
+       WHERE t.daemon_id = ?`).get(daemonId);
+        return row ? targetFromRow(row) : undefined;
+    }
+    list() {
+        const rows = this.connection.prepare(`SELECT t.daemon_id, t.display_name, t.identity_public_key, t.credential_ref,
+              t.created_at, t.updated_at, r.endpoint
+       FROM runtime_targets t
+       JOIN runtime_direct_routes r ON r.daemon_id = t.daemon_id
+       ORDER BY lower(t.display_name), t.daemon_id`).all();
+        return rows.map(targetFromRow);
+    }
+    remove(daemonIdInput) {
+        const daemonId = validId(daemonIdInput, "daemonId");
+        const remove = this.connection.transaction(() => {
+            const target = this.get(daemonId);
+            if (!target)
+                return undefined;
+            const result = this.connection
+                .prepare("DELETE FROM runtime_targets WHERE daemon_id = ?")
+                .run(daemonId);
+            if (result.changes !== 1)
+                throw new Error("Runtime target changed concurrently");
+            return target;
+        });
+        return remove.immediate();
+    }
+}
+export class RemoteRuntimeTargetConflictError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RemoteRuntimeTargetConflictError";
+    }
+}
+function normalizeTargetInput(input) {
+    const daemonId = validId(input.daemonId, "daemonId");
+    if (daemonId === "local")
+        throw new Error("local is a reserved Runtime target selector");
+    const displayName = validDisplayName(input.displayName);
+    const identityPublicKey = validEd25519PublicKey(input.identityPublicKey);
+    const credentialRef = validCredentialRef(input.credentialRef);
+    const directEndpoint = validDirectEndpoint(input.directEndpoint);
+    return {
+        daemonId,
+        displayName,
+        identityPublicKey,
+        credentialRef,
+        directEndpoint,
+    };
+}
+function normalizePendingEnrollmentInput(input) {
+    const claimId = validId(input.claimId, "claimId");
+    const daemonId = validId(input.daemonId, "daemonId");
+    if (daemonId === "local")
+        throw new Error("local is a reserved Runtime target selector");
+    const identityPublicKey = validEd25519PublicKey(input.identityPublicKey);
+    const credentialRef = validCredentialRef(input.credentialRef);
+    if (!/^[0-9a-f]{64}$/.test(input.offerFingerprint)) {
+        throw new Error("offerFingerprint is invalid");
+    }
+    const expiresAt = validTimestamp(input.expiresAt, "expiresAt");
+    return {
+        claimId,
+        daemonId,
+        identityPublicKey,
+        credentialRef,
+        offerFingerprint: input.offerFingerprint,
+        expiresAt,
+    };
+}
+function insertTarget(connection, input, now) {
+    connection.prepare(`INSERT INTO runtime_targets
+       (daemon_id, display_name, identity_public_key, credential_ref, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(input.daemonId, input.displayName, input.identityPublicKey, input.credentialRef, now, now);
+    connection.prepare(`INSERT INTO runtime_direct_routes
+       (daemon_id, endpoint, updated_at)
+     VALUES (?, ?, ?)`).run(input.daemonId, input.directEndpoint, now);
+}
+function targetFromRow(row) {
+    const input = normalizeTargetInput({
+        daemonId: row.daemon_id,
+        displayName: row.display_name,
+        identityPublicKey: row.identity_public_key,
+        credentialRef: row.credential_ref,
+        directEndpoint: row.endpoint,
+    });
+    const createdAt = validTimestamp(row.created_at, "createdAt");
+    const updatedAt = validTimestamp(row.updated_at, "updatedAt");
+    return {
+        daemonId: input.daemonId,
+        displayName: input.displayName,
+        identityPublicKey: input.identityPublicKey,
+        credentialRef: input.credentialRef,
+        directRoute: {
+            endpoint: input.directEndpoint,
+        },
+        createdAt,
+        updatedAt,
+    };
+}
+function pendingEnrollmentFromRow(row) {
+    return {
+        claimId: validId(row.claim_id, "claimId"),
+        daemonId: validId(row.daemon_id, "daemonId"),
+        identityPublicKey: validEd25519PublicKey(row.identity_public_key),
+        credentialRef: validCredentialRef(row.credential_ref),
+        offerFingerprint: /^[0-9a-f]{64}$/.test(row.offer_fingerprint)
+            ? row.offer_fingerprint
+            : invalidStoredOfferFingerprint(),
+        expiresAt: validTimestamp(row.expires_at, "expiresAt"),
+        createdAt: validTimestamp(row.created_at, "createdAt"),
+    };
+}
+function invalidStoredOfferFingerprint() {
+    throw new Error("stored Runtime target offerFingerprint is invalid");
+}
+function validDisplayName(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_DISPLAY_NAME_CHARS ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new Error("displayName is invalid");
+    }
+    return value;
+}
+function validEd25519PublicKey(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]{59}$/.test(value)) {
+        throw new Error("identityPublicKey is invalid");
+    }
+    try {
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.byteLength !== 44 || bytes.toString("base64url") !== value)
+            throw new Error();
+        const key = createPublicKey({ key: bytes, format: "der", type: "spki" });
+        if (key.asymmetricKeyType !== "ed25519")
+            throw new Error();
+        return key.export({ format: "der", type: "spki" }).toString("base64url");
+    }
+    catch {
+        throw new Error("identityPublicKey is invalid");
+    }
+}
+function validCredentialRef(value) {
+    if (typeof value !== "string" || !CREDENTIAL_REF_PATTERN.test(value)) {
+        throw new Error("credentialRef is invalid");
+    }
+    return value;
+}
+function validDirectEndpoint(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("directEndpoint is invalid");
+    }
+    if ((url.protocol !== "ws:" && url.protocol !== "wss:") ||
+        !url.hostname ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/runtime/direct/v2/control") {
+        throw new Error("directEndpoint is invalid");
+    }
+    return url.toString();
+}
+function validId(value, field) {
+    if (typeof value !== "string" || !OPAQUE_ID_PATTERN.test(value)) {
+        throw new Error(`${field} is invalid`);
+    }
+    return value;
+}
+function validTimestamp(value, field) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`stored Runtime target ${field} is invalid`);
+    }
+    return value;
+}
+function validNow(value) {
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+        throw new Error("Runtime target clock returned an invalid date");
+    }
+    return value;
+}
+function isSqliteConstraint(error) {
+    return typeof error === "object" && error !== null && "code" in error &&
+        typeof error.code === "string" && error.code.startsWith("SQLITE_CONSTRAINT");
+}

package/dist/runtime-share-addresses.d.ts

@@ -0,0 +1,21 @@
+import type { ControlRuntimeShareAddress } from "@rynx-ai/protocol/control";
+interface HostNetworkAddress {
+    address: string;
+    family: string | number;
+    internal: boolean;
+}
+export type HostNetworkInterfaces = NodeJS.Dict<readonly HostNetworkAddress[]>;
+interface ListRuntimeShareAddressesOptions {
+    interfaces?: HostNetworkInterfaces;
+    bindHost?: string;
+}
+/**
+ * List addresses another device may be able to dial.
+ *
+ * This intentionally mirrors reference implementation's discovery policy: expose every
+ * non-internal IPv4 interface and prefer Tailnet addresses, while leaving the
+ * final reachability choice to the operator. Virtual and container interfaces
+ * remain visible because they can be the correct route in some deployments.
+ */
+export declare function listRuntimeShareAddresses({ interfaces, bindHost, }?: ListRuntimeShareAddressesOptions): ControlRuntimeShareAddress[];
+export {};

package/dist/runtime-share-addresses.js

@@ -0,0 +1,50 @@
+import { networkInterfaces } from "node:os";
+/**
+ * List addresses another device may be able to dial.
+ *
+ * This intentionally mirrors reference implementation's discovery policy: expose every
+ * non-internal IPv4 interface and prefer Tailnet addresses, while leaving the
+ * final reachability choice to the operator. Virtual and container interfaces
+ * remain visible because they can be the correct route in some deployments.
+ */
+export function listRuntimeShareAddresses({ interfaces = networkInterfaces(), bindHost = "0.0.0.0", } = {}) {
+    const result = [];
+    const seen = new Set();
+    const concreteBindAddress = bindHost !== "0.0.0.0" && isIpv4Address(bindHost)
+        ? bindHost
+        : undefined;
+    if (bindHost !== "0.0.0.0" && !concreteBindAddress)
+        return result;
+    for (const [interfaceName, addresses] of Object.entries(interfaces)) {
+        if (!addresses)
+            continue;
+        for (const candidate of addresses) {
+            if ((candidate.family === "IPv4" || candidate.family === 4) &&
+                !candidate.internal &&
+                (!concreteBindAddress || candidate.address === concreteBindAddress) &&
+                !seen.has(candidate.address)) {
+                seen.add(candidate.address);
+                result.push({ interfaceName, address: candidate.address });
+            }
+        }
+    }
+    return result.sort((left, right) => Number(isTailnetIpv4Address(right.address)) -
+        Number(isTailnetIpv4Address(left.address)));
+}
+function isTailnetIpv4Address(address) {
+    const octets = ipv4Octets(address);
+    return octets !== undefined &&
+        octets[0] === 100 &&
+        octets[1] >= 64 &&
+        octets[1] <= 127;
+}
+function isIpv4Address(address) {
+    return ipv4Octets(address) !== undefined;
+}
+function ipv4Octets(address) {
+    const octets = address.split(".").map((part) => /^\d+$/.test(part) ? Number(part) : Number.NaN);
+    return octets.length === 4 &&
+        octets.every((octet) => Number.isInteger(octet) && octet >= 0 && octet <= 255)
+        ? octets
+        : undefined;
+}

package/dist/session-browser-capability-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Boot-live authorization for a managed Session to bootstrap its own Browser.
+ *
+ * Capabilities are stable until Session deletion or daemon shutdown. They are
+ * intentionally not short-lived claims and have no refresh protocol.
+ */
+export declare class SessionBrowserCapabilityStore {
+    private readonly records;
+    issue(sessionId: string): string;
+    verify(sessionId: string, capability: string): boolean;
+    revoke(sessionId: string): boolean;
+    revokeAll(): void;
+}

package/dist/session-browser-capability-store.js

@@ -0,0 +1,58 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+const SESSION_ID_MAX_CHARS = 512;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+const CAPABILITY_BYTES = 32;
+const CAPABILITY_CHARS = 43;
+/**
+ * Boot-live authorization for a managed Session to bootstrap its own Browser.
+ *
+ * Capabilities are stable until Session deletion or daemon shutdown. They are
+ * intentionally not short-lived claims and have no refresh protocol.
+ */
+export class SessionBrowserCapabilityStore {
+    records = new Map();
+    issue(sessionId) {
+        requireSessionId(sessionId);
+        const existing = this.records.get(sessionId);
+        if (existing)
+            return existing.capability;
+        const capability = randomBytes(CAPABILITY_BYTES).toString("base64url");
+        this.records.set(sessionId, { capability, digest: digestCapability(capability) });
+        return capability;
+    }
+    verify(sessionId, capability) {
+        if (!isSessionId(sessionId) || !isCapability(capability))
+            return false;
+        const record = this.records.get(sessionId);
+        if (!record)
+            return false;
+        return timingSafeEqual(digestCapability(capability), record.digest);
+    }
+    revoke(sessionId) {
+        if (!isSessionId(sessionId))
+            return false;
+        return this.records.delete(sessionId);
+    }
+    revokeAll() {
+        this.records.clear();
+    }
+}
+function requireSessionId(value) {
+    if (!isSessionId(value)) {
+        throw new TypeError("Session identity must be a bounded opaque ASCII token");
+    }
+}
+function isSessionId(value) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= SESSION_ID_MAX_CHARS &&
+        SESSION_ID_PATTERN.test(value);
+}
+function isCapability(value) {
+    return typeof value === "string" &&
+        value.length === CAPABILITY_CHARS &&
+        /^[A-Za-z0-9_-]+$/.test(value);
+}
+function digestCapability(value) {
+    return createHash("sha256").update(value, "utf8").digest();
+}

package/dist/session-emulator-binding-store.d.ts

@@ -0,0 +1,10 @@
+import type { RemoteRuntimeEmulatorBackend } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { type SessionEmulatorBindingRecord, type SessionEmulatorBindingStore } from "@rynx-ai/server";
+export declare class SqliteSessionEmulatorBindingStore implements SessionEmulatorBindingStore {
+    get(sessionId: string): SessionEmulatorBindingRecord | undefined;
+    findByDevice(backend: RemoteRuntimeEmulatorBackend, deviceId: string): SessionEmulatorBindingRecord | undefined;
+    bind(record: SessionEmulatorBindingRecord): void;
+    release(sessionId: string, bindingId: string): boolean;
+    releaseSession(sessionId: string): boolean;
+    releaseDevice(backend: RemoteRuntimeEmulatorBackend, deviceId: string): number;
+}

package/dist/session-emulator-binding-store.js

@@ -0,0 +1,61 @@
+import { SessionEmulatorBindingConflictError, } from "@rynx-ai/server";
+import { db } from "./db.js";
+export class SqliteSessionEmulatorBindingStore {
+    get(sessionId) {
+        const row = db().prepare(`SELECT session_id, binding_id, backend, device_id, device_name, attached_at
+       FROM session_emulator_bindings WHERE session_id = ?`).get(sessionId);
+        return row ? bindingRecord(row) : undefined;
+    }
+    findByDevice(backend, deviceId) {
+        const row = db().prepare(`SELECT session_id, binding_id, backend, device_id, device_name, attached_at
+       FROM session_emulator_bindings WHERE backend = ? AND device_id = ?`).get(backend, deviceId);
+        return row ? bindingRecord(row) : undefined;
+    }
+    bind(record) {
+        const connection = db();
+        const replace = connection.transaction(() => {
+            connection.prepare("DELETE FROM session_emulator_bindings WHERE session_id = ?")
+                .run(record.sessionId);
+            connection.prepare(`INSERT INTO session_emulator_bindings
+           (session_id, binding_id, backend, device_id, device_name, attached_at)
+         VALUES (@sessionId, @bindingId, @backend, @deviceId, @deviceName, @attachedAt)`).run({
+                ...record,
+                deviceName: record.deviceName ?? null,
+            });
+        });
+        try {
+            replace();
+        }
+        catch (error) {
+            if (isSqliteConstraint(error)) {
+                throw new SessionEmulatorBindingConflictError(undefined, { cause: error });
+            }
+            throw error;
+        }
+    }
+    release(sessionId, bindingId) {
+        return db().prepare("DELETE FROM session_emulator_bindings WHERE session_id = ? AND binding_id = ?").run(sessionId, bindingId).changes > 0;
+    }
+    releaseSession(sessionId) {
+        return db().prepare("DELETE FROM session_emulator_bindings WHERE session_id = ?").run(sessionId).changes > 0;
+    }
+    releaseDevice(backend, deviceId) {
+        return db().prepare("DELETE FROM session_emulator_bindings WHERE backend = ? AND device_id = ?").run(backend, deviceId).changes;
+    }
+}
+function bindingRecord(row) {
+    return {
+        sessionId: row.session_id,
+        bindingId: row.binding_id,
+        backend: row.backend,
+        deviceId: row.device_id,
+        ...(row.device_name ? { deviceName: row.device_name } : {}),
+        attachedAt: row.attached_at,
+    };
+}
+function isSqliteConstraint(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT");
+}

package/dist/session-launch-operations.d.ts

@@ -0,0 +1,41 @@
+import { type MachineSessionRecord } from "@rynx-ai/core";
+type PluginSessionLaunchMeta = Omit<MachineSessionRecord, "id" | "source" | "createdAt" | "updatedAt">;
+export interface EnsurePluginSessionLaunchInput {
+    /** Authenticated plugin identity. The future RPC host must inject this value. */
+    pluginId: string;
+    /** Opaque plugin-owned namespace, such as one connection profile. */
+    scopeId: string;
+    /** Stable across retries. A remote lease token or attempt number is not an operation id. */
+    operationId: string;
+    /** SHA-256 of the host-normalized, execution-affecting launch request. */
+    requestHash: string;
+    session: PluginSessionLaunchMeta;
+}
+export interface EnsurePluginSessionLaunchResult {
+    sessionId: string;
+    disposition: "created" | "replayed";
+}
+export declare class SessionLaunchOperationConflictError extends Error {
+    readonly pluginId: string;
+    readonly scopeId: string;
+    readonly operationId: string;
+    readonly code = "SESSION_LAUNCH_OPERATION_CONFLICT";
+    constructor(pluginId: string, scopeId: string, operationId: string);
+}
+export declare class SessionLaunchOperationTargetDeletedError extends Error {
+    readonly pluginId: string;
+    readonly scopeId: string;
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly code = "SESSION_LAUNCH_OPERATION_TARGET_DELETED";
+    constructor(pluginId: string, scopeId: string, operationId: string, sessionId: string);
+}
+/**
+ * Atomically allocate a persisted machine session for one plugin operation.
+ *
+ * The durable operation row is the idempotency boundary across runner crashes,
+ * daemon restarts, and remote lease re-delivery. It deliberately excludes any
+ * Workspace concept: `scopeId` and `operationId` are opaque to the daemon.
+ */
+export declare function ensurePluginSessionLaunch(input: EnsurePluginSessionLaunchInput): EnsurePluginSessionLaunchResult;
+export {};