Tier 3 Zero-Knowledge Decryption
Overview
Tier 3 ships two decryption SDKs — both open-source under Apache 2.0, both reading the same envelope format. Pick based on where you decrypt:
| SDK | Where it runs | Use case |
|---|---|---|
| Browser SDK (TypeScript) | EchelonGraph dashboard at app.echelongraph.io | Dashboard rendering, ad-hoc analyst queries |
| Go SDK | Anywhere Go runs | SOC pipelines, SIEM forwarders, server-side decryption proxies, analytics notebooks |
Both authenticate against your KMS (AWS / GCP / Vault) using your own credentials — EchelonGraph never sees the plaintext.
The browser SDK is bundled with the EchelonGraph dashboard, so there is nothing for you to install. If you want to host your own decryption UI, the source is Apache 2.0 and yours to copy.
What the envelope guarantees
Every event carries a per-event Data Encryption Key wrapped under your KMS key, an AES-GCM nonce, and ciphertext with a 16-byte AEAD tag. The additional authenticated data binds each envelope to tenantID|agentID, so a payload will not open under a different tenant or agent identity. If both are empty, no AAD is applied.
KMS providers
| Provider | Customer identity | Status |
|---|---|---|
| Vault Transit | OIDC sign-in via your IdP → Vault returns a token | Shipped (T3.11) |
| AWS KMS | Your IdP → Cognito Identity Pool / AssumeRoleWithWebIdentity → STS temp creds | Shipped (T3.12) |
| GCP Cloud KMS | Google Identity Services / Workload Identity Federation → OAuth access token | Shipped (T3.13) |
The SDK never holds long-lived credentials; rotation stays the responsibility of your own auth context. On GCP, the federated identity's IAM grant must include cloudkms.cryptoKeyVersions.useToDecrypt on the configured key. Custom endpoints are supported on both clouds — AWS FIPS and VPC endpoints, GCP regional and VPC SC perimeter endpoints.
Dependencies and bundle size
Provider implementations load lazily, so you ship only what you use: a Vault-only customer ships ~5 KB gzipped, AWS-only ~7 KB (hand-rolled SigV4, no aws-sdk-js), GCP-only ~3 KB (REST + bearer token, no gRPC or protobuf). Error codes such as kms_auth_failed and aes_gcm_decrypt_failed are stable strings, meant to be matched on rather than parsed out of messages.
Threat model
Protects against: EchelonGraph staff curiosity, EchelonGraph DB compromise, network interception, cross-tenant leak.
Does NOT protect against (by design): customer's KMS compromise, customer's browser session compromise (XSS / malicious extension), EchelonGraph backend code injection that could MITM the customer's KMS calls. Mitigations: HTTPS-only, CSP locked to our origin, SRI on the SDK chunk, customer rotates KEK on suspected compromise.
Licensing and assurance
The browser SDK is license-gated (T3.11+). The Go SDK is unrestricted — open-source, no license check. Both are Apache 2.0 and covered by 119 unit tests across all four providers (Local + Vault + AWS SigV4 + GCP OAuth REST): envelope edge cases, AES-GCM round-trip, KMS auth and credential refresh, retry policies, and error mapping per HTTP status.
Reviewing this with your security team
A call walks through your key hierarchy and KEK rotation, the identity federation path from your IdP to your KMS, and how your own pipelines consume the ciphertext. Talk to us about deployment