Secure Worker Callbacks With HMAC for Remediation Agents

DATA Remediation starts with a user-visible promise: when a creator reports a product issue, VibeChopper can preserve the context, turn it into an agent-trackable job, and show progress while the repair path moves. That progress has to be trustworthy. A status tracker that accepts anonymous updates is worse than no tracker at all, because it can make an unverified actor look like the repair system. Send feedback with context

The secure callback layer exists for that reason. Remediation agents are allowed to run outside the web request that created the job. They can claim work, report lifecycle events, mark a job ready for publish, and report publish results. Those are powerful actions. A forged event could make a broken job look fixed. A forged completion could unlock the wrong next step. A forged publish result could send the wrong notification. The API boundary needs to prove that the callback came from a worker holding the shared secret and that the message is fresh enough to accept.

VibeChopper handles that boundary in server/dataRemediationRunner.ts. The worker signs each callback with HMAC-SHA256 over the exact raw request body and a timestamp. The server reads x-data-remediation-timestamp and x-data-remediation-signature, accepts the legacy remediation header names for compatibility, verifies timestamp skew, reconstructs the expected signature over the raw body, and rejects the request before route logic runs if anything is wrong.

This is not security theater. It is the difference between a status page that reports what the remediation worker actually did and a status page that trusts whatever JSON arrived. The public product action is simple: see remediation status tracking. The backend contract is deliberate: every worker callback must be signed, current, and validated before it can mutate remediation state.

The signing contract is compact. The worker builds a timestamp, serializes the callback body, and computes an HMAC-SHA256 digest with the shared secret. The signed payload format is timestamp + '.' + rawBody. The server performs the same calculation and compares the expected digest to the submitted signature.

That dot between timestamp and body looks small, but separators matter. Without a stable boundary, concatenated values can become ambiguous as formats evolve. With a separator, the verifier has a crisp message shape: this timestamp, followed by this exact body. Both the dev runner and the headless worker use the same format, and the focused smoke test checks that the script signature equals signDataRemediationBody(Buffer.from(body), timestamp, secret).

The exact-body detail matters even more. JSON can be semantically equivalent while bytewise different. Key order, spacing, omitted defaults, and string escaping can all change after parsing and reserializing. A verifier that signs JSON.stringify(req.body) after middleware has transformed the payload may accidentally accept one dialect while the worker signed another. VibeChopper prefers req.rawBody when available and falls back only when needed, because webhook-style verification should bind to the bytes that crossed the boundary.

The header format is equally practical. Workers send x-data-remediation-timestamp and x-data-remediation-signature. The signature may include a sha256= prefix, and the server strips it before verification. The route layer does not need to know these details. It uses requireDataRemediationWorkerHmac, which either calls next() with a verified request or returns a JSON error with the right status code.

HMAC verification is necessary, but it is not the whole design. The worker API should also be narrow. VibeChopper exposes four signed worker actions: claim the next job, append worker events, complete a job, and report a publish result. Each route has a specific purpose and a Zod-validated body. The signature proves where the request came from. The schema proves that the payload is shaped like something the route knows how to handle. Open the edit-run receipts

POST /api/data-remediation/worker/claim accepts a worker ID and capabilities list, then returns a claimed job. POST /api/data-remediation/worker/:id/events appends progress with an optional status patch. POST /api/data-remediation/worker/:id/complete records awaiting_publish, checks_failed, or failed. POST /api/data-remediation/worker/:id/publish-result records whether the fix published and stores deploy metadata or failure details.

That separation keeps the remediation lifecycle understandable. A worker cannot send arbitrary database mutations through one generic command endpoint. It can only move the job through known surfaces. The public status tracker can render the event rail. Notification code can react to publish success or failure. Admin views can inspect the same job record without reverse-engineering a blob of worker output.

This mirrors the AI edit run architecture elsewhere in VibeChopper. Natural-language video editing becomes credible when plans, tool calls, artifacts, and render verification are visible as typed events instead of loose logs. Remediation works the same way. Agent work is allowed to be asynchronous, but the callbacks that describe that work remain structured, signed, and product-owned.

HMAC proves possession of the shared secret. It does not, by itself, prove that a message is new. If an attacker captures a valid callback and the server accepts it forever, the signature becomes reusable. VibeChopper reduces that risk with a timestamp skew limit. The verifier parses the submitted timestamp as a number or date string and rejects callbacks more than five minutes away from server time.

The result is a bounded replay window. A callback signed for the current moment can pass. A stale event from yesterday cannot. A future-dated event that falls outside the allowed skew cannot. This is a practical protection for worker callbacks because remediation events are short-lived operational messages, not archival documents that should be replayable months later.

The server returns 401 for missing signature headers, stale timestamps, and invalid signatures. It returns 503 when the worker shared secret is not configured. Those statuses are intentionally different. Missing or invalid credentials are authentication failures. Missing server configuration means the product cannot safely accept worker callbacks yet. That distinction helps operators diagnose whether the problem is a caller, a clock, or the environment.

There is still a design choice here. Timestamp skew is not the same as one-time nonce storage. A strict nonce ledger can make replay protection stronger, but it also adds persistence, cleanup, and duplicate-delivery decisions. For this worker surface, the five-minute HMAC timestamp window gives VibeChopper a clear baseline: callbacks have to be signed and current before the job state changes.

Signature comparison has its own trap. A naive string comparison may stop at the first different character. In sensitive contexts, response timing can leak how much of the candidate signature matched. VibeChopper avoids that by decoding both signatures as hex buffers and using Node's crypto.timingSafeEqual after confirming the buffers have the same length. Create your editing login

The verifier also checks that the submitted signature is a 64-character hex digest before comparison. That format check avoids malformed input reaching the timing-safe comparison path and keeps errors consistent. The comparison helper lowercases the submitted signature and compares it to the expected HMAC digest. A valid signature passes. A missing, malformed, wrong-length, or wrong-value signature does not reach route behavior.

This is the same security posture VibeChopper applies to user-facing access systems: keep authentication decisions at the boundary, make the happy path explicit, and do not let business logic decide whether a caller was authentic. Passkeys, bearer-token native auth, and HMAC worker callbacks are different mechanisms, but they share the same product expectation. The actor has to prove the right capability before state changes.

That boundary makes code easier to review. The route handler for worker events can focus on Zod parsing, status patches, job existence, and event append behavior. It does not need to remember how HMAC works. The middleware either verified the request or did not call the handler. Security improves because the route is smaller, and maintainability improves because the callback protocol lives in one place.

The visible payoff is the remediation status page. A user can open a route such as /data-remediation/status/sample and see the lifecycle of a repair job. The page is useful only if the events behind it are credible. Signed worker callbacks let the product show progress without giving the public internet a writeable progress log. Send feedback with context

Progress events are intentionally concise. A worker can report investigation phases, check results, file notes, branch or commit metadata, publish status, and failure details. The server stores those events against the remediation job. Notification code can later tell the submitter when the fix passed production checks and is live. The public status page can show where the job is without exposing internal secrets or letting unsigned clients invent milestones.

This is the same operational pattern as upload monitoring and render verification. Long-running work needs an observable trail. Uploads need resumable sessions and telemetry. Renders need artifact verification. Remediation jobs need signed events. In each case, VibeChopper avoids asking users to trust a spinner. The product records specific state transitions that can survive refreshes, background workers, and asynchronous completion.

For creators, the language is simple: report feedback with context and watch the fix move. For developers, the mechanics are stricter: authenticate callbacks, validate payloads, append typed events, and keep status views read-oriented. That is how an AI repair loop becomes a product surface instead of a pile of terminal output.

The callback verifier reads DATA_REMEDIATION_WORKER_SHARED_SECRET, with REMEDIATION_WORKER_SHARED_SECRET as a compatibility fallback. Dispatch also requires explicit enablement through ENABLE_DATA_REMEDIATION_AGENT_DISPATCH. If dispatch is disabled, the runner reports that state. If the SSH command or shared secret is missing, it skips rather than pretending a worker launched. These checks keep remediation automation opt-in and diagnosable.

When dispatch is enabled, the server builds a remote command with the server URL, production URL, shared secret, and serialized job context. It uses shell quoting for environment values and launches the dev runner detached. That runner then reports lifecycle events through the same signed callback channel. The important part is that the callback protocol is the stable contract. The worker can run headlessly, but it still has to speak the signed API.

This boundary also protects product ownership. Remediation workers do not get direct database credentials from the status page. They do not get to bypass route validation because they are internal automation. They interact through the same narrow worker endpoints that the server can authenticate, validate, store, and display. The shared secret is a capability to call those endpoints, not a blank check to mutate the platform.

That distinction matters as agent systems grow. It is tempting to give repair automation broad access because the worker is supposed to help. VibeChopper keeps the integration smaller: the worker receives job context, does the assigned work, and reports signed events. The server remains the owner of job state, status visibility, notifications, and publish result handling.

If you are building remediation agents, background workers, or webhook-style callbacks for an AI product, copy the shape before the exact code. Sign the timestamp and raw body. Use HMAC-SHA256 or another well-understood MAC with a server-held secret. Keep the secret out of client code. Verify the signature before route logic. Reject missing, malformed, stale, and invalid messages with clear status codes.

Preserve the raw body for verification. Do not depend on a parsed object if your worker signed bytes. Put a separator between signed fields. Accept a sha256= prefix if it helps interoperability, but normalize before comparing. Validate that the signature is hex and the expected length. Use timing-safe comparison after length checks. Add focused tests that prove your worker signing helper and server verifier agree on the exact format.

Keep the callback surface narrow. A worker should not need a generic admin endpoint to report progress. Give it a small set of typed actions that match the lifecycle: claim, event, complete, publish result, or whatever your domain requires. Validate every body at the boundary. Treat signed callbacks as authenticated, not automatically correct. Authentication answers who could send it. Validation answers whether the payload is acceptable.

Finally, make the visible status page read from server-owned state. Do not let public status views double as write APIs. Signed worker events should feed a durable event trail. Users should see progress because the product recorded it, not because the browser is holding temporary state. That is how automated remediation stays useful after refreshes, retries, failures, and duplicate callbacks.

Secure worker callbacks are not the flashiest part of DATA Remediation, but they are one of the reasons the loop can be product-grade. A creator reports feedback. VibeChopper turns it into a remediation job. A worker claims the job and reports progress. The server accepts only signed, fresh, validated callbacks. The status page shows the repair moving. Notifications can tell the submitter when the fix is live.

That chain would be fragile if any anonymous POST could impersonate a worker. HMAC gives the callback boundary a clear proof of capability. Timestamp skew makes old messages less useful. Timing-safe comparison removes a class of avoidable signature leaks. Narrow routes and Zod schemas keep the worker from becoming a generic mutation tunnel. The whole system stays understandable.

For VibeChopper, this is part of the larger reliability pattern behind AI-assisted creative software. The user describes the issue. The platform preserves context. Agents can help. But the server still owns trust, validation, status, and durable state. That is how remediation automation earns a place in the product instead of sitting off to the side as an internal script.