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.
- package/CHANGELOG.md +31 -0
- package/README.md +141 -7
- package/index.js +427 -5
- 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.
|
|
6
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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) { 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.
|
|
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
|
|
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
|
}
|