dsh-allow 0.1.1 → 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 +19 -0
  2. package/README.md +40 -19
  3. package/index.js +127 -114
  4. package/package.json +14 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
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
+
3
22
  ## 0.1.1
4
23
 
5
24
  - Security: only `allow_check` is registered by default. `allow_issue`,
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.1 MVP.** Host seam `ctx.allow` + a read-only agent tool, 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,7 +112,8 @@ 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
 
@@ -111,8 +127,10 @@ human-facing client sets `exposeAdminTools: true` in the plugin config.
111
127
  - `allow_check` — check a concrete subject/capability/scope (`scope` optional;
112
128
  omitted means "any active grant for this capability").
113
129
  - `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.
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.
116
134
 
117
135
  This package is a control plane, not a sandbox: it records and answers
118
136
  out-of-turn authorization questions and cannot stop same-process code from
@@ -120,13 +138,14 @@ bypassing it. Do not expose the admin tools to untrusted agents.
120
138
 
121
139
  ## Persistence
122
140
 
123
- In-memory by default. Set `config.stateFile` to a JSON path to persist grants and
124
- the audit log across restarts. Writes go to a sibling temporary file and are
125
- promoted with `rename` (atomic on the same filesystem); the file is created with
126
- mode `0600`. A missing file starts empty; unreadable or malformed state fails
127
- closed with `E_STATE` instead of silently authorizing from a damaged ledger. This
128
- is a local MVP store, not a multi-process ledger: do not point two live writers
129
- 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.
130
149
 
131
150
  ## Security model
132
151
 
@@ -148,7 +167,9 @@ node --test
148
167
  ```
149
168
 
150
169
  Covers issue/check, wildcard and array scopes, expiry, revocation, denial,
151
- 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.
152
173
 
153
174
  ## License
154
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
@@ -37,9 +42,8 @@ function text(value, field, code, max) {
37
42
  return trimmed
38
43
  }
39
44
 
40
- function objectInput(value) { if (!value || typeof value !== 'object' || Array.isArray(value)) {
41
- fail('E_INPUT', 'input must be an object')
42
- }
45
+ function objectInput(value) {
46
+ if (!value || typeof value !== 'object' || Array.isArray(value)) fail('E_INPUT', 'input must be an object')
43
47
  return value
44
48
  }
45
49
 
@@ -66,9 +70,7 @@ function scopeCovers(pattern, requested) {
66
70
 
67
71
  function resolveTtl(ttlMs) {
68
72
  if (ttlMs === undefined) return DEFAULT_TTL_MS
69
- if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0) {
70
- fail('E_TTL', 'ttlMs must be a positive finite number of milliseconds')
71
- }
73
+ if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs) || ttlMs <= 0) fail('E_TTL', 'ttlMs must be a positive finite number of milliseconds')
72
74
  if (ttlMs > MAX_TTL_MS) fail('E_TTL', `ttlMs must not exceed ${MAX_TTL_MS} ms (30 days)`)
73
75
  return ttlMs
74
76
  }
@@ -84,38 +86,42 @@ function cloneEvidence(evidence) {
84
86
  }
85
87
  }
86
88
 
87
- /**
88
- * Durable-enough local state: an in-memory Map by default, or an atomically
89
- * written JSON file when `config.stateFile` is set.
90
- */
91
89
  /** Reject persisted grants that cannot be interpreted safely (fail closed). */
92
90
  function validGrant(grant) {
93
91
  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
92
+ if (![grant.id, grant.subject, grant.capability, grant.approver].every(value => typeof value === 'string' && value !== '')) return false
97
93
  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'
94
+ if (!Number.isFinite(grant.createdAt) || (grant.expiresAt !== null && !Number.isFinite(grant.expiresAt))) return false
95
+ return typeof grant.scope === 'string'
101
96
  || (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
97
  }
106
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
+
110
+ /**
111
+ * Durable-enough local state: an in-memory Map by default, or an atomically
112
+ * written JSON file when `config.stateFile` is set.
113
+ */
107
114
  export class GrantStore {
108
115
  constructor(config = {}) {
109
116
  this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
110
117
  this.stateFile = null
111
118
  if (config.stateFile !== undefined && config.stateFile !== null) {
112
- if (typeof config.stateFile !== 'string' || !config.stateFile.trim()) {
113
- fail('E_STATE', 'stateFile must be a non-empty path string')
114
- }
119
+ if (typeof config.stateFile !== 'string' || !config.stateFile.trim()) fail('E_STATE', 'stateFile must be a non-empty path string')
115
120
  this.stateFile = resolve(config.stateFile)
116
121
  }
117
122
  this.grants = new Map()
118
123
  this.auditLog = []
124
+ this.counts = { allowed: 0, denied: 0, security: 0 }
119
125
  this.nextSeq = 1
120
126
  if (this.stateFile) this.load()
121
127
  }
@@ -132,39 +138,52 @@ export class GrantStore {
132
138
  if (error && error.code === 'ENOENT') return
133
139
  fail('E_STATE', `cannot read state file ${this.stateFile}: ${error.message}`)
134
140
  }
135
- if (!raw || typeof raw !== 'object' || !Array.isArray(raw.grants) || !Array.isArray(raw.audit)) {
136
- fail('E_STATE', `invalid state file ${this.stateFile}`)
137
- }
138
- if (raw.version !== STATE_VERSION) {
139
- fail('E_STATE', `unsupported state version ${String(raw.version)} in ${this.stateFile}`)
140
- }
141
- for (const grant of raw.grants) {
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)
145
- }
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)
146
146
  this.auditLog = raw.audit.slice(-MAX_AUDIT_ENTRIES)
147
+ this.counts = loadCounts(raw.counts, this.auditLog)
148
+ this.trimAudit()
147
149
  this.nextSeq = this.auditLog.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1
148
150
  }
149
151
 
150
152
  save() {
151
153
  if (!this.stateFile) return
152
- mkdirSync(dirname(this.stateFile), { recursive: true })
153
- const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
154
154
  const body = JSON.stringify({
155
- version: STATE_VERSION,
156
- grants: [...this.grants.values()],
157
- audit: this.auditLog,
155
+ version: STATE_VERSION, counts: this.counts, grants: [...this.grants.values()], audit: this.auditLog,
158
156
  }, null, 2) + '\n'
157
+ const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
158
+ let fd
159
159
  try {
160
- 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
161
166
  renameSync(temp, this.stateFile)
162
167
  } catch (error) {
168
+ if (fd !== undefined) { try { closeSync(fd) } catch {} }
163
169
  try { unlinkSync(temp) } catch {}
164
170
  fail('E_STATE', `cannot write state file ${this.stateFile}: ${error.message}`)
165
171
  }
166
172
  }
167
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
+
168
187
  record(event, grant, extra = {}) {
169
188
  const entry = { seq: this.nextSeq++, at: this.now(), event }
170
189
  if (grant) {
@@ -174,10 +193,10 @@ export class GrantStore {
174
193
  entry.scope = clone(grant.scope)
175
194
  }
176
195
  Object.assign(entry, extra)
196
+ if (isCheck(event)) this.counts[event] += 1
197
+ else this.counts.security += 1
177
198
  this.auditLog.push(entry)
178
- if (this.auditLog.length > MAX_AUDIT_ENTRIES) {
179
- this.auditLog.splice(0, this.auditLog.length - MAX_AUDIT_ENTRIES)
180
- }
199
+ this.trimAudit()
181
200
  return entry
182
201
  }
183
202
  }
@@ -246,8 +265,7 @@ export class AllowService {
246
265
  const requestedScope = args.scope === undefined ? null : normalizeScope(args.scope)
247
266
  const requested = requestedScope === null ? null : (Array.isArray(requestedScope) ? requestedScope : [requestedScope])
248
267
  const now = this.sweep()
249
- const candidates = [...this.store.grants.values()]
250
- .filter(grant => grant.subject === subject && grant.capability === capability)
268
+ const candidates = [...this.store.grants.values()].filter(grant => grant.subject === subject && grant.capability === capability)
251
269
  const active = candidates.filter(grant => grant.status === 'active')
252
270
  const matched = active.find(grant => requested === null
253
271
  || requested.every(scope => scopeCovers(grant.scope, scope)))
@@ -284,10 +302,20 @@ export class AllowService {
284
302
  : { allowed: false, reason }
285
303
  }
286
304
 
287
- 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 = {}) {
288
310
  const grantId = text(id, 'grant id', 'E_ID', 128)
289
311
  const grant = this.store.grants.get(grantId)
290
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
+ }
291
319
  this.sweep()
292
320
  if (grant.status !== 'active') return clone(grant)
293
321
  const previous = grant.status
@@ -322,6 +350,17 @@ export class AllowService {
322
350
  if (!Number.isInteger(limit) || limit < 1) fail('E_LIMIT', 'limit must be a positive integer')
323
351
  return this.store.auditLog.slice(-limit).reverse().map(entry => clone(entry))
324
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
+ }
325
364
  }
326
365
 
327
366
  const OUTPUT = {
@@ -337,81 +376,55 @@ const SCOPE_SCHEMA = {
337
376
  ],
338
377
  }
339
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
+
340
383
  /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
341
384
  export function createTools(service, options = {}) {
342
385
  const tools = [
343
- {
344
- name: 'allow_issue',
345
- description: 'Issue a revocable capability grant and return it. Grants expire (default 24h, max 30 days).',
346
- parameters: {
347
- type: 'object',
348
- additionalProperties: false,
349
- properties: {
350
- subject: { type: 'string', description: 'Who receives the grant, e.g. "agent:planner" or "plugin:dsh-act".' },
351
- capability: { type: 'string', description: 'Capability name, e.g. "fs.write" or "tool.invoke".' },
352
- scope: SCOPE_SCHEMA,
353
- ttlMs: { type: 'number', minimum: 1, maximum: MAX_TTL_MS, description: 'Lifetime in milliseconds (default 24h, max 30 days).' },
354
- approver: { type: 'string', description: 'Who approved it (default "user").' },
355
- },
356
- required: ['subject', 'capability'],
357
- },
358
- output: OUTPUT,
359
- async execute(args) {
360
- return service.issue(args)
361
- },
362
- },
363
- {
364
- name: 'allow_check',
365
- description: 'Check whether an active grant covers subject + capability + scope. Does not throw when denied.',
366
- parameters: {
367
- type: 'object',
368
- additionalProperties: false,
369
- properties: {
370
- subject: { type: 'string' },
371
- capability: { type: 'string' },
372
- scope: SCOPE_SCHEMA,
373
- },
374
- required: ['subject', 'capability', 'scope'],
375
- },
376
- output: OUTPUT,
377
- async execute(args) {
378
- return service.check(args)
379
- },
380
- },
381
- {
382
- name: 'allow_revoke',
383
- description: 'Revoke a grant by id. Idempotent for grants that are already revoked or expired.',
384
- parameters: {
385
- type: 'object',
386
- additionalProperties: false,
387
- properties: {
388
- id: { type: 'string', description: 'Grant id returned by allow_issue.' },
389
- },
390
- required: ['id'],
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").' },
391
394
  },
392
- output: OUTPUT,
393
- async execute(args) {
394
- return service.revoke(args.id)
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,
395
403
  },
396
- },
397
- {
398
- name: 'allow_list',
399
- description: 'List grants, optionally filtered by exact subject, capability, status or approver.',
400
- parameters: {
401
- type: 'object',
402
- additionalProperties: false,
403
- properties: {
404
- subject: { type: 'string' },
405
- capability: { type: 'string' },
406
- status: { type: 'string', enum: ['active', 'revoked', 'expired'] },
407
- approver: { type: 'string' },
408
- },
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.' },
409
411
  },
410
- output: OUTPUT,
411
- async execute(args) {
412
- return { grants: service.list(args) }
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' },
413
423
  },
414
- },
424
+ ['subject'],
425
+ async args => ({
426
+ grants: service.list({ ...args, subject: text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH) }),
427
+ })),
415
428
  ]
416
429
  // Issuing, revoking and listing every subject are human-facing operations.
417
430
  // Exposing them to the model would let an agent mint its own Grant and
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-allow",
3
- "version": "0.1.1",
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",
@@ -40,6 +40,19 @@
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": {