dsh-allow 0.1.0 → 0.1.2

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 +31 -0
  2. package/README.md +52 -26
  3. package/index.js +160 -111
  4. package/package.json +17 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2
4
+
5
+ - Audit retention is tiered: at most 200 `allowed`/`denied` events are kept,
6
+ while `issued`, `revoked` and `expired` are evicted only after every check
7
+ event under the total 2000-entry cap. `auditStats()` reports cumulative totals
8
+ (counted even after eviction) and what the retained log still holds.
9
+ - `save()` now opens the sibling temp file, writes, `fsync`s and closes it
10
+ before the atomic `rename`, and removes the temp file when persistence fails.
11
+ The existing in-memory rollback of `issue()`/`revoke()` is covered by
12
+ read-only-directory and rename-failure tests.
13
+ - Admin tools are subject-scoped: `allow_list` requires `subject` (no
14
+ fleet-wide enumeration) and `allow_revoke` requires `id` plus a matching
15
+ `subject` (no cross-subject revocation). Both are still opt-in behind
16
+ `exposeAdminTools: true`.
17
+ - `revoke(id, { subject })` accepts an optional owner guard; the service remains
18
+ backward compatible when it is omitted.
19
+ - Tests: 18 cases, including 2100-check retention, the 2000-entry cap, check
20
+ no-write, persistence failure rollback and cross-subject tool refusal.
21
+
22
+ ## 0.1.1
23
+
24
+ - Security: only `allow_check` is registered by default. `allow_issue`,
25
+ `allow_revoke` and `allow_list` require `exposeAdminTools: true` for a
26
+ human-facing client; exposing them to the model allowed an agent to mint its
27
+ own Grant and bypass Act's write gate.
28
+ - `check()` accepts an omitted scope (any active grant) and no longer rewrites
29
+ the state file on every read.
30
+ - Persisted grants with invalid fields (for example a non-numeric `expiresAt`)
31
+ are dropped, and unsupported state versions fail with `E_STATE`.
32
+ - `issue()` and `revoke()` roll back in-memory state when persistence fails.
33
+
3
34
  ## 0.1.0 — 2026-11-20
4
35
 
5
36
  First functional MVP.
package/README.md CHANGED
@@ -2,8 +2,8 @@
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
6
- default, optional atomic JSON state.
5
+ **Status: 0.1.2 MVP.** Host seam `ctx.allow` + a read-only agent tool, in-memory by
6
+ default, optional atomic JSON state with `fsync`.
7
7
 
8
8
  > **控制面不是沙箱;out-of-turn 授权由 Grant 承担。**
9
9
  >
@@ -47,9 +47,10 @@ tools service.
47
47
  |---|---|
48
48
  | `issue({ subject, capability, scope = '*', ttlMs?, approver = 'user', evidence? })` | `Grant` |
49
49
  | `check({ subject, capability, scope })` | `{ allowed, grant?, reason }` |
50
- | `revoke(id)` | updated `Grant` (idempotent for revoked/expired grants) |
50
+ | `revoke(id, { subject }?)` | updated `Grant`; a supplied `subject` must match the owner; idempotent for revoked/expired grants |
51
51
  | `list(filter?)` | `Grant[]`, filter by exact `subject`, `capability`, `status` or `approver` |
52
52
  | `audit(limit = 100)` | newest-first audit events |
53
+ | `auditStats()` | `{ totals, retained, limits }` audit counters |
53
54
 
54
55
  Grant shape (timestamps are Unix milliseconds):
55
56
 
@@ -69,11 +70,25 @@ Grant shape (timestamps are Unix milliseconds):
69
70
  ```
70
71
 
71
72
  `check` returns `reason: 'allowed' | 'no-grant' | 'expired' | 'revoked' |
72
- 'scope-mismatch'`. A successful check updates `usedAt` and writes an `allowed`
73
- audit event. Every denial is audited as `denied`, and elapsed grants are
74
- materialized as `expired` before `check`/`list`/`revoke` answer. Audit events are
75
- `issued`, `allowed`, `denied`, `revoked` and `expired`; the newest 2000 are kept
76
- (newest first from `audit()`).
73
+ 'scope-mismatch'`. A successful check updates `usedAt` and records an `allowed`
74
+ audit event. Every denial is recorded as `denied`, and elapsed grants are
75
+ materialized as `expired` before `check`/`list`/`revoke` answer. Checks answer
76
+ from memory and do not rewrite the state file; only an expiry transition inside
77
+ `sweep()` persists.
78
+
79
+ ### Audit retention
80
+
81
+ Audit events are `issued`, `allowed`, `denied`, `revoked` and `expired`. Security
82
+ events (`issued`, `revoked`, `expired`) outlive routine checks:
83
+
84
+ - At most `MAX_CHECK_AUDIT_ENTRIES` (200) `allowed`/`denied` events are retained;
85
+ a new check evicts the oldest check event.
86
+ - The whole log is capped at `MAX_AUDIT_ENTRIES` (2000). When it is full, the
87
+ oldest `allowed`/`denied` events are evicted first; security events are only
88
+ evicted once no check events are left.
89
+ - `audit(limit)` still returns the newest retained events, and `auditStats()`
90
+ reports cumulative totals (counted even after eviction) beside what is
91
+ retained, so a check flood cannot erase an `issued`/`revoked` trail.
77
92
 
78
93
  ### Scope matching
79
94
 
@@ -97,31 +112,40 @@ Grant scope may be a string or an array; a requested array must be fully covered
97
112
  - Expiry uses the service clock (`Date.now()` by default); a backwards clock is
98
113
  treated as expiry. There is no implicit renewal.
99
114
  - Expected failures throw an `Error` with a stable `code` such as `E_SUBJECT`,
100
- `E_CAPABILITY`, `E_SCOPE`, `E_TTL`, `E_GRANT_NOT_FOUND`, `E_STATE`.
115
+ `E_SUBJECT_MISMATCH`, `E_CAPABILITY`, `E_SCOPE`, `E_TTL`,
116
+ `E_GRANT_NOT_FOUND`, `E_STATE`.
101
117
 
102
118
  ## Agent tools
103
119
 
104
- Plain object `ToolDefinition`s, no `@deepseek-ai/dsh-tools` import:
120
+ Plain object `ToolDefinition`s, no `@deepseek-ai/dsh-tools` import.
105
121
 
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 }`.
122
+ **Default surface: `allow_check` only.** Issuing, revoking or listing every
123
+ subject are human-facing operations. Exposing them to the model lets an agent
124
+ mint its own Grant and bypass Act's write gate, so they stay off unless a
125
+ human-facing client sets `exposeAdminTools: true` in the plugin config.
110
126
 
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.
127
+ - `allow_check` — check a concrete subject/capability/scope (`scope` optional;
128
+ omitted means "any active grant for this capability").
129
+ - `allow_issue` (opt-in) — issue a grant (`subject`, `capability` required).
130
+ - `allow_revoke` (opt-in) — revoke a grant by `id`; `subject` is required and
131
+ must match the grant owner, so one subject cannot revoke another's grant.
132
+ - `allow_list` (opt-in) — list grants for a required `subject` (optional exact
133
+ `capability`, `status` and `approver` filters); there is no fleet-wide listing.
134
+
135
+ This package is a control plane, not a sandbox: it records and answers
136
+ out-of-turn authorization questions and cannot stop same-process code from
137
+ bypassing it. Do not expose the admin tools to untrusted agents.
115
138
 
116
139
  ## Persistence
117
140
 
118
- In-memory by default. Set `config.stateFile` to a JSON path to persist grants and
119
- the audit log across restarts. Writes go to a sibling temporary file and are
120
- promoted with `rename` (atomic on the same filesystem); the file is created with
121
- mode `0600`. A missing file starts empty; unreadable or malformed state fails
122
- closed with `E_STATE` instead of silently authorizing from a damaged ledger. This
123
- is a local MVP store, not a multi-process ledger: do not point two live writers
124
- at the same file.
141
+ In-memory by default. Set `config.stateFile` to a JSON path to persist grants,
142
+ counters and the audit log across restarts. Writes go to a sibling temporary file
143
+ opened with mode `0600`, are `fsync`ed, and are promoted with `rename` (atomic on
144
+ the same filesystem); a failed write removes the temporary file and surfaces
145
+ `E_STATE`, while `issue`/`revoke` roll back their in-memory change. A missing
146
+ file starts empty; unreadable or malformed state fails closed with `E_STATE`
147
+ instead of silently authorizing from a damaged ledger. This is a local MVP store,
148
+ not a multi-process ledger: do not point two live writers at the same file.
125
149
 
126
150
  ## Security model
127
151
 
@@ -143,7 +167,9 @@ node --test
143
167
  ```
144
168
 
145
169
  Covers issue/check, wildcard and array scopes, expiry, revocation, denial,
146
- list/audit, validation, tool registration and `stateFile` round-trips.
170
+ list/audit, validation, tool registration, audit retention under check floods,
171
+ cross-subject tool refusal, persistence-failure rollback and `stateFile`
172
+ round-trips.
147
173
 
148
174
  ## License
149
175
 
package/index.js CHANGED
@@ -8,7 +8,7 @@
8
8
  */
9
9
 
10
10
  import { randomUUID } from 'node:crypto'
11
- import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
11
+ import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs'
12
12
  import { dirname, resolve } from 'node:path'
13
13
 
14
14
  /** Cordis plugin name. */
@@ -21,8 +21,13 @@ export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
21
21
  export const MAX_TTL_MS = 30 * 24 * 60 * 60 * 1000
22
22
  export const MAX_SUBJECT_LENGTH = 256, MAX_CAPABILITY_LENGTH = 256, MAX_SCOPE_LENGTH = 512, MAX_APPROVER_LENGTH = 128
23
23
  export const MAX_AUDIT_ENTRIES = 2000
24
+ /** `allowed`/`denied` are sampled so routine checks cannot flush the security trail. */
25
+ export const MAX_CHECK_AUDIT_ENTRIES = 200
24
26
  const STATE_VERSION = 1
25
27
 
28
+ const CHECK_EVENTS = new Set(['allowed', 'denied'])
29
+ const isCheck = event => CHECK_EVENTS.has(event)
30
+
26
31
  function fail(code, message) {
27
32
  const error = new Error(message)
28
33
  error.code = code
@@ -38,9 +43,7 @@ function text(value, field, code, max) {
38
43
  }
39
44
 
40
45
  function objectInput(value) {
41
- if (!value || typeof value !== 'object' || Array.isArray(value)) {
42
- fail('E_INPUT', 'input must be an object')
43
- }
46
+ if (!value || typeof value !== 'object' || Array.isArray(value)) fail('E_INPUT', 'input must be an object')
44
47
  return value
45
48
  }
46
49
 
@@ -67,9 +70,7 @@ function scopeCovers(pattern, requested) {
67
70
 
68
71
  function resolveTtl(ttlMs) {
69
72
  if (ttlMs === undefined) return DEFAULT_TTL_MS
70
- if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0) {
71
- fail('E_TTL', 'ttlMs must be a positive finite number of milliseconds')
72
- }
73
+ if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0) fail('E_TTL', 'ttlMs must be a positive finite number of milliseconds')
73
74
  if (ttlMs > MAX_TTL_MS) fail('E_TTL', `ttlMs must not exceed ${MAX_TTL_MS} ms (30 days)`)
74
75
  return ttlMs
75
76
  }
@@ -85,6 +86,27 @@ function cloneEvidence(evidence) {
85
86
  }
86
87
  }
87
88
 
89
+ /** Reject persisted grants that cannot be interpreted safely (fail closed). */
90
+ function validGrant(grant) {
91
+ if (!grant || typeof grant !== 'object') return false
92
+ if (![grant.id, grant.subject, grant.capability, grant.approver].every(value => typeof value === 'string' && value !== '')) return false
93
+ if (!['active', 'revoked', 'expired'].includes(grant.status)) return false
94
+ if (!Number.isFinite(grant.createdAt) || (grant.expiresAt !== null && !Number.isFinite(grant.expiresAt))) return false
95
+ return typeof grant.scope === 'string'
96
+ || (Array.isArray(grant.scope) && grant.scope.length > 0 && grant.scope.every(scope => typeof scope === 'string'))
97
+ }
98
+
99
+ /** Persisted counters are advisory; when absent or malformed, derive them from the log. */
100
+ function loadCounts(value, audit) {
101
+ const count = number => (Number.isSafeInteger(number) && number >= 0 ? number : 0)
102
+ if (value && typeof value === 'object' && !Array.isArray(value)) return { allowed: count(value.allowed), denied: count(value.denied), security: count(value.security) }
103
+ return audit.reduce((counts, entry) => {
104
+ if (isCheck(entry?.event)) counts[entry.event] += 1
105
+ else counts.security += 1
106
+ return counts
107
+ }, { allowed: 0, denied: 0, security: 0 })
108
+ }
109
+
88
110
  /**
89
111
  * Durable-enough local state: an in-memory Map by default, or an atomically
90
112
  * written JSON file when `config.stateFile` is set.
@@ -94,13 +116,12 @@ export class GrantStore {
94
116
  this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
95
117
  this.stateFile = null
96
118
  if (config.stateFile !== undefined && config.stateFile !== null) {
97
- if (typeof config.stateFile !== 'string' || !config.stateFile.trim()) {
98
- fail('E_STATE', 'stateFile must be a non-empty path string')
99
- }
119
+ if (typeof config.stateFile !== 'string' || !config.stateFile.trim()) fail('E_STATE', 'stateFile must be a non-empty path string')
100
120
  this.stateFile = resolve(config.stateFile)
101
121
  }
102
122
  this.grants = new Map()
103
123
  this.auditLog = []
124
+ this.counts = { allowed: 0, denied: 0, security: 0 }
104
125
  this.nextSeq = 1
105
126
  if (this.stateFile) this.load()
106
127
  }
@@ -117,37 +138,52 @@ export class GrantStore {
117
138
  if (error && error.code === 'ENOENT') return
118
139
  fail('E_STATE', `cannot read state file ${this.stateFile}: ${error.message}`)
119
140
  }
120
- if (!raw || typeof raw !== 'object' || !Array.isArray(raw.grants) || !Array.isArray(raw.audit)) {
121
- fail('E_STATE', `invalid state file ${this.stateFile}`)
122
- }
123
- 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)
128
- }
141
+ if (!raw || typeof raw !== 'object' || !Array.isArray(raw.grants) || !Array.isArray(raw.audit)) fail('E_STATE', `invalid state file ${this.stateFile}`)
142
+ if (raw.version !== STATE_VERSION) fail('E_STATE', `unsupported state version ${String(raw.version)} in ${this.stateFile}`)
143
+ // Unknown fields are tolerated; records that cannot be evaluated safely are
144
+ // dropped so a corrupted file cannot create a permanent grant.
145
+ for (const grant of raw.grants) if (validGrant(grant)) this.grants.set(grant.id, grant)
129
146
  this.auditLog = raw.audit.slice(-MAX_AUDIT_ENTRIES)
147
+ this.counts = loadCounts(raw.counts, this.auditLog)
148
+ this.trimAudit()
130
149
  this.nextSeq = this.auditLog.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1
131
150
  }
132
151
 
133
152
  save() {
134
153
  if (!this.stateFile) return
135
- mkdirSync(dirname(this.stateFile), { recursive: true })
136
- const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
137
154
  const body = JSON.stringify({
138
- version: STATE_VERSION,
139
- grants: [...this.grants.values()],
140
- audit: this.auditLog,
155
+ version: STATE_VERSION, counts: this.counts, grants: [...this.grants.values()], audit: this.auditLog,
141
156
  }, null, 2) + '\n'
157
+ const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
158
+ let fd
142
159
  try {
143
- writeFileSync(temp, body, { encoding: 'utf8', mode: 0o600 })
160
+ mkdirSync(dirname(this.stateFile), { recursive: true })
161
+ fd = openSync(temp, 'wx', 0o600)
162
+ writeSync(fd, body)
163
+ fsyncSync(fd)
164
+ closeSync(fd)
165
+ fd = undefined
144
166
  renameSync(temp, this.stateFile)
145
167
  } catch (error) {
168
+ if (fd !== undefined) { try { closeSync(fd) } catch {} }
146
169
  try { unlinkSync(temp) } catch {}
147
170
  fail('E_STATE', `cannot write state file ${this.stateFile}: ${error.message}`)
148
171
  }
149
172
  }
150
173
 
174
+ /** Keep the newest check events, then evict check events before security events. */
175
+ trimAudit() {
176
+ let checks = this.auditLog.filter(entry => isCheck(entry?.event)).length
177
+ while (checks > MAX_CHECK_AUDIT_ENTRIES) {
178
+ this.auditLog.splice(this.auditLog.findIndex(entry => isCheck(entry?.event)), 1)
179
+ checks -= 1
180
+ }
181
+ while (this.auditLog.length > MAX_AUDIT_ENTRIES) {
182
+ const at = this.auditLog.findIndex(entry => isCheck(entry?.event))
183
+ this.auditLog.splice(at < 0 ? 0 : at, 1)
184
+ }
185
+ }
186
+
151
187
  record(event, grant, extra = {}) {
152
188
  const entry = { seq: this.nextSeq++, at: this.now(), event }
153
189
  if (grant) {
@@ -157,10 +193,10 @@ export class GrantStore {
157
193
  entry.scope = clone(grant.scope)
158
194
  }
159
195
  Object.assign(entry, extra)
196
+ if (isCheck(event)) this.counts[event] += 1
197
+ else this.counts.security += 1
160
198
  this.auditLog.push(entry)
161
- if (this.auditLog.length > MAX_AUDIT_ENTRIES) {
162
- this.auditLog.splice(0, this.auditLog.length - MAX_AUDIT_ENTRIES)
163
- }
199
+ this.trimAudit()
164
200
  return entry
165
201
  }
166
202
  }
@@ -213,7 +249,12 @@ export class AllowService {
213
249
  if (evidence !== undefined) grant.evidence = evidence
214
250
  this.store.grants.set(grant.id, grant)
215
251
  this.store.record('issued', grant, { approver, expiresAt: grant.expiresAt })
216
- this.store.save()
252
+ try {
253
+ this.store.save()
254
+ } catch (error) {
255
+ this.store.grants.delete(grant.id)
256
+ throw error
257
+ }
217
258
  return clone(grant)
218
259
  }
219
260
 
@@ -221,18 +262,17 @@ export class AllowService {
221
262
  const args = objectInput(input)
222
263
  const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
223
264
  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]
265
+ const requestedScope = args.scope === undefined ? null : normalizeScope(args.scope)
266
+ const requested = requestedScope === null ? null : (Array.isArray(requestedScope) ? requestedScope : [requestedScope])
226
267
  const now = this.sweep()
227
- const candidates = [...this.store.grants.values()]
228
- .filter(grant => grant.subject === subject && grant.capability === capability)
268
+ const candidates = [...this.store.grants.values()].filter(grant => grant.subject === subject && grant.capability === capability)
229
269
  const active = candidates.filter(grant => grant.status === 'active')
230
- const matched = active.find(grant => requested.every(scope => scopeCovers(grant.scope, scope)))
270
+ const matched = active.find(grant => requested === null
271
+ || requested.every(scope => scopeCovers(grant.scope, scope)))
231
272
 
232
273
  if (matched) {
233
274
  matched.usedAt = now
234
275
  this.store.record('allowed', matched)
235
- this.store.save()
236
276
  return { allowed: true, grant: clone(matched), reason: 'allowed' }
237
277
  }
238
278
 
@@ -253,25 +293,40 @@ export class AllowService {
253
293
  this.store.record('denied', null, {
254
294
  subject,
255
295
  capability,
256
- scope: clone(requestedScope),
296
+ scope: requested === null ? '*' : clone(requestedScope),
257
297
  reason,
258
298
  ...(grant ? { grantId: grant.id } : {}),
259
299
  })
260
- this.store.save()
261
300
  return grant
262
301
  ? { allowed: false, grant: clone(grant), reason }
263
302
  : { allowed: false, reason }
264
303
  }
265
304
 
266
- revoke(id) {
305
+ /**
306
+ * Revoke a grant by id. `options.subject` is optional for trusted service
307
+ * callers; when given it must match the grant owner.
308
+ */
309
+ revoke(id, options = {}) {
267
310
  const grantId = text(id, 'grant id', 'E_ID', 128)
268
311
  const grant = this.store.grants.get(grantId)
269
312
  if (!grant) fail('E_GRANT_NOT_FOUND', `unknown grant: ${grantId}`)
313
+ const subject = options?.subject === undefined
314
+ ? null
315
+ : text(options.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
316
+ if (subject !== null && grant.subject !== subject) {
317
+ fail('E_SUBJECT_MISMATCH', 'grant does not belong to this subject')
318
+ }
270
319
  this.sweep()
271
320
  if (grant.status !== 'active') return clone(grant)
321
+ const previous = grant.status
272
322
  grant.status = 'revoked'
273
323
  this.store.record('revoked', grant)
274
- this.store.save()
324
+ try {
325
+ this.store.save()
326
+ } catch (error) {
327
+ grant.status = previous
328
+ throw error
329
+ }
275
330
  return clone(grant)
276
331
  }
277
332
 
@@ -295,6 +350,17 @@ export class AllowService {
295
350
  if (!Number.isInteger(limit) || limit < 1) fail('E_LIMIT', 'limit must be a positive integer')
296
351
  return this.store.auditLog.slice(-limit).reverse().map(entry => clone(entry))
297
352
  }
353
+
354
+ /** Cumulative event totals plus what the retained log still holds. */
355
+ auditStats() {
356
+ const retained = { allowed: 0, denied: 0, security: 0 }
357
+ for (const entry of this.store.auditLog) {
358
+ if (isCheck(entry?.event)) retained[entry.event] += 1
359
+ else retained.security += 1
360
+ }
361
+ return { totals: { ...this.store.counts }, retained: { ...retained, entries: this.store.auditLog.length },
362
+ limits: { entries: MAX_AUDIT_ENTRIES, checkEntries: MAX_CHECK_AUDIT_ENTRIES } }
363
+ }
298
364
  }
299
365
 
300
366
  const OUTPUT = {
@@ -310,90 +376,73 @@ const SCOPE_SCHEMA = {
310
376
  ],
311
377
  }
312
378
 
379
+ function defineTool(name, description, properties, required, execute) {
380
+ return { name, description, parameters: { type: 'object', additionalProperties: false, properties, required }, output: OUTPUT, execute }
381
+ }
382
+
313
383
  /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
314
- export function createTools(service) {
315
- return [
316
- {
317
- name: 'allow_issue',
318
- description: 'Issue a revocable capability grant and return it. Grants expire (default 24h, max 30 days).',
319
- parameters: {
320
- type: 'object',
321
- additionalProperties: false,
322
- properties: {
323
- subject: { type: 'string', description: 'Who receives the grant, e.g. "agent:planner" or "plugin:dsh-act".' },
324
- capability: { type: 'string', description: 'Capability name, e.g. "fs.write" or "tool.invoke".' },
325
- scope: SCOPE_SCHEMA,
326
- ttlMs: { type: 'number', minimum: 1, maximum: MAX_TTL_MS, description: 'Lifetime in milliseconds (default 24h, max 30 days).' },
327
- approver: { type: 'string', description: 'Who approved it (default "user").' },
328
- },
329
- required: ['subject', 'capability'],
330
- },
331
- output: OUTPUT,
332
- async execute(args) {
333
- return service.issue(args)
384
+ export function createTools(service, options = {}) {
385
+ const tools = [
386
+ defineTool('allow_issue',
387
+ 'Issue a revocable capability grant and return it. Grants expire (default 24h, max 30 days).',
388
+ {
389
+ subject: { type: 'string', description: 'Who receives the grant, e.g. "agent:planner" or "plugin:dsh-act".' },
390
+ capability: { type: 'string', description: 'Capability name, e.g. "fs.write" or "tool.invoke".' },
391
+ scope: SCOPE_SCHEMA,
392
+ ttlMs: { type: 'number', minimum: 1, maximum: MAX_TTL_MS, description: 'Lifetime in milliseconds (default 24h, max 30 days).' },
393
+ approver: { type: 'string', description: 'Who approved it (default "user").' },
334
394
  },
335
- },
336
- {
337
- name: 'allow_check',
338
- description: 'Check whether an active grant covers subject + capability + scope. Does not throw when denied.',
339
- parameters: {
340
- type: 'object',
341
- additionalProperties: false,
342
- properties: {
343
- subject: { type: 'string' },
344
- capability: { type: 'string' },
345
- scope: SCOPE_SCHEMA,
346
- },
347
- required: ['subject', 'capability', 'scope'],
395
+ ['subject', 'capability'],
396
+ async args => service.issue(args)),
397
+ defineTool('allow_check',
398
+ 'Check whether an active grant covers subject + capability + scope. Does not throw when denied.',
399
+ {
400
+ subject: { type: 'string' },
401
+ capability: { type: 'string' },
402
+ scope: SCOPE_SCHEMA,
348
403
  },
349
- output: OUTPUT,
350
- async execute(args) {
351
- return service.check(args)
404
+ ['subject', 'capability', 'scope'],
405
+ async args => service.check(args)),
406
+ defineTool('allow_revoke',
407
+ 'Revoke one of the subject\'s grants by id; the subject must own the grant.',
408
+ {
409
+ id: { type: 'string', description: 'Grant id returned by allow_issue.' },
410
+ subject: { type: 'string', description: 'Owner of the grant; must match the stored subject.' },
352
411
  },
353
- },
354
- {
355
- name: 'allow_revoke',
356
- description: 'Revoke a grant by id. Idempotent for grants that are already revoked or expired.',
357
- parameters: {
358
- type: 'object',
359
- additionalProperties: false,
360
- properties: {
361
- id: { type: 'string', description: 'Grant id returned by allow_issue.' },
362
- },
363
- required: ['id'],
412
+ ['id', 'subject'],
413
+ async args => service.revoke(args.id, {
414
+ subject: text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH),
415
+ })),
416
+ defineTool('allow_list',
417
+ 'List one subject\'s grants. Subject is required so the tool cannot enumerate other subjects.',
418
+ {
419
+ subject: { type: 'string', description: 'Exact subject whose grants are returned.' },
420
+ capability: { type: 'string' },
421
+ status: { type: 'string', enum: ['active', 'revoked', 'expired'] },
422
+ approver: { type: 'string' },
364
423
  },
365
- output: OUTPUT,
366
- async execute(args) {
367
- return service.revoke(args.id)
368
- },
369
- },
370
- {
371
- name: 'allow_list',
372
- description: 'List grants, optionally filtered by exact subject, capability, status or approver.',
373
- parameters: {
374
- type: 'object',
375
- additionalProperties: false,
376
- properties: {
377
- subject: { type: 'string' },
378
- capability: { type: 'string' },
379
- status: { type: 'string', enum: ['active', 'revoked', 'expired'] },
380
- approver: { type: 'string' },
381
- },
382
- },
383
- output: OUTPUT,
384
- async execute(args) {
385
- return { grants: service.list(args) }
386
- },
387
- },
424
+ ['subject'],
425
+ async args => ({
426
+ grants: service.list({ ...args, subject: text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH) }),
427
+ })),
388
428
  ]
429
+ // Issuing, revoking and listing every subject are human-facing operations.
430
+ // Exposing them to the model would let an agent mint its own Grant and
431
+ // bypass Act's write gate, so they stay off unless a human-facing client
432
+ // explicitly opts in.
433
+ return options.exposeAdminTools === true
434
+ ? tools
435
+ : tools.filter(tool => tool.name === 'allow_check')
389
436
  }
390
437
 
391
- /** Mount the service at `ctx.allow` and register the four agent tools. */
438
+ /** Mount the service at `ctx.allow`; only the read-only check tool is public. */
392
439
  export function apply(ctx, config = {}) {
393
440
  const service = new AllowService(ctx, config)
394
441
  ctx.provide('allow', service)
395
442
  if (ctx.tools && typeof ctx.tools.register === 'function') {
396
- for (const tool of createTools(service)) ctx.tools.register(tool)
443
+ for (const tool of createTools(service, { exposeAdminTools: config.exposeAdminTools === true })) {
444
+ ctx.tools.register(tool)
445
+ }
397
446
  }
398
447
  return service
399
448
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-allow",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
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,16 +34,30 @@
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,
41
41
  "bundle": {
42
42
  "patch": "./cordis.patch.yml"
43
+ },
44
+ "os": {
45
+ "service": "allow",
46
+ "provides": [
47
+ "allow"
48
+ ],
49
+ "capabilities": [],
50
+ "tools": [
51
+ "allow_check"
52
+ ],
53
+ "ui": null,
54
+ "stability": "experimental",
55
+ "since": "0.1.0"
43
56
  }
44
57
  },
45
58
  "publishConfig": {
46
- "access": "public"
59
+ "access": "public",
60
+ "registry": "https://registry.npmjs.org/"
47
61
  },
48
62
  "scripts": {
49
63
  "test": "node --test"