Skip to content

Archived ApherisFold documentation

This page is part of the archived ApherisFold and Hub documentation. For Apheris Foundry, see the Foundry overview.

Foundry webhook security🔗

Foundry receives Nextflow execution events at a fixed internal endpoint:

POST /foundry/webhook

The callback URL never contains a credential. Each run gets a cryptographically random 128-bit password, and nf-weblog sends it with the fixed username foundry using HTTP Basic authentication. Reverse proxies, ingress controllers, and other access-log processors therefore see only the fixed request path.

Replay protection🔗

Hub requires every event to contain the utcTime emitted by nf-weblog and accepts events only within ten minutes of Hub's current time. Hub retains a SHA-256 identity of the canonical JSON event in PostgreSQL for at least twenty minutes, pruning expired receipts globally as webhook traffic arrives. The receipt and run update are committed in the same transaction, so duplicate deliveries, replica races, and coordinator restarts cannot apply an exact event twice. Receipt-retention cleanup is best-effort and never blocks ingestion.

Equivalent JSON objects with different key ordering have the same identity. Customer-hosted deployments must keep the Hub and launcher clocks synchronized.

Delivery and recovery🔗

nf-weblog 1.1.2 sends each callback at most once: it logs transport and non-success HTTP responses but does not retry them. Replay receipts prevent a duplicate from being applied; they do not guarantee delivery. A transient Hub, network, or database failure can therefore leave real-time step data absent.

Hub recovers terminal state through Kubernetes launcher polling. Run reads also rebuild observability from persisted Nextflow trace and log files when those files are available. These fallbacks can be delayed and may not reconstruct every intermediate real-time event. A deployment that requires guaranteed callback delivery needs a retry-capable sender or durable outbox in the workflow plugin.

Upgrade compatibility🔗

The fixed Basic-auth endpoint is intentionally incompatible with the previous tokenized-path endpoint. Before upgrading to this version, stop accepting new Foundry runs and wait for every active run to reach a terminal state. Deploy all Hub replicas as a coordinated, non-rolling cutover; otherwise callbacks routed between old and new replicas return 404 and are not retried. Apply the same drain and coordinated cutover before rolling back across this version boundary.

Deployment posture🔗

Trusted-cluster development and proof-of-concept deployments may use the cluster-internal HTTP service when the cluster network is trusted. This accepts the risk that a workload able to observe internal traffic could recover the Basic credential.

Customer-hosted deployments must:

  • expose the webhook only over TLS, including traffic from the launcher;
  • configure proxies and diagnostics not to record Authorization headers;
  • restrict read access to the Hub database and launcher environment, which contain the per-run credential; and
  • restrict webhook network reachability to expected workflow workloads where the platform provides that control.

The supported nf-weblog authentication mechanism is Basic authentication; it does not provide per-message HMAC signatures. TLS protects the body in transit, the per-run credential authenticates the sender, and timestamped durable receipts prevent captured requests from being replayed. A workload that already possesses the live run credential can still construct a new event. Deployments whose threat model requires protection from a compromised credential holder need a signing-capable workflow plugin and a separate key-management design.