{"id":13542802,"url":"https://github.com/zboralski/codecserver","last_synced_at":"2026-01-15T00:57:32.793Z","repository":{"id":156735063,"uuid":"632132458","full_name":"zboralski/codecserver","owner":"zboralski","description":"Integrating HashiCorp's Vault Transit secrets engine with Temporal, providing seamless encryption and decryption for data in transit.","archived":false,"fork":false,"pushed_at":"2023-04-26T20:58:23.000Z","size":59,"stargazers_count":24,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T12:38:48.749Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zboralski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-04-24T19:24:36.000Z","updated_at":"2025-03-03T19:44:35.000Z","dependencies_parsed_at":"2024-01-16T17:02:38.048Z","dependency_job_id":"7f75d15c-7cb2-47e3-b669-03e7fd18c9b4","html_url":"https://github.com/zboralski/codecserver","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zboralski/codecserver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fcodecserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fcodecserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fcodecserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fcodecserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zboralski","download_url":"https://codeload.github.com/zboralski/codecserver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zboralski%2Fcodecserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28440981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"ssl_error","status_checked_at":"2026-01-15T00:55:20.945Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T11:00:18.066Z","updated_at":"2026-01-15T00:57:32.776Z","avatar_url":"https://github.com/zboralski.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":["Libraries"],"readme":"# Temporal Codec Server\n\nThis repository provides a solution for integrating the Transit Secrets Engine from HashiCorp's Vault with Temporal.\n\nThe Transit Secrets Engine, provided by HashiCorp's Vault, delivers cryptographic services for data in transit. It functions as \"cryptography as a service\" or \"encryption as a service\" and handles tasks such as encryption, signing and verifying data, generating data hashes and HMACs, and supplying random bytes.\n\nThe main purpose of Transit is to encrypt application data while storing encrypted data in a primary data store. This approach eases the encryption/decryption burden on application developers and places it on Vault operators.\n\n## NIST Rotation Guidance\n\nPeriodic rotation of the encryption keys is recommended, even in the absence of compromise. For AES-GCM keys, rotation should occur before approximately 2^32 encryptions have been performed by a key version, following the guidelines of NIST publication 800-38D. It is recommended that operators estimate the encryption rate of a key and use that to determine a frequency of rotation that prevents the guidance limits from being reached. For example, if one determines that the estimated rate is 40 million operations per day, then rotating a key every three months is sufficient.\n\nThe Vault Transit secrets engine enables simple encryption key rotation. Key rotation can be performed manually or automatically through an API endpoint via cron, a CI pipeline, or a Temporal workflow.\n\nVault manages a versioned keyring, allowing the admin to determine the minimum decryption version. When data is encrypted with Vault, the key version used for encryption is added to the beginning of the ciphertext.\n\n## Rotating the key\n\nThe key rotation process in the Transit secrets engine is entirely transparent to the Temporal codec implementation because the ciphertext is prefixed with the key version. This approach ensures seamless operation during key rotation without affecting the codec implementation.\n\nTo rotate the underlying encryption key, generate a new encryption key and add it to the keyring for the specified key:\n\n```bash\nvault write -f transit/keys/default/rotate\n```\n\n## References\n- [Transit Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/transit)\n- [Encryption as a Service: Transit Secrets Engine](https://developer.hashicorp.com/vault/tutorials/encryption-as-a-service/eaas-transit)\n- [codec-server go sample](https://github.com/temporalio/samples-go/tree/main/codec-server)\n- [encryption go sample](https://github.com/temporalio/samples-go/tree/main/encryption)\n\n## Setup\n\n1. Set up a vault development server\n\n```bash\nexport VAULT_ADDR=http://localhost:8200\nexport VAULT_TOKEN=root\nexport VAULT_DEV_ROOT_TOKEN_ID=$VAULT_TOKEN\n\nvault server -dev\n```\n\n### Enable the Transit secrets engine\n\n```bash\nvault secrets enable transit\n```\n\n### Map keys to namespaces\n\n```bash\nvault write -f transit/keys/default\n```\n\n### Test that the encryption is working\n\n```bash\ngo test\nPASS\nok      github.com/zboralski/codecserver        0.045s\n```\n\n### Configuring the Temporal client\n\n```go\nfunc NewClient(options client.Options) (client.Client, error) {\n    vaultClient, err := vault.New(vault.WithEnvironment())\n    if err != nil {\n      return nil, err\n    }\n\n    if options.HostPort == \"\" {\n      options.HostPort = os.Getenv(\"TEMPORAL_GRPC_ENDPOINT\")\n    }\n\n    if options.Logger == nil {\n      options.Logger = zap.NewLogger()\n    }\n\n    options.DataConverter = codecserver.NewEncryptionDataConverter(\n        vaultClient,\n        converter.GetDefaultDataConverter(),\n        codecserver.DataConverterOptions{Compress: true, KeyID: namespace},\n    )\n    options.ContextPropagators = []workflow.ContextPropagator{codecserver.NewContextPropagator()}\n\n    return client.NewClient(options)\n}\n```\n\n### Start the codec server\n\nThe `CORS_ORIGIN` should be set to the Temporal UI URL.\n\nThe `TLS_CERT_FILE` and `TLS_KEY_FILE` environment variables are used to enable Transport Layer Security (TLS) encryption for the codecserver application. TLS is a cryptographic protocol that provides secure communication over the internet.\n\nTo enable TLS, you need to set the `TLS_CERT_FILE` and `TLS_KEY_FILE` environment variables to the paths of the certificate and key files, respectively. The certificate file contains the public key, and the key file contains the private key that are used to establish a secure connection.\n\nAssuming you have the certificate and key files ready, you can start the codecserver application with TLS enabled using the following command:\n\n```bash\nCORS_ORIGIN=https://localhost:8080 TLS_CERT_FILE=/path/to/cert.pem TLS_KEY_FILE=/path/to/key.pem ./codecserver\n```\n\n### Waypoint\n\n```bash\nwaypoint init\nwaypoint up\n```\n\n## Roadmap\n\n- [ ] Test OIDC code path in the codec server: The OIDC code path in the codec server has not yet been tested and is on my to-do list for further examination and implementation.\n- [ ] Create a sample for [temporalio/samples-go](https://github.com/temporalio/samples-go)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). By using the software or documentation in this repository, you agree to the terms of this license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzboralski%2Fcodecserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzboralski%2Fcodecserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzboralski%2Fcodecserver/lists"}