dsh-act 0.3.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,39 @@
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
+
23
+ ## 0.4.0
24
+
25
+ - Add a bounded `os.result/v1` envelope to `act_list`:
26
+ `{ schema, ok, tool, summary, items, page, truncated, next, error }`.
27
+ `summary` is `"N actions"` (≤200 chars), `page` reports
28
+ `{ limit, offset, returned, total, hasMore }`, and `next` suggests
29
+ `act_invoke` (plus `allow_request` for a write/danger action).
30
+ - Keep the legacy `actions` array byte-for-byte compatible; it still carries
31
+ each action's `id`, `title`, `risk` and optional `description`.
32
+ - Return failures as `{ ok: false, code, error }` without changing the original
33
+ `code`; `error` carries `{ code, message, retryable, remediation, nextTools }`.
34
+ - Ship the zero-dependency helper `lib/result.js`; add envelope tests for
35
+ fields, filtering, `next`, and failure compatibility.
36
+
3
37
  ## 0.3.0
4
38
 
5
39
  - Add four real filesystem actions:
package/README.md CHANGED
@@ -2,13 +2,18 @@
2
2
 
3
3
  > Typed action registry and agent-facing action bus for DeepSeek Harness.
4
4
 
5
- **Status: 0.3.0 — real filesystem actions, previews and undo**
6
-
7
- 0.3.0 turns Act from a demo registry into a usable action bus: the 0.1
8
- `echo` / `now` / `list` actions stay compatible, and four filesystem actions
9
- (`fs.read` / `fs.write` / `fs.list` / `fs.undo`) execute real work behind one
10
- grant, preview and undo pipeline. The action panel and `dsh-act` CLI are still
11
- 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.
12
17
 
13
18
  Act is an **action bus**, not a repository task runner such as `dsh-actions`:
14
19
  plugins register typed `ActionDescriptor`s once, and humans, agents and future
@@ -58,7 +63,8 @@ directory. Every filesystem action is restricted to that tree.
58
63
  - `fs.write` replaces the whole file (`create: false` requires an existing
59
64
  file). It writes a sibling temporary file and renames it into place, so a
60
65
  reader never observes a half-written file. Text over `maxWriteBytes` is
61
- rejected with `E_TOO_LARGE`.
66
+ rejected with `E_TOO_LARGE`. A tainted call also needs the `:tainted` Grant
67
+ (see below).
62
68
  - `fs.list` returns absolute paths. `limit` defaults to 200 and is clamped to
63
69
  1000. `recursive: true` descends into real subdirectories only; symlinks are
64
70
  reported as `symlink` and are never followed.
@@ -120,6 +126,48 @@ capability. Affirmative decisions are `true`, `'allow'`, or an object with
120
126
  `granted` / `allowed` / `allow` / `permitted === true`, or `decision` /
121
127
  `status === 'allow'`.
122
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
+
123
171
  ## Preview
124
172
 
125
173
  A write can be previewed before any grant is requested:
@@ -199,7 +247,7 @@ Results never throw for expected failures:
199
247
  | Success | `{ ok: true, actionId, result }` |
200
248
  | Preview | `{ ok: true, actionId, preview }` |
201
249
  | Unknown id | `{ ok: false, code: 'action_not_found', actionId }` |
202
- | Missing grant | `{ ok: false, code: 'grant_required', actionId, capability, hint? }` |
250
+ | Missing grant | `{ ok: false, code: 'grant_required', actionId, capability, tainted?, hint? }` |
203
251
  | Action threw | `{ ok: false, code: 'action_failed', message, reason? }` |
204
252
 
205
253
  Filesystem `reason` codes: `E_INVALID_ARGUMENT` (wrong type, unknown field,
@@ -212,11 +260,17 @@ original `reason`.
212
260
 
213
261
  ## Agent tools
214
262
 
215
- - `act_list` — read-only; optional `query` string; returns `{ actions }` with
216
- `id`, `title`, `risk` and optional `description`.
263
+ - `act_list` — read-only; optional `query` string. Returns the `os.result/v1`
264
+ envelope plus the unchanged `actions` array (each with `id`, `title`, `risk`
265
+ and optional `description`). `summary` is `"N actions"`; `page` reports the
266
+ returned/total count; `next` suggests `act_invoke` and, for a write/danger
267
+ action, `allow_request`. Failures return `{ ok: false, code, error }` while
268
+ keeping the original `code`.
217
269
  - `act_invoke` — `id` required, `args` optional object, `preview` optional
218
- boolean. The effective risk is the target descriptor's risk; `write` /
219
- `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.
220
274
 
221
275
  ## Test
222
276
 
@@ -227,7 +281,10 @@ node --test
227
281
 
228
282
  The suite covers reads, writes, listing, path traversal and symlink escapes,
229
283
  missing grants and hints, previews that do not touch disk, undo (restore,
230
- created-file removal, stale detection), read/write caps and `act_list` risks.
284
+ created-file removal, stale detection), read/write caps, `act_list` risks and
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.
231
288
 
232
289
  ## License
233
290
 
package/index.js CHANGED
@@ -1,11 +1,18 @@
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.
7
+ * 0.4.0 adds an `os.result/v1` envelope to `act_list` (`schema`/`ok`/`items`/
8
+ * `summary`/`page`/`truncated`/`next`/`error`) while keeping `actions` intact.
3
9
  * 0.3.0 adds real filesystem actions (`fs.read` / `fs.write` / `fs.list` /
4
10
  * `fs.undo`) with a workdir allowlist, read caps, atomic writes, previews and
5
11
  * undo tokens. Plain ESM, no runtime dependencies.
6
12
  * @module dsh-act
7
13
  */
8
14
  import { filesystem, fsActions } from './fs-actions.js'
15
+ import { failEnvelope, okEnvelope, pageOf, step } from './lib/result.js'
9
16
 
10
17
  export const name = 'dsh-act'
11
18
  export const inject = ['tools']
@@ -13,6 +20,7 @@ export const inject = ['tools']
13
20
  const ID_PATTERN = /^[a-z][a-z0-9_.-]{1,63}$/
14
21
  const RISKS = ['read', 'write', 'danger']
15
22
  const RISK_RANK = { read: 0, write: 1, danger: 2 }
23
+ const TAINT_SUFFIX = ':tainted'
16
24
  const schema = (properties, required) => ({ type: 'object', additionalProperties: false, properties, ...(required === undefined ? {} : { required }) })
17
25
  const output = {
18
26
  schema: { type: 'object', additionalProperties: true },
@@ -88,6 +96,12 @@ function granted(decision) {
88
96
  || decision.decision === 'allow' || decision.status === 'allow'
89
97
  }
90
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
+
91
105
  /** Structured action failure; `reason` preserves the machine-readable code. */
92
106
  function failure(error) {
93
107
  const result = { code: 'action_failed', ok: false, message: error instanceof Error ? error.message : String(error) }
@@ -169,13 +183,15 @@ export class ActService {
169
183
  }
170
184
 
171
185
  const capability = `act:invoke:${action.id}`
172
- if (action.risk !== 'read' && action.authorize !== false
173
- && !(await this.#authorized(capability, meta))) {
174
- const result = { ok: false, code: 'grant_required', actionId: action.id, capability }
175
- if (typeof this.#allow()?.request === 'function') {
176
- result.hint = `Call allow_request for capability "${capability}" with the target scope, then retry.`
177
- }
178
- 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)
179
195
  }
180
196
 
181
197
  try {
@@ -185,6 +201,16 @@ export class ActService {
185
201
  }
186
202
  }
187
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
+
188
214
  /** Resolve the optional Allow service through `ctx.get('allow')` or `ctx.allow`. */
189
215
  #allow() {
190
216
  const ctx = this.#ctx
@@ -219,7 +245,37 @@ function listTool(service) {
219
245
  parameters: schema({ query: { type: 'string', description: 'Optional id/title/description filter.' } }),
220
246
  output,
221
247
  async execute(args) {
222
- return { actions: service.list(args?.query).map(summarize) }
248
+ try {
249
+ const actions = service.list(args?.query).map(summarize)
250
+ const next = []
251
+ if (actions.length > 0) {
252
+ next.push(step('act_invoke', { id: actions[0].id }, 'Invoke one of the listed actions by id.'))
253
+ }
254
+ const gated = actions.find(action => action.risk !== 'read')
255
+ if (gated !== undefined) {
256
+ next.push(step(
257
+ 'allow_request',
258
+ { capability: `act:invoke:${gated.id}` },
259
+ `Request a Grant before invoking the ${gated.risk} action "${gated.id}".`,
260
+ ))
261
+ }
262
+ if (actions.length === 0) {
263
+ next.push(step('act_list', {}, 'No actions matched; call act_list without a query.'))
264
+ }
265
+ return okEnvelope('act_list', {
266
+ items: actions,
267
+ summary: `${actions.length} actions`,
268
+ page: pageOf({ limit: actions.length, returned: actions.length, total: actions.length }),
269
+ next,
270
+ legacy: { actions },
271
+ })
272
+ } catch (error) {
273
+ return failEnvelope('act_list', error, {
274
+ remediation: 'Retry act_list with no query or with a plain text filter.',
275
+ nextTools: [step('act_list', {}, 'Retry without a filter.')],
276
+ legacy: { actions: [] },
277
+ })
278
+ }
223
279
  },
224
280
  }
225
281
  }
@@ -233,12 +289,15 @@ function invokeTool(service) {
233
289
  name: 'act_invoke',
234
290
  description: 'Invoke a registered Act action by id. '
235
291
  + 'write and danger actions return grant_required until the Allow service grants '
236
- + 'capability "act:invoke:<id>" for the caller. Pass preview:true to preview a '
237
- + '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.',
238
295
  parameters: schema({
239
296
  id: { type: 'string', description: 'Registered action id, e.g. "fs.read".' },
240
297
  args: { type: 'object', additionalProperties: true, description: 'Action arguments.' },
241
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.' },
242
301
  }, ['id']),
243
302
  output,
244
303
  async execute(args, exec) {
@@ -251,6 +310,8 @@ function invokeTool(service) {
251
310
  const subject = exec?.agent?.session?.id ?? exec?.agent?.id
252
311
  if (subject !== undefined) meta.subject = subject
253
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
254
315
  return service.invoke(args.id, args.args, meta)
255
316
  },
256
317
  }
package/lib/result.js ADDED
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Zero-dependency `os.result/v1` envelope helpers for the agent tools.
3
+ * Legacy fields stay exactly as they were; the envelope adds bounded metadata.
4
+ * @module dsh-act/result
5
+ */
6
+
7
+ export const RESULT_SCHEMA = 'os.result/v1'
8
+ export const MAX_SUMMARY = 200
9
+ export const MAX_NEXT = 3
10
+
11
+ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
12
+
13
+ /** Trim and cap a summary at `max` characters, marking the cut with an ellipsis. */
14
+ export function clip(text, max = MAX_SUMMARY) {
15
+ const value = typeof text === 'string' ? text.trim() : ''
16
+ return value.length > max ? `${value.slice(0, max - 1)}…` : value
17
+ }
18
+
19
+ /** One page descriptor; `hasMore` tells the caller whether another page exists. */
20
+ export function pageOf({ limit = 0, offset = 0, returned = 0, total = 0 } = {}) {
21
+ return { limit, offset, returned, total, hasMore: offset + returned < total }
22
+ }
23
+
24
+ /** One suggested next tool call. */
25
+ export function step(tool, args = {}, why = '') {
26
+ return { tool, args: isObject(args) ? args : {}, ...(typeof why === 'string' && why !== '' ? { why } : {}) }
27
+ }
28
+
29
+ function nextList(value) {
30
+ return (Array.isArray(value) ? value : [])
31
+ .filter(item => isObject(item) && typeof item.tool === 'string' && item.tool !== '')
32
+ .slice(0, MAX_NEXT)
33
+ }
34
+
35
+ /** Keep `summary` as a string, or as a legacy object plus `summaryText`. */
36
+ function summaryFields(fields, fallback) {
37
+ if (isObject(fields.summary)) {
38
+ return { summary: fields.summary, summaryText: clip(fields.summaryText ?? fallback) }
39
+ }
40
+ return { summary: clip(fields.summary ?? fallback) }
41
+ }
42
+
43
+ /** Build a successful envelope, merging unchanged legacy fields. */
44
+ export function okEnvelope(tool, fields = {}) {
45
+ const items = Array.isArray(fields.items) ? fields.items : []
46
+ const page = fields.page ?? pageOf({ limit: items.length, returned: items.length, total: items.length })
47
+ return {
48
+ schema: RESULT_SCHEMA,
49
+ ok: true,
50
+ tool,
51
+ ...(isObject(fields.legacy) ? fields.legacy : {}),
52
+ ...summaryFields(fields, `${items.length} item(s)`),
53
+ items,
54
+ page,
55
+ truncated: fields.truncated === true,
56
+ next: nextList(fields.next),
57
+ error: null,
58
+ }
59
+ }
60
+
61
+ /** Build a failure envelope; the original `code` is preserved at both levels. */
62
+ export function failEnvelope(tool, error, fields = {}) {
63
+ const code = typeof error?.code === 'string' && error.code !== '' ? error.code : 'E_INTERNAL'
64
+ const message = clip(error instanceof Error ? error.message : String(error), 240)
65
+ const next = nextList(fields.nextTools)
66
+ return {
67
+ schema: RESULT_SCHEMA,
68
+ ok: false,
69
+ tool,
70
+ ...(isObject(fields.legacy) ? fields.legacy : {}),
71
+ code,
72
+ ...summaryFields(fields, `${tool} failed: ${message}`),
73
+ items: [],
74
+ page: fields.page ?? pageOf({}),
75
+ truncated: false,
76
+ next,
77
+ error: {
78
+ code,
79
+ message,
80
+ retryable: fields.retryable === true,
81
+ remediation: clip(fields.remediation ?? 'Fix the request, then retry once.'),
82
+ nextTools: next,
83
+ },
84
+ }
85
+ }
86
+
87
+ export default { RESULT_SCHEMA, MAX_SUMMARY, MAX_NEXT, clip, pageOf, step, okEnvelope, failEnvelope }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-act",
3
- "version": "0.3.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",
@@ -10,6 +10,7 @@
10
10
  },
11
11
  "files": [
12
12
  "index.js",
13
+ "lib",
13
14
  "fs-actions.js",
14
15
  "cordis.patch.yml",
15
16
  "README.md",