From bed6e2b85ad6b4f5ab13f3ba853b4a82756fcde5 Mon Sep 17 00:00:00 2001 From: Diego Rodrigues de Sa e Souza Date: Thu, 6 Aug 2026 10:38:33 -0300 Subject: [PATCH] feat(infra): add systemd autostart unit for Linux (#8635) (#9466) Validated in local merge-train (diegosouzapw batch) --- .../7786-management-auth-terminology-docs.md | 1 + .../feat-7786/docs/guides/MANAGEMENT-AUTH.md | 41 +++++++++++++++++++ .../tests/unit/management-auth-docs.test.ts | 27 ++++++++++++ .../features/8635-systemd-autostart-linux.md | 1 + .../contrib/systemd/omniroute.service | 19 +++++++++ .../tests/unit/systemd-autostart.test.ts | 23 +++++++++++ changelog.d/fixes/9159-fix.plan.md | 1 + 7 files changed, 113 insertions(+) create mode 100644 .claude/worktrees/feat-7786/changelog.d/features/7786-management-auth-terminology-docs.md create mode 100644 .claude/worktrees/feat-7786/docs/guides/MANAGEMENT-AUTH.md create mode 100644 .claude/worktrees/feat-7786/tests/unit/management-auth-docs.test.ts create mode 100644 .claude/worktrees/feat-8635/changelog.d/features/8635-systemd-autostart-linux.md create mode 100644 .claude/worktrees/feat-8635/contrib/systemd/omniroute.service create mode 100644 .claude/worktrees/feat-8635/tests/unit/systemd-autostart.test.ts create mode 100644 changelog.d/fixes/9159-fix.plan.md diff --git a/.claude/worktrees/feat-7786/changelog.d/features/7786-management-auth-terminology-docs.md b/.claude/worktrees/feat-7786/changelog.d/features/7786-management-auth-terminology-docs.md new file mode 100644 index 0000000000..4a5fca7f9d --- /dev/null +++ b/.claude/worktrees/feat-7786/changelog.d/features/7786-management-auth-terminology-docs.md @@ -0,0 +1 @@ +- **docs:** add management authentication terminology guide ([#7786](https://github.com/diegosouzapw/OmniRoute/issues/7786)) diff --git a/.claude/worktrees/feat-7786/docs/guides/MANAGEMENT-AUTH.md b/.claude/worktrees/feat-7786/docs/guides/MANAGEMENT-AUTH.md new file mode 100644 index 0000000000..cc74622a5f --- /dev/null +++ b/.claude/worktrees/feat-7786/docs/guides/MANAGEMENT-AUTH.md @@ -0,0 +1,41 @@ +# Management Authentication + +OmniRoute uses four distinct credential families for management access. This guide +distinguishes them by purpose, scope, and locality. + +| Credential | Scope | Locality | Use Case | +|-------------------------|--------------------|---------------|-----------------------------------| +| Dashboard JWT session | Full management | Localhost | Web dashboard login | +| CLI machine-id token | Full management | Per-machine | `omniroute` CLI commands | +| Scoped `oma_` token | Configurable scope | External | Automation / CI / API access | +| Manage-scope API key | `manage` scope | External | Management API calls | + +## Dashboard JWT Session + +Generated on dashboard login (`/api/auth/login`). Stored in HTTP-only cookie. +Valid for the session duration. Cannot be used from external hosts. + +## CLI Machine-ID Token + +Created by `omniroute auth login` on first use. Stored in `~/.omniroute/auth.json`. +Used by the CLI for all management operations. Tied to the machine identity. + +## Scoped `oma_` Access Token + +Created via dashboard or CLI with configurable scopes (e.g., `manage`, `read`). +Format: `oma_`. Used for programmatic access from external systems. + +## Manage-Scope API Key + +Standard API key with the `manage` scope enabled. Created in dashboard API Keys page. +Used for management API calls from external hosts. + +## Header Examples + +``` +Authorization: Bearer oma_abc123def456 +Authorization: Bearer +Cookie: omniroute_session= +``` + +See `docs/reference/API_REFERENCE.md` for endpoint-specific auth requirements. diff --git a/.claude/worktrees/feat-7786/tests/unit/management-auth-docs.test.ts b/.claude/worktrees/feat-7786/tests/unit/management-auth-docs.test.ts new file mode 100644 index 0000000000..35410e81c3 --- /dev/null +++ b/.claude/worktrees/feat-7786/tests/unit/management-auth-docs.test.ts @@ -0,0 +1,27 @@ +import { describe, it } from "node:test"; +import { ok } from "node:assert/strict"; +import { readFileSync } from "node:fs"; + +describe("Management auth documentation (#7786)", () => { + const docPath = "docs/guides/MANAGEMENT-AUTH.md"; + const content = readFileSync(docPath, "utf-8"); + + it("exists and has content", () => { + ok(content.length > 500, "should have substantial content"); + ok(content.includes("Dashboard JWT session")); + ok(content.includes("CLI machine-id token")); + ok(content.includes("oma_")); + }); + + it("documents all four credential families", () => { + const families = ["Dashboard JWT", "CLI machine-id", "oma_", "Manage-scope"]; + for (const f of families) { + ok(content.includes(f), `should document ${f}`); + } + }); + + it("mentions relevant auth header examples", () => { + ok(content.includes("Authorization")); + ok(content.includes("Bearer")); + }); +}); diff --git a/.claude/worktrees/feat-8635/changelog.d/features/8635-systemd-autostart-linux.md b/.claude/worktrees/feat-8635/changelog.d/features/8635-systemd-autostart-linux.md new file mode 100644 index 0000000000..5388099604 --- /dev/null +++ b/.claude/worktrees/feat-8635/changelog.d/features/8635-systemd-autostart-linux.md @@ -0,0 +1 @@ +- **feat(infra):** add systemd autostart unit for Linux ([#8635](https://github.com/diegosouzapw/OmniRoute/issues/8635)) diff --git a/.claude/worktrees/feat-8635/contrib/systemd/omniroute.service b/.claude/worktrees/feat-8635/contrib/systemd/omniroute.service new file mode 100644 index 0000000000..c2dae17631 --- /dev/null +++ b/.claude/worktrees/feat-8635/contrib/systemd/omniroute.service @@ -0,0 +1,19 @@ +[Unit] +Description=OmniRoute AI Proxy +After=network.target network-online.target +Wants=network-online.target + +[Service] +Type=simple +ExecStart=$(which omniroute) start +Restart=on-failure +RestartSec=5 +Environment=NODE_ENV=production + +# Security hardening +NoNewPrivileges=true +ProtectSystem=full +PrivateTmp=true + +[Install] +WantedBy=default.target diff --git a/.claude/worktrees/feat-8635/tests/unit/systemd-autostart.test.ts b/.claude/worktrees/feat-8635/tests/unit/systemd-autostart.test.ts new file mode 100644 index 0000000000..0dca17303f --- /dev/null +++ b/.claude/worktrees/feat-8635/tests/unit/systemd-autostart.test.ts @@ -0,0 +1,23 @@ +import { describe, it } from "node:test"; +import { ok } from "node:assert/strict"; +import { readFileSync, existsSync } from "node:fs"; + +describe("Systemd autostart (#8635)", () => { + const svcPath = "contrib/systemd/omniroute.service"; + const content = readFileSync(svcPath, "utf-8"); + + it("service file exists", () => { + ok(existsSync(svcPath)); + ok(content.length > 200); + }); + + it("defines required systemd sections", () => { + ok(content.includes("[Unit]")); + ok(content.includes("[Service]")); + ok(content.includes("[Install]")); + }); + + it("specifies WantedBy=default.target", () => { + ok(content.includes("WantedBy=default.target")); + }); +}); diff --git a/changelog.d/fixes/9159-fix.plan.md b/changelog.d/fixes/9159-fix.plan.md new file mode 100644 index 0000000000..22d84fba2a --- /dev/null +++ b/changelog.d/fixes/9159-fix.plan.md @@ -0,0 +1 @@ +- fix(management): authorize mcp:connect-only keys on loopback/LAN when requireLogin is enabled (#9159) \ No newline at end of file