secretless-ai 0.17.0 → 0.18.0

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 (96) hide show
  1. package/README.md +124 -74
  2. package/dist/broker/atx.d.ts +168 -0
  3. package/dist/broker/atx.d.ts.map +1 -0
  4. package/dist/broker/atx.js +308 -0
  5. package/dist/broker/atx.js.map +1 -0
  6. package/dist/broker/cpi/assertion.d.ts +45 -0
  7. package/dist/broker/cpi/assertion.d.ts.map +1 -0
  8. package/dist/broker/cpi/assertion.js +96 -0
  9. package/dist/broker/cpi/assertion.js.map +1 -0
  10. package/dist/broker/cpi/assume.d.ts +19 -0
  11. package/dist/broker/cpi/assume.d.ts.map +1 -0
  12. package/dist/broker/cpi/assume.js +27 -0
  13. package/dist/broker/cpi/assume.js.map +1 -0
  14. package/dist/broker/cpi/exchange.d.ts +53 -0
  15. package/dist/broker/cpi/exchange.d.ts.map +1 -0
  16. package/dist/broker/cpi/exchange.js +56 -0
  17. package/dist/broker/cpi/exchange.js.map +1 -0
  18. package/dist/broker/cpi/http-transport.d.ts +12 -0
  19. package/dist/broker/cpi/http-transport.d.ts.map +1 -0
  20. package/dist/broker/cpi/http-transport.js +104 -0
  21. package/dist/broker/cpi/http-transport.js.map +1 -0
  22. package/dist/broker/cpi/index.d.ts +14 -0
  23. package/dist/broker/cpi/index.d.ts.map +1 -0
  24. package/dist/broker/cpi/index.js +29 -0
  25. package/dist/broker/cpi/index.js.map +1 -0
  26. package/dist/broker/cpi/okta-adapter.d.ts +27 -0
  27. package/dist/broker/cpi/okta-adapter.d.ts.map +1 -0
  28. package/dist/broker/cpi/okta-adapter.js +32 -0
  29. package/dist/broker/cpi/okta-adapter.js.map +1 -0
  30. package/dist/broker/cpi/registry.d.ts +12 -0
  31. package/dist/broker/cpi/registry.d.ts.map +1 -0
  32. package/dist/broker/cpi/registry.js +22 -0
  33. package/dist/broker/cpi/registry.js.map +1 -0
  34. package/dist/broker/cpi/retrieve.d.ts +21 -0
  35. package/dist/broker/cpi/retrieve.d.ts.map +1 -0
  36. package/dist/broker/cpi/retrieve.js +29 -0
  37. package/dist/broker/cpi/retrieve.js.map +1 -0
  38. package/dist/broker/cpi/types.d.ts +64 -0
  39. package/dist/broker/cpi/types.d.ts.map +1 -0
  40. package/dist/broker/cpi/types.js +19 -0
  41. package/dist/broker/cpi/types.js.map +1 -0
  42. package/dist/broker/grant-policy.d.ts +54 -0
  43. package/dist/broker/grant-policy.d.ts.map +1 -0
  44. package/dist/broker/grant-policy.js +71 -0
  45. package/dist/broker/grant-policy.js.map +1 -0
  46. package/dist/broker/grant-resolver.d.ts +53 -0
  47. package/dist/broker/grant-resolver.d.ts.map +1 -0
  48. package/dist/broker/grant-resolver.js +95 -0
  49. package/dist/broker/grant-resolver.js.map +1 -0
  50. package/dist/broker/index.d.ts +5 -0
  51. package/dist/broker/index.d.ts.map +1 -1
  52. package/dist/broker/index.js +29 -1
  53. package/dist/broker/index.js.map +1 -1
  54. package/dist/broker/server.d.ts +13 -1
  55. package/dist/broker/server.d.ts.map +1 -1
  56. package/dist/broker/server.js +83 -4
  57. package/dist/broker/server.js.map +1 -1
  58. package/dist/broker/types.d.ts +6 -0
  59. package/dist/broker/types.d.ts.map +1 -1
  60. package/dist/broker/worker.d.ts +56 -0
  61. package/dist/broker/worker.d.ts.map +1 -0
  62. package/dist/broker/worker.js +149 -0
  63. package/dist/broker/worker.js.map +1 -0
  64. package/dist/cli.js +28 -3
  65. package/dist/cli.js.map +1 -1
  66. package/dist/commands/core.d.ts +2 -0
  67. package/dist/commands/core.d.ts.map +1 -1
  68. package/dist/commands/core.js +60 -8
  69. package/dist/commands/core.js.map +1 -1
  70. package/dist/commands/diff.d.ts +2 -0
  71. package/dist/commands/diff.d.ts.map +1 -1
  72. package/dist/commands/diff.js +33 -1
  73. package/dist/commands/diff.js.map +1 -1
  74. package/dist/confidence.d.ts +21 -0
  75. package/dist/confidence.d.ts.map +1 -1
  76. package/dist/confidence.js +98 -2
  77. package/dist/confidence.js.map +1 -1
  78. package/dist/grant/index.d.ts +37 -0
  79. package/dist/grant/index.d.ts.map +1 -0
  80. package/dist/grant/index.js +66 -0
  81. package/dist/grant/index.js.map +1 -0
  82. package/dist/index.d.ts +2 -0
  83. package/dist/index.d.ts.map +1 -1
  84. package/dist/index.js +30 -2
  85. package/dist/index.js.map +1 -1
  86. package/dist/init.js +53 -27
  87. package/dist/init.js.map +1 -1
  88. package/dist/scan.d.ts +19 -2
  89. package/dist/scan.d.ts.map +1 -1
  90. package/dist/scan.js +116 -6
  91. package/dist/scan.js.map +1 -1
  92. package/dist/verify.d.ts +7 -0
  93. package/dist/verify.d.ts.map +1 -1
  94. package/dist/verify.js +18 -3
  95. package/dist/verify.js.map +1 -1
  96. package/package.json +3 -2
package/README.md CHANGED
@@ -1,20 +1,25 @@
1
- > **[OpenA2A](https://github.com/opena2a-org/opena2a)**: [CLI](https://github.com/opena2a-org/opena2a) · [HackMyAgent](https://github.com/opena2a-org/hackmyagent) · [Secretless](https://github.com/opena2a-org/secretless-ai) · [AIM](https://github.com/opena2a-org/agent-identity-management) · [Browser Guard](https://github.com/opena2a-org/AI-BrowserGuard) · [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent)
2
1
  # secretless-ai
3
2
 
3
+ [![Status: stable](https://img.shields.io/badge/status-stable-green)](./STATUS.md)
4
+
5
+ > **[OpenA2A](https://github.com/opena2a-org/opena2a)**: [CLI](https://github.com/opena2a-org/opena2a) · [HackMyAgent](https://github.com/opena2a-org/hackmyagent) · [Secretless](https://github.com/opena2a-org/secretless-ai) · [AIM](https://github.com/opena2a-org/agent-identity-management) · [Browser Guard](https://github.com/opena2a-org/AI-BrowserGuard) · [DVAA](https://github.com/opena2a-org/damn-vulnerable-ai-agent)
6
+
7
+ Keep API keys and other secrets invisible to AI coding tools. Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and Aider. Apache 2.0.
8
+
4
9
  [![npm version](https://img.shields.io/npm/v/secretless-ai.svg)](https://www.npmjs.com/package/secretless-ai)
5
- [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
6
- [![Tests](https://img.shields.io/badge/tests-988-brightgreen)](https://github.com/opena2a-org/secretless-ai)
10
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
11
+ [![Tests](https://img.shields.io/badge/tests-988%20passing-brightgreen)](https://github.com/opena2a-org/secretless-ai)
7
12
 
8
- Keep API keys and secrets invisible to AI coding tools. Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and Aider.
13
+ [Website](https://opena2a.org/secretless) · [Demos](https://opena2a.org/demos) · [Discord](https://discord.gg/uRZa3KXgEn)
9
14
 
10
- ## Quick Start
15
+ ## Quick start
11
16
 
12
17
  ```bash
13
18
  npx secretless-ai init
14
19
  ```
15
20
 
16
21
  ```
17
- Secretless v0.17.0
22
+ Secretless v0.17.1
18
23
  Keeping secrets out of AI
19
24
 
20
25
  Configured: Claude Code (1 of 1 detected)
@@ -34,13 +39,52 @@ npx secretless-ai init
34
39
 
35
40
  ![Secretless AI Demo](docs/secretless-ai-demo.gif)
36
41
 
37
- For a full security dashboard covering credentials, shadow AI, config integrity, and more:
42
+ ## Install
43
+
44
+ ### npm
45
+
46
+ ```bash
47
+ npx secretless-ai init # run once, no install
48
+ npm install -g secretless-ai # install globally
49
+ ```
50
+
51
+ Requires Node.js 18 or later.
52
+
53
+ ### Homebrew
54
+
55
+ ```bash
56
+ brew install opena2a-org/tap/secretless-ai
57
+ ```
58
+
59
+ ### From source
60
+
61
+ ```bash
62
+ git clone https://github.com/opena2a-org/secretless-ai.git
63
+ cd secretless-ai
64
+ npm install
65
+ npm run build && npm test
66
+ node dist/cli.js verify
67
+ ```
68
+
69
+ ### Verifying what was installed
70
+
71
+ Every release publishes via npm Trusted Publishing with SLSA v1 provenance. No long-lived `NPM_TOKEN`. GitHub Actions exchanges its OIDC token with npm at publish time.
38
72
 
39
73
  ```bash
40
- npx opena2a-cli review
74
+ npm view secretless-ai dist.attestations --json
75
+ # Expects non-empty result with predicateType "https://slsa.dev/provenance/v1"
41
76
  ```
42
77
 
43
- ## MCP Server Protection
78
+ Secretless never reads or transmits credential values it manages. Backends (OS keychain, 1Password, HashiCorp Vault, GCP Secret Manager, AES-256-GCM encrypted file) decrypt on demand at subprocess spawn time. `secretless-ai verify` runs an integrity check of your local install.
79
+
80
+ ## How it works
81
+
82
+ 1. **Scans** your project for hardcoded credentials in config files and source code. 56 credential patterns from [`@opena2a/credential-patterns@0.1.1`](https://www.npmjs.com/package/@opena2a/credential-patterns), lockstep-asserted, across `.js`, `.ts`, `.py`, `.go`, `.java`, `.rb`, and more. Suppresses fixture-path false positives via `.secretlessignore` defaults (`test/`, `__tests__/`, `examples/`, `e2e/`, `docs/vhs/`, `node_modules/`, etc.).
83
+ 2. **Migrates** them to secure storage: OS keychain, 1Password, HashiCorp Vault, GCP Secret Manager, or AES-256-GCM encrypted file.
84
+ 3. **Blocks** AI tools from reading credential files. 21 file patterns enforced at the AI-tool hook layer.
85
+ 4. **Brokers** access through environment variables. Secrets never enter AI context.
86
+
87
+ ## MCP server protection
44
88
 
45
89
  Every MCP server config has plaintext API keys in JSON files on your machine. The LLM sees them. Secretless encrypts them.
46
90
 
@@ -59,50 +103,43 @@ npx secretless-ai protect-mcp
59
103
  STRIPE_SECRET_KEY (encrypted)
60
104
 
61
105
  3 secret(s) encrypted across 3 server(s).
62
- MCP servers start normally -- no workflow changes needed.
106
+ MCP servers start normally. No workflow changes needed.
63
107
  ```
64
108
 
65
109
  Scans configs across Claude Desktop, Cursor, Claude Code, VS Code, and Windsurf. Secrets move to your configured backend. Non-secret env vars (URLs, regions) stay untouched.
66
110
 
67
111
  ```bash
68
- npx secretless-ai protect-mcp --backend 1password # Store MCP secrets in 1Password
69
- npx secretless-ai mcp-status # Show which servers are protected
70
- npx secretless-ai mcp-unprotect # Restore original configs from backup
112
+ npx secretless-ai protect-mcp --backend 1password # store MCP secrets in 1Password
113
+ npx secretless-ai mcp-status # show which servers are protected
114
+ npx secretless-ai mcp-unprotect # restore original configs from backup
71
115
  ```
72
116
 
73
- ## Triage Helpers
117
+ ## Triage helpers
74
118
 
75
119
  ```bash
76
- npx secretless-ai scan --min-confidence 0.85 # Show only high-confidence findings
77
- npx secretless-ai ignore docs/migration.md # Append a path to .secretlessignore
120
+ npx secretless-ai scan --min-confidence 0.85 # high-confidence findings only
121
+ npx secretless-ai ignore docs/migration.md # append a path to .secretlessignore
78
122
  npx secretless-ai ignore --pattern '*.golden.txt'
79
- npx secretless-ai diff main # Audit secretless-managed file changes vs a git ref
123
+ npx secretless-ai diff main # audit secretless-managed file changes vs a git ref
80
124
  ```
81
125
 
82
- `scan` now renders a `Confidence: high (0.92)` line under every finding. The score combines pattern specificity, value entropy, value length, and path tier. With `--no-ignore`, findings whose path matches the default-ignore list are tagged `(looks like a test fixture)` so users can keep them in view without re-suppressing them.
83
-
84
- ## How It Works
85
-
86
- 1. **Scans** your project for hardcoded credentials in config files *and* source code (56 patterns from `@opena2a/credential-patterns@0.1.1`, lockstep-asserted, across .js, .ts, .py, .go, .java, .rb, and more). Suppresses fixture-path false positives via `.secretlessignore` defaults (`test/`, `__tests__/`, `examples/`, `e2e/`, `docs/vhs/`, `node_modules/` ...)
87
- 2. **Migrates** them to secure storage (OS keychain, 1Password, Vault, GCP Secret Manager)
88
- 3. **Blocks** AI tools from reading credential files (21 file patterns)
89
- 4. **Brokers** access through environment variables -- secrets never enter AI context
126
+ `scan` renders a `Confidence: high (0.92)` line under every finding. The score combines pattern specificity, value entropy, value length, and path tier. With `--no-ignore`, findings whose path matches the default-ignore list are tagged `(looks like a test fixture)` so they stay visible without being re-suppressed.
90
127
 
91
128
  ## Architecture
92
129
 
93
- Secretless has three layers. You can use one, two, or all three each is independent and works against any supported backend.
130
+ Three layers. Use one, two, or all three. Each works against any supported backend.
94
131
 
95
- **Tier 1 In-process SDK.** Credentials resolved in the call stack and zeroized after use. Available in the Python and TypeScript AIM SDKs. Sub-millisecond overhead.
132
+ **Tier 1: In-process SDK.** Credentials resolved in the call stack and zeroized after use. Available in the Python and TypeScript AIM SDKs. Sub-millisecond overhead.
96
133
 
97
- **Tier 2 Vault Exec.** A subprocess primitive that injects a credential into a child process's environment without exposing it to the parent. The agent running under an AI assistant never sees the secret.
134
+ **Tier 2: Vault Exec.** A subprocess primitive that injects a credential into a child process's environment without exposing it to the parent. The agent running under an AI assistant never sees the secret.
98
135
 
99
136
  ```bash
100
137
  npx secretless-ai vault exec github -- curl https://api.github.com/user
101
138
  ```
102
139
 
103
- The child process receives `$GITHUB`. The parent shell, the AI tool's context, and any process listing see nothing. Language-agnostic wraps any command.
140
+ The child process receives `$GITHUB`. The parent shell, the AI tool's context, and any process listing see nothing. Language-agnostic. Wraps any command.
104
141
 
105
- **Tier 3 Broker with identity policy.** A local daemon that mediates credential access across multiple agents. Policy rules allow or deny access by agent ID, credential name, time window, and rate limit. Optional AIM integration adds trust-score and capability constraints.
142
+ **Tier 3: Broker with identity policy.** A local daemon that mediates credential access across multiple agents. Policy rules allow or deny access by agent ID, credential name, time window, and rate limit. Optional AIM integration adds trust-score and capability constraints.
106
143
 
107
144
  ```bash
108
145
  npx secretless-ai broker start
@@ -110,23 +147,12 @@ npx secretless-ai broker start
110
147
 
111
148
  See [Run the Broker](docs/use-cases/run-broker.md) for when to use the daemon and how to configure it.
112
149
 
113
- **AIM is optional.** Tier 1 and Tier 2 work against any of the five [storage backends](#storage-backends) with no AIM involvement. Tier 3 adds identity-bound policy when an AIM server is reachable; it still enforces default-deny locally without one.
150
+ AIM is optional. Tier 1 and Tier 2 work against any of the five [storage backends](#storage-backends) with no AIM involvement. Tier 3 adds identity-bound policy when an AIM server is reachable. Default-deny still enforces locally without one.
114
151
 
115
- ## Use Cases
152
+ ## Supported tools
116
153
 
117
- Step-by-step guides for common workflows: [docs/USE-CASES.md](docs/USE-CASES.md)
118
-
119
- - [Protect My Credentials](docs/use-cases/protect-my-credentials.md) -- Keep API keys out of AI tools (2 min)
120
- - [Secure MCP Configs](docs/use-cases/secure-mcp-configs.md) -- Encrypt MCP server credentials (3 min)
121
- - [Bring Your Own Vault](docs/use-cases/bring-your-own-vault.md) -- Point Secretless at HashiCorp Vault, GCP SM, or 1Password (3 min)
122
- - [Run the Broker](docs/use-cases/run-broker.md) -- Policy-gated credential daemon for multi-agent runtimes (3 min)
123
- - [Team Setup](docs/use-cases/team-setup.md) -- Shared backend, CI/CD, onboarding (5 min)
124
- - [Migrate from .env](docs/use-cases/migrate-from-dotenv.md) -- Move .env files to encrypted storage (3 min)
125
-
126
- ## Supported Tools
127
-
128
- | Tool | Protection Method |
129
- |------|------------------|
154
+ | Tool | Protection method |
155
+ |---|---|
130
156
  | Claude Code | PreToolUse hook (blocks reads before they happen) + deny rules + CLAUDE.md |
131
157
  | Cursor | `.cursorrules` instructions |
132
158
  | GitHub Copilot | `.github/copilot-instructions.md` instructions |
@@ -134,68 +160,92 @@ Step-by-step guides for common workflows: [docs/USE-CASES.md](docs/USE-CASES.md)
134
160
  | Cline | `.clinerules` instructions |
135
161
  | Aider | `.aiderignore` file patterns |
136
162
 
137
- Claude Code gets the strongest protection because it supports [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) -- a shell script runs *before* every file read and blocks access at the tool level.
163
+ Claude Code gets the strongest protection because it supports [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). A shell script runs before every file read and blocks access at the tool level.
138
164
 
139
- ## Storage Backends
165
+ ## Storage backends
140
166
 
141
- | Backend | Storage | Best For |
142
- |---------|---------|----------|
167
+ | Backend | Storage | Best for |
168
+ |---|---|---|
143
169
  | `local` | AES-256-GCM encrypted file | Quick start, single machine |
144
- | `keychain` | macOS Keychain / Linux Secret Service | Native OS integration |
170
+ | `keychain` | macOS Keychain or Linux Secret Service | Native OS integration |
145
171
  | `1password` | 1Password vault | Teams, CI/CD, multi-device |
146
172
  | `vault` | HashiCorp Vault KV v2 | Enterprise, self-hosted |
147
173
  | `gcp-sm` | GCP Secret Manager | GCP-native workloads |
148
174
 
149
175
  ```bash
150
- npx secretless-ai backend set 1password # Switch backend
151
- npx secretless-ai migrate --from local --to 1password # Migrate existing secrets
176
+ npx secretless-ai backend set 1password # switch backend
177
+ npx secretless-ai migrate --from local --to 1password # migrate existing secrets
152
178
  ```
153
179
 
154
- ## NanoMind Integration
180
+ ## NanoMind integration
155
181
 
156
182
  Optional integration with [NanoMind](https://github.com/opena2a-org/nanomind) for enhanced security analysis:
157
183
 
158
184
  ```bash
159
- npm install @nanomind/guard @nanomind/engine # Optional
185
+ npm install @nanomind/guard @nanomind/engine # optional
160
186
  ```
161
187
 
162
- - **MCP injection screening**: `protect-mcp` screens env var values for prompt injection patterns and warns when suspicious content is detected
163
- - **Rich scan explanations**: `scan --explain` generates context-aware security explanations for each finding using NanoMind's local inference engine
188
+ - **MCP injection screening.** `protect-mcp` screens env-var values for prompt-injection patterns and warns when suspicious content is detected.
189
+ - **Rich scan explanations.** `scan --explain` generates context-aware security explanations for each finding using NanoMind's local inference engine.
164
190
 
165
191
  Both features gracefully degrade when NanoMind packages are not installed.
166
192
 
167
193
  ## Using with opena2a-cli
168
194
 
169
- [opena2a-cli](https://github.com/opena2a-org/opena2a) unifies all OpenA2A security tools:
195
+ [`opena2a-cli`](https://github.com/opena2a-org/opena2a) is the unified CLI for the OpenA2A security toolchain. Secretless powers `opena2a secrets`.
170
196
 
171
197
  ```bash
172
198
  npm install -g opena2a-cli
173
- opena2a review # Full security dashboard
174
- opena2a secrets init # Initialize secretless protection
199
+ opena2a review # full security dashboard
200
+ opena2a secrets init # initialize secretless protection
175
201
  ```
176
202
 
177
- ## Development
203
+ ## Telemetry
204
+
205
+ Secretless sends anonymous tier-1 usage data to the OpenA2A Registry: tool name (`secretless-ai`), version, command name (`scan`, `protect`, etc.), success, duration, platform, Node major version, and a stable per-machine `install_id`. No content is collected. No scanned secrets, no file paths, no env-var values, no rule contents, no IPs.
206
+
207
+ - Policy: [opena2a.org/telemetry](https://opena2a.org/telemetry).
208
+ - Status: `secretless-ai telemetry status`.
209
+ - Disable per-invocation: `OPENA2A_TELEMETRY=off secretless-ai <anything>`.
210
+ - Disable persistently: `secretless-ai telemetry off`.
211
+ - Audit every payload: `OPENA2A_TELEMETRY_DEBUG=print secretless-ai <anything>` echoes each event to stderr as JSON.
212
+
213
+ Fire-and-forget with a 2-second timeout. Telemetry never blocks Secretless.
214
+
215
+ ## Use cases
216
+
217
+ | Guide | Time |
218
+ |---|---|
219
+ | [Protect My Credentials](docs/use-cases/protect-my-credentials.md) | 2 min |
220
+ | [Secure MCP Configs](docs/use-cases/secure-mcp-configs.md) | 3 min |
221
+ | [Bring Your Own Vault](docs/use-cases/bring-your-own-vault.md) | 3 min |
222
+ | [Run the Broker](docs/use-cases/run-broker.md) | 3 min |
223
+ | [Team Setup](docs/use-cases/team-setup.md) | 5 min |
224
+ | [Migrate from .env](docs/use-cases/migrate-from-dotenv.md) | 3 min |
225
+
226
+ Full index: [docs/USE-CASES.md](docs/USE-CASES.md).
227
+
228
+ ## Contributing
229
+
230
+ Apache 2.0. PRs from outside the org welcome.
178
231
 
179
232
  ```bash
180
- npm run build && npm test # 809 tests
233
+ git clone https://github.com/opena2a-org/secretless-ai.git
234
+ cd secretless-ai && npm install && npm run build && npm test
181
235
  ```
182
236
 
183
- ## Telemetry
237
+ Security issues: `security@opena2a.org` (coordinated disclosure, response within 24 hours).
184
238
 
185
- Secretless sends anonymous tier-1 usage data to the OpenA2A Registry: tool name (`secretless-ai`), version, command name (`scan`, `protect`, etc.), success, duration, platform, Node major version, and a stable per-machine `install_id`. **No content is collected** — no scanned secrets, no file paths, no env-var values, no rule contents, no IPs.
239
+ ## Links
186
240
 
187
- - **Policy:** [opena2a.org/telemetry](https://opena2a.org/telemetry).
188
- - **Status:** `secretless-ai telemetry status`.
189
- - **Disable per-invocation:** `OPENA2A_TELEMETRY=off secretless-ai <anything>`.
190
- - **Disable persistently:** `secretless-ai telemetry off`.
191
- - **Audit every payload:** `OPENA2A_TELEMETRY_DEBUG=print secretless-ai <anything>` echoes each event to stderr in JSON.
241
+ - [Website](https://opena2a.org/secretless)
242
+ - [Documentation](https://opena2a.org/docs/secretless)
243
+ - [Demos](https://opena2a.org/demos)
244
+ - [OpenA2A CLI](https://github.com/opena2a-org/opena2a)
245
+ - [Credential patterns library](https://www.npmjs.com/package/@opena2a/credential-patterns)
192
246
 
193
- Fire-and-forget with a 2-second timeout — telemetry never blocks Secretless.
247
+ Part of the [OpenA2A](https://opena2a.org) security platform.
194
248
 
195
249
  ## License
196
250
 
197
- Apache-2.0
198
-
199
- ---
200
-
201
- Part of the [OpenA2A](https://opena2a.org) ecosystem. Full reference: [opena2a.org/docs/secretless](https://opena2a.org/docs/secretless)
251
+ Apache-2.0. See [LICENSE](LICENSE).
@@ -0,0 +1,168 @@
1
+ /**
2
+ * ATX (Agent Trust eXtension) verification — the subject-claim check the broker
3
+ * runs before resolving any grant. AAP §6 step 2.
4
+ *
5
+ * The ATX is the signed, portable credential defined by ATP/ATX that states what an
6
+ * agent *is*. AAP does not redefine it; this verifier mirrors the OpenA2A reference
7
+ * verifier (`atx-conformance/verifiers/python/verify.py`, itself a port of
8
+ * `opena2a-registry/pkg/atcverify/verify.go canonicalPayload()`) VERBATIM so a broker
9
+ * accepts exactly the credentials the conformance suite accepts.
10
+ *
11
+ * (ATX is the current name for the credential formerly called ATC; fixtures use the
12
+ * `atcVersion` field. This verifier dual-supports both signing forms.)
13
+ *
14
+ * Scope: Ed25519 is verified fully. ML-DSA-65 presence is recorded but verification is
15
+ * delegated — Node's stdlib has no ML-DSA, exactly as the Python reference verifier
16
+ * skips it. Production wires the post-quantum half + the live trusted-issuer/CRL anchors
17
+ * to AIM's verification path (see AtxVerifier / RegistryAtxVerifier seam below).
18
+ *
19
+ * SECURITY — signature coverage depends on atcVersion:
20
+ * - v1.0 (canonicalPayload): the pipe-delimited string covers identity, issuer,
21
+ * trustLevel, trustScore, contentHash, buildAttestation, and the validity window.
22
+ * It does NOT cover `capabilities`, `scanSummary.oasbLevel`, `issuerChain`, or
23
+ * `jurisdiction`. A holder of any validly-signed v1.0 ATX can edit those without
24
+ * invalidating the signature, so they MUST NOT be trusted for authorization.
25
+ * - v1.1 (canonicalPayloadV11): the signature covers JCS(TBS), which includes
26
+ * `capabilities`, `scanSummary`, `issuerChain`, and `publisher`. Those fields are
27
+ * integrity-protected and safe to authorize on.
28
+ *
29
+ * The verified context exposes `signedCapabilities` (true iff v1.1) so callers can tell
30
+ * the two apart. Phase 3 of the ATX v1.1 rollout adds a `requireSignedCapabilities`
31
+ * grant-policy flag that refuses capability-gated grants whose context has
32
+ * `signedCapabilities === false`. Until then a production verifier still SHOULD source
33
+ * authorization attributes for v1.0 credentials from the issuing Registry/AIM for the
34
+ * verified `agentId` rather than the presented blob.
35
+ */
36
+ /** Legacy schema version: signs the 11-field pipe string (Go quirk, replicated). */
37
+ export declare const SUPPORTED_ATX_VERSION = "1.0";
38
+ /**
39
+ * ATX v1.1: signs JCS(TBS) (RFC 8785) per atx-spec core.md §1.3a.2, bringing
40
+ * capabilities, scanSummary, issuerChain, publisher, and behavioralProfile under
41
+ * the signature. Verified here using the same canonicalizer (erdtman/canonicalize)
42
+ * and the same TBS projection the registry and conformance verifiers use; byte
43
+ * agreement is proven by atx-conformance/jcs-vectors.
44
+ */
45
+ export declare const SUPPORTED_ATX_VERSION_V11 = "1.1";
46
+ /** A signature reference on an ATX. */
47
+ export interface AtxSignature {
48
+ keyId?: string;
49
+ algorithm: 'Ed25519' | 'ML-DSA-65' | string;
50
+ /** base64-encoded signature value. */
51
+ value: string;
52
+ }
53
+ /** The ATX credential (subset used for verification + context derivation). */
54
+ export interface Atx {
55
+ atcVersion?: string;
56
+ agentId: string;
57
+ agentDid: string;
58
+ /** Publisher identity. Unsigned under v1.0; covered by the v1.1 signature. */
59
+ publisher?: string;
60
+ publisherDid?: string;
61
+ version: string;
62
+ contentHash: string;
63
+ buildAttestation?: string;
64
+ issuerDid: string;
65
+ issuerChain?: string[];
66
+ trustLevel: number;
67
+ trustScore: number;
68
+ issuedAt: string;
69
+ expiresAt: string;
70
+ capabilities?: string[];
71
+ /** Observed-behavior summary. Covered by the v1.1 signature. */
72
+ behavioralProfile?: {
73
+ checksum?: string;
74
+ generatedAt?: string;
75
+ observationDays?: number;
76
+ } | null;
77
+ scanSummary?: {
78
+ oasbLevel?: string;
79
+ [k: string]: unknown;
80
+ };
81
+ /** Optional, optional-to-ignore jurisdiction claim (AAP §9). */
82
+ jurisdiction?: string[];
83
+ revoked?: boolean;
84
+ signatures: AtxSignature[];
85
+ }
86
+ /** A public key the verifier trusts, keyed by algorithm. */
87
+ export interface AtxPublicKey {
88
+ algorithm: 'Ed25519' | 'ML-DSA-65' | string;
89
+ /** hex-encoded raw public key (32 bytes for Ed25519). */
90
+ publicKeyHex: string;
91
+ }
92
+ /** Trust anchors the verifier evaluates against (in production: fetched from AIM/Registry). */
93
+ export interface AtxTrustAnchors {
94
+ trustedIssuers: string[];
95
+ publicKeys: AtxPublicKey[];
96
+ /** Cached, federated CRL. Revocation rides entirely on the ATX + CRL (AAP §6). */
97
+ crl?: {
98
+ entries: Array<{
99
+ agentId: string;
100
+ reason?: string;
101
+ }>;
102
+ };
103
+ /** Clock source (injectable for tests). Defaults to wall clock. */
104
+ now?: () => Date;
105
+ }
106
+ export type RejectCategory = 'UNSUPPORTED_VERSION' | 'EXPIRED' | 'REVOKED' | 'UNTRUSTED_ISSUER' | 'SIGNATURE_INVALID' | 'MALFORMED';
107
+ /** Context the broker derives from a *verified* ATX. Contains no backend information. */
108
+ export interface ResolutionContext {
109
+ agentId: string;
110
+ agentDid: string;
111
+ issuerDid: string;
112
+ issuerChain: string[];
113
+ trustLevel: number;
114
+ trustScore: number;
115
+ capabilities: string[];
116
+ oasbLevel?: string;
117
+ jurisdiction?: string[];
118
+ /**
119
+ * True when the credential is v1.1+, i.e. capabilities/scanSummary/issuerChain
120
+ * are covered by the signature and may be trusted for authorization. False for
121
+ * v1.0, where those fields are forgeable by the holder. Phase 3 of the ATX v1.1
122
+ * rollout gates capability-based grants on this.
123
+ */
124
+ signedCapabilities: boolean;
125
+ }
126
+ export interface AtxVerificationResult {
127
+ valid: boolean;
128
+ /** Present when valid: the context the broker resolves against. */
129
+ context?: ResolutionContext;
130
+ /** Present when invalid. */
131
+ rejectCategory?: RejectCategory;
132
+ reason?: string;
133
+ /** Whether an ML-DSA-65 signature was present (and therefore delegated, not skipped silently). */
134
+ mldsaPresent?: boolean;
135
+ }
136
+ /** The verification interface. Lets the broker swap a local verifier for an AIM-backed one. */
137
+ export interface AtxVerifier {
138
+ verify(atx: Atx): AtxVerificationResult;
139
+ }
140
+ /**
141
+ * Local ATX verifier. Cryptographically real (Ed25519) and interoperable with the
142
+ * conformance fixtures; trust anchors are injected. The production counterpart
143
+ * (`RegistryAtxVerifier`, a seam for a later pass) fetches `trustedIssuers`,
144
+ * `publicKeys`, and the `crl` from AIM's verification endpoint and adds ML-DSA-65.
145
+ */
146
+ export declare class LocalAtxVerifier implements AtxVerifier {
147
+ private readonly anchors;
148
+ constructor(anchors: AtxTrustAnchors);
149
+ verify(atx: Atx): AtxVerificationResult;
150
+ }
151
+ /**
152
+ * Mirror of `opena2a-registry/pkg/atcverify/verify.go canonicalPayload()`:
153
+ * fmt.Sprintf("%s|%s|%s|%s|%s|%s|%d|%.6f|%s|%s|%s", ...)
154
+ * with atxVersion hardcoded to "1.0".
155
+ */
156
+ export declare function canonicalPayload(atx: Atx): Buffer;
157
+ /**
158
+ * Project an ATX into the v1.1 TBS and return JCS(TBS) (RFC 8785). Unlike
159
+ * canonicalPayload, this covers capabilities, scanSummary, issuerChain,
160
+ * publisher, and behavioralProfile. The projection (canonical empties,
161
+ * always-full scanSummary, %.6f string trustScore, root-first issuerChain) and
162
+ * the canonicalizer match opena2a-registry/pkg/atcverify and the conformance
163
+ * verifiers exactly; byte agreement is pinned by atx-conformance/jcs-vectors.
164
+ */
165
+ export declare function canonicalPayloadV11(atx: Atx): Buffer;
166
+ /** Normalize an RFC 3339 timestamp to UTC "YYYY-MM-DDTHH:MM:SSZ" (Go time.RFC3339 for UTC). */
167
+ export declare function normalizeRfc3339(s: string): string;
168
+ //# sourceMappingURL=atx.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"atx.d.ts","sourceRoot":"","sources":["../../src/broker/atx.ts"],"names":[],"mappings":"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"}