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.
- package/CHANGELOG.md +19 -0
- package/README.md +40 -19
- package/index.js +127 -114
- 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.
|
|
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,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`,
|
|
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
|
|
115
|
-
|
|
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
|
|
124
|
-
the audit log across restarts. Writes go to a sibling temporary file
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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
|
|
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,
|
|
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) {
|
|
41
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
type: '
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
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
|
-
|
|
393
|
-
async
|
|
394
|
-
|
|
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
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
type: '
|
|
402
|
-
|
|
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
|
-
|
|
411
|
-
async
|
|
412
|
-
|
|
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.
|
|
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": {
|