dsh-allow 0.0.1 → 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 +31 -0
  2. package/README.md +141 -7
  3. package/index.js +427 -5
  4. package/package.json +7 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
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
+
15
+ ## 0.1.0 — 2026-11-20
16
+
17
+ First functional MVP.
18
+
19
+ - Add `GrantStore` and `AllowService` with `issue`, `check`, `revoke`, `list`
20
+ and `audit`.
21
+ - Grant lifecycle: `active`, `revoked`, `expired`; default TTL 24h, hard maximum
22
+ 30 days; expiry evaluated against the service clock.
23
+ - Scope matching: `*`, `prefix:*`, exact strings and arrays of patterns.
24
+ - Successful checks refresh `usedAt`; issue, allowed, denied, revoked and
25
+ automatic expiry events are appended to the audit log.
26
+ - Optional JSON persistence via `config.stateFile` with temp-file + rename
27
+ atomic writes (mode `0600`); memory-only by default.
28
+ - Host seam `ctx.provide('allow', service)` and four plain-object agent tools:
29
+ `allow_issue`, `allow_check`, `allow_revoke`, `allow_list`.
30
+ - Input validation with stable error codes; no runtime dependencies and no build
31
+ step.
32
+ - Tests: 10 cases via `node --test`.
33
+
3
34
  ## 0.0.1
4
35
 
5
36
  - Reserve the `dsh-allow` package name.
package/README.md CHANGED
@@ -2,11 +2,22 @@
2
2
 
3
3
  > Revocable capability grants and an audit-ready permission center for DeepSeek Harness.
4
4
 
5
- **Status: 0.0.1 name reservation.** The working design lives in the
6
- [dsh-os design notes](https://github.com/PerryLink/dsh-os#readme). A functional MVP is planned for 0.1.0.
5
+ **Status: 0.1.1 MVP.** Host seam `ctx.allow` + a read-only agent tool, in-memory by
6
+ default, optional atomic JSON state.
7
+
8
+ > **控制面不是沙箱;out-of-turn 授权由 Grant 承担。**
9
+ >
10
+ > **This is a control plane, not a sandbox. Out-of-turn authorization is carried
11
+ > by grants.** A grant records and answers "who approved what, for how long and
12
+ > under which scope". It cannot stop same-process code from bypassing the check,
13
+ > and it does not replace DSH's approval prompt, permission rules, presets or OS
14
+ > sandbox. When a human is not in an open turn, a grant is the authorization
15
+ > object to check before acting.
7
16
 
8
17
  **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
9
- of their respective owners.
18
+ of their respective owners. This is an independent community package. It is also
19
+ unrelated to other projects that happen to use the name `dsh-allow`: Allow issues
20
+ capability grants; it does not hand out shell file permissions.
10
21
 
11
22
  ## Install
12
23
 
@@ -14,8 +25,131 @@ of their respective owners.
14
25
  dsh plugin --profile web add dsh-allow
15
26
  ```
16
27
 
17
- ## Design
28
+ No runtime dependencies, no build step, Node.js 22+.
29
+
30
+ ## Host seam
31
+
32
+ ```js
33
+ import { apply } from 'dsh-allow'
34
+
35
+ const service = apply(ctx, { stateFile: '/path/to/allow-state.json' })
36
+ // or consume the seam:
37
+ const allow = ctx.get('allow')
38
+ ```
39
+
40
+ `apply` returns the service, calls `ctx.provide('allow', service)` and registers
41
+ the tools when `ctx.tools` is available. The service can be constructed without a
42
+ tools service.
43
+
44
+ ### Service API
45
+
46
+ | Method | Result |
47
+ |---|---|
48
+ | `issue({ subject, capability, scope = '*', ttlMs?, approver = 'user', evidence? })` | `Grant` |
49
+ | `check({ subject, capability, scope })` | `{ allowed, grant?, reason }` |
50
+ | `revoke(id)` | updated `Grant` (idempotent for revoked/expired grants) |
51
+ | `list(filter?)` | `Grant[]`, filter by exact `subject`, `capability`, `status` or `approver` |
52
+ | `audit(limit = 100)` | newest-first audit events |
53
+
54
+ Grant shape (timestamps are Unix milliseconds):
55
+
56
+ ```js
57
+ {
58
+ id: 'grant_<uuid>',
59
+ subject: 'agent:planner',
60
+ capability: 'fs.write',
61
+ scope: 'repo:*',
62
+ status: 'active', // active | revoked | expired
63
+ createdAt: 1700000000000,
64
+ expiresAt: 1700086400000,
65
+ approver: 'user',
66
+ evidence: { approvalId: '...' }, // optional
67
+ usedAt: 1700000001000, // last successful check
68
+ }
69
+ ```
70
+
71
+ `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()`).
77
+
78
+ ### Scope matching
79
+
80
+ Grant scope may be a string or an array; a requested array must be fully covered.
81
+
82
+ | Grant scope | Requested | Match |
83
+ |---|---|---|
84
+ | `*` | anything | yes |
85
+ | `repo:*` | `repo:src/a.js` | yes (prefix) |
86
+ | `repo:*` | `repositories` | no |
87
+ | `repo:src` | `repo:src` | yes (exact) |
88
+ | `repo:src` | `repo:src/a.js` | no |
89
+ | `['one', 'two:*']` | `two:deep` | yes (any entry) |
90
+
91
+ ### TTL and validation
92
+
93
+ - Default TTL is 24 hours; maximum is 30 days. Non-positive, non-finite or
94
+ oversized `ttlMs` is rejected with `E_TTL`.
95
+ - `subject` and `capability` must be non-empty strings (256 characters max);
96
+ `scope` entries are at most 512 characters; `approver` is at most 128.
97
+ - Expiry uses the service clock (`Date.now()` by default); a backwards clock is
98
+ treated as expiry. There is no implicit renewal.
99
+ - 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`.
101
+
102
+ ## Agent tools
103
+
104
+ Plain object `ToolDefinition`s, no `@deepseek-ai/dsh-tools` import.
105
+
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
+
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.
120
+
121
+ ## Persistence
122
+
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.
130
+
131
+ ## Security model
132
+
133
+ - **Fail closed.** Unknown grants, wrong scope, expired/revoked grants and state
134
+ errors never become `allowed`.
135
+ - **No default allow.** A grant only allows; it cannot override a deny from DSH
136
+ policy. Deny stays priority.
137
+ - **Revocation is forward-looking.** A revoked grant rejects the next check, but
138
+ cannot stop work already in flight.
139
+ - **No secrets.** Only grant metadata and the caller-supplied evidence reference
140
+ are stored; never store credential values in `evidence`.
141
+ - **No tamper-proof claim.** The audit log survives restarts when `stateFile` is
142
+ set, but an administrator who can rewrite the file can rewrite history.
143
+
144
+ ## Test
145
+
146
+ ```sh
147
+ node --test
148
+ ```
149
+
150
+ Covers issue/check, wildcard and array scopes, expiry, revocation, denial,
151
+ list/audit, validation, tool registration and `stateFile` round-trips.
152
+
153
+ ## License
18
154
 
19
- - Host seam: `ctx.allow` (planned)
20
- - Agent tools and CLI are declared in the package's design doc.
21
- - License: MIT.
155
+ MIT.
package/index.js CHANGED
@@ -1,13 +1,435 @@
1
1
  /**
2
- * dsh-allow — Revocable capability grants and an audit-ready permission center for DeepSeek Harness.
2
+ * dsh-allow — Revocable capability grants and an audit-ready permission center
3
+ * for DeepSeek Harness.
3
4
  *
4
- * 0.0.1 placeholder: the bundle loads and provides a stable package name.
5
- * The functional implementation lands in 0.1.0.
5
+ * This is a control plane, not a sandbox: it records and answers out-of-turn
6
+ * authorization questions. It cannot stop same-process code from bypassing it.
6
7
  * @module dsh-allow
7
8
  */
8
9
 
10
+ import { randomUUID } from 'node:crypto'
11
+ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
12
+ import { dirname, resolve } from 'node:path'
13
+
9
14
  /** Cordis plugin name. */
10
15
  export const name = 'dsh-allow'
11
16
 
12
- /** Mount the plugin. The 0.0.1 placeholder intentionally has no side effects. */
13
- export function apply() {}
17
+ /** The bundle needs the host tool registry to expose its agent tools. */
18
+ export const inject = ['tools']
19
+
20
+ export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
21
+ export const MAX_TTL_MS = 30 * 24 * 60 * 60 * 1000
22
+ export const MAX_SUBJECT_LENGTH = 256, MAX_CAPABILITY_LENGTH = 256, MAX_SCOPE_LENGTH = 512, MAX_APPROVER_LENGTH = 128
23
+ export const MAX_AUDIT_ENTRIES = 2000
24
+ const STATE_VERSION = 1
25
+
26
+ function fail(code, message) {
27
+ const error = new Error(message)
28
+ error.code = code
29
+ throw error
30
+ }
31
+
32
+ function text(value, field, code, max) {
33
+ if (typeof value !== 'string') fail(code, `${field} must be a string`)
34
+ const trimmed = value.trim()
35
+ if (!trimmed) fail(code, `${field} must not be empty`)
36
+ if (trimmed.length > max) fail(code, `${field} must be at most ${max} characters`)
37
+ return trimmed
38
+ }
39
+
40
+ function objectInput(value) { if (!value || typeof value !== 'object' || Array.isArray(value)) {
41
+ fail('E_INPUT', 'input must be an object')
42
+ }
43
+ return value
44
+ }
45
+
46
+ /** `*` and `foo:*` are grant-side patterns; strings and arrays are accepted. */
47
+ function normalizeScope(scope) {
48
+ if (scope === undefined) return '*'
49
+ if (Array.isArray(scope)) {
50
+ if (scope.length === 0) fail('E_SCOPE', 'scope must not be an empty array')
51
+ return scope.map(value => text(value, 'scope', 'E_SCOPE', MAX_SCOPE_LENGTH))
52
+ }
53
+ return text(scope, 'scope', 'E_SCOPE', MAX_SCOPE_LENGTH)
54
+ }
55
+
56
+ function scopeCovers(pattern, requested) {
57
+ if (Array.isArray(pattern)) return pattern.some(value => scopeCovers(value, requested))
58
+ if (pattern === '*') return true
59
+ if (typeof pattern !== 'string' || typeof requested !== 'string') return false
60
+ if (pattern.endsWith(':*')) {
61
+ const prefix = pattern.slice(0, -1)
62
+ return requested === prefix || requested.startsWith(prefix)
63
+ }
64
+ return pattern === requested
65
+ }
66
+
67
+ function resolveTtl(ttlMs) {
68
+ 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
+ }
72
+ if (ttlMs > MAX_TTL_MS) fail('E_TTL', `ttlMs must not exceed ${MAX_TTL_MS} ms (30 days)`)
73
+ return ttlMs
74
+ }
75
+
76
+ const clone = value => structuredClone(value)
77
+
78
+ function cloneEvidence(evidence) {
79
+ if (evidence === undefined || evidence === null) return undefined
80
+ try {
81
+ return structuredClone(evidence)
82
+ } catch {
83
+ fail('E_EVIDENCE', 'evidence must be structured-cloneable')
84
+ }
85
+ }
86
+
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
+ /** 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
+
107
+ export class GrantStore {
108
+ constructor(config = {}) {
109
+ this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
110
+ this.stateFile = null
111
+ 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
+ }
115
+ this.stateFile = resolve(config.stateFile)
116
+ }
117
+ this.grants = new Map()
118
+ this.auditLog = []
119
+ this.nextSeq = 1
120
+ if (this.stateFile) this.load()
121
+ }
122
+
123
+ now() {
124
+ return this.clock()
125
+ }
126
+
127
+ load() {
128
+ let raw
129
+ try {
130
+ raw = JSON.parse(readFileSync(this.stateFile, 'utf8'))
131
+ } catch (error) {
132
+ if (error && error.code === 'ENOENT') return
133
+ fail('E_STATE', `cannot read state file ${this.stateFile}: ${error.message}`)
134
+ }
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
+ }
146
+ this.auditLog = raw.audit.slice(-MAX_AUDIT_ENTRIES)
147
+ this.nextSeq = this.auditLog.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1
148
+ }
149
+
150
+ save() {
151
+ if (!this.stateFile) return
152
+ mkdirSync(dirname(this.stateFile), { recursive: true })
153
+ const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
154
+ const body = JSON.stringify({
155
+ version: STATE_VERSION,
156
+ grants: [...this.grants.values()],
157
+ audit: this.auditLog,
158
+ }, null, 2) + '\n'
159
+ try {
160
+ writeFileSync(temp, body, { encoding: 'utf8', mode: 0o600 })
161
+ renameSync(temp, this.stateFile)
162
+ } catch (error) {
163
+ try { unlinkSync(temp) } catch {}
164
+ fail('E_STATE', `cannot write state file ${this.stateFile}: ${error.message}`)
165
+ }
166
+ }
167
+
168
+ record(event, grant, extra = {}) {
169
+ const entry = { seq: this.nextSeq++, at: this.now(), event }
170
+ if (grant) {
171
+ entry.grantId = grant.id
172
+ entry.subject = grant.subject
173
+ entry.capability = grant.capability
174
+ entry.scope = clone(grant.scope)
175
+ }
176
+ Object.assign(entry, extra)
177
+ this.auditLog.push(entry)
178
+ if (this.auditLog.length > MAX_AUDIT_ENTRIES) {
179
+ this.auditLog.splice(0, this.auditLog.length - MAX_AUDIT_ENTRIES)
180
+ }
181
+ return entry
182
+ }
183
+ }
184
+
185
+ /** Host seam `ctx.allow`: issue, check, revoke, list and audit grants. */
186
+ export class AllowService {
187
+ constructor(ctx, config = {}) {
188
+ this.ctx = ctx
189
+ this.store = new GrantStore(config)
190
+ }
191
+
192
+ /** Mark elapsed grants as expired and write one audit event per transition. */
193
+ sweep() {
194
+ const now = this.store.now()
195
+ let changed = false
196
+ for (const grant of this.store.grants.values()) {
197
+ if (grant.status !== 'active') continue
198
+ const elapsed = typeof grant.expiresAt === 'number' && grant.expiresAt <= now
199
+ const clockRollback = typeof grant.createdAt === 'number' && now < grant.createdAt
200
+ if (!elapsed && !clockRollback) continue
201
+ grant.status = 'expired'
202
+ this.store.record('expired', grant)
203
+ changed = true
204
+ }
205
+ if (changed) this.store.save()
206
+ return now
207
+ }
208
+
209
+ issue(input = {}) {
210
+ const args = objectInput(input)
211
+ const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
212
+ const capability = text(args.capability, 'capability', 'E_CAPABILITY', MAX_CAPABILITY_LENGTH)
213
+ const scope = normalizeScope(args.scope)
214
+ const approver = args.approver === undefined
215
+ ? 'user'
216
+ : text(args.approver, 'approver', 'E_APPROVER', MAX_APPROVER_LENGTH)
217
+ const ttlMs = resolveTtl(args.ttlMs)
218
+ const evidence = cloneEvidence(args.evidence)
219
+ const now = this.store.now()
220
+ const grant = {
221
+ id: `grant_${randomUUID()}`,
222
+ subject,
223
+ capability,
224
+ scope,
225
+ status: 'active',
226
+ createdAt: now,
227
+ expiresAt: now + ttlMs,
228
+ approver,
229
+ }
230
+ if (evidence !== undefined) grant.evidence = evidence
231
+ this.store.grants.set(grant.id, grant)
232
+ this.store.record('issued', grant, { approver, expiresAt: grant.expiresAt })
233
+ try {
234
+ this.store.save()
235
+ } catch (error) {
236
+ this.store.grants.delete(grant.id)
237
+ throw error
238
+ }
239
+ return clone(grant)
240
+ }
241
+
242
+ check(input = {}) {
243
+ const args = objectInput(input)
244
+ const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
245
+ const capability = text(args.capability, 'capability', 'E_CAPABILITY', MAX_CAPABILITY_LENGTH)
246
+ const requestedScope = args.scope === undefined ? null : normalizeScope(args.scope)
247
+ const requested = requestedScope === null ? null : (Array.isArray(requestedScope) ? requestedScope : [requestedScope])
248
+ const now = this.sweep()
249
+ const candidates = [...this.store.grants.values()]
250
+ .filter(grant => grant.subject === subject && grant.capability === capability)
251
+ const active = candidates.filter(grant => grant.status === 'active')
252
+ const matched = active.find(grant => requested === null
253
+ || requested.every(scope => scopeCovers(grant.scope, scope)))
254
+
255
+ if (matched) {
256
+ matched.usedAt = now
257
+ this.store.record('allowed', matched)
258
+ return { allowed: true, grant: clone(matched), reason: 'allowed' }
259
+ }
260
+
261
+ const expired = candidates.find(grant => grant.status === 'expired')
262
+ const revoked = candidates.find(grant => grant.status === 'revoked')
263
+ let reason = 'no-grant'
264
+ let grant
265
+ if (active.length > 0) {
266
+ reason = 'scope-mismatch'
267
+ grant = active[0]
268
+ } else if (expired) {
269
+ reason = 'expired'
270
+ grant = expired
271
+ } else if (revoked) {
272
+ reason = 'revoked'
273
+ grant = revoked
274
+ }
275
+ this.store.record('denied', null, {
276
+ subject,
277
+ capability,
278
+ scope: requested === null ? '*' : clone(requestedScope),
279
+ reason,
280
+ ...(grant ? { grantId: grant.id } : {}),
281
+ })
282
+ return grant
283
+ ? { allowed: false, grant: clone(grant), reason }
284
+ : { allowed: false, reason }
285
+ }
286
+
287
+ revoke(id) {
288
+ const grantId = text(id, 'grant id', 'E_ID', 128)
289
+ const grant = this.store.grants.get(grantId)
290
+ if (!grant) fail('E_GRANT_NOT_FOUND', `unknown grant: ${grantId}`)
291
+ this.sweep()
292
+ if (grant.status !== 'active') return clone(grant)
293
+ const previous = grant.status
294
+ grant.status = 'revoked'
295
+ this.store.record('revoked', grant)
296
+ try {
297
+ this.store.save()
298
+ } catch (error) {
299
+ grant.status = previous
300
+ throw error
301
+ }
302
+ return clone(grant)
303
+ }
304
+
305
+ list(filter = {}) {
306
+ if (filter === undefined || filter === null) filter = {}
307
+ if (typeof filter !== 'object' || Array.isArray(filter)) fail('E_FILTER', 'filter must be an object')
308
+ this.sweep()
309
+ const results = []
310
+ for (const grant of this.store.grants.values()) {
311
+ if (filter.subject !== undefined && grant.subject !== filter.subject) continue
312
+ if (filter.capability !== undefined && grant.capability !== filter.capability) continue
313
+ if (filter.status !== undefined && grant.status !== filter.status) continue
314
+ if (filter.approver !== undefined && grant.approver !== filter.approver) continue
315
+ results.push(clone(grant))
316
+ }
317
+ return results
318
+ }
319
+
320
+ /** Newest-first audit events, capped by `limit` (default 100). */
321
+ audit(limit = 100) {
322
+ if (!Number.isInteger(limit) || limit < 1) fail('E_LIMIT', 'limit must be a positive integer')
323
+ return this.store.auditLog.slice(-limit).reverse().map(entry => clone(entry))
324
+ }
325
+ }
326
+
327
+ const OUTPUT = {
328
+ schema: { type: 'object', additionalProperties: true },
329
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
330
+ }
331
+
332
+ const SCOPE_SCHEMA = {
333
+ description: 'Granted scope: "*", an exact string, a "prefix:*" pattern, or an array of these.',
334
+ anyOf: [
335
+ { type: 'string' },
336
+ { type: 'array', items: { type: 'string' }, minItems: 1 },
337
+ ],
338
+ }
339
+
340
+ /** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
341
+ export function createTools(service, options = {}) {
342
+ 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'],
391
+ },
392
+ output: OUTPUT,
393
+ async execute(args) {
394
+ return service.revoke(args.id)
395
+ },
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
+ },
409
+ },
410
+ output: OUTPUT,
411
+ async execute(args) {
412
+ return { grants: service.list(args) }
413
+ },
414
+ },
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')
423
+ }
424
+
425
+ /** Mount the service at `ctx.allow`; only the read-only check tool is public. */
426
+ export function apply(ctx, config = {}) {
427
+ const service = new AllowService(ctx, config)
428
+ ctx.provide('allow', service)
429
+ if (ctx.tools && typeof ctx.tools.register === 'function') {
430
+ for (const tool of createTools(service, { exposeAdminTools: config.exposeAdminTools === true })) {
431
+ ctx.tools.register(tool)
432
+ }
433
+ }
434
+ return service
435
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-allow",
3
- "version": "0.0.1",
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,6 +43,10 @@
43
43
  }
44
44
  },
45
45
  "publishConfig": {
46
- "access": "public"
46
+ "access": "public",
47
+ "registry": "https://registry.npmjs.org/"
48
+ },
49
+ "scripts": {
50
+ "test": "node --test"
47
51
  }
48
52
  }