Skip to content

Add Nexus secure credential propagation sample - #808

Draft
bergundy wants to merge 3 commits into
mainfrom
nexus-secure-credential-propagation
Draft

bergundy wants to merge 3 commits into
mainfrom
nexus-secure-credential-propagation

Conversation

@bergundy

Copy link
Copy Markdown
Member

What changed?

Adds core/src/main/java/io/temporal/samples/nexussecurecredentialpropagation, a sample that propagates an end-user JWT from a client, through a caller Workflow, to a Nexus Operation handler without the JWT appearing in plaintext in history, Temporal headers, or Nexus headers.

  • Receiver-encrypted headers. The credential travels only in headers, encrypted with Tink HPKE to the receiving hop (caller Worker for the start hop, Nexus handler for the Nexus hop). Clients and caller Workers hold only public keys for the hops they send on.
  • Bound to the exact arguments. Each header's HPKE context binds it to the hop's context and to a SHA-256 digest of the transmitted argument ciphertexts, their positions, and count. No input is canonicalized or re-serialized. The payload codec hands the digest to the interceptors through a thread local and knows nothing about credentials.
  • Continue-as-new headers are bound to firstExecutionRunId (the Java SDK builds that header before encoding arguments). Child Workflows never receive the credential.
  • Handler. Takes the route from the actual Nexus request, validates the JWT, authorizes the input against the principal and a client-sealed intent (which bounds what signals/updates can steer the Workflow into), derives the backing Workflow ID from principal + business identity, and signs operation tokens so they can't be forged for cancellation.
  • Codec. Context-bound Tink AEAD payloads; rejections are non-retryable PayloadValidationError so the handler reports BAD_REQUEST instead of retrying.
  • Adds com.google.crypto.tink:tink:1.23.0 to core.

The README documents the threat model, wire formats, key distribution, replay cases, steering alternatives, and the access-layer boundary for replayed cancels.

Why?

To show a replay-safe way to carry end-user identity across a Nexus call where neither history readers nor holders of sender-side keys can read or repurpose the credential.

Breaking changes?

None.

Testing

  • SecureCredentialPropagationTest (20 end-to-end tests against the test server): start / signal-with-start / update-with-start, continue-as-new to another type plus retry, child Workflows, cancellation, argument reorder/duplicate/truncate/substitute, copied continue-as-new header, key-less attacker replaying captured Nexus input and headers (exact replay, input swap, endpoint move, missing credential), intent and subject checks, wrong audience, and a misordered interceptor.
  • CryptoComponentsTest (18 unit tests): framing, header contexts and parsing, args digest, codec context binding, JWT validation, intent policy, resource IDs, operation tokens.
  • Full :core:test passes.
  • Ran the three-process demo against a local dev server (Server 1.32) and verified neither history contains the JWT, its claims, or business values.

Propagate an end-user JWT from a client, through a caller Workflow, to a
Nexus Operation handler without exposing it in history or headers.

Each credential header is encrypted with Tink HPKE to the receiving hop
and bound to the hop's context and to a digest of the exact argument
ciphertexts it accompanies, so no sender-side key can decrypt or
repurpose it and no input needs deterministic serialization. The
handler validates the JWT, authorizes the input against a client-sealed
intent, derives the backing Workflow ID from the principal and business
identity, and signs its operation tokens.

Includes end-to-end tests against the test server, covering start-path,
continue-as-new, replay, substitution, and authorization cases, plus
unit tests of the cryptographic components.
@bergundy
bergundy requested review from a team, antmendoza and tsurdilo as code owners October 13, 2026 16:54
@bergundy
bergundy marked this pull request as draft October 13, 2026 16:55
Public HPKE keys need not be secret: they only let a holder seal a
header around a token they already have. Document that sender
authentication requires a signature, and that the client-sealed intent
does not replace server-side authorization.
VerifyCredentialBinding reads a Workflow history and, for each
credential header, recomputes the args digest from the event's input
ciphertexts (or uses firstExecutionRunId for continue-as-new headers),
opens the header with that context, and confirms that a context with
one bit changed is rejected and that the digest is not present in the
header bytes. It prints only the credential's subject and issuer and
exits non-zero on failure.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant