@hivemagnus/magnus-server 1.0.1 → 1.0.3

package/.env.example

@@ -86,6 +86,13 @@ CORS_ORIGIN=https://magnus.example.com:3000
 # Optional integrations — each is off until configured
 # ═══════════════════════════════════════════════════════════════════════════
 
+# ── Interoperating with older clients (optional) ──
+# JSON object mapping legacy /api/v1 path prefixes to current ones. Requests are
+# rewritten before routing, so auth, scopes and audit see the current path.
+# MAGNUS_ROUTE_ALIASES_JSON={"/api/v1/resource-leases/old-name/admission":"/api/v1/resource-leases/admission"}
+# Legacy webhook type names mapped to a current format (generic, slack, discord, mattermost).
+# MAGNUS_WEBHOOK_TYPE_ALIASES=legacy-chat=mattermost
+
 # ── Hive IAM: verify RS256 access tokens issued by Hive IAM ──
 # When set, JWT_SECRET is no longer required for user tokens.
 # IAM_CORE_URL=https://iam.example.com
@@ -139,6 +146,9 @@ CORS_ORIGIN=https://magnus.example.com:3000
 # APPROVAL_SIGNER_PUBLIC_KEY_PATH=/etc/magnus-server/approval-signer.pub
 # APPROVAL_TELEGRAM_ACTOR_SHA256=
 # APPROVAL_IPHONE_ACTOR_SHA256=
+# Signature domain prefixes accepted for approval decisions; the first is preferred.
+# Add a legacy signer domain (for example legacy.approval) to interoperate with older signers.
+# MAGNUS_APPROVAL_ASSERTION_DOMAINS=magnus.approval-assertion
 # Read-only digests for an external observability collector and the fleet-check reporter.
 # MAGNUS_COLLECTOR_TOKEN_SHA256=
 # MAGNUS_FLEET_CHECK_TOKEN_SHA256=

package/README.md

@@ -132,6 +132,21 @@ Unknown destinations and changed keys fail before authentication. Multiple
 pins permit a reviewed host-key rotation; remove the old pin afterward.
 This setting does not enable the retired browser deployment routes.
 
+## Interoperating with older components
+
+Every switch below is off or set to current behaviour by default. Set them only
+while older clients, signers or scripts still talk to this server.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MAGNUS_APPROVAL_ASSERTION_DOMAINS` | `magnus.approval-assertion` | Comma-separated signature domain prefixes accepted for signed approval decisions (the signed message starts with `<prefix>.v<N>`). Add a legacy signer domain, for example `magnus.approval-assertion,legacy.approval`. The first entry is preferred. Allowed characters: `a-z`, `0-9`, `.` and `-`. |
+| `MAGNUS_ROUTE_ALIASES_JSON` | unset | JSON object mapping legacy `/api/v1` path prefixes to current ones, for example `{"/api/v1/resource-leases/old-name/admission": "/api/v1/resource-leases/admission"}`. Requests are rewritten before routing, so authentication, endpoint scopes, rate limits and audit see the current path. Aliases cannot chain or contain `.`/`..` segments. |
+| `MAGNUS_WEBHOOK_TYPE_ALIASES` | unset | Comma-separated `legacy=format` pairs, for example `legacy-chat=mattermost`, so webhook endpoints stored or submitted under an older type name keep their delivery format. New and edited endpoints store the current format. |
+
+Older Hermes Agent plugins also need `MAGNUS_PLUGIN_API_ENABLED=true`, and an
+older approval bridge needs `MAGNUS_APPROVAL_BRIDGE_CONSUMER`. See the
+[changelog](../../CHANGELOG.md) for renamed variables.
+
 ## Develop
 
 From the repository root:

package/agent-version.json

@@ -1 +1 @@
-{"version":"1.0.1"}
+{"version":"1.0.3"}

package/dist/cli/env-catalog.js

@@ -3,6 +3,8 @@ export const ENV_CATALOG = [
     // ── Core ──
     { name: 'NODE_ENV', group: 'core', default: 'development', description: 'development, production or test. Production enforces TLS, DATABASE_URL and strict CORS.' },
     { name: 'LOG_LEVEL', group: 'core', default: 'info', description: 'debug, info, warn, error or fatal.' },
+    { name: 'MAGNUS_ROUTE_ALIASES_JSON', group: 'core', description: 'Optional JSON object mapping legacy /api/v1 path prefixes to current ones, for clients built against older route names. Requests are rewritten before routing, so auth and audit see the current path. Unset means no aliases.' },
+    { name: 'MAGNUS_WEBHOOK_TYPE_ALIASES', group: 'core', description: 'Optional comma-separated legacy=format pairs (format: generic, slack, discord or mattermost) so webhook endpoints stored or submitted under an older type name keep their delivery format.' },
     { name: 'MAGNUS_HOME', group: 'paths', default: '~/.magnus', description: 'Base directory for server-owned data (audit logs, credential rotation state, backups).' },
     { name: 'MAGNUS_ENV_FILE', group: 'paths', description: 'Env file loaded at startup (set by `--env-file`). Variables already in the environment win.' },
     { name: 'AUDIT_LOG_DIR', group: 'paths', default: '$MAGNUS_HOME/audit-logs', description: 'Directory for the append-only audit log files.' },
@@ -81,6 +83,7 @@ export const ENV_CATALOG = [
     { name: 'APPROVAL_SIGNER_PUBLIC_KEY_PEM', group: 'plugins', description: 'Ed25519 public key (PEM) that signs approval decisions. _B64 (DER) and _PATH variants are also accepted.' },
     { name: 'APPROVAL_TELEGRAM_ACTOR_SHA256', group: 'plugins', description: 'Actor binding digest for decisions from the Telegram channel.' },
     { name: 'APPROVAL_IPHONE_ACTOR_SHA256', group: 'plugins', description: 'Actor binding digest for decisions from the iPhone channel.' },
+    { name: 'MAGNUS_APPROVAL_ASSERTION_DOMAINS', group: 'plugins', default: 'magnus.approval-assertion', description: 'Comma-separated signature domain prefixes accepted for approval decisions (signed message is <prefix>.v<N>). The first is preferred; add a legacy signer domain to keep older signers working.' },
     { name: 'MAGNUS_COLLECTOR_TOKEN_SHA256', group: 'plugins', description: 'SHA-256 digest of a read-only external observability collector credential.' },
     { name: 'MAGNUS_FLEET_CHECK_TOKEN_SHA256', group: 'plugins', description: 'SHA-256 digest of the fleet-check reporter credential.' },
     // ── Hermes registry ──

package/dist/config/env.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import path from 'node:path';
+import { parseRouteAliases } from './route-aliases.js';
+import { webhookTypeAliases } from '../services/webhook-types.js';
 // ─── Shared environment schema — validated with Zod ───
 const portSchema = z.coerce.number().int().min(1).max(65535);
 const booleanEnvSchema = z.enum(['true', 'false']).default('false').transform((value) => value === 'true');
@@ -48,6 +50,10 @@ export const envSchema = z.object({
     APPROVAL_TELEGRAM_ACTOR_SHA256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     APPROVAL_IPHONE_ACTOR_SHA256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     MAGNUS_APPROVAL_BRIDGE_CONSUMER: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/i).optional(),
+    // Accepted approval-assertion signature domain prefixes (comma-separated); first is preferred.
+    MAGNUS_APPROVAL_ASSERTION_DOMAINS: z.string()
+        .regex(/^\s*[a-z0-9](?:[a-z0-9.-]{0,98}[a-z0-9])?\s*(?:,\s*[a-z0-9](?:[a-z0-9.-]{0,98}[a-z0-9])?\s*)*$/, 'must list domain prefixes made of a-z, 0-9, "." and "-", separated by commas')
+        .optional(),
     // Security Fusion: off (default) | local (in-process) | remote (external security console).
     SECURITY_FUSION_MODE: z.enum(['off', 'local', 'remote']).default('off'),
     SECURITY_FUSION_API_URL: z.string().url().optional(),
@@ -151,7 +157,27 @@ export const envSchema = z.object({
     HERMES_HIVEMEM_WORKSPACE_ID: z.string().optional(),
     HERMES_HIVEMEM_DEFAULT_SCOPE: z.enum(['private', 'shared']).optional(),
     HERMES_OPENAI_RUNTIME: z.enum(['auto', 'codex_app_server']).optional(),
+    // Optional legacy-path -> current-path prefix map for older clients (see config/route-aliases.ts).
+    MAGNUS_ROUTE_ALIASES_JSON: z.string().optional(),
+    // Optional legacy webhook type names: comma-separated legacy=format pairs.
+    MAGNUS_WEBHOOK_TYPE_ALIASES: z.string()
+        .regex(/^\s*(?:[a-z][a-z0-9_-]{0,31}\s*=\s*(?:generic|slack|discord|mattermost)\s*(?:,\s*|$))*$/, 'must list legacy=format pairs, where format is generic, slack, discord or mattermost')
+        .optional(),
 }).superRefine((env, ctx) => {
+    try {
+        webhookTypeAliases(env.MAGNUS_WEBHOOK_TYPE_ALIASES);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['MAGNUS_WEBHOOK_TYPE_ALIASES'],
+            message: error instanceof Error ? error.message : 'MAGNUS_WEBHOOK_TYPE_ALIASES is invalid' });
+    }
+    try {
+        parseRouteAliases(env.MAGNUS_ROUTE_ALIASES_JSON);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['MAGNUS_ROUTE_ALIASES_JSON'],
+            message: error instanceof Error ? error.message : 'MAGNUS_ROUTE_ALIASES_JSON is invalid' });
+    }
     if (env.HEALTH_SNAPSHOT_FULL_FIDELITY_HOURS > env.HEALTH_SNAPSHOT_RETENTION_DAYS * 24) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/dist/config/route-aliases.js

@@ -0,0 +1,73 @@
+/**
+ * Optional request path aliases for clients built against older route names.
+ *
+ * `MAGNUS_ROUTE_ALIASES_JSON` is a JSON object that maps a legacy path prefix
+ * to the current one, for example
+ * `{"/api/v1/old/prefix": "/api/v1/new/prefix"}`. A request whose path equals a
+ * legacy prefix, or continues it after a `/`, is rewritten before routing, so
+ * authentication, endpoint scopes, rate limits and audit all see the current
+ * path. Unset (the default) means no aliases.
+ */
+const segment = '[A-Za-z0-9._~-]+';
+const aliasPath = new RegExp(`^/api/v1(?:/${segment})+$`);
+function validPath(path) {
+    return aliasPath.test(path) && !path.split('/').some(part => part === '.' || part === '..');
+}
+/** Parse and validate the alias map; throws a descriptive error when it is malformed. */
+export function parseRouteAliases(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return [];
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON must be a JSON object');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON must be a JSON object');
+    const entries = Object.entries(value);
+    if (entries.length > 64)
+        throw new Error('MAGNUS_ROUTE_ALIASES_JSON may define at most 64 aliases');
+    const aliases = [];
+    for (const [from, to] of entries) {
+        if (typeof to !== 'string' || !validPath(from) || !validPath(to))
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON keys and values must be /api/v1/... paths without "." or ".." segments');
+        if (from === to)
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON maps a path to itself');
+        aliases.push({ from, to });
+    }
+    for (const { to } of aliases)
+        if (aliases.some(alias => to === alias.from || to.startsWith(`${alias.from}/`)))
+            throw new Error('MAGNUS_ROUTE_ALIASES_JSON targets must not be aliases themselves');
+    // Longest prefix first, so a more specific alias wins.
+    return aliases.sort((a, b) => b.from.length - a.from.length);
+}
+/** The current path for `path`, or null when no alias applies. */
+export function resolveRouteAlias(path, aliases) {
+    for (const { from, to } of aliases) {
+        if (path === from)
+            return to;
+        if (path.startsWith(`${from}/`))
+            return to + path.slice(from.length);
+    }
+    return null;
+}
+/** Wrap a fetch handler so legacy paths reach their current routes. Returns `fetch` unchanged without aliases. */
+export function withRouteAliases(fetch, aliases) {
+    if (!aliases.length)
+        return fetch;
+    return (request, env, context) => {
+        const url = new URL(request.url);
+        const target = resolveRouteAlias(url.pathname, aliases);
+        if (target === null)
+            return fetch(request, env, context);
+        url.pathname = target;
+        const init = {
+            method: request.method, headers: request.headers, redirect: request.redirect, signal: request.signal,
+            ...(request.body ? { body: request.body, duplex: 'half' } : {}),
+        };
+        return fetch(new Request(url, init), env, context);
+    };
+}
+//# sourceMappingURL=route-aliases.js.map