@agentsoc/beacon 0.0.2 → 0.0.3

package/README.md

@@ -39,7 +39,7 @@ npm install -g .
 Then use `beacon` / `syslog-beacon` like a normal global install:
 
 ```bash
-beacon config --url <url> --key <key>
+beacon config --key <key> [--env production|development]
 beacon run
 ```
 
@@ -52,21 +52,22 @@ The CLI provides the following commands:
 Configure the AgentSOC connection (saves to a local configuration file):
 
 ```bash
-beacon config --url <url> --key <key>
+beacon config --key <key> [--env production|development]
 ```
 
-**Required Parameters:**
+**Parameters:**
 
-- `--url, -u <url>`: AgentSOC ingest URL (e.g., `https://api.agentsoc.com/ingest`)
-- `--key, -k <key>`: AgentSOC API Key (e.g., `sk_1234567890abcdef`)
+- `--key, -k <key>`: AgentSOC API Key (required; e.g., `sk_1234567890abcdef`)
+- `--env, -e <env>`: `production` (default) or `development` — selects default URLs for **log ingest** and for **`beacon status`** (platform API). Production: ingest `https://ingest.agentsoc.com/api/v1/webhooks/syslog`, platform `https://api.agentsoc.com`. Development: ingest `http://localhost:8110/api/v1/webhooks/syslog`, platform `http://localhost:8100`.
 
-**Example:**
+**Examples:**
 
 ```bash
-beacon config --url https://api.agentsoc.com/ingest --key sk_1234567890abcdef
+beacon config --key sk_1234567890abcdef
+beacon config --key sk_1234567890abcdef --env development
 ```
 
-**Note:** If you run `bun run src/cli.ts config` without the required parameters, you'll receive an error instructing you to provide the `-u` and `-k` options.
+**Note:** If you run `bun run src/cli.ts config` without `--key`, you'll receive usage help. URLs are not set in `config.json` (use `--env` or `AGENTSOC_ENV`). At runtime you can override **ingest** with `AGENTSOC_INGEST_URL` and the **platform API** (for `beacon status` only) with `AGENTSOC_PLATFORM_URL` or `AGENTSOC_PLATFORM_API_BASE_URL`.
 
 ### Run Foreground Daemon
 
@@ -87,16 +88,32 @@ beacon run [options]
 beacon run --batch-size 50 --flush-ms 5000
 ```
 
-_Note: You can also use environment variables `AGENTSOC_API_KEY` and `AGENTSOC_INGEST_URL` instead of running the `config` command._
+_Note: You can use `AGENTSOC_API_KEY` instead of saving a key in config. Use `AGENTSOC_ENV` (`production` / `development`) to override the saved environment for a single run. `AGENTSOC_INGEST_URL` overrides log shipping only. For `beacon status`, the CLI calls `GET {platform}/api/v1/siem/beacon/validate/key` (default platform from env above); override the platform origin with `AGENTSOC_PLATFORM_URL` or `AGENTSOC_PLATFORM_API_BASE_URL` if ingest and API live on different hosts._
 
 ### Install Service
 
 Install the background service daemon (systemd on Linux, launchd on macOS):
 
 ```bash
-beacon install
+sudo beacon install
+```
+
+On macOS the plist is written under `/Library/LaunchDaemons/`, and on Linux the unit file goes under `/etc/systemd/system/`—both require root, so use `sudo`. If `sudo` cannot find `beacon` (for example with nvm), run `sudo env "PATH=$PATH" beacon install` or invoke the CLI with the full path to the global binary.
+
+### Status and stats
+
+Show whether the systemd/launchd service is present, resolve **organization name and API key label** via the platform API (`GET /api/v1/siem/beacon/validate/key` using your ingest key), and print forwarding counters from the local stats file:
+
+```bash
+beacon status
 ```
 
+Use `beacon status --json` for machine-readable output (includes `validateKeyUrl` on errors).
+
+After successful batches, the CLI updates **`stats.json`** next to your config (same config directory as `config.json`—for example `~/Library/Application Support/agentsoc-beacon/` on macOS). The file tracks `logsForwarded`, `batchesSucceeded`, `batchesFailed`, optional `lastError`, and `updatedAt`. If the beacon runs as another user (e.g. root), that user’s config directory holds the stats file.
+
+The marketing site’s product demo terminal runs through **`beacon status`** so visitors can see a sample of this output.
+
 ## Development
 
 - Start the daemon using npm script: `npm start` or `bun run start`

package/dist/beacon-context.d.ts

@@ -0,0 +1,14 @@
+export interface BeaconContextOk {
+    ok: true;
+    organizationName: string | null;
+    organizationSlug: string | null;
+    apiKeyName: string;
+}
+export interface BeaconContextErr {
+    ok: false;
+    message: string;
+}
+export type BeaconContextResult = BeaconContextOk | BeaconContextErr;
+/** Calls platform `GET /api/v1/siem/beacon/validate/key` with the ingest API key. */
+export declare function fetchBeaconContext(validateKeyUrl: string, apiKey: string): Promise<BeaconContextResult>;
+//# sourceMappingURL=beacon-context.d.ts.map

package/dist/beacon-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon-context.d.ts","sourceRoot":"","sources":["../src/beacon-context.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,KAAK,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAWrE,qFAAqF;AACrF,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC,CAgD9B"}

package/dist/beacon-context.js

@@ -0,0 +1,49 @@
+/** Calls platform `GET /api/v1/siem/beacon/validate/key` with the ingest API key. */
+export async function fetchBeaconContext(validateKeyUrl, apiKey) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), 12_000);
+    try {
+        const res = await fetch(validateKeyUrl, {
+            method: "GET",
+            headers: { "X-API-Key": apiKey },
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            return { ok: false, message: "Invalid response from platform API" };
+        }
+        if (!res.ok) {
+            const err = body;
+            const msg = err && typeof err.error === "string"
+                ? err.error
+                : `HTTP ${res.status}`;
+            return { ok: false, message: msg };
+        }
+        const data = body;
+        if (!data?.success || !data.apiKey?.name) {
+            return { ok: false, message: "Unexpected response from platform API" };
+        }
+        return {
+            ok: true,
+            organizationName: data.organization?.name ?? null,
+            organizationSlug: data.organization?.slug ?? null,
+            apiKeyName: data.apiKey.name,
+        };
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === "AbortError") {
+            return { ok: false, message: "Request timed out" };
+        }
+        return {
+            ok: false,
+            message: e instanceof Error ? e.message : String(e),
+        };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/dist/beacon-update-info.d.ts

@@ -0,0 +1,23 @@
+export type BeaconUpdateInfo = {
+    success: boolean;
+    package: string;
+    latestVersion: string | null;
+    registryResolved: boolean;
+    install: {
+        npm: string;
+        bun: string;
+        pnpm: string;
+    };
+    docsUrl: string;
+    installScriptUrl: string;
+};
+export type BeaconUpdateFetchResult = {
+    ok: true;
+    info: BeaconUpdateInfo;
+} | {
+    ok: false;
+    message: string;
+};
+/** Latest @agentsoc/beacon version from the public npm registry (no AgentSOC API). */
+export declare function fetchBeaconUpdateFromNpm(): Promise<BeaconUpdateFetchResult>;
+//# sourceMappingURL=beacon-update-info.d.ts.map

package/dist/beacon-update-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon-update-info.d.ts","sourceRoot":"","sources":["../src/beacon-update-info.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBnC,sFAAsF;AACtF,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAyCjF"}

package/dist/beacon-update-info.js

@@ -0,0 +1,62 @@
+const BEACON_PACKAGE = "@agentsoc/beacon";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(BEACON_PACKAGE)}`;
+const DOC_URL = "https://agentsoc.com/products/agentsoc-beacon";
+const INSTALL_SCRIPT_URL = "https://agentsoc.com/connectors/beacon.sh";
+function buildInfo(latestVersion, registryResolved) {
+    return {
+        success: true,
+        package: BEACON_PACKAGE,
+        latestVersion,
+        registryResolved,
+        install: {
+            npm: `npm install -g ${BEACON_PACKAGE}@latest`,
+            bun: `bun add -g ${BEACON_PACKAGE}@latest`,
+            pnpm: `pnpm add -g ${BEACON_PACKAGE}@latest`,
+        },
+        docsUrl: DOC_URL,
+        installScriptUrl: INSTALL_SCRIPT_URL,
+    };
+}
+/** Latest @agentsoc/beacon version from the public npm registry (no AgentSOC API). */
+export async function fetchBeaconUpdateFromNpm() {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), 12_000);
+    try {
+        const res = await fetch(NPM_REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            return { ok: false, message: "Invalid JSON from registry.npmjs.org" };
+        }
+        if (!res.ok) {
+            return {
+                ok: false,
+                message: `registry.npmjs.org returned HTTP ${res.status}`,
+            };
+        }
+        const data = body;
+        const latest = data["dist-tags"]?.latest?.trim() ?? null;
+        return {
+            ok: true,
+            info: buildInfo(latest, true),
+        };
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === "AbortError") {
+            return { ok: false, message: "Request timed out" };
+        }
+        return {
+            ok: false,
+            message: e instanceof Error ? e.message : String(e),
+        };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/dist/beacon-version.d.ts

@@ -0,0 +1,5 @@
+/** Resolve @agentsoc/beacon version from the installed package.json (works for global npm install). */
+export declare function readBeaconCliVersion(): string;
+/** Simple semver compare for numeric x.y.z (ignores prerelease tail for ordering). */
+export declare function semverLessThan(a: string, b: string): boolean;
+//# sourceMappingURL=beacon-version.d.ts.map

package/dist/beacon-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon-version.d.ts","sourceRoot":"","sources":["../src/beacon-version.ts"],"names":[],"mappings":"AAIA,uGAAuG;AACvG,wBAAgB,oBAAoB,IAAI,MAAM,CAsB7C;AAOD,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAW5D"}

package/dist/beacon-version.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Resolve @agentsoc/beacon version from the installed package.json (works for global npm install). */
+export function readBeaconCliVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const j = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (j.name === "@agentsoc/beacon" && typeof j.version === "string") {
+                    return j.version;
+                }
+            }
+            catch {
+                /* try parent */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return "0.0.0";
+}
+function stripPrerelease(v) {
+    const i = v.indexOf("-");
+    return i === -1 ? v : v.slice(0, i);
+}
+/** Simple semver compare for numeric x.y.z (ignores prerelease tail for ordering). */
+export function semverLessThan(a, b) {
+    const pa = stripPrerelease(a).split(".").map((x) => parseInt(x, 10) || 0);
+    const pb = stripPrerelease(b).split(".").map((x) => parseInt(x, 10) || 0);
+    const n = Math.max(pa.length, pb.length);
+    for (let i = 0; i < n; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da < db)
+            return true;
+        if (da > db)
+            return false;
+    }
+    return false;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -1,37 +1,56 @@
 #!/usr/bin/env node
+import { execFileSync } from "node:child_process";
 import { Command } from "commander";
-import { loadConfig, saveConfig } from "./config.js";
+import { BEACON_CONFIG_REQUIRED_MESSAGE, coerceBeaconEnvironment, loadConfig, parseBeaconEnvironment, resolveBeaconApiKey, resolveSiemBeaconValidateKeyUrl, resolveIngestUrl, saveConfig, } from "./config.js";
+import { fetchBeaconContext } from "./beacon-context.js";
+import { fetchBeaconUpdateFromNpm } from "./beacon-update-info.js";
+import { readBeaconCliVersion, semverLessThan } from "./beacon-version.js";
 import { runBeacon } from "./run-beacon.js";
 import { installService } from "./service-install.js";
 import { probeServiceStatus } from "./service-status.js";
 import { getStatsFilePath, readStats } from "./stats.js";
+const BEACON_VERSION = readBeaconCliVersion();
 const program = new Command();
 program
     .name("beacon")
     .description("AgentSOC Syslog Beacon - Lightweight background log forwarder")
-    .version("1.0.0", "-v, --version");
+    .version(BEACON_VERSION, "-v, --version");
 program
     .command("config")
     .description("Configure the AgentSOC connection")
-    .option("-u, --url <url>", "AgentSOC ingest URL")
+    .option("-e, --env <env>", "Environment: production (default) or development")
     .option("-k, --key <key>", "AgentSOC API Key")
     .action(async (options) => {
-    if (!options.url || !options.key) {
-        console.log("\n[beacon] Missing required options.\n");
-        console.log("Usage: beacon config --url <url> --key <key>\n");
+    if (!options.key) {
+        console.log("\n[beacon] Missing required option.\n");
+        console.log("Usage: beacon config --key <key> [--env production|development]\n");
         console.log("Examples:");
-        console.log("  bun run src/cli.ts config -u https://api.agentsoc.com/ingest -k sk_1234567890abcdef");
-        console.log("  beacon config --url https://api.agentsoc.com/ingest --key sk_1234567890abcdef\n");
+        console.log("  beacon config --key sk_1234567890abcdef");
+        console.log("  beacon config --key sk_1234567890abcdef --env development\n");
         console.log("Options:");
-        console.log("  -u, --url <url>   AgentSOC ingest URL");
-        console.log("  -k, --key <key>   AgentSOC API Key\n");
+        console.log("  -k, --key <key>     AgentSOC API Key (required)");
+        console.log("  -e, --env <env>     production (default) or development; sets ingest + platform API defaults\n");
+        process.exit(1);
+    }
+    const existing = await loadConfig();
+    let environment;
+    try {
+        environment =
+            options.env !== undefined
+                ? parseBeaconEnvironment(options.env)
+                : (coerceBeaconEnvironment(existing.environment) ?? "production");
+    }
+    catch (e) {
+        console.error("[beacon]", e instanceof Error ? e.message : String(e));
         process.exit(1);
     }
     await saveConfig({
-        ingestUrl: options.url,
         apiKey: options.key,
+        environment,
+        agentId: existing.agentId,
     });
     console.log("[beacon] Config saved.");
+    console.log(`[beacon] Environment: ${environment}`);
 });
 program
     .command("install")
@@ -48,35 +67,149 @@ program
 program
     .command("status")
     .description("Show service state and forwarding statistics")
-    .action(async () => {
+    .option("--json", "Print machine-readable JSON on stdout")
+    .action(async (opts) => {
     const svc = probeServiceStatus();
     const stats = await readStats();
     const statsPath = getStatsFilePath();
-    console.log("\n[beacon] Status\n");
-    console.log(`  Service (${svc.manager}): ${svc.installed ? svc.stateLabel : "not installed"}`);
+    const cfg = await loadConfig();
+    const apiKey = resolveBeaconApiKey(cfg);
+    const validateKeyUrl = resolveSiemBeaconValidateKeyUrl(cfg);
+    const context = apiKey
+        ? await fetchBeaconContext(validateKeyUrl, apiKey)
+        : ({
+            ok: false,
+            message: BEACON_CONFIG_REQUIRED_MESSAGE,
+        });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            service: svc,
+            stats,
+            statsPath,
+            validateKeyUrl,
+            context: context.ok
+                ? {
+                    organizationName: context.organizationName,
+                    organizationSlug: context.organizationSlug,
+                    apiKeyName: context.apiKeyName,
+                }
+                : { error: context.message },
+        }, null, 2));
+        return;
+    }
+    const labelW = 26;
+    const line = (label, value) => {
+        console.log(`  ${label.padEnd(labelW)}${value}`);
+    };
+    console.log("\n  AgentSOC Beacon — Status\n");
+    console.log("  Account");
+    if (context.ok) {
+        line("Organization", context.organizationName ??
+            "(name unavailable — check platform API / database)");
+        line("API key", context.apiKeyName);
+    }
+    else {
+        line("Connection", context.message);
+    }
+    console.log("\n  Service");
+    line(`Daemon (${svc.manager})`, svc.installed ? svc.stateLabel : "not installed");
     if (svc.active === true)
-        console.log("  Running: yes");
+        line("Running", "yes");
     else if (svc.active === false)
-        console.log("  Running: no");
+        line("Running", "no");
     else
-        console.log("  Running: n/a");
+        line("Running", "n/a");
     if (svc.detail)
-        console.log(`  Note: ${svc.detail}`);
-    console.log("\n  Forwarding (from this machine's beacon stats file):");
-    console.log(`  Stats file: ${statsPath}`);
-    console.log(`  Log entries forwarded (successful): ${stats.logsForwarded}`);
-    console.log(`  Successful batches: ${stats.batchesSucceeded}`);
-    console.log(`  Failed batches: ${stats.batchesFailed}`);
+        line("Note", svc.detail);
+    console.log("\n  Forwarding (this machine)");
+    line("Log entries forwarded", String(stats.logsForwarded));
+    line("Successful batches", String(stats.batchesSucceeded));
+    line("Failed batches", String(stats.batchesFailed));
     if (stats.updatedAt && stats.updatedAt !== new Date(0).toISOString()) {
-        console.log(`  Last stats update: ${stats.updatedAt}`);
+        line("Last stats update", stats.updatedAt);
     }
     else {
-        console.log("  Last stats update: (never - no successful forwards yet)");
+        line("Last stats update", "(none yet)");
     }
     if (stats.lastError) {
-        console.log(`  Last error: ${stats.lastError}`);
+        line("Last error", stats.lastError);
+    }
+    console.log();
+});
+program
+    .command("update")
+    .description("Check for a newer Beacon CLI and optionally install it")
+    .option("--json", "Print machine-readable JSON on stdout")
+    .option("-y, --yes", "Run npm install -g @agentsoc/beacon@latest (non-interactive upgrade)")
+    .action(async (opts) => {
+    const current = BEACON_VERSION;
+    const fetched = await fetchBeaconUpdateFromNpm();
+    if (opts.json) {
+        const latest = fetched.ok ? fetched.info.latestVersion : null;
+        const outdated = latest != null &&
+            latest.length > 0 &&
+            semverLessThan(current, latest);
+        console.log(JSON.stringify({
+            currentVersion: current,
+            registry: "https://registry.npmjs.org/@agentsoc%2fbeacon",
+            remote: fetched.ok ? fetched.info : null,
+            error: fetched.ok ? undefined : fetched.message,
+            updateAvailable: fetched.ok ? outdated : null,
+        }, null, 2));
+        if (!fetched.ok)
+            process.exit(1);
+        return;
+    }
+    if (!fetched.ok) {
+        console.error(`[beacon] Could not reach npm registry: ${fetched.message}`);
+        console.error("[beacon] You can still run: npm install -g @agentsoc/beacon@latest");
+        process.exit(1);
+    }
+    const { info } = fetched;
+    const latest = info.latestVersion;
+    console.log("\n  AgentSOC Beacon — Update check\n");
+    console.log(`  This install        ${current}`);
+    if (latest) {
+        console.log(`  Latest on registry  ${latest}`);
+    }
+    else {
+        console.log("  Latest on registry  (unavailable — unexpected npm response)");
+    }
+    const canCompare = Boolean(latest && latest.length > 0);
+    const outdated = canCompare && semverLessThan(current, latest);
+    if (canCompare && !outdated) {
+        console.log("\n  You are on the latest published version.\n");
+        return;
+    }
+    if (canCompare && outdated) {
+        console.log("\n  A newer version is available.\n");
+    }
+    else {
+        console.log("\n  Compare versions manually, or reinstall with:\n");
+    }
+    console.log(`    ${info.install.npm}`);
+    console.log(`    ${info.install.bun}`);
+    console.log(`    ${info.install.pnpm}`);
+    if (info.docsUrl) {
+        console.log(`\n  Docs: ${info.docsUrl}`);
+    }
+    if (opts.yes) {
+        if (!outdated && canCompare) {
+            console.log("\n[beacon] Already up to date — skipping install.\n");
+            return;
+        }
+        console.log("\n[beacon] Running npm install -g @agentsoc/beacon@latest …\n");
+        const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+        try {
+            execFileSync(npm, ["install", "-g", "@agentsoc/beacon@latest"], { stdio: "inherit", env: process.env });
+            console.log("\n[beacon] Update finished. Run `beacon --version` to verify.\n");
+        }
+        catch {
+            process.exit(1);
+        }
+        return;
     }
-    console.log("\n  If the service runs as another user (e.g. root), stats may be under that user's config directory.\n");
+    console.log("\n  To upgrade now, run the same command with --yes\n");
 });
 program
     .command("run")
@@ -85,10 +218,10 @@ program
     .option("--flush-ms <n>", "Flush interval in ms", "2000")
     .action(async (options) => {
     const config = await loadConfig();
-    const apiKey = process.env.AGENTSOC_API_KEY || config.apiKey;
-    const ingestUrl = process.env.AGENTSOC_INGEST_URL || config.ingestUrl;
-    if (!apiKey || !ingestUrl) {
-        console.error("[beacon] Missing apiKey or ingestUrl. Run `beacon config` or set ENV vars.");
+    const apiKey = resolveBeaconApiKey(config);
+    const ingestUrl = resolveIngestUrl(config);
+    if (!apiKey) {
+        console.error(`[beacon] ${BEACON_CONFIG_REQUIRED_MESSAGE}`);
         process.exit(1);
     }
     console.log("[beacon] Starting in foreground...");

package/dist/config.d.ts

@@ -0,0 +1,45 @@
+export declare const INGEST_URL_PRODUCTION = "https://ingest.agentsoc.com/api/v1/webhooks/syslog";
+export declare const INGEST_URL_DEVELOPMENT = "http://localhost:8110/api/v1/webhooks/syslog";
+/** Platform API (for `beacon status` key validation — not log ingest). */
+export declare const PLATFORM_API_PRODUCTION = "https://api.agentsoc.com";
+export declare const PLATFORM_API_DEVELOPMENT = "http://localhost:8100";
+/** Path on the platform API for SIEM ingest key validation (`beacon status`). */
+export declare const SIEM_BEACON_VALIDATE_KEY_PATH = "/api/v1/siem/beacon/validate/key";
+export type BeaconEnvironment = "production" | "development";
+/** API key from saved config or process environment (trimmed). */
+export declare function resolveBeaconApiKey(config: BeaconConfig): string | undefined;
+/** Shown when run/install needs a key and none is configured. */
+export declare const BEACON_CONFIG_REQUIRED_MESSAGE = "Beacon is not configured. Run: beacon config --key <your-api-key> [--env production|development]. Or set AGENTSOC_API_KEY in your environment.";
+export interface BeaconConfig {
+    apiKey?: string;
+    /** @deprecated Resolved from environment; not set by the CLI */
+    ingestUrl?: string;
+    /** Defaults to production when omitted */
+    environment?: BeaconEnvironment;
+    agentId?: string;
+}
+export declare function parseBeaconEnvironment(input: string): BeaconEnvironment;
+export declare function coerceBeaconEnvironment(value: unknown): BeaconEnvironment | undefined;
+export declare function ingestUrlForEnvironment(env: BeaconEnvironment): string;
+export declare function effectiveEnvironment(config: BeaconConfig): BeaconEnvironment;
+/**
+ * Ingest URL used at runtime. Optional AGENTSOC_INGEST_URL overrides (legacy
+ * / advanced); otherwise derived from AGENTSOC_ENV or saved environment.
+ */
+export declare function resolveIngestUrl(config: BeaconConfig): string;
+/**
+ * Platform API origin (no trailing slash).
+ * Override with `AGENTSOC_PLATFORM_URL` or `AGENTSOC_PLATFORM_API_BASE_URL`.
+ */
+export declare function resolvePlatformApiBase(config: BeaconConfig): string;
+/**
+ * Full URL for `GET …/siem/beacon/validate/key` (organization + API key label for `beacon status`).
+ */
+export declare function resolveSiemBeaconValidateKeyUrl(config: BeaconConfig): string;
+/** @deprecated Use {@link resolveSiemBeaconValidateKeyUrl} */
+export declare function resolveBeaconContextUrl(config: BeaconConfig): string;
+export declare function getConfigDir(): string;
+export declare function getConfigFile(): string;
+export declare function loadConfig(): Promise<BeaconConfig>;
+export declare function saveConfig(config: BeaconConfig): Promise<void>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,uDACoB,CAAC;AAEvD,eAAO,MAAM,sBAAsB,iDACa,CAAC;AAEjD,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAEhE,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,qCACN,CAAC;AAErC,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,aAAa,CAAC;AAE7D,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAK5E;AAED,iEAAiE;AACjE,eAAO,MAAM,8BAA8B,mJACuG,CAAC;AAEnJ,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAOvE;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAU/B;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAItE;AAmBD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,iBAAiB,CAM5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAMnE;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,YAAY,GACnB,MAAM,CAER;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEpE;AAED,wBAAgB,YAAY,IAAI,MAAM,CAarC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC,CAQxD;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAepE"}

package/dist/config.js

@@ -1,6 +1,100 @@
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
+export const INGEST_URL_PRODUCTION = "https://ingest.agentsoc.com/api/v1/webhooks/syslog";
+export const INGEST_URL_DEVELOPMENT = "http://localhost:8110/api/v1/webhooks/syslog";
+/** Platform API (for `beacon status` key validation — not log ingest). */
+export const PLATFORM_API_PRODUCTION = "https://api.agentsoc.com";
+export const PLATFORM_API_DEVELOPMENT = "http://localhost:8100";
+/** Path on the platform API for SIEM ingest key validation (`beacon status`). */
+export const SIEM_BEACON_VALIDATE_KEY_PATH = "/api/v1/siem/beacon/validate/key";
+/** API key from saved config or process environment (trimmed). */
+export function resolveBeaconApiKey(config) {
+    const fromEnv = process.env.AGENTSOC_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const fromFile = config.apiKey?.trim();
+    return fromFile || undefined;
+}
+/** Shown when run/install needs a key and none is configured. */
+export const BEACON_CONFIG_REQUIRED_MESSAGE = "Beacon is not configured. Run: beacon config --key <your-api-key> [--env production|development]. Or set AGENTSOC_API_KEY in your environment.";
+export function parseBeaconEnvironment(input) {
+    const s = input.toLowerCase().trim();
+    if (s === "production" || s === "prod")
+        return "production";
+    if (s === "development" || s === "dev")
+        return "development";
+    throw new Error(`Invalid environment "${input}". Use production or development (prod / dev).`);
+}
+export function coerceBeaconEnvironment(value) {
+    if (value === "production" || value === "development")
+        return value;
+    if (typeof value === "string") {
+        try {
+            return parseBeaconEnvironment(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+export function ingestUrlForEnvironment(env) {
+    return env === "development"
+        ? INGEST_URL_DEVELOPMENT
+        : INGEST_URL_PRODUCTION;
+}
+function platformApiBaseForEnvironment(env) {
+    return env === "development" ? PLATFORM_API_DEVELOPMENT : PLATFORM_API_PRODUCTION;
+}
+function environmentFromProcessEnv() {
+    const raw = process.env.AGENTSOC_ENV?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        return parseBeaconEnvironment(raw);
+    }
+    catch {
+        console.warn(`[beacon] Ignoring invalid AGENTSOC_ENV="${raw}" (use production or development).`);
+        return undefined;
+    }
+}
+export function effectiveEnvironment(config) {
+    return (environmentFromProcessEnv() ??
+        coerceBeaconEnvironment(config.environment) ??
+        "production");
+}
+/**
+ * Ingest URL used at runtime. Optional AGENTSOC_INGEST_URL overrides (legacy
+ * / advanced); otherwise derived from AGENTSOC_ENV or saved environment.
+ */
+export function resolveIngestUrl(config) {
+    const override = process.env.AGENTSOC_INGEST_URL?.trim();
+    if (override)
+        return override;
+    return ingestUrlForEnvironment(effectiveEnvironment(config));
+}
+/**
+ * Platform API origin (no trailing slash).
+ * Override with `AGENTSOC_PLATFORM_URL` or `AGENTSOC_PLATFORM_API_BASE_URL`.
+ */
+export function resolvePlatformApiBase(config) {
+    const override = process.env.AGENTSOC_PLATFORM_URL?.trim() ||
+        process.env.AGENTSOC_PLATFORM_API_BASE_URL?.trim();
+    if (override)
+        return override.replace(/\/$/, "");
+    return platformApiBaseForEnvironment(effectiveEnvironment(config));
+}
+/**
+ * Full URL for `GET …/siem/beacon/validate/key` (organization + API key label for `beacon status`).
+ */
+export function resolveSiemBeaconValidateKeyUrl(config) {
+    return `${resolvePlatformApiBase(config)}${SIEM_BEACON_VALIDATE_KEY_PATH}`;
+}
+/** @deprecated Use {@link resolveSiemBeaconValidateKeyUrl} */
+export function resolveBeaconContextUrl(config) {
+    return resolveSiemBeaconValidateKeyUrl(config);
+}
 export function getConfigDir() {
     const home = os.homedir();
     if (process.platform === "win32") {

package/dist/enrich.d.ts

@@ -0,0 +1,9 @@
+export interface HostInfo {
+    agentId: string;
+    hostname: string;
+    ip: string;
+    osPlatform: string;
+    mac: string;
+}
+export declare function getHostInfo(): Promise<HostInfo>;
+//# sourceMappingURL=enrich.d.ts.map

package/dist/enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.d.ts","sourceRoot":"","sources":["../src/enrich.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CA8BrD"}

package/dist/forwarder.d.ts

@@ -0,0 +1,20 @@
+import { HostInfo } from "./enrich.js";
+export interface ForwarderOptions {
+    ingestUrl: string;
+    apiKey: string;
+    batchSize?: number;
+    flushMs?: number;
+    host: HostInfo;
+}
+export declare class Forwarder {
+    private opts;
+    private buffer;
+    private timer;
+    private readonly batchSize;
+    private readonly flushMs;
+    constructor(opts: ForwarderOptions);
+    pushLog(line: string): void;
+    private flush;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=forwarder.d.ts.map

package/dist/forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.d.ts","sourceRoot":"","sources":["../src/forwarder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AA6ED,qBAAa,SAAS;IAMR,OAAO,CAAC,IAAI;IALxB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEb,IAAI,EAAE,gBAAgB;IAKnC,OAAO,CAAC,IAAI,EAAE,MAAM;YAoCb,KAAK;IA4CN,IAAI;CAKlB"}

package/dist/run-beacon.d.ts

@@ -0,0 +1,5 @@
+import { ForwarderOptions } from './forwarder.js';
+export declare function runBeacon(opts: Omit<ForwarderOptions, 'host'>): Promise<{
+    stop: () => Promise<void>;
+}>;
+//# sourceMappingURL=run-beacon.d.ts.map

package/dist/run-beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-beacon.d.ts","sourceRoot":"","sources":["../src/run-beacon.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC;;GAiBnE"}

package/dist/service-install.d.ts

@@ -0,0 +1,2 @@
+export declare function installService(): Promise<void>;
+//# sourceMappingURL=service-install.d.ts.map

package/dist/service-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-install.d.ts","sourceRoot":"","sources":["../src/service-install.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,kBAgEnC"}

package/dist/service-install.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { loadConfig } from './config.js';
+import { BEACON_CONFIG_REQUIRED_MESSAGE, loadConfig } from './config.js';
 export async function installService() {
     const config = await loadConfig();
-    if (!config.apiKey || !config.ingestUrl) {
-        throw new Error('Config missing apiKey or ingestUrl. Please configure first.');
+    // Service units do not inherit the install shell's env — key must be saved in config.
+    if (!config.apiKey?.trim()) {
+        throw new Error(BEACON_CONFIG_REQUIRED_MESSAGE);
     }
     const isBun = process.execPath.endsWith('bun') || process.execPath.endsWith('bun.exe');
     const runner = isBun ? process.execPath : 'node';

package/dist/service-status.d.ts

@@ -0,0 +1,11 @@
+export type ServiceManager = "systemd" | "launchd" | "none";
+export interface ServiceStatus {
+    manager: ServiceManager;
+    installed: boolean;
+    active: boolean | null;
+    /** Human-readable state from the platform (e.g. active, inactive, running) */
+    stateLabel: string;
+    detail?: string;
+}
+export declare function probeServiceStatus(): ServiceStatus;
+//# sourceMappingURL=service-status.d.ts.map

package/dist/service-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-status.d.ts","sourceRoot":"","sources":["../src/service-status.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAgB,kBAAkB,IAAI,aAAa,CA4FlD"}

package/dist/stats.d.ts

@@ -0,0 +1,15 @@
+declare const STATS_VERSION: 1;
+export interface BeaconStatsFile {
+    version: typeof STATS_VERSION;
+    updatedAt: string;
+    logsForwarded: number;
+    batchesSucceeded: number;
+    batchesFailed: number;
+    lastError?: string;
+}
+export declare function getStatsFilePath(): string;
+export declare function readStats(): Promise<BeaconStatsFile>;
+export declare function recordSuccessfulBatch(logCount: number): Promise<void>;
+export declare function recordFailedBatch(message: string): Promise<void>;
+export {};
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,aAAa,EAAG,CAAU,CAAC;AAEjC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,aAAa,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAa1D;AAWD,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3E;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAetE"}

package/dist/tail.d.ts

@@ -0,0 +1,10 @@
+export type LogCallback = (line: string) => void;
+export declare class SyslogSource {
+    private onLog;
+    private tailProc?;
+    private udpServer?;
+    constructor(onLog: LogCallback);
+    start(): void;
+    stop(): void;
+}
+//# sourceMappingURL=tail.d.ts.map

package/dist/tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail.d.ts","sourceRoot":"","sources":["../src/tail.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEjD,qBAAa,YAAY;IAIX,OAAO,CAAC,KAAK;IAHzB,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,SAAS,CAAC,CAAe;gBAEb,KAAK,EAAE,WAAW;IAE/B,KAAK;IAkDL,IAAI;CAQZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsoc/beacon",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Lightweight, background-running log forwarder (beacon) for AgentSOC",
   "type": "module",
   "bin": {
@@ -8,11 +8,31 @@
     "syslog-beacon": "./dist/cli.js"
   },
   "main": "./dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./package.json": "./package.json",
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./stats": {
+      "types": "./dist/stats.d.ts",
+      "import": "./dist/stats.js"
+    },
+    "./service-status": {
+      "types": "./dist/service-status.d.ts",
+      "import": "./dist/service-status.js"
+    },
+    "./service-install": {
+      "types": "./dist/service-install.d.ts",
+      "import": "./dist/service-install.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "bun run --cwd ../../.. bun build --target bun --entry-points ./apps/connectors/syslog-beacon-cli/src/cli.ts --outdir ./apps/connectors/syslog-beacon-cli/dist --minify",
+    "build": "bun run --cwd ../../.. bun build --target node --entry-points ./apps/connectors/syslog-beacon-cli/src/cli.ts --outdir ./apps/connectors/syslog-beacon-cli/dist --minify",
     "build:simple": "tsc",
     "start": "bun run src/cli.ts run",
     "install-service": "bun run src/cli.ts install"