dsh-act 0.4.0 → 0.5.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/CHANGELOG.md +20 -0
- package/README.md +64 -15
- package/index.js +37 -9
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.0
|
|
4
|
+
|
|
5
|
+
- Add a minimal tainted-write gate. When `meta.tainted === true` or
|
|
6
|
+
`meta.taintToken` is a non-empty string, every non-read action that is not
|
|
7
|
+
`authorize: false` needs `act:invoke:<id>:tainted` **after** the normal
|
|
8
|
+
`act:invoke:<id>` Grant. A missing tainted Grant returns `grant_required` with
|
|
9
|
+
that capability, `tainted: true` and an `allow_request` hint; nothing is
|
|
10
|
+
executed.
|
|
11
|
+
- `act_invoke` accepts optional `tainted` and `taintToken` arguments and
|
|
12
|
+
forwards them to `meta`. `meta.tainted` is supplied by the caller/host, never
|
|
13
|
+
inferred from action arguments; `preview` and `read` calls are unchanged.
|
|
14
|
+
- Act does not verify tokens: a token is a taint claim that raises the gate, so
|
|
15
|
+
a forged token can neither authorize nor downgrade a call. An omitted claim
|
|
16
|
+
falls back to the normal single-Grant path.
|
|
17
|
+
- Document the limit: this is a minimal gate, not taint tracking; the durable
|
|
18
|
+
fix is host-produced result metadata.
|
|
19
|
+
- Tests: normal write needs only the base capability; tainted write needs both
|
|
20
|
+
Grants in order; forged and empty tokens; tool forwarding; preview/read
|
|
21
|
+
exemptions.
|
|
22
|
+
|
|
3
23
|
## 0.4.0
|
|
4
24
|
|
|
5
25
|
- Add a bounded `os.result/v1` envelope to `act_list`:
|
package/README.md
CHANGED
|
@@ -2,16 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
> Typed action registry and agent-facing action bus for DeepSeek Harness.
|
|
4
4
|
|
|
5
|
-
**Status: 0.
|
|
6
|
-
|
|
7
|
-
0.
|
|
8
|
-
|
|
9
|
-
`
|
|
10
|
-
|
|
11
|
-
`
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
5
|
+
**Status: 0.5.0 — tainted writes need two Grants.**
|
|
6
|
+
|
|
7
|
+
0.5.0 adds a minimal tainted-write gate: when the caller/host marks an action
|
|
8
|
+
call as tainted (`meta.tainted` or `meta.taintToken`), a `write`/`danger` action
|
|
9
|
+
needs `act:invoke:<id>:tainted` in addition to its normal Grant. 0.4.0 keeps
|
|
10
|
+
every 0.1/0.3 field and adds a bounded `os.result/v1` envelope to `act_list`:
|
|
11
|
+
`schema`, `ok`, `items`, `summary`, `page`, `truncated`, `next` and `error`,
|
|
12
|
+
with the legacy `actions` array untouched. 0.3.0 turned Act from a demo registry
|
|
13
|
+
into a usable action bus: the 0.1 `echo` / `now` / `list` actions stay
|
|
14
|
+
compatible, and four filesystem actions (`fs.read` / `fs.write` / `fs.list` /
|
|
15
|
+
`fs.undo`) execute real work behind one grant, preview and undo pipeline. The
|
|
16
|
+
action panel and `dsh-act` CLI are still planned for a later release.
|
|
15
17
|
|
|
16
18
|
Act is an **action bus**, not a repository task runner such as `dsh-actions`:
|
|
17
19
|
plugins register typed `ActionDescriptor`s once, and humans, agents and future
|
|
@@ -61,7 +63,8 @@ directory. Every filesystem action is restricted to that tree.
|
|
|
61
63
|
- `fs.write` replaces the whole file (`create: false` requires an existing
|
|
62
64
|
file). It writes a sibling temporary file and renames it into place, so a
|
|
63
65
|
reader never observes a half-written file. Text over `maxWriteBytes` is
|
|
64
|
-
rejected with `E_TOO_LARGE`.
|
|
66
|
+
rejected with `E_TOO_LARGE`. A tainted call also needs the `:tainted` Grant
|
|
67
|
+
(see below).
|
|
65
68
|
- `fs.list` returns absolute paths. `limit` defaults to 200 and is clamped to
|
|
66
69
|
1000. `recursive: true` descends into real subdirectories only; symlinks are
|
|
67
70
|
reported as `symlink` and are never followed.
|
|
@@ -123,6 +126,48 @@ capability. Affirmative decisions are `true`, `'allow'`, or an object with
|
|
|
123
126
|
`granted` / `allowed` / `allow` / `permitted === true`, or `decision` /
|
|
124
127
|
`status === 'allow'`.
|
|
125
128
|
|
|
129
|
+
## Tainted writes (0.5.0)
|
|
130
|
+
|
|
131
|
+
A call is **tainted** when the caller or host sets `meta.tainted === true` or
|
|
132
|
+
passes a non-empty `meta.taintToken` (for example the token from `snip_get`).
|
|
133
|
+
Then `invoke()` performs both checks, in this order:
|
|
134
|
+
|
|
135
|
+
```js
|
|
136
|
+
await allow.check({ subject, capability: 'act:invoke:fs.write' })
|
|
137
|
+
await allow.check({ subject, capability: 'act:invoke:fs.write:tainted' })
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The second check applies to every non-read action that is not opted out with
|
|
141
|
+
`authorize: false` (so `fs.write` and custom `write`/`danger` actions, but not
|
|
142
|
+
`fs.undo`, whose single-use token is already the capability). If either check is
|
|
143
|
+
missing or non-affirmative, the call returns `grant_required` with the missing
|
|
144
|
+
`capability`, and the tainted denial also carries `tainted: true` plus an
|
|
145
|
+
`allow_request` hint:
|
|
146
|
+
|
|
147
|
+
```js
|
|
148
|
+
{ ok: false, code: 'grant_required', actionId: 'fs.write',
|
|
149
|
+
capability: 'act:invoke:fs.write:tainted', tainted: true,
|
|
150
|
+
hint: 'Call allow_request for capability "act:invoke:fs.write:tainted" …' }
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The agent tool accepts both claims and forwards them to `meta`:
|
|
154
|
+
|
|
155
|
+
```js
|
|
156
|
+
await act_invoke({ id: 'fs.write', args: { path, text }, tainted: true })
|
|
157
|
+
await act_invoke({ id: 'fs.write', args: { path, text }, taintToken: entry.taintToken })
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`meta.tainted` is supplied by the caller/host, never inferred from the action's
|
|
161
|
+
arguments; Act does not inspect `args.text`. `preview: true` runs before any
|
|
162
|
+
grant check and never touches disk.
|
|
163
|
+
|
|
164
|
+
> **This is a minimal gate, not taint tracking.** Act does not verify
|
|
165
|
+
> `taintToken`: a non-empty token is only a claim that raises the bar, and a
|
|
166
|
+
> forged token can neither authorize nor downgrade the call. A caller that omits
|
|
167
|
+
> `tainted`/`taintToken` gets the normal single-Grant path. The durable fix is
|
|
168
|
+
> host-produced result metadata that the host attaches to every tool result and
|
|
169
|
+
> passes to Act, plus a taint-aware planner — not a per-plugin label.
|
|
170
|
+
|
|
126
171
|
## Preview
|
|
127
172
|
|
|
128
173
|
A write can be previewed before any grant is requested:
|
|
@@ -202,7 +247,7 @@ Results never throw for expected failures:
|
|
|
202
247
|
| Success | `{ ok: true, actionId, result }` |
|
|
203
248
|
| Preview | `{ ok: true, actionId, preview }` |
|
|
204
249
|
| Unknown id | `{ ok: false, code: 'action_not_found', actionId }` |
|
|
205
|
-
| Missing grant | `{ ok: false, code: 'grant_required', actionId, capability, hint? }` |
|
|
250
|
+
| Missing grant | `{ ok: false, code: 'grant_required', actionId, capability, tainted?, hint? }` |
|
|
206
251
|
| Action threw | `{ ok: false, code: 'action_failed', message, reason? }` |
|
|
207
252
|
|
|
208
253
|
Filesystem `reason` codes: `E_INVALID_ARGUMENT` (wrong type, unknown field,
|
|
@@ -222,8 +267,10 @@ original `reason`.
|
|
|
222
267
|
action, `allow_request`. Failures return `{ ok: false, code, error }` while
|
|
223
268
|
keeping the original `code`.
|
|
224
269
|
- `act_invoke` — `id` required, `args` optional object, `preview` optional
|
|
225
|
-
boolean
|
|
226
|
-
|
|
270
|
+
boolean, `tainted` optional boolean, `taintToken` optional string. The
|
|
271
|
+
effective risk is the target descriptor's risk; `write` / `danger` actions
|
|
272
|
+
still go through the Allow checks above, and a tainted call also needs the
|
|
273
|
+
`:tainted` capability.
|
|
227
274
|
|
|
228
275
|
## Test
|
|
229
276
|
|
|
@@ -235,7 +282,9 @@ node --test
|
|
|
235
282
|
The suite covers reads, writes, listing, path traversal and symlink escapes,
|
|
236
283
|
missing grants and hints, previews that do not touch disk, undo (restore,
|
|
237
284
|
created-file removal, stale detection), read/write caps, `act_list` risks and
|
|
238
|
-
the 0.4.0 envelope (summary/page/next, legacy `actions`, failure `error`)
|
|
285
|
+
the 0.4.0 envelope (summary/page/next, legacy `actions`, failure `error`), plus
|
|
286
|
+
the 0.5.0 taint gate: one Grant for a normal write, both Grants for a tainted
|
|
287
|
+
write, forged/empty tokens, tool forwarding and preview/read exemptions.
|
|
239
288
|
|
|
240
289
|
## License
|
|
241
290
|
|
package/index.js
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* dsh-act — typed action registry and agent-facing action bus for DeepSeek Harness.
|
|
3
|
+
* 0.5.0 adds a minimal tainted-write gate: when the caller marks meta.tainted
|
|
4
|
+
* or supplies a taintToken, a write action also needs the
|
|
5
|
+
* `act:invoke:<id>:tainted` capability in addition to its normal Grant. The
|
|
6
|
+
* caller/host supplies the taint flag; Act does not track data flow.
|
|
3
7
|
* 0.4.0 adds an `os.result/v1` envelope to `act_list` (`schema`/`ok`/`items`/
|
|
4
8
|
* `summary`/`page`/`truncated`/`next`/`error`) while keeping `actions` intact.
|
|
5
9
|
* 0.3.0 adds real filesystem actions (`fs.read` / `fs.write` / `fs.list` /
|
|
@@ -16,6 +20,7 @@ export const inject = ['tools']
|
|
|
16
20
|
const ID_PATTERN = /^[a-z][a-z0-9_.-]{1,63}$/
|
|
17
21
|
const RISKS = ['read', 'write', 'danger']
|
|
18
22
|
const RISK_RANK = { read: 0, write: 1, danger: 2 }
|
|
23
|
+
const TAINT_SUFFIX = ':tainted'
|
|
19
24
|
const schema = (properties, required) => ({ type: 'object', additionalProperties: false, properties, ...(required === undefined ? {} : { required }) })
|
|
20
25
|
const output = {
|
|
21
26
|
schema: { type: 'object', additionalProperties: true },
|
|
@@ -91,6 +96,12 @@ function granted(decision) {
|
|
|
91
96
|
|| decision.decision === 'allow' || decision.status === 'allow'
|
|
92
97
|
}
|
|
93
98
|
|
|
99
|
+
/** A caller/host-supplied taint claim. Act never infers it from action args. */
|
|
100
|
+
function isTainted(meta) {
|
|
101
|
+
return meta?.tainted === true
|
|
102
|
+
|| (typeof meta?.taintToken === 'string' && meta.taintToken !== '')
|
|
103
|
+
}
|
|
104
|
+
|
|
94
105
|
/** Structured action failure; `reason` preserves the machine-readable code. */
|
|
95
106
|
function failure(error) {
|
|
96
107
|
const result = { code: 'action_failed', ok: false, message: error instanceof Error ? error.message : String(error) }
|
|
@@ -172,13 +183,15 @@ export class ActService {
|
|
|
172
183
|
}
|
|
173
184
|
|
|
174
185
|
const capability = `act:invoke:${action.id}`
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
186
|
+
const gated = action.risk !== 'read' && action.authorize !== false
|
|
187
|
+
if (gated && !(await this.#authorized(capability, meta))) {
|
|
188
|
+
return this.#grantRequired(action, capability)
|
|
189
|
+
}
|
|
190
|
+
// Minimal taint gate: a caller/host claim raises the bar for writes and
|
|
191
|
+
// danger actions. It never lowers it; Act does not verify the token.
|
|
192
|
+
const taintedCapability = `${capability}${TAINT_SUFFIX}`
|
|
193
|
+
if (gated && isTainted(meta) && !(await this.#authorized(taintedCapability, meta))) {
|
|
194
|
+
return this.#grantRequired(action, taintedCapability, true)
|
|
182
195
|
}
|
|
183
196
|
|
|
184
197
|
try {
|
|
@@ -188,6 +201,16 @@ export class ActService {
|
|
|
188
201
|
}
|
|
189
202
|
}
|
|
190
203
|
|
|
204
|
+
/** Fail-closed grant result; tainted denials always point at allow_request. */
|
|
205
|
+
#grantRequired(action, capability, tainted = false) {
|
|
206
|
+
const result = { ok: false, code: 'grant_required', actionId: action.id, capability }
|
|
207
|
+
if (tainted) result.tainted = true
|
|
208
|
+
if (tainted || typeof this.#allow()?.request === 'function') {
|
|
209
|
+
result.hint = `Call allow_request for capability "${capability}" with the target scope, then retry.`
|
|
210
|
+
}
|
|
211
|
+
return result
|
|
212
|
+
}
|
|
213
|
+
|
|
191
214
|
/** Resolve the optional Allow service through `ctx.get('allow')` or `ctx.allow`. */
|
|
192
215
|
#allow() {
|
|
193
216
|
const ctx = this.#ctx
|
|
@@ -266,12 +289,15 @@ function invokeTool(service) {
|
|
|
266
289
|
name: 'act_invoke',
|
|
267
290
|
description: 'Invoke a registered Act action by id. '
|
|
268
291
|
+ 'write and danger actions return grant_required until the Allow service grants '
|
|
269
|
-
+ 'capability "act:invoke:<id>" for the caller.
|
|
270
|
-
+ 'write
|
|
292
|
+
+ 'capability "act:invoke:<id>" for the caller. If the arguments are tainted '
|
|
293
|
+
+ '(tainted:true or a taintToken from snip_get/seek/trigger), the write also needs '
|
|
294
|
+
+ '"act:invoke:<id>:tainted". Pass preview:true to preview a write without touching disk.',
|
|
271
295
|
parameters: schema({
|
|
272
296
|
id: { type: 'string', description: 'Registered action id, e.g. "fs.read".' },
|
|
273
297
|
args: { type: 'object', additionalProperties: true, description: 'Action arguments.' },
|
|
274
298
|
preview: { type: 'boolean', description: 'Preview without executing (write actions).' },
|
|
299
|
+
tainted: { type: 'boolean', description: 'Set when args came from untrusted external content; requires the extra :tainted Grant.' },
|
|
300
|
+
taintToken: { type: 'string', description: 'Opaque token from snip_get/seek/trigger; treated as taint evidence and requires the extra :tainted Grant.' },
|
|
275
301
|
}, ['id']),
|
|
276
302
|
output,
|
|
277
303
|
async execute(args, exec) {
|
|
@@ -284,6 +310,8 @@ function invokeTool(service) {
|
|
|
284
310
|
const subject = exec?.agent?.session?.id ?? exec?.agent?.id
|
|
285
311
|
if (subject !== undefined) meta.subject = subject
|
|
286
312
|
if (args.preview === true) meta.preview = true
|
|
313
|
+
if (args.tainted === true) meta.tainted = true
|
|
314
|
+
if (typeof args.taintToken === 'string' && args.taintToken !== '') meta.taintToken = args.taintToken
|
|
287
315
|
return service.invoke(args.id, args.args, meta)
|
|
288
316
|
},
|
|
289
317
|
}
|