Skip to content

Key custody model

xcore-agent never generates or stores long-lived secrets.

The .xdeploy flow

The artifact's per-version data-encryption key (DEK) is obtained at deploy time from XCore Hub and kept only in memory for the duration of one deployment:

XDevKey (authenticates the project)
        │
        ├── POST /v1/auth ──────────────► bearer token
        │
Deployment credential (authorizes THIS deployment)
        │
        ├── POST /v1/deployments/authorize ──► DEK (unwrapped, in memory only)
        │
        └── decrypt artifact, install, forget DEK

The two secrets are deliberately not the same: a leaked XDevKey does not, by itself, grant artifact decryption. Access revocation is enforced at POST /v1/deployments/authorize, on the Hub side.

At build time, the DEK and the signer public key are printed to stdout for the operator to distribute — the packer saves neither.

Signing keys

  • Ed25519 (.xdeploy): a signer private key signs the ciphertext at build time (--signing-key-file); agents verify against the public key. If no key file is given, a throwaway key is generated and not saved — fine for local testing only.
  • HMAC-SHA256 (marketplace): the plugin developer's own xdevkeys signing secret — a symmetric shared secret. Whoever holds it can also forge signatures, so --signing-secret is a required CLI argument that the operator supplies deliberately. See The real marketplace flow.

Host-local secrets

  • --plugin-secret-key (XCORE_PLUGIN_SECRET) — the host's own plugins.secret_key from the root integration.yaml, used to sign execution_mode: trusted plugins with plugin.sig so the host's strict_trusted check can load them. Host-local, never embedded in the artifact.
  • --git-token / API keys / deployment credentials — passed at the CLI or via environment variables, never stored by the agent.

Summary

Secret Generated by Stored by agent? Purpose
DEK (per version) Packer at build No — memory only during one deploy Decrypt the artifact
Ed25519 signer key Packer at build No — public key distributed Sign/verify .xdeploy
HMAC signing secret Plugin developer (xdevkeys) No — operator supplies it Sign/verify marketplace ZIP
XDevKey XCore Hub No Authenticate the project
Deployment credential XCore Hub No Authorize DEK unwrap
plugins.secret_key Host operator No Sign trusted-mode plugins locally