composiohq/keyring repository overview

⁠Keyring

Keyring is a credential-holding proxy: the one place where your third-party API credentials exist in plaintext. You store secrets as encrypted envelopes that only keyring's KMS-backed keys can open, and you use them by forwarding API requests through keyring, which decrypts each secret in-flight, injects it into the outbound request, and streams the provider's response back.

Plaintext credentials never leave the proxy except to the provider they belong to. Anything secret coming back — token exchanges, refreshes — is encrypted before it returns to you.

• Envelope encryption — two-tier key hierarchy (KMS-wrapped DEKs, AES-256-GCM payloads) with AWS KMS, GCP Cloud KMS, and HashiCorp Vault Transit adapters. You choose DEK granularity: per org, per account, per secret.
• Request forwarding — secrets referenced as Quill expressions (bearer / basic / HMAC / JWT / SigV4 — composed, not hardcoded), resolved inside the proxy. Request and response bodies stream through unbuffered.
• Deny-by-default policy — per-toolkit origin allowlists, credential-endpoint guards, SSRF protection, and JWT authentication on every call.

Source and issues: https://github.com/ComposioHQ/keyring⁠

⁠Tags

Pin by digest in production. alpha and latest move under you; a digest does not.

Every image carries SLSA provenance and SPDX SBOM attestations (runtime and bundled dependencies), signed and pushed to the registry:

gh attestation verify oci://composiohq/keyring:<tag> --repo ComposioHQ/keyring

⁠Image characteristics

Because there is no shell, anything running a command in the container must exec the node binary directly. Use the exec form, never CMD-SHELL:

["CMD", "/usr/local/bin/node", "/app/healthcheck.mjs"]

docker exec /bin/sh will not work, by design.

⁠Before you deploy

Provision these first. Keyring validates configuration aggressively and will refuse to serve traffic if any of them is wrong.

⁠1. KMS keys — two symmetric, one asymmetric

Keyring needs three distinct keys, and the config schema rejects any overlap between them.

The two symmetric sections must use separate KMS keys and separate adapter ids — enforced at config load, not a convention. Adapter ids must match ^[a-z0-9][a-z0-9_-]*$.

The asymmetric key is what lets you hand keyring a secret without its operator ever seeing it: your client seals to the public key, and only KMS can unseal it.

On AWS:

# Two symmetric CMKs — credential and authorization_gate must be DIFFERENT keys
aws kms create-key --key-usage ENCRYPT_DECRYPT --key-spec SYMMETRIC_DEFAULT
aws kms create-key --key-usage ENCRYPT_DECRYPT --key-spec SYMMETRIC_DEFAULT
# One asymmetric RSA key — secret_transfer
aws kms create-key --key-usage ENCRYPT_DECRYPT --key-spec RSA_3072

RSA_2048, RSA_3072, and RSA_4096 are all accepted. The transfer key is validated on first use: KeyUsage must be ENCRYPT_DECRYPT and the key must advertise RSAES_OAEP_SHA_256, otherwise the JWKS route fails.

⁠IAM: least privilege

Grant the task role exactly this — nothing more:

kms:GenerateDataKey is not required. Keyring generates DEKs locally with a CSPRNG and wraps them with kms:Encrypt; it never calls GenerateDataKey. If you have seen that permission recommended elsewhere, it is stale — do not grant it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:Encrypt", "kms:Decrypt"],
      "Resource": [
        "arn:aws:kms:REGION:ACCOUNT:key/CREDENTIAL_KEY_ID",
        "arn:aws:kms:REGION:ACCOUNT:key/GATE_KEY_ID"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["kms:GetPublicKey", "kms:Decrypt"],
      "Resource": "arn:aws:kms:REGION:ACCOUNT:key/TRANSFER_KEY_ID"
    }
  ]
}

Other backends: GCP Cloud KMS (transfer keys need the full cryptoKeyVersions/N resource name and RSA_DECRYPT_OAEP_{2048,3072,4096}_SHA256) and HashiCorp Vault Transit (transfer key type rsa-2048|3072|4096, decryption enabled).

⁠2. Origin allowlist (optional)

Keyring's allowlist decides which hosts each toolkit's credentials may be sent to. You do not have to configure one. Leave origin_policy unset and the image enforces the manifest compiled into it at build time — a snapshot covering ~1,070 toolkits — so a deployment always has a real allowlist rather than silently skipping the origin, exchange-endpoint, and body-secret guards.

Which source is active is visible at startup on the Loaded encryption services log line: config.origin_policy.source is bundled or remote.

Use the bundled default when the toolkits you call are in the snapshot and you are content to update the allowlist by upgrading the image.

Set origin_policy.manifest_url to enforce your own copy when you need registry changes sooner than your next image upgrade, or when you call a toolkit the snapshot does not list — self-hosted apps and apps configured per connection have no fixed address, so they are absent from it and requests to them are denied.

"origin_policy": { "manifest_url": "https://config.example.com/keyring/origin-manifest.json" }

A remote manifest is fetched over HTTP, cached for 60 seconds, and must use HTTPS in production. The bundled one is read from memory and has neither constraint.

Manifest format:

{
  "toolkits": {
    "example_toolkit": {
      "allowed_origins": ["https://api.example.com", "https://*.example.com"],
      "exchange_endpoints": [
        {
          "url": "https://api.example.com/oauth/token",
          "sensitive_fields": [["access_token"], ["refresh_token"]]
        }
      ]
    }
  }
}

allowed_origins is required per toolkit. exchange_endpoints marks token endpoints, which are then blocked from the general forwarding route and always encrypted on the way back. An optional body_secrets grant is the only way a secret may be resolved inside a forward request body — its absence denies every secret in a forward body.

Note that origin matching is exact on scheme, host, and port; * wildcards apply to host labels only.

⁠3. A JWT issuer

Every /api/v1/* call must present Authorization: Bearer <jwt>. Your issuer must produce tokens that satisfy all of the following:

jti becomes auth.token_id in every log line for that request, so make it unique per token if you want per-request traceability.

When the JWKS endpoint is unreachable, keyring retries 3 times with backoff and then answers 503 with Retry-After: 5 — deliberately not 401, so clients retry instead of treating the token as invalid.

⁠4. An OpenTelemetry collector

Required unless you explicitly opt out. See the next section — this is the single most consequential deployment decision.

⁠Run the collector as a sidecar

Run the collector in the same task/pod and point OTEL_COLLECTOR_URL at http://localhost:4318.

This is a correctness and latency decision, not a preference. With AUDIT_DURABILITY=required (the default), the audit event for a sensitive operation is exported synchronously, in the request path, and the response is withheld until the collector acknowledges it:

• OTLP protobuf POST to <OTEL_COLLECTOR_URL>/v1/logs.
• Each attempt times out at 2s; up to 3 attempts with 100 ms / 200 ms backoff — roughly 6.3s worst case when unreachable.
• 429 and 5xx are retried. Everything else, including redirects, fails immediately.
• On terminal failure the request fails closed with a 500. No sensitive response is returned that was not durably audited.

Pointing OTEL_COLLECTOR_URL at a vendor intake across the internet puts that vendor's latency and availability in front of every sensitive request. A loopback sidecar keeps acknowledgment local and lets the collector batch and retry egress itself.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 512

exporters:
  otlphttp:
    endpoint: https://otlp.your-vendor.example.com
    headers:
      api-key: ${env:VENDOR_API_KEY}

service:
  pipelines: # logs is the one in the request path; traces/metrics are async
    logs: { receivers: [otlp], processors: [batch], exporters: [otlphttp] }
    traces: { receivers: [otlp], processors: [batch], exporters: [otlphttp] }
    metrics: { receivers: [otlp], processors: [batch], exporters: [otlphttp] }

Traces, logs, and metrics also export to <base>/v1/{traces,logs,metrics} on the same base URL.

If you genuinely cannot run a collector, set AUDIT_DURABILITY=best_effort deliberately. Telemetry becomes batched and best-effort, and a sensitive response can be returned whose audit event was never persisted.

⁠Configuration

⁠Environment variables

Invalid env fails every route, including health checks. Runtime env validation is global, so a bad value 500s /healthz too. On this image it is worse than that: the Node entrypoint validates at boot and, on failure, logs the error and never binds the port — the process may not exit non-zero, so your orchestrator sees a container that is up but refusing connections. Treat the absence of the Keyring API listening on ... log line as the failure signal.

⁠ENCRYPTION_CONFIG

All three sections are mandatory: credential, authorization_gate, secret_transfer. dek_cache is optional but you should always set it.

The example below omits origin_policy on purpose: that is the default, and it enforces the bundled manifest. Add it only to point at your own copy — see Origin allowlist⁠ for when that is necessary.

{
  "credential": {
    "active_adapter_id": "aws-credential",
    "active_key_id": "arn:aws:kms:REGION:ACCOUNT:key/CREDENTIAL_KEY_ID",
    "adapters": {
      "aws-credential": {
        "type": "aws",
        "region": "REGION",
        "credential_source": "runtime_environment",
        "allowed_key_ids": ["arn:aws:kms:REGION:ACCOUNT:key/CREDENTIAL_KEY_ID"]
      }
    }
  },
  "authorization_gate": {
    "active_adapter_id": "aws-gate",
    "active_key_id": "arn:aws:kms:REGION:ACCOUNT:key/GATE_KEY_ID",
    "adapters": {
      "aws-gate": {
        "type": "aws",
        "region": "REGION",
        "credential_source": "runtime_environment",
        "allowed_key_ids": ["arn:aws:kms:REGION:ACCOUNT:key/GATE_KEY_ID"]
      }
    }
  },
  "secret_transfer": {
    "active_kid": "transfer-2026-01",
    "adapters": {
      "aws-transfer": {
        "type": "aws",
        "region": "REGION",
        "credential_source": "runtime_environment",
        "keys": {
          "transfer-2026-01": "arn:aws:kms:REGION:ACCOUNT:key/TRANSFER_KEY_ID"
        }
      }
    }
  },
  "dek_cache": { "capacity": 1024, "ttl_seconds": 300 }
}

secret_transfer.keys maps kid → key reference, and active_kid selects which key is currently handed out. To rotate, add the new kid alongside the old one so in-flight sealed secrets stay decryptable, then switch active_kid.

⁠Always enable the DEK cache

dek_cache is opt-in. Omit the key and caching is off entirely — every single operation pays a KMS round trip. Always set it in production:

"dek_cache": { "capacity": 1024, "ttl_seconds": 300 }

If the key is present but a field is omitted, capacity defaults to 256 and ttl_seconds to 600. Size capacity to your working set of distinct DEKs; treat ttl_seconds as the maximum staleness you accept after a key rotation.

Measured on a short-lived serverless runtime it skipped ~96% of KMS unwraps (one kms:Decrypt per environment per TTL window); a hit costs 2–3 ms versus ~200 ms for a KMS-bound unwrap. Long-lived tasks share one cache and do better.

It stores non-extractable key handles in process memory only, must never be externalized (plaintext DEKs do not leave the process), and losing it to task churn costs only a re-unwrap.

⁠Credential sourcing

credential_source: "runtime_environment" resolves AWS credentials from the platform: env vars first, then the container credentials endpoint (AWS_CONTAINER_CREDENTIALS_RELATIVE_URI / _FULL_URI). On ECS this is the task role, delivered by the agent — nothing to configure in the container. Credentials refresh 5 minutes ahead of expiry.

EC2 IMDS and IRSA/web-identity are deliberately unsupported. Resolution happens eagerly at startup, so a task without a usable credential source fails at boot rather than on the first KMS call. The boot log line to look for is aws.credential_source: container_endpoint.

Use credential_source: "static" only outside AWS; it requires inline access_key_id/secret_access_key, which must be absent when using runtime_environment.

⁠Deploying on ECS / Fargate

{
  "family": "keyring",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "1024",
  "memory": "2048",
  "runtimePlatform": { "cpuArchitecture": "ARM64", "operatingSystemFamily": "LINUX" },
  "taskRoleArn": "arn:aws:iam::ACCOUNT:role/keyring-task",
  "executionRoleArn": "arn:aws:iam::ACCOUNT:role/keyring-execution",
  "containerDefinitions": [
    {
      "name": "keyring",
      "image": "composiohq/keyring@sha256:REPLACE_WITH_DIGEST",
      "essential": true,
      "portMappings": [{ "containerPort": 7464, "protocol": "tcp" }],
      "dependsOn": [{ "containerName": "otel-collector", "condition": "START" }],
      "environment": [
        { "name": "APP_ENV", "value": "production" },
        { "name": "HOST", "value": "0.0.0.0" },
        { "name": "PORT", "value": "7464" },
        { "name": "LOG_LEVEL", "value": "info" },
        { "name": "AUDIT_DURABILITY", "value": "required" },
        { "name": "OTEL_COLLECTOR_URL", "value": "http://localhost:4318" },
        { "name": "AUTH_AUDIENCE", "value": "keyring-production" },
        { "name": "AUTH_ISSUER", "value": "https://issuer.example.com" },
        { "name": "AUTH_JWKS_URL", "value": "https://issuer.example.com/.well-known/jwks.json" }
      ],
      "secrets": [
        {
          "name": "ENCRYPTION_CONFIG",
          "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:keyring/encryption-config"
        }
      ],
      "healthCheck": {
        "command": ["CMD", "/usr/local/bin/node", "/app/healthcheck.mjs"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 15
      }
    },
    {
      "name": "otel-collector",
      "image": "otel/opentelemetry-collector-contrib@sha256:REPLACE_WITH_DIGEST",
      "essential": true,
      "portMappings": [{ "containerPort": 4318, "protocol": "tcp" }],
      "secrets": [
        {
          "name": "VENDOR_API_KEY",
          "valueFrom": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:keyring/otel-vendor-key"
        }
      ]
    }
  ]
}

Notes on the above:

• Containers in a task share a network namespace, so http://localhost:4318 reaches the sidecar with no service discovery.
• The collector is essential: true deliberately: with AUDIT_DURABILITY=required, a task whose collector died cannot serve sensitive requests and should be replaced, not left running degraded.
• dependsOn: START avoids a window where keyring accepts traffic before the collector listens. Use HEALTHY if your collector image defines a health check.
• ENCRYPTION_CONFIG goes in secrets, not environment — it names your KMS keys, and task definition revisions are readable by anyone with ecs:DescribeTaskDefinition.
• The execution role needs secretsmanager:GetSecretValue (plus kms:Decrypt on the secret's key). The task role is what carries the KMS permissions above. They are different roles; mixing them up is the most common failure here.
• Keep enableExecuteCommand: false on the service. With it off, ecs:ExecuteCommand is rejected server-side, so there is no interactive path into a container holding plaintext credentials.

⁠Service, load balancer, scaling

• ALB target group on port 7464, health check path /healthz. Keyring is stateless; instances are interchangeable.
• Scale on CPU utilization and ALB request count per target.
• Set deregistration delay and terminationGracePeriodSeconds above your longest expected forwarded response. Forwarded bodies stream, so a large upload or slow provider can outlive a default drain window and get cut off mid-response.
• There is no built-in rate limiting. Apply quotas at the edge (WAF, ALB rules, or an upstream gateway) — nothing inside keyring will shed load for you.

⁠Verify the deployment

Boot succeeded only if you see Keyring API listening on .... Then, in order:

curl -fsS https://keyring.internal.example.com/healthz     # 200, no auth
curl -fsS https://keyring.internal.example.com/transfer-keys   # 200, no auth
curl -fsS -H "Authorization: Bearer $JWT" \
  https://keyring.internal.example.com/metadata

GET /transfer-keys matters more than it looks: transfer keys are validated lazily, not at boot. A wrong key spec, missing kms:GetPublicKey, or a non-OAEP key surfaces as a 500 on this route and nowhere earlier. Always hit it after a config change.

GET /metadata returns version, environment, runtime, and the authenticated issuer / token_id. A 200 proves your JWT issuer, JWKS URL, audience, and this deployment all agree end to end — it is the fastest auth smoke test you have.

⁠API surface

⁠Limits worth knowing before load testing

Outbound requests are SSRF-guarded: https: is required outside local, private/loopback/link-local/CGNAT ranges are blocked (including IPv4-mapped and NAT64-embedded forms), redirects are manual with a 10-hop cap, and authorization / cookie / proxy-authorization are stripped on cross-origin hops.

⁠What to alert on

• Absence of Keyring API listening on ... after a deploy — the process is up but not serving.
• audit.export_failure_reason / audit.export_endpoint warnings — sustained failures mean sensitive requests are failing closed.
• 503 responses with Retry-After — your JWKS endpoint is unreachable, not a client problem.
• 500 on /transfer-keys — transfer key misconfiguration or missing kms:GetPublicKey.

Two things dominate tail latency: the upstream provider's own response time, and audit-export acknowledgment when AUDIT_DURABILITY=required. A healthy loopback collector makes the second negligible; a remote or struggling one makes it the whole story.

Start at 1 vCPU / 2 GB per task and size from your own load test: the numbers depend on payload sizes, cache hit rate, and provider latency, since forwarding holds a connection open for the life of the upstream request.