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 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.4.0 — result envelopes on `act_list`**
6
-
7
- 0.4.0 keeps every 0.1/0.3 field and adds a bounded `os.result/v1` envelope to
8
- `act_list`: `schema`, `ok`, `items`, `summary`, `page`, `truncated`, `next` and
9
- `error`, with the legacy `actions` array untouched. 0.3.0 turned Act from a
10
- demo registry into a usable action bus: the 0.1
11
- `echo` / `now` / `list` actions stay compatible, and four filesystem actions
12
- (`fs.read` / `fs.write` / `fs.list` / `fs.undo`) execute real work behind one
13
- grant, preview and undo pipeline. The action panel and `dsh-act` CLI are still
14
- planned for a later release.
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. The effective risk is the target descriptor's risk; `write` /
226
- `danger` actions still go through the Allow check above.
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
- if (action.risk !== 'read' && action.authorize !== false
176
- && !(await this.#authorized(capability, meta))) {
177
- const result = { ok: false, code: 'grant_required', actionId: action.id, capability }
178
- if (typeof this.#allow()?.request === 'function') {
179
- result.hint = `Call allow_request for capability "${capability}" with the target scope, then retry.`
180
- }
181
- return result
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. Pass preview:true to preview a '
270
- + 'write without touching disk.',
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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-act",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Typed action registry with filesystem actions, previews and undo for DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "main": "index.js",