@openscout/protocol 0.2.98 → 0.2.102

package/dist/machines.d.ts

@@ -0,0 +1,231 @@
+import type { AdvertiseScope, MetadataMap, ScoutId } from "./common.js";
+/**
+ * Machines — the physical (or virtual) boxes Scout knows about.
+ *
+ * A machine is NOT a node. A node is a Scout broker runtime; a machine is the
+ * computer it runs on. The distinction matters because most machines Scout can
+ * see are not running Scout at all: a tailnet peer, a Mac advertising itself on
+ * the LAN, a Linux box that only answers ARP. Modelling them as nodes would
+ * either invent fake nodes or make them invisible, and both were wrong.
+ *
+ * A machine record is assembled from **evidence**, never asserted. Four
+ * channels report independently and none of them is authoritative:
+ *
+ * | channel   | tells us                                        |
+ * | --------- | ----------------------------------------------- |
+ * | `scout`   | a broker node lives here (id, mesh, urls)       |
+ * | `tailnet` | reachable over Tailscale (stable peer id, IPs)  |
+ * | `lan`     | seen on this network (mDNS advert, ARP neighbor)|
+ * | `host`    | terminal hosts present (herdr, tmux, zellij)    |
+ *
+ * The join between them is `machineIdentityKeys` + `groupMachineEvidence`.
+ * Everything else in this module is a pure derivation over a group, so the
+ * whole model is testable without a network, a broker, or a database.
+ */
+export declare const MACHINE_ID_PREFIX = "mach-";
+export type MachineEvidenceKind = "scout" | "tailnet" | "lan" | "host";
+export type MachinePlatform = "macos" | "linux" | "windows" | "ios" | "android" | "unknown";
+/**
+ * What a machine can do *for Scout*, as observed — never as configured. A
+ * capability is present because something answered, so an operator reading
+ * `herdr` on a row knows a herdr probe actually succeeded there.
+ */
+export type MachineCapability = "scout-broker" | "scout-web" | "scout-pairing" | "herdr" | "tmux" | "zellij" | "ssh" | "vnc" | "smb" | "http";
+export type MachineRouteKind = "loopback" | "lan" | "tailnet" | "mesh" | "relay";
+/** One way to reach a machine. Ordered by preference in `deriveMachineRoutes`. */
+export interface MachineRoute {
+    kind: MachineRouteKind;
+    host: string;
+    port?: number;
+    url?: string;
+    lastSeenAt?: number;
+}
+export type MachineTerminalHost = "herdr" | "tmux" | "zellij";
+export type LanDiscoveryMethod = "mdns" | "arp";
+interface MachineEvidenceBase {
+    kind: MachineEvidenceKind;
+    observedAt: number;
+}
+/** A Scout broker node registered with, or discovered by, this broker. */
+export interface ScoutMachineEvidence extends MachineEvidenceBase {
+    kind: "scout";
+    nodeId: ScoutId;
+    meshId?: ScoutId;
+    nodeName: string;
+    hostName?: string;
+    brokerUrl?: string;
+    webUrl?: string;
+    advertiseScope?: AdvertiseScope;
+    tailnetName?: string;
+    isSelf?: boolean;
+}
+/** A `tailscale status` peer (or self). Present whether or not it runs Scout. */
+export interface TailnetMachineEvidence extends MachineEvidenceBase {
+    kind: "tailnet";
+    peerId: string;
+    hostName?: string;
+    dnsName?: string;
+    tailnetName?: string;
+    addresses: string[];
+    online: boolean;
+    os?: string;
+    tags?: string[];
+    isSelf?: boolean;
+}
+/** A local-network sighting: an mDNS service instance or an ARP neighbor. */
+export interface LanMachineEvidence extends MachineEvidenceBase {
+    kind: "lan";
+    method: LanDiscoveryMethod;
+    hostName?: string;
+    instanceName?: string;
+    /** Full service type as browsed, e.g. `_openscout._tcp`. */
+    serviceType?: string;
+    addresses: string[];
+    port?: number;
+    macAddress?: string;
+    /** Best-effort OUI vendor. Null whenever the prefix is not in the table. */
+    vendor?: string;
+    interfaceName?: string;
+    txt?: MetadataMap;
+}
+/** A terminal host observed on a machine Scout can probe. */
+export interface HostMachineEvidence extends MachineEvidenceBase {
+    kind: "host";
+    host: MachineTerminalHost;
+    /** Machine this was probed on — host probes are never self-identifying. */
+    hostName?: string;
+    nodeId?: ScoutId;
+    sessionCount: number;
+    runningSessionCount?: number;
+    version?: string;
+}
+export type MachineEvidence = ScoutMachineEvidence | TailnetMachineEvidence | LanMachineEvidence | HostMachineEvidence;
+/**
+ * Identity keys, split by how long they stay true.
+ *
+ * `durable` keys name the machine itself — a Tailscale node id, a MAC, a Scout
+ * node id, a hostname. They are persisted with the record and re-join evidence
+ * across passes, days apart.
+ *
+ * `transient` keys are only true right now. A LAN IP is the important one: it
+ * is what joins an ARP row to an mDNS advert *inside one scan*, and it is
+ * exactly what DHCP hands to a different machine next week. Persisting it
+ * would silently fuse two machines, so it never leaves the pass that saw it.
+ */
+export interface MachineIdentityKeys {
+    durable: string[];
+    transient: string[];
+}
+/** mDNS service types Scout browses, and what each one proves. */
+export declare const MACHINE_SERVICE_CAPABILITIES: Readonly<Record<string, MachineCapability>>;
+/** Browsed for inventory. `_workstation._tcp` proves nothing but presence. */
+export declare const MACHINE_LAN_SERVICE_TYPES: readonly string[];
+export declare function normalizeMachineHostName(value: string | null | undefined): string;
+/**
+ * Lowercase colon-form MAC. Returns "" for entries that identify nothing —
+ * broadcast, all-zero, or an incomplete ARP row.
+ *
+ * BSD `arp` drops leading zeros (`3c:22:fb:1:2:3`), so octets are padded
+ * rather than the string being scrubbed of separators: scrubbing turns that
+ * nine-character form into a rejected MAC instead of a valid one.
+ */
+export declare function normalizeMacAddress(value: string | null | undefined): string;
+export declare function normalizeMachineAddress(value: string | null | undefined): string;
+export declare function isLoopbackAddress(value: string): boolean;
+/** Tailscale's CGNAT range (100.64.0.0/10) and its IPv6 ULA prefix. */
+export declare function isTailnetAddress(value: string): boolean;
+/**
+ * The keys one piece of evidence claims. Two pieces of evidence describe the
+ * same machine when they share any key — see `groupMachineEvidence`.
+ */
+export declare function machineIdentityKeys(evidence: MachineEvidence): MachineIdentityKeys;
+export interface MachineEvidenceGroup {
+    /** Durable keys only — what gets persisted so the next pass re-joins here. */
+    identityKeys: string[];
+    evidence: MachineEvidence[];
+    /**
+     * Indices of every seed this group attached to, ascending. More than one
+     * means fresh evidence proved two records were always the same machine —
+     * the first is the survivor, the rest are absorbed by the caller.
+     */
+    seedIndices: number[];
+}
+/**
+ * Union-find over identity keys. Evidence lands in the same group when it
+ * shares any key, directly or through a chain — an ARP row and an mDNS advert
+ * share an IP; the advert and a tailnet peer share a hostname; so all three
+ * describe one machine even though ARP and Tailscale share nothing at all.
+ *
+ * `seeds` are the durable key sets of machines already on record. They enter
+ * the union as members, which is what lets a machine seen only by ARP today
+ * and only by Tailscale tomorrow stay one record: the seed bridges the passes.
+ */
+export declare function groupMachineEvidence(evidence: readonly MachineEvidence[], seeds?: readonly (readonly string[])[]): MachineEvidenceGroup[];
+/**
+ * Deterministic id from a group's durable keys, so two brokers observing the
+ * same machine mint the same id and a restart never renumbers the fleet.
+ * FNV-1a ×2, matching `stableChannelId`.
+ */
+export declare function stableMachineId(identityKeys: readonly string[]): ScoutId;
+/**
+ * The name to show. Scout's own name for the node wins because the operator
+ * chose it; then the tailnet hostname, then whatever the LAN advertised. A
+ * machine known only by MAC gets its MAC, never a fabricated label.
+ */
+export declare function deriveMachineName(evidence: readonly MachineEvidence[]): string;
+export declare function deriveMachinePlatform(evidence: readonly MachineEvidence[]): MachinePlatform;
+export declare function deriveMachineCapabilities(evidence: readonly MachineEvidence[]): MachineCapability[];
+/**
+ * Routes, best first: loopback (it's this machine), then LAN (no hop), then
+ * tailnet, then whatever the mesh advertised. This is the order a caller
+ * should dial, and it mirrors the LAN-first preference iOS already uses.
+ */
+/**
+ * Every way we know to reach this machine, best first. `isSelf` decides whether
+ * loopback belongs at all: a peer advertising `http://127.0.0.1:43120` is
+ * describing its own loopback, which is not a route to it from here.
+ */
+export declare function deriveMachineRoutes(evidence: readonly MachineEvidence[], isSelf?: boolean): MachineRoute[];
+export type MachinePresence = "online" | "recent" | "offline";
+/** Anything seen inside this window counts as present. */
+export declare const MACHINE_ONLINE_WINDOW_MS: number;
+export declare const MACHINE_RECENT_WINDOW_MS: number;
+export interface MachineRecord {
+    id: ScoutId;
+    /** Operator-set name. Null means "use `name`". */
+    displayName: string | null;
+    /** Derived from the strongest evidence — recomputed every pass. */
+    name: string;
+    platform: MachinePlatform;
+    /** Durable keys, sorted. The join key set for the next pass. */
+    identityKeys: string[];
+    isSelf: boolean;
+    scoutNodeId?: ScoutId;
+    meshId?: ScoutId;
+    tailnetId?: string;
+    tailnetName?: string;
+    hostNames: string[];
+    addresses: string[];
+    macAddresses: string[];
+    capabilities: MachineCapability[];
+    routes: MachineRoute[];
+    evidence: MachineEvidence[];
+    /** Operator marked it worth keeping even when nothing has seen it in weeks. */
+    pinned: boolean;
+    notes?: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    metadata?: MetadataMap;
+}
+export declare function machineLabel(machine: Pick<MachineRecord, "displayName" | "name">): string;
+export declare function machinePresence(machine: Pick<MachineRecord, "lastSeenAt">, now?: number): MachinePresence;
+/**
+ * Build (or rebuild) a record from a group. `previous` carries the parts an
+ * operator owns — id, chosen name, notes, pin, first-seen — which no amount of
+ * fresh evidence may overwrite.
+ */
+export declare function buildMachineRecord(group: MachineEvidenceGroup, previous?: Partial<MachineRecord> | null): MachineRecord;
+/** Sort for display: this machine, then present ones, then by name. */
+export declare function compareMachines(a: MachineRecord, b: MachineRecord): number;
+export {};
+//# sourceMappingURL=machines.d.ts.map

package/dist/machines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines.d.ts","sourceRoot":"","sources":["../src/machines.ts"],"names":[],"mappings":"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"}