@profullstack/fleet 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @profullstack/fleet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read an [OpenDevice](https://logicsrc.com/docs/opendevice) inventory, the one file that lists every machine you run (servers, desktops, laptops, phones, tablets). Then:
+
+- **cost**: add up what the fleet costs a month, per currency, by provider, profile and scope
+- **observe**: collect each box's public metadata (DNS, reverse DNS, ASN, TLS certificate, SSH banner, HTTP server, open well-known ports, well-known files)
+- **export**: turn the costs into CoinPay finances recurring charges, with stable keys and payees for matching against bank feeds
+- **join**: match the inventory against agent-reported machines (ThreatCrush servers, W3BS fleet machines), so the boxes without an agent still show up
+
+ThreatCrush's dashboard and w3bs.org/fleet read inventories through this package.
+
+```sh
+npm i @profullstack/fleet
+npx fleet list opendevice.json
+```
+
+## CLI
+
+```
+fleet list     [inventory]   Every device, its profile, provider and monthly cost
+fleet cost     [inventory]   Monthly run rate: total, by provider, profile, scope
+fleet validate [inventory]   Errors and warnings against the spec
+fleet observe  [inventory]   Collect public metadata; --write saves it into the file
+fleet coinpay  [inventory]   Costs as CoinPay recurring charges (JSON)
+```
+
+`inventory` is a path or an https URL (`--header "Authorization: Bearer ..."` for a private one). It defaults to `$FLEET_INVENTORY`, then `./opendevice.json`. Add `--json` for machine output.
+
+```
+$ fleet list
+ID             PROFILE  STATUS   PROVIDER       $/MO
+app1           server   active   Example Racks  $149.00
+eu1            server   active   Euro VPS       €10.00
+ops-phone      phone    active   -              $25.00
+design-laptop  desktop  active   -              $40.00
+
+Monthly: €10.00 + $214.00  (4 counted)
+```
+
+## API
+
+```js
+import { parseInventory, validateInventory, fleetCost, toCoinPayCosts, matchAgents, loadInventory, formatMonthly } from '@profullstack/fleet';
+import { observe, observeInventory } from '@profullstack/fleet/observe'; // Node only
+
+const inv = await loadInventory('https://ops.example/opendevice.json', { headers: { authorization: `Bearer ${token}` } });
+const cost = fleetCost(inv);            // { monthly: { USD: 590 }, by_provider, by_profile, by_scope, devices, unstated, counted }
+formatMonthly(cost.monthly);            // "$590.00"
+toCoinPayCosts(inv);                    // [{ key: 'device:dev2', payee: 'DEDIROCK', monthlyEquivalent: 149, cadence: 'monthly', ... }]
+matchAgents(inv, threatcrushServers);   // { devices: [{ device, agents: [...] }], unmatched: [...] }
+```
+
+### Cost rules (from the spec)
+
+- Monthly run rate: `month` as is, `year / 12`, `hour * 730`. `once` counts only with `amortize_months` and `since`.
+- Totals stay per currency. Nothing is converted.
+- A `group` shared by several devices on one bill counts once, from the device that states `amount`.
+- A device with no `amount` is **unstated** and listed as such, never guessed.
+- `retired` devices and costs past `until` count zero.
+
+### Observation rules
+
+Only what anyone could see without the device's credentials, and only for devices you run. Private addresses (RFC 1918, CGNAT, link-local, ULA) are never probed. Client profiles (desktop, phone, tablet) are not network-probed.
+
+## License
+
+MIT, Profullstack, Inc.

package/bin/fleet.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// fleet: read an OpenDevice inventory, show what the fleet costs a month, observe
+// public metadata, and export costs for CoinPay.
+import { writeFile } from 'node:fs/promises';
+import { fleetCost, formatMonthly, loadInventory, toCoinPayCosts, validateInventory } from '../src/index.js';
+import { observeInventory } from '../src/observe.js';
+
+const HELP = `fleet - OpenDevice inventories (https://logicsrc.com/docs/opendevice)
+
+Usage:
+  fleet list     [inventory]   Every device, its profile, provider and monthly cost
+  fleet cost     [inventory]   Monthly run rate: total, by provider, profile, scope
+  fleet validate [inventory]   Errors and warnings against the spec
+  fleet observe  [inventory]   Collect public metadata (DNS, PTR, ASN, TLS, SSH, ports)
+                               --write saves it back into the file
+  fleet coinpay  [inventory]   Costs as CoinPay recurring charges (JSON)
+
+  inventory is a path or an https URL; default $FLEET_INVENTORY or ./opendevice.json
+  --json         machine output     --header "K: V"  send a header with a URL
+`;
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => {
+  const i = args.indexOf(f);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const positional = args.filter((a, i) => !a.startsWith('--') && !(args[i - 1] === '--header'));
+const [cmd, where = process.env.FLEET_INVENTORY || './opendevice.json'] = positional;
+const json = flag('--json');
+const out = (v) => process.stdout.write(`${typeof v === 'string' ? v : JSON.stringify(v, null, 2)}\n`);
+
+function headers() {
+  const h = opt('--header');
+  if (!h) return undefined;
+  const i = h.indexOf(':');
+  return { [h.slice(0, i).trim()]: h.slice(i + 1).trim() };
+}
+
+function pad(rows) {
+  const w = rows[0].map((_, c) => Math.max(...rows.map((r) => String(r[c]).length)));
+  return rows.map((r) => r.map((v, c) => String(v).padEnd(w[c])).join('  ').trimEnd()).join('\n');
+}
+
+async function main() {
+  if (!cmd || cmd === 'help' || flag('--help') || flag('-h')) return out(HELP);
+  const inv = await loadInventory(where, { headers: headers() });
+  if (cmd === 'validate') {
+    const r = validateInventory(inv);
+    if (json) return out(r);
+    for (const e of r.errors) out(`error: ${e}`);
+    for (const w of r.warnings) out(`warn:  ${w}`);
+    out(r.valid ? `ok: ${inv.devices.length} devices` : 'invalid');
+    process.exitCode = r.valid ? 0 : 1;
+    return;
+  }
+  if (cmd === 'list' || cmd === 'cost') {
+    const c = fleetCost(inv);
+    if (json) return out(cmd === 'list' ? c.devices : c);
+    if (cmd === 'list') {
+      const rows = [['ID', 'PROFILE', 'STATUS', 'PROVIDER', '$/MO']];
+      for (const d of c.devices) {
+        const m = d.monthly;
+        rows.push([d.id, d.profile, d.status, d.provider ?? '-', m.state === 'stated' ? formatMonthly({ [m.currency]: m.amount }) : m.state]);
+      }
+      out(pad(rows));
+    }
+    out(`\nMonthly: ${formatMonthly(c.monthly)}  (${c.counted} counted${c.unstated.length ? `, unstated: ${c.unstated.join(', ')}` : ''})`);
+    if (cmd === 'cost') {
+      for (const [label, m] of [['provider', c.by_provider], ['profile', c.by_profile], ['scope', c.by_scope]]) {
+        out(`\nBy ${label}:`);
+        for (const [k, v] of Object.entries(m)) {
+          const cur = k.split(' ').pop();
+          out(`  ${k.slice(0, -cur.length - 1).padEnd(20)} ${formatMonthly({ [cur]: v })}`);
+        }
+      }
+    }
+    return;
+  }
+  if (cmd === 'coinpay') return out(toCoinPayCosts(inv));
+  if (cmd === 'observe') {
+    const next = await observeInventory(inv);
+    if (flag('--write')) {
+      if (/^https?:/.test(where)) throw new Error('--write needs a local file');
+      await writeFile(where, `${JSON.stringify({ ...next, updated: new Date().toISOString() }, null, 2)}\n`);
+      return out(`observed ${next.devices.filter((d) => d.observed).length} devices -> ${where}`);
+    }
+    return out(next.devices.map((d) => ({ id: d.id, observed: d.observed ?? null })));
+  }
+  out(HELP);
+  process.exitCode = 2;
+}
+
+main().catch((err) => {
+  process.stderr.write(`fleet: ${err.message}\n`);
+  process.exitCode = 1;
+});

package/example.json

@@ -0,0 +1,23 @@
+{
+  "operator": { "name": "Northwind Labs", "web": "https://northwind.example" },
+  "updated": "2026-10-28T06:00:00Z",
+  "currency": "USD",
+  "devices": [
+    {
+      "id": "app1", "name": "app1", "profile": "server", "role": "shared app box",
+      "hostnames": ["app1.northwind.example"], "addresses": { "ipv4": ["203.0.113.10"] },
+      "provider": { "name": "Example Racks", "offer": { "descriptor": "https://racks.example/.well-known/openserver.json", "id": "dedi-epyc-16" } },
+      "cost": { "amount": 149, "interval": "month", "payee": "RACKS EXAMPLE", "paid_with": "paypal", "since": "2026-09-17" }
+    },
+    {
+      "id": "eu1", "name": "eu1", "hostnames": ["eu1.northwind.example"],
+      "provider": { "name": "Euro VPS" },
+      "cost": { "amount": 120, "currency": "EUR", "interval": "year" }
+    },
+    { "id": "ops-phone", "name": "On-call phone", "profile": "phone", "vendor": "Google", "model": "Pixel 9",
+      "os": { "name": "Android", "version": "17", "patch": "2026-10-05" },
+      "cost": { "amount": 25, "interval": "month", "payee": "CARRIER EXAMPLE" } },
+    { "id": "design-laptop", "name": "Design laptop", "profile": "desktop", "form": "laptop",
+      "cost": { "amount": 1440, "interval": "once", "amortize_months": 36, "since": "2026-01-10" } }
+  ]
+}

package/index.d.ts

@@ -0,0 +1,97 @@
+export const SPEC: string;
+export type Profile = 'server' | 'desktop' | 'phone' | 'tablet' | 'other';
+export type Status = 'active' | 'standby' | 'retired' | 'unknown';
+export type Interval = 'hour' | 'month' | 'year' | 'once';
+export const PROFILES: Profile[];
+export const STATUSES: Status[];
+export const INTERVALS: Interval[];
+
+export interface Cost {
+  amount?: number | null;
+  currency?: string;
+  interval?: Interval;
+  payee?: string;
+  paid_with?: string;
+  scope?: 'business' | 'personal';
+  category?: string;
+  next_due?: string;
+  since?: string;
+  until?: string;
+  amortize_months?: number;
+  group?: string;
+  note?: string;
+  [key: string]: unknown;
+}
+
+export interface Device {
+  id: string;
+  name: string;
+  profile: Profile;
+  status: Status;
+  role?: string;
+  hostnames: string[];
+  addresses: { ipv4: string[]; ipv6: string[]; private?: string[] };
+  provider?: { name?: string; web?: string; offer?: { descriptor?: string; id?: string }; account?: string };
+  location?: { country?: string; region?: string };
+  hardware?: Record<string, unknown>;
+  os?: { name?: string; version?: string; patch?: string };
+  cost?: Cost;
+  agents?: Array<{ name: string; version?: string; id?: string }>;
+  tags?: string[];
+  observed?: Record<string, unknown> & { at?: string };
+  vendor?: string;
+  model?: string;
+  form?: string;
+  [key: string]: unknown;
+}
+
+export interface Inventory {
+  operator?: { name?: string; web?: string; profile?: string };
+  updated?: string;
+  currency?: string;
+  devices: Device[];
+  [key: string]: unknown;
+}
+
+export type CostState = 'stated' | 'unstated' | 'grouped' | 'ended' | 'once' | 'retired';
+export interface Monthly { amount: number | null; currency: string | null; state: CostState }
+
+export interface FleetCost {
+  /** Per currency; nothing is converted. */
+  monthly: Record<string, number>;
+  /** Keys are "<name> <CUR>". */
+  by_provider: Record<string, number>;
+  by_profile: Record<string, number>;
+  by_scope: Record<string, number>;
+  devices: Array<{ id: string; name: string; profile: Profile; status: Status; provider: string | null; monthly: Monthly }>;
+  unstated: string[];
+  counted: number;
+}
+
+export interface CoinPayCost {
+  key: string;
+  payee: string;
+  amount: number;
+  currency: string;
+  cadence: 'monthly' | 'yearly';
+  monthlyEquivalent: number;
+  scope: string;
+  category: string;
+  paidWith: string | null;
+  nextExpected: string | null;
+  device: { id: string; name: string; profile: Profile; provider: string | null };
+  source: string;
+}
+
+export function parseInventory(input: string | object): Inventory;
+export function validateInventory(input: string | object): { valid: boolean; errors: string[]; warnings: string[] };
+export function monthlyCost(device: Device, opts?: { now?: Date }): Monthly;
+export function fleetCost(input: string | object, opts?: { now?: Date }): FleetCost;
+export function toCoinPayCosts(input: string | object, opts?: { now?: Date; source?: string }): CoinPayCost[];
+export function matchAgents<A>(
+  input: string | object,
+  agents: A[],
+  opts?: { hostname?: (a: A) => string | null | undefined; name?: (a: A) => string | null | undefined; ip?: (a: A) => string | null | undefined },
+): { devices: Array<{ device: Device; agents: A[] }>; unmatched: A[] };
+export function loadInventory(where: string, opts?: { headers?: Record<string, string> }): Promise<Inventory>;
+export function formatMonthly(monthly: Record<string, number> | undefined): string;

package/observe.d.ts

@@ -0,0 +1,5 @@
+import type { Device, Inventory } from './index.js';
+export const PORTS: number[];
+export const WELLKNOWN: string[];
+export function observe(device: Device, opts?: { timeoutMs?: number; ports?: number[]; now?: () => Date }): Promise<Record<string, unknown> & { at: string }>;
+export function observeInventory(inv: Inventory, opts?: { concurrency?: number; timeoutMs?: number; ports?: number[] }): Promise<Inventory>;

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@profullstack/fleet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read an OpenDevice inventory (servers, desktops, phones, tablets), add up what the fleet costs a month, observe each box's public metadata, and export the costs for CoinPay. Used by ThreatCrush and w3bs.org/fleet.",
+  "keywords": ["fleet", "opendevice", "openserver", "inventory", "hosting", "cost", "coinpay", "threatcrush", "w3bs"],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/fleet.git" },
+  "homepage": "https://logicsrc.com/opendevice",
+  "bugs": { "url": "https://github.com/profullstack/fleet/issues" },
+  "license": "MIT",
+  "author": "Profullstack, Inc.",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
+    "./observe": { "types": "./observe.d.ts", "import": "./src/observe.js" },
+    "./package.json": "./package.json"
+  },
+  "bin": { "fleet": "bin/fleet.js" },
+  "files": ["src", "bin", "index.d.ts", "observe.d.ts", "example.json", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/index.js

@@ -0,0 +1,268 @@
+// @profullstack/fleet: read an OpenDevice inventory (logicsrc.com/docs/opendevice),
+// add up what the fleet costs a month, and hand those costs to the tools that need
+// them (CoinPay finances, the ThreatCrush dashboard, w3bs.org/fleet).
+//
+// Pure functions only; nothing here touches the network except loadInventory.
+// Observation of public metadata lives in ./observe.js and is Node-only.
+
+export const SPEC = 'https://logicsrc.com/docs/opendevice';
+export const PROFILES = ['server', 'desktop', 'phone', 'tablet', 'other'];
+export const STATUSES = ['active', 'standby', 'retired', 'unknown'];
+export const INTERVALS = ['hour', 'month', 'year', 'once'];
+const HOURS_PER_MONTH = 730;
+
+const slug = (s) =>
+  String(s ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x) : []);
+
+function defaultProfile(d) {
+  if (PROFILES.includes(d.profile)) return d.profile;
+  const hasNet = list(d.hostnames).length || list(d.addresses?.ipv4).length || list(d.addresses?.ipv6).length;
+  return hasNet ? 'server' : 'other';
+}
+
+/**
+ * Normalize an inventory: every device gets an id, a profile and a status, and the
+ * inventory's default currency is applied to costs that state none. Unknown keys
+ * are kept, per the spec.
+ */
+export function parseInventory(input) {
+  const doc = typeof input === 'string' ? JSON.parse(input) : input;
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.devices)) {
+    throw new TypeError('OpenDevice inventory needs a "devices" array');
+  }
+  const currency = typeof doc.currency === 'string' ? doc.currency.toUpperCase() : undefined;
+  const seen = new Set();
+  const devices = doc.devices.map((raw, i) => {
+    const d = { ...raw };
+    d.name = typeof d.name === 'string' && d.name ? d.name : `device-${i + 1}`;
+    let id = typeof d.id === 'string' && d.id ? d.id : slug(d.name) || `device-${i + 1}`;
+    while (seen.has(id)) id = `${id}-${i + 1}`;
+    seen.add(id);
+    d.id = id;
+    d.profile = defaultProfile(d);
+    d.status = STATUSES.includes(d.status) ? d.status : 'active';
+    d.hostnames = list(d.hostnames);
+    d.addresses = { ...d.addresses, ipv4: list(d.addresses?.ipv4), ipv6: list(d.addresses?.ipv6) };
+    if (d.cost && typeof d.cost === 'object') {
+      d.cost = { ...d.cost };
+      d.cost.currency = (d.cost.currency || currency || 'USD').toUpperCase();
+      if (!d.cost.interval) d.cost.interval = 'month';
+      if (!d.cost.category) d.cost.category = d.profile === 'server' || d.profile === 'other' ? 'hosting' : 'devices';
+    }
+    return d;
+  });
+  return { ...doc, currency, devices };
+}
+
+const SECRET_KEYS = ['password', 'secret', 'token', 'private_key', 'api_key'];
+
+function hasKey(value, keys) {
+  if (!value || typeof value !== 'object') return null;
+  for (const [k, v] of Object.entries(value)) {
+    if (keys.includes(k.toLowerCase())) return k;
+    const inner = hasKey(v, keys);
+    if (inner) return inner;
+  }
+  return null;
+}
+
+/** Problems a reader should show; an inventory with only warnings is still usable. */
+export function validateInventory(input) {
+  const errors = [];
+  const warnings = [];
+  let inv;
+  try {
+    inv = parseInventory(input);
+  } catch (err) {
+    return { valid: false, errors: [err.message], warnings };
+  }
+  const raw = (typeof input === 'string' ? JSON.parse(input) : input).devices;
+  const groups = new Map();
+  inv.devices.forEach((d, i) => {
+    const at = `devices[${i}] (${d.id})`;
+    if (!raw[i]?.name) errors.push(`${at}: name is required`);
+    if (raw[i]?.profile && !PROFILES.includes(raw[i].profile)) warnings.push(`${at}: unknown profile "${raw[i].profile}"`);
+    if (raw[i]?.number || raw[i]?.phone_number) errors.push(`${at}: a phone number is never part of an OpenDevice record`);
+    const secret = hasKey(raw[i], SECRET_KEYS);
+    if (secret) errors.push(`${at}: credentials ("${secret}") never belong in an inventory`);
+    const c = d.cost;
+    if (c) {
+      if (!INTERVALS.includes(c.interval)) errors.push(`${at}: cost.interval must be one of ${INTERVALS.join(', ')}`);
+      if (c.amount != null && !(typeof c.amount === 'number' && Number.isFinite(c.amount) && c.amount >= 0)) {
+        errors.push(`${at}: cost.amount must be a non-negative number`);
+      }
+      if (c.amount == null && !c.group) warnings.push(`${at}: cost has no amount (counted as unstated)`);
+      if (c.group) {
+        const g = groups.get(c.group) ?? [];
+        g.push({ id: d.id, amount: c.amount });
+        groups.set(c.group, g);
+      }
+    } else if (d.status !== 'retired') {
+      warnings.push(`${at}: no cost stated`);
+    }
+  });
+  for (const [g, members] of groups) {
+    const payers = members.filter((m) => m.amount != null);
+    if (payers.length !== 1) warnings.push(`cost.group "${g}": exactly one device should state the amount (found ${payers.length})`);
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function inWindow(cost, now) {
+  const t = now.getTime();
+  if (cost.since && Date.parse(cost.since) > t) return false;
+  if (cost.until && Date.parse(cost.until) < t) return false;
+  return true;
+}
+
+const round = (n) => Math.round(n * 100) / 100;
+
+/**
+ * One device's monthly run rate, per the spec's Cost section.
+ * state: stated | unstated | grouped | ended | once | retired
+ */
+export function monthlyCost(device, { now = new Date() } = {}) {
+  const c = device.cost;
+  if (device.status === 'retired') return { amount: 0, currency: c?.currency ?? null, state: 'retired' };
+  if (!c) return { amount: null, currency: null, state: 'unstated' };
+  if (c.amount == null) return { amount: null, currency: c.currency ?? null, state: c.group ? 'grouped' : 'unstated' };
+  if (!inWindow(c, now)) return { amount: 0, currency: c.currency, state: 'ended' };
+  const a = c.amount;
+  switch (c.interval) {
+    case 'hour':
+      return { amount: round(a * HOURS_PER_MONTH), currency: c.currency, state: 'stated' };
+    case 'year':
+      return { amount: round(a / 12), currency: c.currency, state: 'stated' };
+    case 'once': {
+      const months = Number(c.amortize_months);
+      if (!(months > 0) || !c.since) return { amount: 0, currency: c.currency, state: 'once' };
+      const end = new Date(c.since);
+      end.setMonth(end.getMonth() + months);
+      if (now > end) return { amount: 0, currency: c.currency, state: 'ended' };
+      return { amount: round(a / months), currency: c.currency, state: 'stated' };
+    }
+    default:
+      return { amount: round(a), currency: c.currency, state: 'stated' };
+  }
+}
+
+const add = (map, key, n) => map.set(key, round((map.get(key) ?? 0) + n));
+const obj = (map) => Object.fromEntries([...map.entries()].sort());
+
+/**
+ * The fleet's monthly run rate. Totals are per currency; nothing is converted.
+ * A group's cost is counted once, from the device that states the amount.
+ */
+export function fleetCost(input, { now = new Date() } = {}) {
+  const inv = parseInventory(input);
+  const total = new Map();
+  const byProvider = new Map();
+  const byProfile = new Map();
+  const byScope = new Map();
+  const devices = inv.devices.map((d) => {
+    const m = monthlyCost(d, { now });
+    if (m.state === 'stated' && m.amount > 0) {
+      add(total, m.currency, m.amount);
+      add(byProvider, `${d.provider?.name ?? 'self'} ${m.currency}`, m.amount);
+      add(byProfile, `${d.profile} ${m.currency}`, m.amount);
+      add(byScope, `${d.cost.scope ?? 'business'} ${m.currency}`, m.amount);
+    }
+    return { id: d.id, name: d.name, profile: d.profile, status: d.status, provider: d.provider?.name ?? null, monthly: m };
+  });
+  return {
+    monthly: obj(total),
+    by_provider: obj(byProvider),
+    by_profile: obj(byProfile),
+    by_scope: obj(byScope),
+    devices,
+    unstated: devices.filter((d) => d.monthly.state === 'unstated').map((d) => d.id),
+    counted: devices.filter((d) => d.monthly.state === 'stated').length,
+  };
+}
+
+/** Next billing date: next_due if stated, else the next monthly anniversary of since. */
+function nextDue(cost, now) {
+  if (cost.next_due) return new Date(cost.next_due).toISOString();
+  if (!cost.since || cost.interval !== 'month') return null;
+  const d = new Date(cost.since);
+  while (d <= now) d.setMonth(d.getMonth() + 1);
+  return d.toISOString();
+}
+
+const CADENCE = { hour: 'monthly', month: 'monthly', year: 'yearly', once: 'monthly' };
+
+/**
+ * Costs in the shape CoinPay finances uses for a recurring charge, one per device
+ * with a stated run rate. `key` is stable, so re-importing updates instead of
+ * adding. CoinPay matches each one against bank charges by payee before counting it.
+ */
+export function toCoinPayCosts(input, { now = new Date(), source = 'opendevice' } = {}) {
+  const inv = parseInventory(input);
+  return inv.devices
+    .map((d) => ({ d, m: monthlyCost(d, { now }) }))
+    .filter(({ m }) => m.state === 'stated' && m.amount > 0)
+    .map(({ d, m }) => ({
+      key: `device:${d.id}`,
+      payee: d.cost.payee ?? d.provider?.name ?? d.name,
+      amount: d.cost.interval === 'hour' || d.cost.interval === 'once' ? m.amount : d.cost.amount,
+      currency: m.currency,
+      cadence: CADENCE[d.cost.interval],
+      monthlyEquivalent: m.amount,
+      scope: d.cost.scope ?? 'business',
+      category: d.cost.category,
+      paidWith: d.cost.paid_with ?? null,
+      nextExpected: nextDue(d.cost, now),
+      device: { id: d.id, name: d.name, profile: d.profile, provider: d.provider?.name ?? null },
+      source,
+    }));
+}
+
+const norm = (s) => String(s ?? '').trim().toLowerCase().replace(/\.$/, '');
+
+/**
+ * Join inventory devices with agent-reported machines (ThreatCrush servers,
+ * W3BS fleet machines). An agent row matches a device when its hostname, name or
+ * IP equals one of the device's id, name, hostnames or addresses. Returns every
+ * device, agent or not, plus the agent rows that match no device.
+ */
+export function matchAgents(input, agents, { hostname = (a) => a.hostname, name = (a) => a.name, ip = (a) => a.ip_address } = {}) {
+  const inv = parseInventory(input);
+  const used = new Set();
+  const devices = inv.devices.map((d) => {
+    const keys = new Set([d.id, d.name, ...d.hostnames, ...d.addresses.ipv4, ...d.addresses.ipv6].map(norm));
+    const hits = [];
+    agents.forEach((a, i) => {
+      if (used.has(i)) return;
+      if ([hostname(a), name(a), ip(a)].some((v) => v && keys.has(norm(v)))) {
+        used.add(i);
+        hits.push(a);
+      }
+    });
+    return { device: d, agents: hits };
+  });
+  return { devices, unmatched: agents.filter((_, i) => !used.has(i)) };
+}
+
+/** Read an inventory from an http(s) URL or a local path (Node). */
+export async function loadInventory(where, { headers } = {}) {
+  if (/^https?:\/\//.test(where)) {
+    const res = await fetch(where, { headers });
+    if (!res.ok) throw new Error(`${where}: HTTP ${res.status}`);
+    return parseInventory(await res.text());
+  }
+  const { readFile } = await import('node:fs/promises');
+  return parseInventory(await readFile(where, 'utf8'));
+}
+
+/** A per-currency total for display: "$1,234.00 + €53.00". */
+export function formatMonthly(monthly) {
+  const parts = Object.entries(monthly ?? {}).map(([cur, n]) =>
+    new Intl.NumberFormat('en-US', { style: 'currency', currency: cur }).format(n),
+  );
+  return parts.length ? parts.join(' + ') : '—';
+}

package/src/observe.js

@@ -0,0 +1,178 @@
+// Observe a device's public metadata, per the OpenDevice rule: only what anyone on
+// the internet could see without the device's credentials. DNS, reverse DNS, the
+// routing registry (Team Cymru's public DNS service), the TLS certificate and SSH
+// banner the device hands every connection, the HTTP Server header, which of a
+// fixed list of ports answer, and which well-known files are served.
+//
+// Only observe devices you run. Node-only.
+import { promises as dns } from 'node:dns';
+import net from 'node:net';
+import tls from 'node:tls';
+
+export const PORTS = [22, 25, 53, 80, 443, 465, 587, 993, 2202, 3000, 5432, 6379, 8080, 8443];
+export const WELLKNOWN = ['security.txt', 'openprofile.md', 'openserver.json', 'opendevice.json'];
+
+const settle = async (p, fallback = null) => {
+  try {
+    return await p;
+  } catch {
+    return fallback;
+  }
+};
+
+function timeout(ms) {
+  return new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), ms).unref?.());
+}
+
+const race = (p, ms) => Promise.race([p, timeout(ms)]);
+
+function isPrivate(ip) {
+  if (net.isIPv4(ip)) {
+    const [a, b] = ip.split('.').map(Number);
+    return a === 10 || a === 127 || (a === 172 && b >= 16 && b < 32) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b < 128) || (a === 169 && b === 254);
+  }
+  const l = ip.toLowerCase();
+  return l === '::1' || l.startsWith('fe80') || l.startsWith('fc') || l.startsWith('fd');
+}
+
+function portOpen(host, port, ms) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host, port });
+    const done = (ok) => {
+      s.destroy();
+      resolve(ok);
+    };
+    s.setTimeout(ms, () => done(false));
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+  });
+}
+
+function sshBanner(host, port, ms) {
+  return new Promise((resolve) => {
+    const s = net.connect({ host, port });
+    let buf = '';
+    const done = (v) => {
+      s.destroy();
+      resolve(v);
+    };
+    s.setTimeout(ms, () => done(null));
+    s.on('data', (chunk) => {
+      buf += chunk.toString('latin1');
+      const line = buf.split(/\r?\n/)[0];
+      if (buf.includes('\n')) done(line.startsWith('SSH-') ? { port, banner: line.trim() } : null);
+    });
+    s.once('error', () => done(null));
+  });
+}
+
+function tlsCert(host, servername, port, ms) {
+  return new Promise((resolve) => {
+    const s = tls.connect({ host, port, servername, rejectUnauthorized: false });
+    const done = (v) => {
+      s.destroy();
+      resolve(v);
+    };
+    s.setTimeout(ms, () => done(null));
+    s.once('secureConnect', () => {
+      const c = s.getPeerCertificate();
+      if (!c || !c.subject) return done(null);
+      done({
+        port,
+        subject: c.subject.CN ?? null,
+        names: (c.subjectaltname ?? '').split(/,\s*/).filter(Boolean).map((n) => n.replace(/^DNS:/, '')),
+        issuer: c.issuer?.O ?? c.issuer?.CN ?? null,
+        not_after: c.valid_to ? new Date(c.valid_to).toISOString() : null,
+        valid: s.authorized,
+      });
+    });
+    s.once('error', () => done(null));
+  });
+}
+
+async function asnOf(ip) {
+  if (!net.isIPv4(ip)) return null;
+  const rev = ip.split('.').reverse().join('.');
+  const origin = await settle(dns.resolveTxt(`${rev}.origin.asn.cymru.com`));
+  const first = origin?.[0]?.join('').split('|').map((s) => s.trim());
+  if (!first?.[0]) return null;
+  const number = Number(first[0].split(' ')[0]);
+  const detail = await settle(dns.resolveTxt(`AS${number}.asn.cymru.com`));
+  const org = detail?.[0]?.join('').split('|').map((s) => s.trim())[4] ?? null;
+  return { number, org, prefix: first[1] ?? null, country: first[2] ?? null };
+}
+
+/**
+ * Observe one device. Returns an `observed` block; it never throws for an
+ * unreachable device, it just reports less.
+ */
+export async function observe(device, { timeoutMs = 4000, ports = PORTS, now = () => new Date() } = {}) {
+  const hostnames = device.hostnames ?? [];
+  const out = { at: now().toISOString() };
+  const a = new Set(device.addresses?.ipv4 ?? []);
+  const aaaa = new Set(device.addresses?.ipv6 ?? []);
+  if (hostnames.length) {
+    out.dns = { a: [], aaaa: [] };
+    for (const h of hostnames) {
+      for (const ip of (await settle(race(dns.resolve4(h), timeoutMs), [])) ?? []) {
+        out.dns.a.includes(ip) || out.dns.a.push(ip);
+        a.add(ip);
+      }
+      for (const ip of (await settle(race(dns.resolve6(h), timeoutMs), [])) ?? []) {
+        out.dns.aaaa.includes(ip) || out.dns.aaaa.push(ip);
+        aaaa.add(ip);
+      }
+    }
+  }
+  const publicIps = [...a, ...aaaa].filter((ip) => !isPrivate(ip));
+  if (!publicIps.length) return out;
+  const target = [...a].find((ip) => !isPrivate(ip)) ?? publicIps[0];
+
+  out.ptr = [];
+  for (const ip of publicIps) for (const n of (await settle(race(dns.reverse(ip), timeoutMs), [])) ?? []) out.ptr.includes(n) || out.ptr.push(n);
+  out.asn = await settle(race(asnOf(target), timeoutMs));
+
+  const open = await Promise.all(ports.map((p) => portOpen(target, p, timeoutMs).then((ok) => (ok ? p : null))));
+  out.ports = open.filter((p) => p != null);
+
+  const sshPorts = out.ports.filter((p) => p === 22 || p === 2202);
+  for (const p of sshPorts) {
+    const b = await sshBanner(target, p, timeoutMs);
+    if (b) {
+      out.ssh = out.ssh ?? [];
+      out.ssh.push(b);
+    }
+  }
+  const name = hostnames[0] ?? target;
+  if (out.ports.includes(443)) out.tls = await tlsCert(target, net.isIP(name) ? undefined : name, 443, timeoutMs);
+  if (out.ports.includes(443) || out.ports.includes(80)) {
+    const base = `${out.ports.includes(443) ? 'https' : 'http'}://${name}`;
+    const res = await settle(fetch(base, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) }));
+    if (res) out.http = { status: res.status, server: res.headers.get('server') };
+    out.wellknown = [];
+    for (const file of WELLKNOWN) {
+      const r = await settle(fetch(`${base}/.well-known/${file}`, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMs) }));
+      if (r?.status === 200) out.wellknown.push(file);
+    }
+  }
+  return out;
+}
+
+/** Observe every server/other device in an inventory, a few at a time. */
+export async function observeInventory(inv, { concurrency = 3, ...opts } = {}) {
+  const targets = inv.devices.filter((d) => (d.profile === 'server' || d.profile === 'other') && d.status !== 'retired');
+  const results = new Map();
+  let i = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, targets.length) }, async () => {
+      while (i < targets.length) {
+        const d = targets[i++];
+        results.set(d.id, await observe(d, opts));
+      }
+    }),
+  );
+  return {
+    ...inv,
+    devices: inv.devices.map((d) => (results.has(d.id) ? { ...d, observed: { ...d.observed, ...results.get(d.id) } } : d)),
+  };
+}