@hivemagnus/magnus-server 0.0.0-stage → 1.0.2

package/dist/utils/heartbeat-peer.js

@@ -0,0 +1,19 @@
+import { getConnInfo } from '@hono/node-server/conninfo';
+import { normalizeIpAddress } from './ip.js';
+/**
+ * Read the peer address from the Node adapter before considering proxy
+ * metadata. Port 4000 accepts agents directly, so a caller-controlled
+ * x-forwarded-for header must not override the authenticated socket peer.
+ * The header remains a fallback for adapter-free tests and explicitly
+ * forwarded deployments where no socket binding is available.
+ */
+export function heartbeatPeerAddress(c) {
+    let socketAddress = '';
+    try {
+        socketAddress = getConnInfo(c).remote.address ?? '';
+    }
+    catch { /* adapter-free request */ }
+    const forwardedAddress = c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ?? '';
+    return normalizeIpAddress(socketAddress || forwardedAddress);
+}
+//# sourceMappingURL=heartbeat-peer.js.map

package/dist/utils/idempotency.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { getRedis } from '../queue/redis.js';
+import { routePath } from 'hono/route';
+import { HttpError } from '../middleware/error-handler.js';
+const IDEMPOTENCY_TTL_SECONDS = 86_400;
+const RELEASE_IF_OWNED = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end";
+/** Keys are namespaced by operation scope and actor, so the same client key
+ * used on another route or by another user is not a duplicate. */
+function idempotencyRedisKey(scope, actorId, key) {
+    return `idem:${createHash('sha256').update(JSON.stringify([scope, actorId, key])).digest('hex')}`;
+}
+/**
+ * Atomically claim an idempotency key (Redis SET NX, 24-hour TTL). Throws 409
+ * DUPLICATE_REQUEST if the key is already held for this scope and actor.
+ * Callers claim after validation, dry-run, and preflight checks, immediately
+ * before the first durable effect.
+ */
+export async function claimIdempotency(scope, actorId, key) {
+    const redis = getRedis();
+    const redisKey = idempotencyRedisKey(scope, actorId, key);
+    const token = randomUUID();
+    const result = await redis.set(redisKey, token, 'EX', IDEMPOTENCY_TTL_SECONDS, 'NX');
+    if (result === null) {
+        throw new HttpError(409, 'DUPLICATE_REQUEST', `Idempotency key already used: ${key}`);
+    }
+    return {
+        async release() {
+            await redis.eval(RELEASE_IF_OWNED, 1, redisKey, token).catch(() => undefined);
+        },
+    };
+}
+/**
+ * Enforce idempotency when the `x-idempotency-key` header is present.
+ * For endpoints where the key is optional — callers that supply it get
+ * duplicate-request protection; callers that omit it proceed normally.
+ * The key is scoped to the matched route and the authenticated actor.
+ */
+export async function enforceIdempotencyFromHeader(c) {
+    const key = c.req.header('x-idempotency-key');
+    if (!key)
+        return undefined;
+    const actorId = c.var.user?.userId ?? 'anonymous';
+    return claimIdempotency(`${c.req.method} ${routePath(c) || c.req.path}`, actorId, key);
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/utils/ip.js

@@ -0,0 +1,25 @@
+import { isIP } from 'node:net';
+/** Strip IPv6-mapped IPv4 prefix and normalize empty values. */
+export function normalizeIpAddress(rawIp) {
+    if (!rawIp)
+        return '';
+    const trimmed = rawIp.trim();
+    return trimmed.startsWith('::ffff:') ? trimmed.slice(7) : trimmed;
+}
+/** Check if an IP is loopback, unspecified, or otherwise unroutable. */
+export function isLoopbackOrUnroutableIp(ipAddress) {
+    const ip = normalizeIpAddress(ipAddress);
+    if (!ip)
+        return true;
+    if (ip === '::1' || ip === '::' || ip === '0.0.0.0')
+        return true;
+    if (ip.startsWith('127.'))
+        return true;
+    return false;
+}
+/** Check if an IP is a valid, routable node address. */
+export function isUsableNodeIp(ipAddress) {
+    const ip = normalizeIpAddress(ipAddress);
+    return isIP(ip) !== 0 && !isLoopbackOrUnroutableIp(ip);
+}
+//# sourceMappingURL=ip.js.map

package/dist/utils/json-fields.js

@@ -0,0 +1,94 @@
+/**
+ * Typed parse/serialize helpers for JSON-encoded Prisma string fields.
+ *
+ * Magnus deliberately stores these wire-compatible arrays and objects as
+ * serialized JSON strings. These helpers centralize the serde logic to avoid scattered
+ * `JSON.stringify` / `JSON.parse` casts throughout route files.
+ */
+/**
+ * Parse a JSON-encoded string array from a Prisma field.
+ * Falls back to an empty array if the value is null, undefined, or invalid JSON.
+ */
+export function parseStringArray(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Serialize a string array to a JSON string for storage in a Prisma field.
+ * Accepts undefined for convenience (returns '[]').
+ */
+export function serializeStringArray(value) {
+    return JSON.stringify(value ?? []);
+}
+/**
+ * Parse a JSON-encoded generic array from a Prisma field.
+ * Falls back to the provided default if null, undefined, or invalid JSON.
+ */
+export function parseJsonArray(value, fallback = []) {
+    if (!value)
+        return fallback;
+    if (Array.isArray(value))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Parse a JSON-encoded `Record<string, string>` from a Prisma field.
+ * Falls back to an empty object if null, undefined, or invalid JSON.
+ */
+export function parseStringRecord(value) {
+    if (!value)
+        return {};
+    if (typeof value === 'object' && !Array.isArray(value))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Parse a JSON-encoded `Record<string, unknown>` from a Prisma field.
+ * Falls back to an empty object if null, undefined, or invalid JSON.
+ */
+export function parseJsonRecord(value) {
+    if (!value)
+        return {};
+    if (typeof value === 'object' && !Array.isArray(value))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Serialize a record to a JSON string for storage in a Prisma field.
+ * Accepts undefined for convenience (returns '{}').
+ */
+export function serializeRecord(value) {
+    return JSON.stringify(value ?? {});
+}
+//# sourceMappingURL=json-fields.js.map

package/dist/utils/local-tls.js

@@ -0,0 +1,39 @@
+/** Verified TLS options for loopback connections to local Magnus services. */
+import { existsSync, readFileSync } from 'node:fs';
+import { isIP } from 'node:net';
+export function verifiedLocalTlsOptions(caPath, servername) {
+    const options = {
+        rejectUnauthorized: true,
+    };
+    const normalizedCaPath = caPath?.trim();
+    if (normalizedCaPath) {
+        if (!existsSync(normalizedCaPath)) {
+            throw new Error(`Configured TLS CA does not exist: ${normalizedCaPath}`);
+        }
+        options.ca = readFileSync(normalizedCaPath);
+    }
+    const normalizedServername = servername?.trim();
+    if (normalizedServername && isIP(normalizedServername) === 0) {
+        options.servername = normalizedServername;
+    }
+    return options;
+}
+function controlApiHostname() {
+    try {
+        return new URL(process.env['CONTROL_API_URL'] ?? '').hostname || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function controlHostAgentTlsServername() {
+    const configured = (process.env['CONTROL_HOST_AGENT_TLS_SERVERNAME'] ?? controlApiHostname())?.trim().toLowerCase();
+    return configured && isIP(configured) === 0 ? configured : undefined;
+}
+export function controlApiLoopbackTlsOptions() {
+    return verifiedLocalTlsOptions(process.env['CONTROL_API_CA_PATH'], process.env['CONTROL_API_TLS_SERVERNAME'] ?? controlApiHostname());
+}
+export function controlHostAgentTlsOptions() {
+    return verifiedLocalTlsOptions(process.env['CONTROL_HOST_AGENT_CA_PATH'] ?? process.env['CONTROL_API_CA_PATH'], controlHostAgentTlsServername());
+}
+//# sourceMappingURL=local-tls.js.map

package/dist/utils/magnus-home.js

@@ -0,0 +1,15 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * Base directory for server-owned local data (backups, audit logs, state).
+ * Defaults to `~/.magnus`; override with `MAGNUS_HOME`.
+ */
+export function magnusHome(env = process.env) {
+    const configured = env['MAGNUS_HOME']?.trim();
+    return configured ? resolve(configured) : join(homedir(), '.magnus');
+}
+/** Resolve a path below {@link magnusHome}. */
+export function magnusHomePath(...segments) {
+    return join(magnusHome(), ...segments);
+}
+//# sourceMappingURL=magnus-home.js.map

package/dist/utils/node-url.js

@@ -0,0 +1,59 @@
+import { normalizeIpAddress } from './ip.js';
+import { isIP } from 'node:net';
+/**
+ * Build the base URL for a node-manager agent.
+ *
+ * When TLS_CERT_PATH and TLS_KEY_PATH are configured, agents are assumed to
+ * run behind HTTPS. Otherwise falls back to plain HTTP.
+ */
+export function getNodeBaseUrl(ipAddress, port) {
+    const useTls = process.env['TLS_CERT_PATH'] && process.env['TLS_KEY_PATH'];
+    const protocol = useTls ? 'https' : 'http';
+    return `${protocol}://${ipAddress}:${port}`;
+}
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Derive the certificate hostname an agent should advertise from its reported
+ * OS hostname and the operator-configured TLS suffix. The heartbeat handler
+ * still resolves this name and requires the resolved address to appear in the
+ * authenticated agent's network/caller evidence before persisting it.
+ */
+export function deriveAgentCertificateHostname(reportedFqdn, configuredSuffix) {
+    const reported = reportedFqdn?.trim().toLowerCase().replace(/\.$/, '') ?? '';
+    const suffix = configuredSuffix
+        ?.trim()
+        .toLowerCase()
+        .replace(/^\.+|\.+$/g, '') ?? '';
+    if (!reported || !suffix || !suffix.includes('.'))
+        return null;
+    const suffixLabels = suffix.split('.');
+    if (!suffixLabels.every((label) => DNS_LABEL.test(label)))
+        return null;
+    if (reported.endsWith(`.${suffix}`))
+        return reported;
+    const shortName = reported.split('.')[0] ?? '';
+    if (!DNS_LABEL.test(shortName))
+        return null;
+    const hostname = `${shortName}.${suffix}`;
+    return hostname.length <= 253 ? hostname : null;
+}
+/** Accept the derived certificate name only when DNS points back to this heartbeat. */
+export function verifyAgentCertificateHostname(certificateHostname, resolvedAddress, heartbeatAddresses) {
+    if (!certificateHostname || !resolvedAddress)
+        return null;
+    const resolved = normalizeIpAddress(resolvedAddress);
+    const observed = new Set(heartbeatAddresses.map((value) => normalizeIpAddress(value)));
+    return resolved && observed.has(resolved) ? certificateHostname : null;
+}
+/** Keep inventory hostname aligned with the endpoint identity actually verified by TLS. */
+export function selectAgentEndpointHostname(verifiedCertificateHostname, reportedFqdn, existingHostname, existingEndpoint) {
+    const verified = verifiedCertificateHostname?.trim().toLowerCase();
+    if (verified)
+        return verified;
+    const existing = existingHostname?.trim().toLowerCase();
+    const endpoint = existingEndpoint?.trim().toLowerCase();
+    if (existing && endpoint && existing === endpoint && isIP(existing) === 0)
+        return existing;
+    return reportedFqdn.trim().toLowerCase();
+}
+//# sourceMappingURL=node-url.js.map

package/dist/utils/redact.js

@@ -0,0 +1,26 @@
+const SECRET_PATTERNS = [
+    /sk-[A-Za-z0-9_-]{12,}/g,
+    /(?:api[_-]?key|token|secret|password|passwd|private[_-]?key)\s*[:=]\s*["']?[^"',\s}]+/gi,
+    /Bearer\s+[A-Za-z0-9._~+/-]+=*/g,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+];
+export function redactSecretText(value) {
+    return SECRET_PATTERNS.reduce((text, pattern) => text.replace(pattern, '[REDACTED]'), value);
+}
+export function redactUnknown(value) {
+    if (typeof value === 'string')
+        return redactSecretText(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactUnknown(item));
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).map(([key, item]) => {
+            if (/api[_-]?key|token|secret|password|passwd|private[_-]?key/i.test(key)) {
+                return [key, '[REDACTED]'];
+            }
+            return [key, redactUnknown(item)];
+        });
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+//# sourceMappingURL=redact.js.map

package/dist/utils/safe-equal.js

@@ -0,0 +1,13 @@
+import { timingSafeEqual } from 'node:crypto';
+/** Constant-time string comparison to prevent timing attacks. */
+export function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) {
+        // Compare against self to avoid leaking length information via timing
+        timingSafeEqual(bufA, bufA);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=safe-equal.js.map

package/dist/utils/sentinel-nodes.js

@@ -0,0 +1,16 @@
+/**
+ * Well-known sentinel node IDs.
+ *
+ * These virtual Node records satisfy the `LogEntry.nodeId` foreign-key
+ * constraint for internal log sources (Control API process logs, Dashboard
+ * error reports).  They are seeded by `prisma/seed.ts` with
+ * `metadata: '{"sentinel":true}'` and must be excluded from all fleet-facing
+ * queries (node listing, scan, heartbeat monitor, etc.).
+ */
+/** Sentinel node representing the Control API process itself. */
+export const CONTROL_API_NODE_ID = '__control-api__';
+/** Sentinel node representing the Next.js Dashboard. */
+export const DASHBOARD_NODE_ID = '__dashboard__';
+/** Array of all sentinel node IDs — use in Prisma `id: { notIn: … }` filters. */
+export const SENTINEL_NODE_IDS = [CONTROL_API_NODE_ID, DASHBOARD_NODE_ID];
+//# sourceMappingURL=sentinel-nodes.js.map

package/dist/utils/validate.js

@@ -0,0 +1,41 @@
+/**
+ * Request body / query parsing with Zod schemas.
+ *
+ * Usage:
+ *   const body = await parseBody(c, mySchema);
+ *   // body is fully typed & validated
+ */
+import { HttpError } from '../middleware/error-handler.js';
+/** Format Zod issues into a human-readable string. */
+function formatZodError(error) {
+    return error.issues
+        .map((i) => {
+        const path = i.path.length ? `${i.path.join('.')}: ` : '';
+        return `${path}${i.message}`;
+    })
+        .join('; ');
+}
+/**
+ * Parse and validate the JSON request body against a Zod schema.
+ * Throws HttpError 400 with a machine-readable VALIDATION_ERROR code.
+ */
+export async function parseBody(c, schema) {
+    const raw = await c.req.json();
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        throw new HttpError(400, 'VALIDATION_ERROR', formatZodError(result.error));
+    }
+    return result.data;
+}
+/**
+ * Parse and validate an arbitrary value (e.g. upstream response) against a Zod schema.
+ * Returns `{ success: true, data }` or `{ success: false, error }`.
+ */
+export function safeParse(value, schema) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        return { success: false, error: formatZodError(result.error) };
+    }
+    return { success: true, data: result.data };
+}
+//# sourceMappingURL=validate.js.map

package/package.json

@@ -1,6 +1,121 @@
 {
   "name": "@hivemagnus/magnus-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Magnus server: the fleet control plane API (Hono, PostgreSQL, Redis) for nodes running magnus-agent, with optional Hive IAM, Hive Router, HiveMem, Hermes Agent and external security console integrations.",
+  "keywords": [
+    "magnus",
+    "fleet",
+    "control-plane",
+    "server",
+    "api",
+    "hono",
+    "postgresql",
+    "redis",
+    "ops",
+    "hermes-agent"
+  ],
+  "license": "Apache-2.0",
+  "author": "ChefTaco",
+  "homepage": "https://github.com/ChefTaco/magnus/tree/main/services/control-api#readme",
+  "bugs": {
+    "url": "https://github.com/ChefTaco/magnus/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChefTaco/magnus.git",
+    "directory": "services/control-api"
+  },
+  "type": "module",
+  "bin": {
+    "magnus-server": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist/**/*.js",
+    "dist/ai/*.md",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "!dist/**/*-test-fixture.js",
+    "prisma/schema.prisma",
+    "prisma/migrations",
+    "prisma.config.ts",
+    "agent-version.json",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "engines": {
+    "node": "^24.22.1 || ^26.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "@prisma/config": {
+      "deepmerge-ts": "8.0.1"
+    },
+    "@prisma/dev": {
+      "@hono/node-server": "2.1.0"
+    },
+    "fast-uri": "3.1.9",
+    "mysql2": "3.24.4"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc --build && node scripts/copy-assets.mjs",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/cli.js start",
+    "clean": "node -e \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true});fs.rmSync('tsconfig.tsbuildinfo',{force:true})\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run --config vitest.integration.config.ts --passWithNoTests --fileParallelism=false",
+    "test:ci": "vitest run --coverage",
+    "lint": "eslint src/",
+    "db:generate": "prisma generate",
+    "db:migrate": "prisma migrate dev",
+    "db:migrate:deploy": "prisma migrate deploy",
+    "webhooks:migrate-credentials": "tsx scripts/migrate-webhook-credentials.ts",
+    "db:seed": "tsx prisma/seed.ts",
+    "db:studio": "prisma studio",
+    "db:reset": "prisma migrate reset --force",
+    "engineering:recovery-exercise": "node dist/scripts/run-disposable-recovery-exercise.js",
+    "engineering:recovery-reap": "node dist/scripts/run-disposable-recovery-exercise.js --reap-orphans",
+    "check": "node dist/cli.js check",
+    "compose:check": "bash scripts/check-compose.sh",
+    "prepublishOnly": "npm run db:generate && npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@hivemagnus/magnus-contracts": "1.0.2",
+    "@hono/node-server": "^2.1.5",
+    "@hono/swagger-ui": "^0.6.2",
+    "@prisma/adapter-pg": "7.10.1",
+    "@prisma/client": "^7.10.1",
+    "argon2": "^0.45.1",
+    "bullmq": "^5.30.0",
+    "dotenv": "^18.0.9",
+    "hono": "4.13.14",
+    "ioredis": "^5.4.0",
+    "jose": "^6.2.13",
+    "ky": "^2.2.0",
+    "nanoid": "^5.0.0",
+    "pg": "^8.23.1",
+    "ssh2": "^1.17.0",
+    "ws": "^8.22.0",
+    "yaml": "2.9.1",
+    "zod": "^4.6.7",
+    "@hivemagnus/magnus-skills": "1.0.2",
+    "prisma": "^7.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/pg": "^8.23.1",
+    "@types/ssh2": "^1.15.6",
+    "@types/ws": "^8.18.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.12"
+  },
+  "prisma": {
+    "schema": "prisma/schema.prisma",
+    "seed": "tsx prisma/seed.ts"
+  }
+}