feat: runtime config management API + supporting backend work

[roziscoding]

Context

Adds a runtime config management API so peers, servers, and settings can be managed live (no restart), plus the supporting backend work this branch accumulated. jack's config stays a hand-editable, version-controllable config.jsonc (the file is the source of truth) — the management API mutates it through a single serialized writer and applies changes to the live connector map.

What's included

Config management API (the main deliverable)

• A separate management surface on its own port (getManagementApp + a 2nd Bun.serve on MANAGEMENT_PORT), guarded by X-Management-Key (constant-time compare), started only when MANAGEMENT_KEY is set. The public peer port never exposes /config.
• ConfigService: one in-process serialized write queue; rollback-safe atomic file writes (tmp→rename, randomized temp name, preserved perms); persists the raw config so {env}/{file} secret refs are never resolved into the file.
• Live peers CRUD: add / remove (disable-as-soft-delete, in-flight drains) / rename / URL-change rekey with a peer_id download cascade.
• Live servers CRUD (+ source/destination list reconciliation).
• Live connector visibility: search fan-out (/torznab, /peer, /items, /servers, qB) reads connectors live, so add/remove is searchable without restart.
• Migration write-back: a migrated config is persisted with a .bak; also fixes a pre-existing crash where an up-to-date config failed to parse on the next boot.

Supporting backend work (earlier commits on this branch)

• Sensitive-field redaction in logs + a span-attribute redacting funnel.
• Versioned config migration system; TypeScript 6 bump (noUnusedLocals/Parameters).
• Connector-lifecycle refactor (decorator rename; ConnectorManager-shaped deps).

Notes

• No UI yet — the management API is the backend foundation; UI/CLI/BFF are out of scope.
• MANAGEMENT_KEY is operator-set via env (no first-boot key generation).

Testing

• bun test: 223 pass / 0 fail · tsc --noEmit: clean · eslint .: clean

Greptile Summary

This PR adds a runtime config management API on a separate port (MANAGEMENT_PORT), guarded by X-Management-Key with a constant-time comparison. It introduces a ConnectorManager class that replaces the old initializeConnectors function, a ConfigService with a serialized write queue and rollback-safe atomic file writes, and a versioned config migration system. Live CRUD for peers and servers is fully wired through controller, router, and service layers.

• Config management API: A distinct Hono app on its own port reads and mutates config.jsonc through ConfigService, which uses an async mutex to serialize writes and tmp→rename for atomic persistence. Mutation routes are dynamically registered only when a ConfigService is injected.
• ConnectorManager: Replaces the previous flat arrays with a map-based manager whose servers/peers getters are read live on each request, enabling add/remove without restart. Soft-delete (disable rather than evict) lets in-flight downloads drain.
• Config migration: migrateConfig applies versioned transformations on startup and writes the migrated file atomically after backing up the original; a pre-existing crash on up-to-date configs is fixed.

Confidence Score: 4/5

Safe to merge for new deployments; a downgrade after first boot risks silently emptying the config file due to a mis-scoped Zod .catch.

The migration's .catch({ version: 0 }) is placed on the entire z.looseObject(...) rather than on just the version field. Any future config (version number above the current maximum) collapses the whole object to { version: 0 }, runs all migrations against the resulting empty structure, and writes the stripped result back to disk — permanently overwriting all peer and server configuration with no visible warning beyond a routine 'Config migrated' log line. A .bak is created so recovery is possible, but operators won't know they need it until their connectors are gone. Everything else — the constant-time key comparison, the serialized write queue, atomic tmp→rename persistence, and the soft-delete drain strategy — is correct and well-tested.

apps/backend/src/lib/config.ts — specifically the migrateConfig function's .catch placement on line 188.

Important Files Changed

Filename	Overview
apps/backend/src/lib/config.ts	Adds versioned config migration, RawPeerConfig/RawServerConfig schemas, and a version field to AppConfig. The .catch({ version: 0 }) in migrateConfig discards all config content when the version is out of range.
apps/backend/src/modules/config/config.service.ts	New ConfigService with a serialized write queue, rollback-safe persist-then-commit ordering, and generic CRUD over peers/servers. Logic is sound; queue poisoning prevention is correctly handled.
apps/backend/src/middleware/require-management-key.ts	New constant-time key comparison via SHA-256 hash normalization and a manual XOR loop. Implementation is correct; hashing to a fixed-width digest avoids the length-mismatch issue with timingSafeEqual.
apps/backend/src/lib/servers/index.ts	ConnectorManager replaces the old initializeConnectors function with a map-based, live-queryable design. Soft-delete (disable without eviction) is intentionally traded against memory accumulation on high-churn setups.
apps/backend/src/index.ts	Wires ConnectorManager, ConfigService, and management server. Port-collision guard is correct but uses logger.fatal without exiting, which is semantically misleading.
apps/backend/src/lib/atomic-write.ts	New utility for atomic tmp→rename file writes with randomized temp name, preserved permissions, and cleanup on failure. Correct and well-commented.
apps/backend/src/management-app.ts	New Hono app on the management port; globally applies secureHeaders, requireManagementKey, and handleError. No public routes are exposed here.
apps/backend/src/modules/config/config.controller.ts	New ConfigController funnels all mutations through a private #mutate helper that guards ConfigService presence and maps ZodErrors to BadRequestError. Clean design.
apps/backend/src/modules/config/config.router.ts	Mutation routes are conditionally registered at construction time based on controller.canMutate. Missing routes return 404 rather than 500 when no ConfigService is wired.
apps/backend/src/lib/span-attributes.ts	New centralized span attribute funnel with redaction, serialization, size-capping, and sensitive-URL query-param masking. Cleanly replaces scattered span.setAttribute calls.

Sequence Diagram

sequenceDiagram
    participant Client as API Client
    participant MgmtApp as Management App (MANAGEMENT_PORT)
    participant Middleware as requireManagementKey
    participant Controller as ConfigController
    participant Service as ConfigService (queue)
    participant Manager as ConnectorManager
    participant Disk as config.jsonc

    Client->>MgmtApp: "POST /config/peers {X-Management-Key}"
    MgmtApp->>Middleware: validate key (SHA-256 constant-time)
    alt invalid key
        Middleware-->>Client: 401 Unauthorized
    end
    Middleware->>Controller: addPeer(body)
    Controller->>Service: addPeer(input)
    Service->>Service: "#enqueue(task) — serialize write"
    Service->>Service: validate (PeerConfig + RawPeerConfig)
    Service->>Service: check url/name uniqueness
    Service->>Disk: atomicWrite (tmp → rename)
    Service->>Service: "this.#raw = next"
    Service->>Manager: addPeerConnector(resolved)
    Manager->>Manager: PeerConnector.init()
    Controller-->>Client: "201 { ok: true }"

    Note over Client,Disk: Public app reads connectorManager.peers live on next request

Loading

_{Reviews (1): Last reviewed commit: "refactor: complete connector-lifecycle r..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[github-actions]

🐳 Docker image published

This PR has been built and pushed to GHCR:

ghcr.io/roziscoding/jack:pr-24

Pull and run it locally:

docker pull ghcr.io/roziscoding/jack:pr-24
docker run --rm ghcr.io/roziscoding/jack:pr-24

Last built from commit 1f1b143. Heads up: this image is automatically deleted when the PR is closed.

[greptile-apps]

The .catch({ version: 0 }) on the entire z.looseObject(...) parse fires when the version field fails validation — including when version > LATEST_MIGRATION (a downgrade scenario). When it fires, configObject becomes { version: 0 }, discarding every other field (servers, peers, jack, etc.). All migrations then run against that empty object, and the stripped result is atomically written back to disk with a .bak of the original. The backup means data is recoverable, but the production config is silently emptied on first boot after a downgrade — operators may not notice until all their peers and servers are gone.

Applying the catch only to the version field, not the entire schema, keeps the rest of the config intact regardless of the version value.

Suggested change

	const configObject = z
	.looseObject({ version: z.number().max(LATEST_MIGRATION).min(0).default(0) })
	.catch({ version: 0 })
	.parse(rawConfigObject)
	const configObject = z
	.looseObject({ version: z.number().max(LATEST_MIGRATION).min(0).default(0).catch(0) })
	.parse(rawConfigObject)

[greptile-apps]

logger.fatal conventionally signals that the process is about to terminate. Here the application continues serving on the public port — only the management listener is skipped. Using logger.error (or logger.warn) avoids a false alarm in log aggregators and on-call alerting that are configured to page on fatal-level entries.

Suggested change

	logger.fatal({ port: envs.MANAGEMENT_PORT }, 'MANAGEMENT_PORT collides with the public port; not starting the management API')
	logger.error({ port: envs.MANAGEMENT_PORT }, 'MANAGEMENT_PORT collides with the public port; not starting the management API')

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!