dsh-allow 0.1.0 → 0.1.1

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 (4) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +15 -10
  3. package/index.js +54 -18
  4. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.1
4
+
5
+ - Security: only `allow_check` is registered by default. `allow_issue`,
6
+ `allow_revoke` and `allow_list` require `exposeAdminTools: true` for a
7
+ human-facing client; exposing them to the model allowed an agent to mint its
8
+ own Grant and bypass Act's write gate.
9
+ - `check()` accepts an omitted scope (any active grant) and no longer rewrites
10
+ the state file on every read.
11
+ - Persisted grants with invalid fields (for example a non-numeric `expiresAt`)
12
+ are dropped, and unsupported state versions fail with `E_STATE`.
13
+ - `issue()` and `revoke()` roll back in-memory state when persistence fails.
14
+
3
15
  ## 0.1.0 — 2026-11-20
4
16
 
5
17
  First functional MVP.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Revocable capability grants and an audit-ready permission center for DeepSeek Harness.
4
4
 
5
- **Status: 0.1.0 MVP.** Host seam `ctx.allow` + four agent tools, in-memory by
5
+ **Status: 0.1.1 MVP.** Host seam `ctx.allow` + a read-only agent tool, in-memory by
6
6
  default, optional atomic JSON state.
7
7
 
8
8
  > **控制面不是沙箱;out-of-turn 授权由 Grant 承担。**
@@ -101,17 +101,22 @@ Grant scope may be a string or an array; a requested array must be fully covered
101
101
 
102
102
  ## Agent tools
103
103
 
104
- Plain object `ToolDefinition`s, no `@deepseek-ai/dsh-tools` import:
104
+ Plain object `ToolDefinition`s, no `@deepseek-ai/dsh-tools` import.
105
105
 
106
- - `allow_issue` — issue a grant (`subject`, `capability` required).
107
- - `allow_check` — check a concrete subject/capability/scope.
108
- - `allow_revoke` — revoke by grant id.
109
- - `allow_list` — list grants with optional exact filters; returns `{ grants }`.
106
+ **Default surface: `allow_check` only.** Issuing, revoking or listing every
107
+ subject are human-facing operations. Exposing them to the model lets an agent
108
+ mint its own Grant and bypass Act's write gate, so they stay off unless a
109
+ human-facing client sets `exposeAdminTools: true` in the plugin config.
110
110
 
111
- The bundled issue/revoke tools are an MVP integration seam, not an authentication
112
- boundary. This package cannot tell a human caller from a same-process agent; a
113
- production profile should expose issue/revoke only to human-facing clients and
114
- keep `check`/`list` for agents.
111
+ - `allow_check` — check a concrete subject/capability/scope (`scope` optional;
112
+ omitted means "any active grant for this capability").
113
+ - `allow_issue` (opt-in) — issue a grant (`subject`, `capability` required).
114
+ - `allow_revoke` (opt-in) — revoke by grant id.
115
+ - `allow_list` (opt-in) — list grants with optional exact filters.
116
+
117
+ This package is a control plane, not a sandbox: it records and answers
118
+ out-of-turn authorization questions and cannot stop same-process code from
119
+ bypassing it. Do not expose the admin tools to untrusted agents.
115
120
 
116
121
  ## Persistence
117
122
 
package/index.js CHANGED
@@ -37,8 +37,7 @@ function text(value, field, code, max) {
37
37
  return trimmed
38
38
  }
39
39
 
40
- function objectInput(value) {
41
- if (!value || typeof value !== 'object' || Array.isArray(value)) {
40
+ function objectInput(value) { if (!value || typeof value !== 'object' || Array.isArray(value)) {
42
41
  fail('E_INPUT', 'input must be an object')
43
42
  }
44
43
  return value
@@ -89,6 +88,22 @@ function cloneEvidence(evidence) {
89
88
  * Durable-enough local state: an in-memory Map by default, or an atomically
90
89
  * written JSON file when `config.stateFile` is set.
91
90
  */
91
+ /** Reject persisted grants that cannot be interpreted safely (fail closed). */
92
+ function validGrant(grant) {
93
+ if (!grant || typeof grant !== 'object') return false
94
+ if (typeof grant.id !== 'string' || grant.id === '') return false
95
+ if (typeof grant.subject !== 'string' || grant.subject === '') return false
96
+ if (typeof grant.capability !== 'string' || grant.capability === '') return false
97
+ if (!['active', 'revoked', 'expired'].includes(grant.status)) return false
98
+ if (!Number.isFinite(grant.createdAt)) return false
99
+ if (grant.expiresAt !== null && !Number.isFinite(grant.expiresAt)) return false
100
+ const scopeOk = typeof grant.scope === 'string'
101
+ || (Array.isArray(grant.scope) && grant.scope.length > 0 && grant.scope.every(scope => typeof scope === 'string'))
102
+ if (!scopeOk) return false
103
+ if (typeof grant.approver !== 'string' || grant.approver === '') return false
104
+ return true
105
+ }
106
+
92
107
  export class GrantStore {
93
108
  constructor(config = {}) {
94
109
  this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
@@ -120,11 +135,13 @@ export class GrantStore {
120
135
  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.grants) || !Array.isArray(raw.audit)) {
121
136
  fail('E_STATE', `invalid state file ${this.stateFile}`)
122
137
  }
138
+ if (raw.version !== STATE_VERSION) {
139
+ fail('E_STATE', `unsupported state version ${String(raw.version)} in ${this.stateFile}`)
140
+ }
123
141
  for (const grant of raw.grants) {
124
- if (!grant || typeof grant.id !== 'string' || typeof grant.subject !== 'string' || typeof grant.capability !== 'string') {
125
- fail('E_STATE', `invalid grant record in ${this.stateFile}`)
126
- }
127
- this.grants.set(grant.id, grant)
142
+ // Unknown fields are tolerated; records that cannot be evaluated safely
143
+ // are dropped so a corrupted file cannot create a permanent grant.
144
+ if (validGrant(grant)) this.grants.set(grant.id, grant)
128
145
  }
129
146
  this.auditLog = raw.audit.slice(-MAX_AUDIT_ENTRIES)
130
147
  this.nextSeq = this.auditLog.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1
@@ -213,7 +230,12 @@ export class AllowService {
213
230
  if (evidence !== undefined) grant.evidence = evidence
214
231
  this.store.grants.set(grant.id, grant)
215
232
  this.store.record('issued', grant, { approver, expiresAt: grant.expiresAt })
216
- this.store.save()
233
+ try {
234
+ this.store.save()
235
+ } catch (error) {
236
+ this.store.grants.delete(grant.id)
237
+ throw error
238
+ }
217
239
  return clone(grant)
218
240
  }
219
241
 
@@ -221,18 +243,18 @@ export class AllowService {
221
243
  const args = objectInput(input)
222
244
  const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
223
245
  const capability = text(args.capability, 'capability', 'E_CAPABILITY', MAX_CAPABILITY_LENGTH)
224
- const requestedScope = normalizeScope(args.scope)
225
- const requested = Array.isArray(requestedScope) ? requestedScope : [requestedScope]
246
+ const requestedScope = args.scope === undefined ? null : normalizeScope(args.scope)
247
+ const requested = requestedScope === null ? null : (Array.isArray(requestedScope) ? requestedScope : [requestedScope])
226
248
  const now = this.sweep()
227
249
  const candidates = [...this.store.grants.values()]
228
250
  .filter(grant => grant.subject === subject && grant.capability === capability)
229
251
  const active = candidates.filter(grant => grant.status === 'active')
230
- const matched = active.find(grant => requested.every(scope => scopeCovers(grant.scope, scope)))
252
+ const matched = active.find(grant => requested === null
253
+ || requested.every(scope => scopeCovers(grant.scope, scope)))
231
254
 
232
255
  if (matched) {
233
256
  matched.usedAt = now
234
257
  this.store.record('allowed', matched)
235
- this.store.save()
236
258
  return { allowed: true, grant: clone(matched), reason: 'allowed' }
237
259
  }
238
260
 
@@ -253,11 +275,10 @@ export class AllowService {
253
275
  this.store.record('denied', null, {
254
276
  subject,
255
277
  capability,
256
- scope: clone(requestedScope),
278
+ scope: requested === null ? '*' : clone(requestedScope),
257
279
  reason,
258
280
  ...(grant ? { grantId: grant.id } : {}),
259
281
  })
260
- this.store.save()
261
282
  return grant
262
283
  ? { allowed: false, grant: clone(grant), reason }
263
284
  : { allowed: false, reason }
@@ -269,9 +290,15 @@ export class AllowService {
269
290
  if (!grant) fail('E_GRANT_NOT_FOUND', `unknown grant: ${grantId}`)
270
291
  this.sweep()
271
292
  if (grant.status !== 'active') return clone(grant)
293
+ const previous = grant.status
272
294
  grant.status = 'revoked'
273
295
  this.store.record('revoked', grant)
274
- this.store.save()
296
+ try {
297
+ this.store.save()
298
+ } catch (error) {
299
+ grant.status = previous
300
+ throw error
301
+ }
275
302
  return clone(grant)
276
303
  }
277
304
 
@@ -311,8 +338,8 @@ const SCOPE_SCHEMA = {
311
338
  }
312
339
 
313
340
  /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
314
- export function createTools(service) {
315
- return [
341
+ export function createTools(service, options = {}) {
342
+ const tools = [
316
343
  {
317
344
  name: 'allow_issue',
318
345
  description: 'Issue a revocable capability grant and return it. Grants expire (default 24h, max 30 days).',
@@ -386,14 +413,23 @@ export function createTools(service) {
386
413
  },
387
414
  },
388
415
  ]
416
+ // Issuing, revoking and listing every subject are human-facing operations.
417
+ // Exposing them to the model would let an agent mint its own Grant and
418
+ // bypass Act's write gate, so they stay off unless a human-facing client
419
+ // explicitly opts in.
420
+ return options.exposeAdminTools === true
421
+ ? tools
422
+ : tools.filter(tool => tool.name === 'allow_check')
389
423
  }
390
424
 
391
- /** Mount the service at `ctx.allow` and register the four agent tools. */
425
+ /** Mount the service at `ctx.allow`; only the read-only check tool is public. */
392
426
  export function apply(ctx, config = {}) {
393
427
  const service = new AllowService(ctx, config)
394
428
  ctx.provide('allow', service)
395
429
  if (ctx.tools && typeof ctx.tools.register === 'function') {
396
- for (const tool of createTools(service)) ctx.tools.register(tool)
430
+ for (const tool of createTools(service, { exposeAdminTools: config.exposeAdminTools === true })) {
431
+ ctx.tools.register(tool)
432
+ }
397
433
  }
398
434
  return service
399
435
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-allow",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Revocable capability grants and an audit-ready permission center for DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "engines": {
36
36
  "node": "^22.19.0 || >=24.9.0",
37
- "dsh": ">=0.2.1-rc.2 <0.3.0 || >=0.2.2-0 <0.3.0"
37
+ "dsh": ">=0.2.1-rc.2 <0.3.0-0"
38
38
  },
39
39
  "dsh": {
40
40
  "manifestVersion": 1,
@@ -43,7 +43,8 @@
43
43
  }
44
44
  },
45
45
  "publishConfig": {
46
- "access": "public"
46
+ "access": "public",
47
+ "registry": "https://registry.npmjs.org/"
47
48
  },
48
49
  "scripts": {
49
50
  "test": "node --test"