Security Model

The connector is a privileged channel: it can manage users and licenses. Its auth model is layered so the surface stays safe even though it isn't tied to a user session.

Request headers

Every connector request carries these headers:

Layer 1 — service token (active)

The portal rejects any connector request whose x-connector-token doesn't match its CONNECTOR_SECRET:

missing/empty secret   → 403 Forbidden  (connector effectively disabled)
wrong token            → 401 Unauthorized
correct token          → request proceeds as the `platform` actor

The authenticated request is attributed to a synthetic platform actor, so every central action lands in the audit log.

Layer 2 — HMAC signature (reserved/hardening)

For tamper-proofing, the Admin Module signs the raw body with the shared secret and sends it as x-connector-signature. The portal recomputes and compares:

import { createHmac } from 'node:crypto'
 
const expected = createHmac('sha256', CONNECTOR_SECRET)
  .update(rawBody)
  .digest('hex')
 
const valid = `sha256=${expected}` === signatureHeader

Layer 3 — replay protection (reserved/hardening)

x-connector-timestamp lets the portal reject stale or replayed requests: discard anything older than a small window (e.g. 5 minutes) and optionally track recently seen request ids.

Operational hygiene

Disabling the connector

To run a deployment fully standalone, leave CONNECTOR_SECRET empty. With no secret configured, the surface rejects every request — the portal accepts no central management at all.