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.
- package/README.md +124 -74
- package/dist/broker/atx.d.ts +168 -0
- package/dist/broker/atx.d.ts.map +1 -0
- package/dist/broker/atx.js +308 -0
- package/dist/broker/atx.js.map +1 -0
- package/dist/broker/cpi/assertion.d.ts +45 -0
- package/dist/broker/cpi/assertion.d.ts.map +1 -0
- package/dist/broker/cpi/assertion.js +96 -0
- package/dist/broker/cpi/assertion.js.map +1 -0
- package/dist/broker/cpi/assume.d.ts +19 -0
- package/dist/broker/cpi/assume.d.ts.map +1 -0
- package/dist/broker/cpi/assume.js +27 -0
- package/dist/broker/cpi/assume.js.map +1 -0
- package/dist/broker/cpi/exchange.d.ts +53 -0
- package/dist/broker/cpi/exchange.d.ts.map +1 -0
- package/dist/broker/cpi/exchange.js +56 -0
- package/dist/broker/cpi/exchange.js.map +1 -0
- package/dist/broker/cpi/http-transport.d.ts +12 -0
- package/dist/broker/cpi/http-transport.d.ts.map +1 -0
- package/dist/broker/cpi/http-transport.js +104 -0
- package/dist/broker/cpi/http-transport.js.map +1 -0
- package/dist/broker/cpi/index.d.ts +14 -0
- package/dist/broker/cpi/index.d.ts.map +1 -0
- package/dist/broker/cpi/index.js +29 -0
- package/dist/broker/cpi/index.js.map +1 -0
- package/dist/broker/cpi/okta-adapter.d.ts +27 -0
- package/dist/broker/cpi/okta-adapter.d.ts.map +1 -0
- package/dist/broker/cpi/okta-adapter.js +32 -0
- package/dist/broker/cpi/okta-adapter.js.map +1 -0
- package/dist/broker/cpi/registry.d.ts +12 -0
- package/dist/broker/cpi/registry.d.ts.map +1 -0
- package/dist/broker/cpi/registry.js +22 -0
- package/dist/broker/cpi/registry.js.map +1 -0
- package/dist/broker/cpi/retrieve.d.ts +21 -0
- package/dist/broker/cpi/retrieve.d.ts.map +1 -0
- package/dist/broker/cpi/retrieve.js +29 -0
- package/dist/broker/cpi/retrieve.js.map +1 -0
- package/dist/broker/cpi/types.d.ts +64 -0
- package/dist/broker/cpi/types.d.ts.map +1 -0
- package/dist/broker/cpi/types.js +19 -0
- package/dist/broker/cpi/types.js.map +1 -0
- package/dist/broker/grant-policy.d.ts +54 -0
- package/dist/broker/grant-policy.d.ts.map +1 -0
- package/dist/broker/grant-policy.js +71 -0
- package/dist/broker/grant-policy.js.map +1 -0
- package/dist/broker/grant-resolver.d.ts +53 -0
- package/dist/broker/grant-resolver.d.ts.map +1 -0
- package/dist/broker/grant-resolver.js +95 -0
- package/dist/broker/grant-resolver.js.map +1 -0
- package/dist/broker/index.d.ts +5 -0
- package/dist/broker/index.d.ts.map +1 -1
- package/dist/broker/index.js +29 -1
- package/dist/broker/index.js.map +1 -1
- package/dist/broker/server.d.ts +13 -1
- package/dist/broker/server.d.ts.map +1 -1
- package/dist/broker/server.js +83 -4
- package/dist/broker/server.js.map +1 -1
- package/dist/broker/types.d.ts +6 -0
- package/dist/broker/types.d.ts.map +1 -1
- package/dist/broker/worker.d.ts +56 -0
- package/dist/broker/worker.d.ts.map +1 -0
- package/dist/broker/worker.js +149 -0
- package/dist/broker/worker.js.map +1 -0
- package/dist/cli.js +28 -3
- package/dist/cli.js.map +1 -1
- package/dist/commands/core.d.ts +2 -0
- package/dist/commands/core.d.ts.map +1 -1
- package/dist/commands/core.js +60 -8
- package/dist/commands/core.js.map +1 -1
- package/dist/commands/diff.d.ts +2 -0
- package/dist/commands/diff.d.ts.map +1 -1
- package/dist/commands/diff.js +33 -1
- package/dist/commands/diff.js.map +1 -1
- package/dist/confidence.d.ts +21 -0
- package/dist/confidence.d.ts.map +1 -1
- package/dist/confidence.js +98 -2
- package/dist/confidence.js.map +1 -1
- package/dist/grant/index.d.ts +37 -0
- package/dist/grant/index.d.ts.map +1 -0
- package/dist/grant/index.js +66 -0
- package/dist/grant/index.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +30 -2
- package/dist/index.js.map +1 -1
- package/dist/init.js +53 -27
- package/dist/init.js.map +1 -1
- package/dist/scan.d.ts +19 -2
- package/dist/scan.d.ts.map +1 -1
- package/dist/scan.js +116 -6
- package/dist/scan.js.map +1 -1
- package/dist/verify.d.ts +7 -0
- package/dist/verify.d.ts.map +1 -1
- package/dist/verify.js +18 -3
- package/dist/verify.js.map +1 -1
- 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.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
|
[](https://www.npmjs.com/package/secretless-ai)
|
|
5
|
-
[](
|
|
6
|
-
[](https://github.com/opena2a-org/secretless-ai)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://github.com/opena2a-org/secretless-ai)
|
|
7
12
|
|
|
8
|
-
|
|
13
|
+
[Website](https://opena2a.org/secretless) · [Demos](https://opena2a.org/demos) · [Discord](https://discord.gg/uRZa3KXgEn)
|
|
9
14
|
|
|
10
|
-
## Quick
|
|
15
|
+
## Quick start
|
|
11
16
|
|
|
12
17
|
```bash
|
|
13
18
|
npx secretless-ai init
|
|
14
19
|
```
|
|
15
20
|
|
|
16
21
|
```
|
|
17
|
-
Secretless v0.17.
|
|
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
|

|
|
36
41
|
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
69
|
-
npx secretless-ai mcp-status
|
|
70
|
-
npx secretless-ai mcp-unprotect
|
|
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
|
|
117
|
+
## Triage helpers
|
|
74
118
|
|
|
75
119
|
```bash
|
|
76
|
-
npx secretless-ai scan --min-confidence 0.85 #
|
|
77
|
-
npx secretless-ai ignore docs/migration.md #
|
|
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 #
|
|
123
|
+
npx secretless-ai diff main # audit secretless-managed file changes vs a git ref
|
|
80
124
|
```
|
|
81
125
|
|
|
82
|
-
`scan`
|
|
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
|
-
|
|
130
|
+
Three layers. Use one, two, or all three. Each works against any supported backend.
|
|
94
131
|
|
|
95
|
-
**Tier 1
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
##
|
|
152
|
+
## Supported tools
|
|
116
153
|
|
|
117
|
-
|
|
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)
|
|
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
|
|
165
|
+
## Storage backends
|
|
140
166
|
|
|
141
|
-
| Backend | Storage | Best
|
|
142
|
-
|
|
167
|
+
| Backend | Storage | Best for |
|
|
168
|
+
|---|---|---|
|
|
143
169
|
| `local` | AES-256-GCM encrypted file | Quick start, single machine |
|
|
144
|
-
| `keychain` | macOS Keychain
|
|
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
|
|
151
|
-
npx secretless-ai migrate --from local --to 1password #
|
|
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
|
|
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 #
|
|
185
|
+
npm install @nanomind/guard @nanomind/engine # optional
|
|
160
186
|
```
|
|
161
187
|
|
|
162
|
-
- **MCP injection screening
|
|
163
|
-
- **Rich scan explanations
|
|
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)
|
|
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 #
|
|
174
|
-
opena2a secrets init #
|
|
199
|
+
opena2a review # full security dashboard
|
|
200
|
+
opena2a secrets init # initialize secretless protection
|
|
175
201
|
```
|
|
176
202
|
|
|
177
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
237
|
+
Security issues: `security@opena2a.org` (coordinated disclosure, response within 24 hours).
|
|
184
238
|
|
|
185
|
-
|
|
239
|
+
## Links
|
|
186
240
|
|
|
187
|
-
-
|
|
188
|
-
-
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
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
|
-
|
|
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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"}
|