dsh-allow 0.0.1 → 0.1.0
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 +136 -7
- package/index.js +391 -5
- package/package.json +4 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.0 — 2026-11-20
|
|
4
|
+
|
|
5
|
+
First functional MVP.
|
|
6
|
+
|
|
7
|
+
- Add `GrantStore` and `AllowService` with `issue`, `check`, `revoke`, `list`
|
|
8
|
+
and `audit`.
|
|
9
|
+
- Grant lifecycle: `active`, `revoked`, `expired`; default TTL 24h, hard maximum
|
|
10
|
+
30 days; expiry evaluated against the service clock.
|
|
11
|
+
- Scope matching: `*`, `prefix:*`, exact strings and arrays of patterns.
|
|
12
|
+
- Successful checks refresh `usedAt`; issue, allowed, denied, revoked and
|
|
13
|
+
automatic expiry events are appended to the audit log.
|
|
14
|
+
- Optional JSON persistence via `config.stateFile` with temp-file + rename
|
|
15
|
+
atomic writes (mode `0600`); memory-only by default.
|
|
16
|
+
- Host seam `ctx.provide('allow', service)` and four plain-object agent tools:
|
|
17
|
+
`allow_issue`, `allow_check`, `allow_revoke`, `allow_list`.
|
|
18
|
+
- Input validation with stable error codes; no runtime dependencies and no build
|
|
19
|
+
step.
|
|
20
|
+
- Tests: 10 cases via `node --test`.
|
|
21
|
+
|
|
3
22
|
## 0.0.1
|
|
4
23
|
|
|
5
24
|
- 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
|
|
6
|
-
|
|
5
|
+
**Status: 0.1.0 MVP.** Host seam `ctx.allow` + four agent tools, 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,126 @@ of their respective owners.
|
|
|
14
25
|
dsh plugin --profile web add dsh-allow
|
|
15
26
|
```
|
|
16
27
|
|
|
17
|
-
|
|
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
|
+
- `allow_issue` — issue a grant (`subject`, `capability` required).
|
|
107
|
+
- `allow_check` — check a concrete subject/capability/scope.
|
|
108
|
+
- `allow_revoke` — revoke by grant id.
|
|
109
|
+
- `allow_list` — list grants with optional exact filters; returns `{ grants }`.
|
|
110
|
+
|
|
111
|
+
The bundled issue/revoke tools are an MVP integration seam, not an authentication
|
|
112
|
+
boundary. This package cannot tell a human caller from a same-process agent; a
|
|
113
|
+
production profile should expose issue/revoke only to human-facing clients and
|
|
114
|
+
keep `check`/`list` for agents.
|
|
115
|
+
|
|
116
|
+
## Persistence
|
|
117
|
+
|
|
118
|
+
In-memory by default. Set `config.stateFile` to a JSON path to persist grants and
|
|
119
|
+
the audit log across restarts. Writes go to a sibling temporary file and are
|
|
120
|
+
promoted with `rename` (atomic on the same filesystem); the file is created with
|
|
121
|
+
mode `0600`. A missing file starts empty; unreadable or malformed state fails
|
|
122
|
+
closed with `E_STATE` instead of silently authorizing from a damaged ledger. This
|
|
123
|
+
is a local MVP store, not a multi-process ledger: do not point two live writers
|
|
124
|
+
at the same file.
|
|
125
|
+
|
|
126
|
+
## Security model
|
|
127
|
+
|
|
128
|
+
- **Fail closed.** Unknown grants, wrong scope, expired/revoked grants and state
|
|
129
|
+
errors never become `allowed`.
|
|
130
|
+
- **No default allow.** A grant only allows; it cannot override a deny from DSH
|
|
131
|
+
policy. Deny stays priority.
|
|
132
|
+
- **Revocation is forward-looking.** A revoked grant rejects the next check, but
|
|
133
|
+
cannot stop work already in flight.
|
|
134
|
+
- **No secrets.** Only grant metadata and the caller-supplied evidence reference
|
|
135
|
+
are stored; never store credential values in `evidence`.
|
|
136
|
+
- **No tamper-proof claim.** The audit log survives restarts when `stateFile` is
|
|
137
|
+
set, but an administrator who can rewrite the file can rewrite history.
|
|
138
|
+
|
|
139
|
+
## Test
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
node --test
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Covers issue/check, wildcard and array scopes, expiry, revocation, denial,
|
|
146
|
+
list/audit, validation, tool registration and `stateFile` round-trips.
|
|
147
|
+
|
|
148
|
+
## License
|
|
18
149
|
|
|
19
|
-
|
|
20
|
-
- Agent tools and CLI are declared in the package's design doc.
|
|
21
|
-
- License: MIT.
|
|
150
|
+
MIT.
|
package/index.js
CHANGED
|
@@ -1,13 +1,399 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* dsh-allow — Revocable capability grants and an audit-ready permission center
|
|
2
|
+
* dsh-allow — Revocable capability grants and an audit-ready permission center
|
|
3
|
+
* for DeepSeek Harness.
|
|
3
4
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
-
/**
|
|
13
|
-
export
|
|
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) {
|
|
41
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) {
|
|
42
|
+
fail('E_INPUT', 'input must be an object')
|
|
43
|
+
}
|
|
44
|
+
return value
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** `*` and `foo:*` are grant-side patterns; strings and arrays are accepted. */
|
|
48
|
+
function normalizeScope(scope) {
|
|
49
|
+
if (scope === undefined) return '*'
|
|
50
|
+
if (Array.isArray(scope)) {
|
|
51
|
+
if (scope.length === 0) fail('E_SCOPE', 'scope must not be an empty array')
|
|
52
|
+
return scope.map(value => text(value, 'scope', 'E_SCOPE', MAX_SCOPE_LENGTH))
|
|
53
|
+
}
|
|
54
|
+
return text(scope, 'scope', 'E_SCOPE', MAX_SCOPE_LENGTH)
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function scopeCovers(pattern, requested) {
|
|
58
|
+
if (Array.isArray(pattern)) return pattern.some(value => scopeCovers(value, requested))
|
|
59
|
+
if (pattern === '*') return true
|
|
60
|
+
if (typeof pattern !== 'string' || typeof requested !== 'string') return false
|
|
61
|
+
if (pattern.endsWith(':*')) {
|
|
62
|
+
const prefix = pattern.slice(0, -1)
|
|
63
|
+
return requested === prefix || requested.startsWith(prefix)
|
|
64
|
+
}
|
|
65
|
+
return pattern === requested
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function resolveTtl(ttlMs) {
|
|
69
|
+
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 (ttlMs > MAX_TTL_MS) fail('E_TTL', `ttlMs must not exceed ${MAX_TTL_MS} ms (30 days)`)
|
|
74
|
+
return ttlMs
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const clone = value => structuredClone(value)
|
|
78
|
+
|
|
79
|
+
function cloneEvidence(evidence) {
|
|
80
|
+
if (evidence === undefined || evidence === null) return undefined
|
|
81
|
+
try {
|
|
82
|
+
return structuredClone(evidence)
|
|
83
|
+
} catch {
|
|
84
|
+
fail('E_EVIDENCE', 'evidence must be structured-cloneable')
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Durable-enough local state: an in-memory Map by default, or an atomically
|
|
90
|
+
* written JSON file when `config.stateFile` is set.
|
|
91
|
+
*/
|
|
92
|
+
export class GrantStore {
|
|
93
|
+
constructor(config = {}) {
|
|
94
|
+
this.clock = typeof config.now === 'function' ? config.now : () => Date.now()
|
|
95
|
+
this.stateFile = null
|
|
96
|
+
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
|
+
}
|
|
100
|
+
this.stateFile = resolve(config.stateFile)
|
|
101
|
+
}
|
|
102
|
+
this.grants = new Map()
|
|
103
|
+
this.auditLog = []
|
|
104
|
+
this.nextSeq = 1
|
|
105
|
+
if (this.stateFile) this.load()
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
now() {
|
|
109
|
+
return this.clock()
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
load() {
|
|
113
|
+
let raw
|
|
114
|
+
try {
|
|
115
|
+
raw = JSON.parse(readFileSync(this.stateFile, 'utf8'))
|
|
116
|
+
} catch (error) {
|
|
117
|
+
if (error && error.code === 'ENOENT') return
|
|
118
|
+
fail('E_STATE', `cannot read state file ${this.stateFile}: ${error.message}`)
|
|
119
|
+
}
|
|
120
|
+
if (!raw || typeof raw !== 'object' || !Array.isArray(raw.grants) || !Array.isArray(raw.audit)) {
|
|
121
|
+
fail('E_STATE', `invalid state file ${this.stateFile}`)
|
|
122
|
+
}
|
|
123
|
+
for (const grant of raw.grants) {
|
|
124
|
+
if (!grant || typeof grant.id !== 'string' || typeof grant.subject !== 'string' || typeof grant.capability !== 'string') {
|
|
125
|
+
fail('E_STATE', `invalid grant record in ${this.stateFile}`)
|
|
126
|
+
}
|
|
127
|
+
this.grants.set(grant.id, grant)
|
|
128
|
+
}
|
|
129
|
+
this.auditLog = raw.audit.slice(-MAX_AUDIT_ENTRIES)
|
|
130
|
+
this.nextSeq = this.auditLog.reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
save() {
|
|
134
|
+
if (!this.stateFile) return
|
|
135
|
+
mkdirSync(dirname(this.stateFile), { recursive: true })
|
|
136
|
+
const temp = `${this.stateFile}.${process.pid}.${randomUUID()}.tmp`
|
|
137
|
+
const body = JSON.stringify({
|
|
138
|
+
version: STATE_VERSION,
|
|
139
|
+
grants: [...this.grants.values()],
|
|
140
|
+
audit: this.auditLog,
|
|
141
|
+
}, null, 2) + '\n'
|
|
142
|
+
try {
|
|
143
|
+
writeFileSync(temp, body, { encoding: 'utf8', mode: 0o600 })
|
|
144
|
+
renameSync(temp, this.stateFile)
|
|
145
|
+
} catch (error) {
|
|
146
|
+
try { unlinkSync(temp) } catch {}
|
|
147
|
+
fail('E_STATE', `cannot write state file ${this.stateFile}: ${error.message}`)
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
record(event, grant, extra = {}) {
|
|
152
|
+
const entry = { seq: this.nextSeq++, at: this.now(), event }
|
|
153
|
+
if (grant) {
|
|
154
|
+
entry.grantId = grant.id
|
|
155
|
+
entry.subject = grant.subject
|
|
156
|
+
entry.capability = grant.capability
|
|
157
|
+
entry.scope = clone(grant.scope)
|
|
158
|
+
}
|
|
159
|
+
Object.assign(entry, extra)
|
|
160
|
+
this.auditLog.push(entry)
|
|
161
|
+
if (this.auditLog.length > MAX_AUDIT_ENTRIES) {
|
|
162
|
+
this.auditLog.splice(0, this.auditLog.length - MAX_AUDIT_ENTRIES)
|
|
163
|
+
}
|
|
164
|
+
return entry
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** Host seam `ctx.allow`: issue, check, revoke, list and audit grants. */
|
|
169
|
+
export class AllowService {
|
|
170
|
+
constructor(ctx, config = {}) {
|
|
171
|
+
this.ctx = ctx
|
|
172
|
+
this.store = new GrantStore(config)
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** Mark elapsed grants as expired and write one audit event per transition. */
|
|
176
|
+
sweep() {
|
|
177
|
+
const now = this.store.now()
|
|
178
|
+
let changed = false
|
|
179
|
+
for (const grant of this.store.grants.values()) {
|
|
180
|
+
if (grant.status !== 'active') continue
|
|
181
|
+
const elapsed = typeof grant.expiresAt === 'number' && grant.expiresAt <= now
|
|
182
|
+
const clockRollback = typeof grant.createdAt === 'number' && now < grant.createdAt
|
|
183
|
+
if (!elapsed && !clockRollback) continue
|
|
184
|
+
grant.status = 'expired'
|
|
185
|
+
this.store.record('expired', grant)
|
|
186
|
+
changed = true
|
|
187
|
+
}
|
|
188
|
+
if (changed) this.store.save()
|
|
189
|
+
return now
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
issue(input = {}) {
|
|
193
|
+
const args = objectInput(input)
|
|
194
|
+
const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
|
|
195
|
+
const capability = text(args.capability, 'capability', 'E_CAPABILITY', MAX_CAPABILITY_LENGTH)
|
|
196
|
+
const scope = normalizeScope(args.scope)
|
|
197
|
+
const approver = args.approver === undefined
|
|
198
|
+
? 'user'
|
|
199
|
+
: text(args.approver, 'approver', 'E_APPROVER', MAX_APPROVER_LENGTH)
|
|
200
|
+
const ttlMs = resolveTtl(args.ttlMs)
|
|
201
|
+
const evidence = cloneEvidence(args.evidence)
|
|
202
|
+
const now = this.store.now()
|
|
203
|
+
const grant = {
|
|
204
|
+
id: `grant_${randomUUID()}`,
|
|
205
|
+
subject,
|
|
206
|
+
capability,
|
|
207
|
+
scope,
|
|
208
|
+
status: 'active',
|
|
209
|
+
createdAt: now,
|
|
210
|
+
expiresAt: now + ttlMs,
|
|
211
|
+
approver,
|
|
212
|
+
}
|
|
213
|
+
if (evidence !== undefined) grant.evidence = evidence
|
|
214
|
+
this.store.grants.set(grant.id, grant)
|
|
215
|
+
this.store.record('issued', grant, { approver, expiresAt: grant.expiresAt })
|
|
216
|
+
this.store.save()
|
|
217
|
+
return clone(grant)
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
check(input = {}) {
|
|
221
|
+
const args = objectInput(input)
|
|
222
|
+
const subject = text(args.subject, 'subject', 'E_SUBJECT', MAX_SUBJECT_LENGTH)
|
|
223
|
+
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]
|
|
226
|
+
const now = this.sweep()
|
|
227
|
+
const candidates = [...this.store.grants.values()]
|
|
228
|
+
.filter(grant => grant.subject === subject && grant.capability === capability)
|
|
229
|
+
const active = candidates.filter(grant => grant.status === 'active')
|
|
230
|
+
const matched = active.find(grant => requested.every(scope => scopeCovers(grant.scope, scope)))
|
|
231
|
+
|
|
232
|
+
if (matched) {
|
|
233
|
+
matched.usedAt = now
|
|
234
|
+
this.store.record('allowed', matched)
|
|
235
|
+
this.store.save()
|
|
236
|
+
return { allowed: true, grant: clone(matched), reason: 'allowed' }
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
const expired = candidates.find(grant => grant.status === 'expired')
|
|
240
|
+
const revoked = candidates.find(grant => grant.status === 'revoked')
|
|
241
|
+
let reason = 'no-grant'
|
|
242
|
+
let grant
|
|
243
|
+
if (active.length > 0) {
|
|
244
|
+
reason = 'scope-mismatch'
|
|
245
|
+
grant = active[0]
|
|
246
|
+
} else if (expired) {
|
|
247
|
+
reason = 'expired'
|
|
248
|
+
grant = expired
|
|
249
|
+
} else if (revoked) {
|
|
250
|
+
reason = 'revoked'
|
|
251
|
+
grant = revoked
|
|
252
|
+
}
|
|
253
|
+
this.store.record('denied', null, {
|
|
254
|
+
subject,
|
|
255
|
+
capability,
|
|
256
|
+
scope: clone(requestedScope),
|
|
257
|
+
reason,
|
|
258
|
+
...(grant ? { grantId: grant.id } : {}),
|
|
259
|
+
})
|
|
260
|
+
this.store.save()
|
|
261
|
+
return grant
|
|
262
|
+
? { allowed: false, grant: clone(grant), reason }
|
|
263
|
+
: { allowed: false, reason }
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
revoke(id) {
|
|
267
|
+
const grantId = text(id, 'grant id', 'E_ID', 128)
|
|
268
|
+
const grant = this.store.grants.get(grantId)
|
|
269
|
+
if (!grant) fail('E_GRANT_NOT_FOUND', `unknown grant: ${grantId}`)
|
|
270
|
+
this.sweep()
|
|
271
|
+
if (grant.status !== 'active') return clone(grant)
|
|
272
|
+
grant.status = 'revoked'
|
|
273
|
+
this.store.record('revoked', grant)
|
|
274
|
+
this.store.save()
|
|
275
|
+
return clone(grant)
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
list(filter = {}) {
|
|
279
|
+
if (filter === undefined || filter === null) filter = {}
|
|
280
|
+
if (typeof filter !== 'object' || Array.isArray(filter)) fail('E_FILTER', 'filter must be an object')
|
|
281
|
+
this.sweep()
|
|
282
|
+
const results = []
|
|
283
|
+
for (const grant of this.store.grants.values()) {
|
|
284
|
+
if (filter.subject !== undefined && grant.subject !== filter.subject) continue
|
|
285
|
+
if (filter.capability !== undefined && grant.capability !== filter.capability) continue
|
|
286
|
+
if (filter.status !== undefined && grant.status !== filter.status) continue
|
|
287
|
+
if (filter.approver !== undefined && grant.approver !== filter.approver) continue
|
|
288
|
+
results.push(clone(grant))
|
|
289
|
+
}
|
|
290
|
+
return results
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/** Newest-first audit events, capped by `limit` (default 100). */
|
|
294
|
+
audit(limit = 100) {
|
|
295
|
+
if (!Number.isInteger(limit) || limit < 1) fail('E_LIMIT', 'limit must be a positive integer')
|
|
296
|
+
return this.store.auditLog.slice(-limit).reverse().map(entry => clone(entry))
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
const OUTPUT = {
|
|
301
|
+
schema: { type: 'object', additionalProperties: true },
|
|
302
|
+
render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
const SCOPE_SCHEMA = {
|
|
306
|
+
description: 'Granted scope: "*", an exact string, a "prefix:*" pattern, or an array of these.',
|
|
307
|
+
anyOf: [
|
|
308
|
+
{ type: 'string' },
|
|
309
|
+
{ type: 'array', items: { type: 'string' }, minItems: 1 },
|
|
310
|
+
],
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Plain ToolDefinition objects; no dependency on `@deepseek-ai/dsh-tools`. */
|
|
314
|
+
export function createTools(service) {
|
|
315
|
+
return [
|
|
316
|
+
{
|
|
317
|
+
name: 'allow_issue',
|
|
318
|
+
description: 'Issue a revocable capability grant and return it. Grants expire (default 24h, max 30 days).',
|
|
319
|
+
parameters: {
|
|
320
|
+
type: 'object',
|
|
321
|
+
additionalProperties: false,
|
|
322
|
+
properties: {
|
|
323
|
+
subject: { type: 'string', description: 'Who receives the grant, e.g. "agent:planner" or "plugin:dsh-act".' },
|
|
324
|
+
capability: { type: 'string', description: 'Capability name, e.g. "fs.write" or "tool.invoke".' },
|
|
325
|
+
scope: SCOPE_SCHEMA,
|
|
326
|
+
ttlMs: { type: 'number', minimum: 1, maximum: MAX_TTL_MS, description: 'Lifetime in milliseconds (default 24h, max 30 days).' },
|
|
327
|
+
approver: { type: 'string', description: 'Who approved it (default "user").' },
|
|
328
|
+
},
|
|
329
|
+
required: ['subject', 'capability'],
|
|
330
|
+
},
|
|
331
|
+
output: OUTPUT,
|
|
332
|
+
async execute(args) {
|
|
333
|
+
return service.issue(args)
|
|
334
|
+
},
|
|
335
|
+
},
|
|
336
|
+
{
|
|
337
|
+
name: 'allow_check',
|
|
338
|
+
description: 'Check whether an active grant covers subject + capability + scope. Does not throw when denied.',
|
|
339
|
+
parameters: {
|
|
340
|
+
type: 'object',
|
|
341
|
+
additionalProperties: false,
|
|
342
|
+
properties: {
|
|
343
|
+
subject: { type: 'string' },
|
|
344
|
+
capability: { type: 'string' },
|
|
345
|
+
scope: SCOPE_SCHEMA,
|
|
346
|
+
},
|
|
347
|
+
required: ['subject', 'capability', 'scope'],
|
|
348
|
+
},
|
|
349
|
+
output: OUTPUT,
|
|
350
|
+
async execute(args) {
|
|
351
|
+
return service.check(args)
|
|
352
|
+
},
|
|
353
|
+
},
|
|
354
|
+
{
|
|
355
|
+
name: 'allow_revoke',
|
|
356
|
+
description: 'Revoke a grant by id. Idempotent for grants that are already revoked or expired.',
|
|
357
|
+
parameters: {
|
|
358
|
+
type: 'object',
|
|
359
|
+
additionalProperties: false,
|
|
360
|
+
properties: {
|
|
361
|
+
id: { type: 'string', description: 'Grant id returned by allow_issue.' },
|
|
362
|
+
},
|
|
363
|
+
required: ['id'],
|
|
364
|
+
},
|
|
365
|
+
output: OUTPUT,
|
|
366
|
+
async execute(args) {
|
|
367
|
+
return service.revoke(args.id)
|
|
368
|
+
},
|
|
369
|
+
},
|
|
370
|
+
{
|
|
371
|
+
name: 'allow_list',
|
|
372
|
+
description: 'List grants, optionally filtered by exact subject, capability, status or approver.',
|
|
373
|
+
parameters: {
|
|
374
|
+
type: 'object',
|
|
375
|
+
additionalProperties: false,
|
|
376
|
+
properties: {
|
|
377
|
+
subject: { type: 'string' },
|
|
378
|
+
capability: { type: 'string' },
|
|
379
|
+
status: { type: 'string', enum: ['active', 'revoked', 'expired'] },
|
|
380
|
+
approver: { type: 'string' },
|
|
381
|
+
},
|
|
382
|
+
},
|
|
383
|
+
output: OUTPUT,
|
|
384
|
+
async execute(args) {
|
|
385
|
+
return { grants: service.list(args) }
|
|
386
|
+
},
|
|
387
|
+
},
|
|
388
|
+
]
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Mount the service at `ctx.allow` and register the four agent tools. */
|
|
392
|
+
export function apply(ctx, config = {}) {
|
|
393
|
+
const service = new AllowService(ctx, config)
|
|
394
|
+
ctx.provide('allow', service)
|
|
395
|
+
if (ctx.tools && typeof ctx.tools.register === 'function') {
|
|
396
|
+
for (const tool of createTools(service)) ctx.tools.register(tool)
|
|
397
|
+
}
|
|
398
|
+
return service
|
|
399
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-allow",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "Revocable capability grants and an audit-ready permission center for DeepSeek Harness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -44,5 +44,8 @@
|
|
|
44
44
|
},
|
|
45
45
|
"publishConfig": {
|
|
46
46
|
"access": "public"
|
|
47
|
+
},
|
|
48
|
+
"scripts": {
|
|
49
|
+
"test": "node --test"
|
|
47
50
|
}
|
|
48
51
|
}
|