Temporal Cloud Proxy Internal Architecture and Module Design

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

​

Module Overview

​

Crypto Layer

Codec (converter.PayloadCodec)
  └── Cipher
        └── CachingMaterialsManager
              └── MaterialsManager  (AWSKMSProvider | GCPKMSProvider)

​

MaterialsManager Interface

type MaterialsManager interface {
    GetMaterial(ctx context.Context, cryptoCtx CryptoContext) (*Material, error)
    DecryptMaterial(ctx context.Context, cryptoCtx CryptoContext, material *Material) (*Material, error)
}

• GetMaterial — generates a new data key (used during encryption). The KMS provider calls GenerateDataKey (AWS) or GenerateRandomBytes + Encrypt (GCP) and returns both the plaintext key and the KMS-encrypted key blob.
• DecryptMaterial — recovers a plaintext key from the encrypted key blob stored in payload metadata (used during decryption). The KMS provider calls Decrypt and returns the recovered plaintext key.

​

CachingMaterialsManager

• MaxAge — wall-clock age of the cached Material since CreatedAt
• MaxMessagesUsed — number of times the cached key has been used (incremented atomically inside a sync.RWMutex)
• MaxCache — maximum number of entries in the LRU; the LRU itself evicts the least-recently-used entry when the limit is reached

​

Cipher

• Encrypt(ctx, EncryptInput) (ciphertext, encryptedKey, error) — fetches a material via GetMaterial, generates a random 12-byte nonce, and encrypts the plaintext with AES-GCM using the PayloadContext as additional authenticated data (AAD). Returns the nonce || ciphertext byte slice and the KMS-encrypted key blob.
• Decrypt(ctx, DecryptInput) (plaintext, error) — calls DecryptMaterial to recover the plaintext key, then opens the AES-GCM sealed message using the PayloadContext as AAD.

​

Codec

• Encode — serialises each *commonpb.Payload, calls Cipher.Encrypt, and wraps the result in a new payload with metadata fields encoding: binary/encrypted, encryption-key-id, and encrypted-data-key.
• Decode — skips payloads whose encoding is not binary/encrypted, extracts encryption-key-id and encrypted-data-key from metadata, calls Cipher.Decrypt, and unmarshals the recovered bytes back into a *commonpb.Payload.

​

Authentication Layer

​

Authenticator Interface

type Authenticator interface {
    Type() string
    Init(ctx context.Context, config map[string]interface{}) error
    Authenticate(ctx context.Context, credentials interface{}) (*AuthenticationResult, error)
    Close() error
}

​

JwtAuthenticator

1. Strips the Bearer prefix from the authorization header value
2. Parses and validates the JWT signature using the live JWKS
3. Checks that at least one audience in the token’s aud claim matches a configured audience
4. Verifies the exp claim has not elapsed
5. Returns an AuthenticationResult with Authenticated: true, the sub claim as Subject, and the full claims map

​

SpiffeAuthenticator

1. Strips the Bearer prefix
2. Calls jwtsvid.ParseAndValidate against the live JWTSource (which handles SVID signature verification and audience matching)
3. Checks that the validated SVID’s SPIFFE ID appears in the configured spiffe_ids allow-list
4. Returns an AuthenticationResult with Authenticated: true and the SPIFFE ID as Subject

​

Request Flow

Worker
  │  gRPC call (unary) with metadata:
  │    workload-id: <workload_id>
  │    authorization: Bearer <token>
  │
  ▼
[transport / grpc.Server]
  │  WorkflowServiceProxyServer forwards call to:
  ▼
[proxy / ProxyProvider.Invoke]
  │  1. Read metadata from incoming context
  │  2. Extract workload-id header
  │  3. RLock → connectionMux[workload_id] lookup → RUnlock
  │  4. If authenticator configured:
  │       Authenticator.Authenticate(ctx, authorization header)
  │       → return codes.Unauthenticated on failure
  │  5. Forward via namespaceConnection.Invoke(ctx, method, req, reply)
  │
  ▼
[namespaceConnection grpc.ClientConn with interceptor chain]
  │  Interceptor 1 (if encryption enabled):
  │    PayloadCodec.Encode(outbound payloads)
  │      → Cipher.Encrypt → CachingMaterialsManager → KMS
  │  Interceptor 2 (if API key auth):
  │    Strip inbound authorization header
  │    Append temporal-namespace + authorization: Bearer <api_key>
  │
  ▼
Temporal Cloud gRPC endpoint (TLS)
  │
  ▼
[response travels back through interceptor chain]
  │  Interceptor 1:
  │    PayloadCodec.Decode(inbound payloads)
  │      → Cipher.Decrypt → CachingMaterialsManager → KMS
  │
  ▼
Worker receives decrypted response

​

Extension Points

​

Adding a New Authenticator

type MyAuthenticator struct { /* fields */ }

func (m *MyAuthenticator) Type() string { return "my-auth" }
func (m *MyAuthenticator) Init(ctx context.Context, config map[string]interface{}) error { /* ... */ }
func (m *MyAuthenticator) Authenticate(ctx context.Context, credentials interface{}) (*AuthenticationResult, error) { /* ... */ }
func (m *MyAuthenticator) Close() error { /* ... */ }

af.providers["my-auth"] = func(config map[string]interface{}) (Authenticator, error) {
    authenticator := &MyAuthenticator{}
    err := authenticator.Init(ctx, config)
    return authenticator, err
}

authentication:
  type: "my-auth"
  config:
    my-param: "value"

​

Adding a New KMS Provider

type MyKMSProvider struct { /* kmsClient, keyID, etc. */ }

func (m *MyKMSProvider) GetMaterial(ctx context.Context, cryptoCtx CryptoContext) (*Material, error) { /* ... */ }
func (m *MyKMSProvider) DecryptMaterial(ctx context.Context, cryptoCtx CryptoContext, material *Material) (*Material, error) { /* ... */ }

cf.providers["my-kms"] = func(args EncryptionCodecOptions) (converter.PayloadCodec, error) {
    keyID := args.LocalEncryptionConfig.Config["key-id"].(string)
    myProvider := crypto.NewMyKMSProvider(keyID)
    return NewEncryptionCodecWithCaching(
        myProvider,
        args.CodecContext,
        keyID,
        args.MetricsHandler,
        cf.cachingConfig,
    ), nil
}

encryption:
  type: "my-kms"
  config:
    key-id: "my-key-identifier"