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.
- package/CHANGELOG.md +31 -0
- package/README.md +52 -26
- package/index.js +160 -111
- 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.
|
|
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`
|
|
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
|
|
73
|
-
audit event. Every denial is
|
|
74
|
-
materialized as `expired` before `check`/`list`/`revoke` answer.
|
|
75
|
-
|
|
76
|
-
|
|
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`,
|
|
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
|
-
|
|
107
|
-
-
|
|
108
|
-
|
|
109
|
-
-
|
|
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
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
|
119
|
-
the audit log across restarts. Writes go to a sibling temporary file
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
|
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,
|
|
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
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
type: '
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
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
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
type: '
|
|
341
|
-
|
|
342
|
-
|
|
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
|
-
|
|
350
|
-
async
|
|
351
|
-
|
|
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
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
},
|
|
363
|
-
|
|
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
|
-
|
|
366
|
-
async
|
|
367
|
-
|
|
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
|
|
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))
|
|
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.
|
|
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
|
|
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"
|