@clef-sh/agent 0.1.10 → 0.1.11-beta.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +118 -34
  2. package/dist/agent.cjs +193 -143
  3. package/dist/agent.cjs.map +4 -4
  4. package/dist/initial-fetch.d.ts +12 -0
  5. package/dist/initial-fetch.d.ts.map +1 -0
  6. package/dist/initial-fetch.js +46 -0
  7. package/dist/initial-fetch.js.map +1 -0
  8. package/dist/main.js +8 -11
  9. package/dist/main.js.map +1 -1
  10. package/dist/server.d.ts.map +1 -1
  11. package/dist/server.js +15 -3
  12. package/dist/server.js.map +1 -1
  13. package/package.json +2 -2
package/README.md CHANGED
@@ -1,36 +1,40 @@
1
1
  # @clef-sh/agent
2
2
 
3
- Sidecar secrets agent for [Clef](https://clef.sh). Wraps `@clef-sh/runtime` in an HTTP API that serves decrypted secrets on `127.0.0.1:7779`. Deploy as a sidecar container, a daemon process, or an AWS Lambda extension.
3
+ Sidecar secrets agent for [Clef](https://clef.sh). Serves decrypted secrets over a localhost HTTP API (`127.0.0.1:7779`). Deploy as a container sidecar, a standalone daemon, or an AWS Lambda extension.
4
4
 
5
- ## Install
5
+ ## Quick Start
6
+
7
+ ### Docker
6
8
 
7
9
  ```bash
8
- npm install @clef-sh/agent
10
+ docker run --rm \
11
+ -e CLEF_AGENT_SOURCE=https://my-bucket.s3.amazonaws.com/clef/api-gateway/production.age.json \
12
+ -e CLEF_AGENT_AGE_KEY=AGE-SECRET-KEY-1... \
13
+ ghcr.io/clef-sh/agent:latest
9
14
  ```
10
15
 
11
- Or use the standalone binary (no Node.js required):
16
+ In KMS envelope mode, no age key is needed — the container's IAM role provides `kms:Decrypt` permission:
12
17
 
13
18
  ```bash
14
- # Download from GitHub releases
15
- curl -Lo clef-agent https://github.com/clef-sh/clef/releases/latest/download/clef-agent-linux-x64
16
- chmod +x clef-agent
19
+ docker run --rm \
20
+ -e CLEF_AGENT_SOURCE=https://my-bucket.s3.amazonaws.com/clef/api-gateway/production.age.json \
21
+ ghcr.io/clef-sh/agent:latest
17
22
  ```
18
23
 
19
- ## Usage
24
+ ### Standalone Binary
20
25
 
21
26
  ```bash
22
- # Point at an HTTP artifact source (S3, CDN, broker URL)
27
+ curl -Lo clef-agent https://github.com/clef-sh/clef/releases/latest/download/clef-agent-linux-x64
28
+ chmod +x clef-agent
23
29
  export CLEF_AGENT_SOURCE=https://my-bucket.s3.amazonaws.com/clef/api-gateway/production.age.json
24
- export CLEF_AGENT_TOKEN=$(openssl rand -hex 32)
25
-
26
- clef-agent
27
- # Listening on http://127.0.0.1:7779
30
+ ./clef-agent
28
31
  ```
29
32
 
30
- Your application reads secrets via HTTP:
33
+ ### npm
31
34
 
32
35
  ```bash
33
- curl -H "Authorization: Bearer $CLEF_AGENT_TOKEN" http://127.0.0.1:7779/v1/secrets
36
+ npm install @clef-sh/agent
37
+ npx clef-agent
34
38
  ```
35
39
 
36
40
  ## API
@@ -43,36 +47,116 @@ curl -H "Authorization: Bearer $CLEF_AGENT_TOKEN" http://127.0.0.1:7779/v1/secre
43
47
  | `GET /v1/secrets/:key` | Bearer | Single secret by key |
44
48
  | `GET /v1/keys` | Bearer | List available key names |
45
49
 
50
+ ```bash
51
+ curl -H "Authorization: Bearer $CLEF_AGENT_TOKEN" http://127.0.0.1:7779/v1/secrets
52
+ ```
53
+
54
+ ## Configuration
55
+
56
+ All configuration is via environment variables. Provide either `SOURCE` (HTTP URL or file path) or the `VCS_*` fields to tell the agent where to fetch the packed artifact.
57
+
58
+ ### Artifact Source
59
+
60
+ | Variable | Default | Description |
61
+ | ---------------------------- | ------- | ---------------------------------------------- |
62
+ | `CLEF_AGENT_SOURCE` | — | HTTP URL or file path to a packed artifact |
63
+ | `CLEF_AGENT_VCS_PROVIDER` | — | VCS provider (`github`, `gitlab`, `bitbucket`) |
64
+ | `CLEF_AGENT_VCS_REPO` | — | Repository (`org/repo`) |
65
+ | `CLEF_AGENT_VCS_TOKEN` | — | VCS authentication token |
66
+ | `CLEF_AGENT_VCS_IDENTITY` | — | Service identity name |
67
+ | `CLEF_AGENT_VCS_ENVIRONMENT` | — | Target environment |
68
+ | `CLEF_AGENT_VCS_REF` | — | Git ref (branch/tag/sha) |
69
+ | `CLEF_AGENT_VCS_API_URL` | — | Custom VCS API base URL |
70
+
71
+ ### Decryption
72
+
73
+ | Variable | Default | Description |
74
+ | ------------------------- | ------- | ---------------------- |
75
+ | `CLEF_AGENT_AGE_KEY` | — | Inline age private key |
76
+ | `CLEF_AGENT_AGE_KEY_FILE` | — | Path to age key file |
77
+
78
+ Not needed for KMS envelope artifacts — the container's IAM role provides `kms:Decrypt` permission on the envelope key.
79
+
80
+ ### Server
81
+
82
+ | Variable | Default | Description |
83
+ | ------------------ | -------------- | ------------------------- |
84
+ | `CLEF_AGENT_PORT` | `7779` | HTTP listen port |
85
+ | `CLEF_AGENT_TOKEN` | auto-generated | Bearer token for API auth |
86
+ | `CLEF_AGENT_ID` | auto-generated | Unique agent instance ID |
87
+
88
+ ### Cache and Reliability
89
+
90
+ | Variable | Default | Description |
91
+ | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
92
+ | `CLEF_AGENT_CACHE_TTL` | `300` | Max seconds to serve without a successful refresh. Set to `0` for JIT mode (decrypt on every request). |
93
+ | `CLEF_AGENT_CACHE_PATH` | — | Disk cache directory for fallback during source outages |
94
+
95
+ ### Security
96
+
97
+ | Variable | Default | Description |
98
+ | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | `CLEF_AGENT_VERIFY_KEY` | — | Public key for artifact signature verification (base64 DER SPKI). When set, unsigned or incorrectly signed artifacts are hard-rejected. |
100
+
101
+ ### Telemetry
102
+
103
+ | Variable | Default | Description |
104
+ | -------------------------- | ------- | ------------------------------- |
105
+ | `CLEF_AGENT_TELEMETRY_URL` | — | OTLP endpoint URL for telemetry |
106
+
107
+ ## Deployment Models
108
+
109
+ ### Container Sidecar (Kubernetes / ECS)
110
+
111
+ Run the agent as a sidecar container in the same pod or task as your application. Your app reads secrets from `http://127.0.0.1:7779/v1/secrets`.
112
+
113
+ ```yaml
114
+ # Kubernetes sidecar example
115
+ containers:
116
+ - name: app
117
+ image: my-app:latest
118
+ env:
119
+ - name: CLEF_AGENT_TOKEN
120
+ value: "my-token"
121
+ - name: clef-agent
122
+ image: ghcr.io/clef-sh/agent:latest
123
+ env:
124
+ - name: CLEF_AGENT_SOURCE
125
+ value: "https://my-bucket.s3.amazonaws.com/clef/api-gateway/production.age.json"
126
+ - name: CLEF_AGENT_TOKEN
127
+ value: "my-token"
128
+ livenessProbe:
129
+ httpGet:
130
+ path: /v1/health
131
+ port: 7779
132
+ readinessProbe:
133
+ httpGet:
134
+ path: /v1/ready
135
+ port: 7779
136
+ ```
137
+
138
+ ### Lambda Extension
139
+
140
+ The SEA binary auto-detects the Lambda environment and runs as an extension. Pre-built layer zips are attached to each [GitHub Release](https://github.com/clef-sh/clef/releases). See the [Lambda Extension docs](https://docs.clef.sh/guide/agent#lambda-extension) for setup instructions.
141
+
142
+ ### Standalone Daemon
143
+
144
+ Run directly as a system service or background process. The agent handles SIGTERM/SIGINT for graceful shutdown.
145
+
46
146
  ## Security
47
147
 
48
148
  - Binds exclusively to `127.0.0.1` — never `0.0.0.0`
49
149
  - Timing-safe bearer token authentication
50
150
  - DNS rebinding protection via Host header validation
51
151
  - `Cache-Control: no-store` on all secrets endpoints
52
- - KMS envelope mode requires no static age key — IAM role is the authentication
53
-
54
- ## Configuration
55
-
56
- | Variable | Required | Default | Description |
57
- | ---------------------------- | -------- | ------- | --------------------------------------------- |
58
- | `CLEF_AGENT_SOURCE` | Yes\* | — | HTTP URL or file path to a packed artifact |
59
- | `CLEF_AGENT_VCS_PROVIDER` | Yes\* | — | VCS provider (github, gitlab, bitbucket) |
60
- | `CLEF_AGENT_VCS_REPO` | Yes\* | — | Repository (org/repo) |
61
- | `CLEF_AGENT_VCS_TOKEN` | Yes\* | — | VCS authentication token |
62
- | `CLEF_AGENT_VCS_IDENTITY` | Yes\* | — | Service identity name |
63
- | `CLEF_AGENT_VCS_ENVIRONMENT` | Yes\* | — | Target environment |
64
- | `CLEF_AGENT_PORT` | No | 7779 | HTTP listen port |
65
- | `CLEF_AGENT_TOKEN` | No | auto | Bearer token (auto-generated if not set) |
66
- | `CLEF_AGENT_AGE_KEY` | No | — | Age private key (not needed for KMS envelope) |
67
- | `CLEF_AGENT_CACHE_TTL` | No | 300 | Max seconds to serve without refresh |
68
-
69
- \_Provide either `SOURCE` or the `VCS\__` fields.
152
+ - No plaintext on disk — decrypted values exist only in process memory
153
+ - KMS envelope mode requires no static key — IAM role is the authentication
70
154
 
71
155
  ## Documentation
72
156
 
73
157
  - [Runtime Agent guide](https://docs.clef.sh/guide/agent)
74
158
  - [Service Identities guide](https://docs.clef.sh/guide/service-identities)
75
- - [Dynamic Secrets guide](https://docs.clef.sh/guide/dynamic-secrets)
159
+ - [CLI pack reference](https://docs.clef.sh/cli/pack)
76
160
 
77
161
  ## License
78
162