dsh-snip 0.1.0 → 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 +15 -0
- package/README.md +21 -9
- package/index.js +77 -28
- package/package.json +25 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Screen `sourceApp` for secrets and validate it: non-strings, control
|
|
6
|
+
characters, labels over 80 characters and secret-looking labels are rejected
|
|
7
|
+
with `SNIP_BAD_SOURCE_APP`; empty labels become `unknown`. Persisted
|
|
8
|
+
snapshots are re-sanitized on load.
|
|
9
|
+
- Persist before committing: `add`, `forget`, `clear` and expiry sweeps build
|
|
10
|
+
the next ledger state, write it, and only then replace memory. A failed write
|
|
11
|
+
now throws `SNIP_STATE_WRITE_FAILED` and leaves both memory and disk at the
|
|
12
|
+
previous state instead of letting them diverge.
|
|
13
|
+
- Confirm and test the redaction boundary: `search` only scans stored (already
|
|
14
|
+
redacted) text, and `forget` leaves no in-memory index or snapshot residue.
|
|
15
|
+
- Add failure-injection tests for a read-only state directory and regression
|
|
16
|
+
tests for `sourceApp`, search-after-redaction and forget-after-reload.
|
|
17
|
+
|
|
3
18
|
## 0.1.0
|
|
4
19
|
|
|
5
20
|
- Implement `SnipService` with `add`, `list`, `search`, `get`, `forget` and
|
package/README.md
CHANGED
|
@@ -3,14 +3,14 @@
|
|
|
3
3
|
> A local-first clipboard ledger for DeepSeek Harness with secret exclusion and
|
|
4
4
|
> `clipboard://` agent handles.
|
|
5
5
|
|
|
6
|
-
**Status: 0.1.
|
|
6
|
+
**Status: 0.1.1 (MVP). A ledger, not a background listener.** Snip records a
|
|
7
7
|
clipping only when a caller explicitly invokes `snip.add(...)` or the `snip_add`
|
|
8
|
-
agent tool. 0.1.
|
|
8
|
+
agent tool. 0.1.1 has no OS clipboard polling, no `snip_capture`, no network
|
|
9
9
|
access and no encryption yet. Secret-looking text is excluded by default.
|
|
10
10
|
Everything stays on this machine: entries live in process memory, plus an
|
|
11
11
|
optional local JSON snapshot when `stateFile` is configured.
|
|
12
12
|
|
|
13
|
-
In one sentence: **0.1.
|
|
13
|
+
In one sentence: **0.1.1 is a ledger, not a background listener; it excludes
|
|
14
14
|
secrets by default and stores clippings locally.**
|
|
15
15
|
|
|
16
16
|
**Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
|
|
@@ -43,7 +43,10 @@ snip.clear() // number removed
|
|
|
43
43
|
Supported kinds are `text`, `html`, `link` and `color`; sensitivities are
|
|
44
44
|
`normal`, `sensitive` and `secret` (`secret` always redacts). Handles are
|
|
45
45
|
`clipboard://<id>` and are accepted anywhere an id is accepted. `get()` returns
|
|
46
|
-
`null` for an unknown, expired or forgotten id.
|
|
46
|
+
`null` for an unknown, expired or forgotten id. `sourceApp` is trimmed, limited
|
|
47
|
+
to 80 characters and rejected with `SNIP_BAD_SOURCE_APP` when it is not a
|
|
48
|
+
string, contains control characters or matches a secret pattern; an empty label
|
|
49
|
+
becomes `unknown`.
|
|
47
50
|
|
|
48
51
|
## Agent tools
|
|
49
52
|
|
|
@@ -87,12 +90,21 @@ Expiry and the entry cap are applied automatically on `add`, `list`, `search`,
|
|
|
87
90
|
API keys.
|
|
88
91
|
- Detection is best-effort, not a guarantee. Set `excludeSecrets: false` to
|
|
89
92
|
opt out (not recommended). `sensitivity: 'secret'` is a caller-side override
|
|
90
|
-
that always redacts.
|
|
93
|
+
that always redacts. `sourceApp` is metadata, not a secret store: labels are
|
|
94
|
+
screened for the same patterns and rejected when they look like a secret,
|
|
95
|
+
independently of `excludeSecrets`.
|
|
96
|
+
- `search` only scans the stored text, so a redacted secret's original value
|
|
97
|
+
can never be found through search; `get` returns only `[redacted:<reason>]`.
|
|
98
|
+
`forget` deletes the map entry and the next snapshot, so no index residue or
|
|
99
|
+
on-disk copy remains.
|
|
91
100
|
- When `stateFile` is set, each mutation writes the snapshot through a
|
|
92
|
-
temporary file and `rename` (atomic replace, mode `0600`)
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
101
|
+
temporary file and `rename` (atomic replace, mode `0600`) **before** the
|
|
102
|
+
in-memory ledger is updated. If the write fails, the call throws
|
|
103
|
+
`SNIP_STATE_WRITE_FAILED` and both memory and disk keep the previous state.
|
|
104
|
+
The snapshot is plain JSON and is **not encrypted in 0.1.1** — protect it
|
|
105
|
+
like any local secret. A snapshot written with detection disabled is
|
|
106
|
+
re-screened on load, and bad `sourceApp` metadata is replaced with `unknown`.
|
|
107
|
+
- 0.1.1 performs no network I/O and does not read the OS clipboard. There is no
|
|
96
108
|
background capture, watcher or timer.
|
|
97
109
|
|
|
98
110
|
## Development
|
package/index.js
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* dsh-snip — local-first clipboard ledger for DeepSeek Harness.
|
|
3
3
|
*
|
|
4
|
-
* 0.1.
|
|
4
|
+
* 0.1.1 records explicit `add` calls only: no clipboard polling, no network,
|
|
5
5
|
* no encryption yet. Secret-looking text is not stored unless the caller
|
|
6
6
|
* explicitly disables `excludeSecrets`.
|
|
7
7
|
* @module dsh-snip
|
|
8
8
|
*/
|
|
9
9
|
import { randomUUID } from 'node:crypto'
|
|
10
|
-
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
|
|
10
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
|
|
11
11
|
import { dirname } from 'node:path'
|
|
12
12
|
|
|
13
13
|
export const name = 'dsh-snip'
|
|
@@ -16,6 +16,8 @@ export const inject = ['tools']
|
|
|
16
16
|
const DAY_MS = 86_400_000
|
|
17
17
|
const PREVIEW_CHARS = 140
|
|
18
18
|
const HANDLE_PREFIX = 'clipboard://'
|
|
19
|
+
const MAX_SOURCE_APP = 80
|
|
20
|
+
const CONTROL_CHARS = /[\u0000-\u001f\u007f]/
|
|
19
21
|
const KINDS = new Set(['text', 'html', 'link', 'color'])
|
|
20
22
|
const SENSITIVITIES = new Set(['normal', 'sensitive', 'secret'])
|
|
21
23
|
|
|
@@ -93,6 +95,36 @@ export function detectSecret(text) {
|
|
|
93
95
|
return null
|
|
94
96
|
}
|
|
95
97
|
|
|
98
|
+
/**
|
|
99
|
+
* Validate the source application label. Labels are metadata, never a secret
|
|
100
|
+
* store: anything secret-looking is rejected instead of silently stored.
|
|
101
|
+
*/
|
|
102
|
+
function normalizeSourceApp(value) {
|
|
103
|
+
if (value === undefined || value === null) return 'unknown'
|
|
104
|
+
if (typeof value !== 'string') throw fail('SNIP_BAD_SOURCE_APP', 'snip: sourceApp must be a string')
|
|
105
|
+
const label = value.trim()
|
|
106
|
+
if (label === '') return 'unknown'
|
|
107
|
+
if (label.length > MAX_SOURCE_APP) {
|
|
108
|
+
throw fail('SNIP_BAD_SOURCE_APP', `snip: sourceApp must be at most ${MAX_SOURCE_APP} characters`)
|
|
109
|
+
}
|
|
110
|
+
if (CONTROL_CHARS.test(label)) {
|
|
111
|
+
throw fail('SNIP_BAD_SOURCE_APP', 'snip: sourceApp must not contain control characters')
|
|
112
|
+
}
|
|
113
|
+
if (detectSecret(label)) {
|
|
114
|
+
throw fail('SNIP_BAD_SOURCE_APP', 'snip: sourceApp must not contain secret-looking text')
|
|
115
|
+
}
|
|
116
|
+
return label
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** Loading a snapshot tolerates bad metadata: drop it instead of failing mount. */
|
|
120
|
+
function safeSourceApp(value) {
|
|
121
|
+
try {
|
|
122
|
+
return normalizeSourceApp(value)
|
|
123
|
+
} catch {
|
|
124
|
+
return 'unknown'
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
96
128
|
/** In-memory ledger with optional atomic JSON snapshot. */
|
|
97
129
|
export class SnipService {
|
|
98
130
|
#entries = new Map()
|
|
@@ -109,10 +141,13 @@ export class SnipService {
|
|
|
109
141
|
this.#maxEntries = positiveInt(config.maxEntries, 200)
|
|
110
142
|
this.#maxBytes = positiveInt(config.maxBytes, 64 * 1024)
|
|
111
143
|
this.#excludeSecrets = config.excludeSecrets !== false
|
|
112
|
-
this.#now = typeof config.now === 'function' ? config.now : Date.now
|
|
144
|
+
this.#now = typeof config.now === 'function' ? config.now : () => Date.now()
|
|
113
145
|
this.#stateFile = typeof config.stateFile === 'string' && config.stateFile.length > 0 ? config.stateFile : null
|
|
114
146
|
if (this.#stateFile) this.#load()
|
|
115
|
-
|
|
147
|
+
const next = new Map(this.#entries)
|
|
148
|
+
const swept = this.#sweep(next)
|
|
149
|
+
if (this.#stateFile) this.#commit(next)
|
|
150
|
+
else if (swept > 0) this.#entries = next
|
|
116
151
|
}
|
|
117
152
|
|
|
118
153
|
/** Store one clipping; return its stable handle and metadata. */
|
|
@@ -133,8 +168,7 @@ export class SnipService {
|
|
|
133
168
|
if (typeof sensitivity !== 'string' || !SENSITIVITIES.has(sensitivity)) {
|
|
134
169
|
throw fail('SNIP_BAD_SENSITIVITY', 'snip: unsupported sensitivity')
|
|
135
170
|
}
|
|
136
|
-
const
|
|
137
|
-
const sourceApp = (rawSource || 'unknown').slice(0, 80)
|
|
171
|
+
const sourceApp = normalizeSourceApp(args.sourceApp)
|
|
138
172
|
|
|
139
173
|
const reason = sensitivity === 'secret'
|
|
140
174
|
? 'sensitivity'
|
|
@@ -153,17 +187,18 @@ export class SnipService {
|
|
|
153
187
|
redacted: reason !== null,
|
|
154
188
|
}
|
|
155
189
|
|
|
156
|
-
this.#
|
|
157
|
-
this.#
|
|
158
|
-
|
|
159
|
-
this.#
|
|
190
|
+
const next = new Map(this.#entries)
|
|
191
|
+
this.#sweep(next)
|
|
192
|
+
next.set(entry.id, entry)
|
|
193
|
+
this.#enforceMax(next)
|
|
194
|
+
this.#commit(next)
|
|
160
195
|
return summaryOf(entry)
|
|
161
196
|
}
|
|
162
197
|
|
|
163
198
|
/** Newest-first summaries, optionally filtered by kind. */
|
|
164
199
|
list(options = {}) {
|
|
165
200
|
const args = options ?? {}
|
|
166
|
-
|
|
201
|
+
this.#sweepAndCommit()
|
|
167
202
|
const kind = typeof args.kind === 'string' && args.kind.length > 0 ? args.kind : null
|
|
168
203
|
return [...this.#entries.values()]
|
|
169
204
|
.reverse()
|
|
@@ -176,7 +211,7 @@ export class SnipService {
|
|
|
176
211
|
search(query, options = {}) {
|
|
177
212
|
const needle = typeof query === 'string' ? query.trim().toLowerCase() : ''
|
|
178
213
|
if (!needle) throw fail('SNIP_BAD_QUERY', 'snip: query must be a non-empty string')
|
|
179
|
-
|
|
214
|
+
this.#sweepAndCommit()
|
|
180
215
|
return [...this.#entries.values()]
|
|
181
216
|
.reverse()
|
|
182
217
|
.filter(entry => entry.text.toLowerCase().includes(needle))
|
|
@@ -187,7 +222,7 @@ export class SnipService {
|
|
|
187
222
|
/** Full entry (including text) by id or `clipboard://` handle; null if absent. */
|
|
188
223
|
get(idOrHandle) {
|
|
189
224
|
const id = resolveId(idOrHandle)
|
|
190
|
-
|
|
225
|
+
this.#sweepAndCommit()
|
|
191
226
|
const entry = this.#entries.get(id)
|
|
192
227
|
if (!entry) return null
|
|
193
228
|
return {
|
|
@@ -201,36 +236,43 @@ export class SnipService {
|
|
|
201
236
|
/** Delete one entry by id or handle; true when it existed. */
|
|
202
237
|
forget(idOrHandle) {
|
|
203
238
|
const id = resolveId(idOrHandle)
|
|
204
|
-
const
|
|
205
|
-
const
|
|
206
|
-
|
|
239
|
+
const next = new Map(this.#entries)
|
|
240
|
+
const swept = this.#sweep(next)
|
|
241
|
+
const removed = next.delete(id)
|
|
242
|
+
if (removed || swept > 0) this.#commit(next)
|
|
207
243
|
return removed
|
|
208
244
|
}
|
|
209
245
|
|
|
210
246
|
/** Delete every entry; return the number removed. */
|
|
211
247
|
clear() {
|
|
212
248
|
const removed = this.#entries.size
|
|
213
|
-
this.#
|
|
214
|
-
if (removed) this.#persist()
|
|
249
|
+
if (removed > 0) this.#commit(new Map())
|
|
215
250
|
return removed
|
|
216
251
|
}
|
|
217
252
|
|
|
218
|
-
|
|
253
|
+
/** Sweep expired/overflowing entries; commit only when something changed. */
|
|
254
|
+
#sweepAndCommit() {
|
|
255
|
+
const next = new Map(this.#entries)
|
|
256
|
+
if (this.#sweep(next) === 0) return
|
|
257
|
+
this.#commit(next)
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
#sweep(entries = this.#entries) {
|
|
219
261
|
const now = this.#now()
|
|
220
262
|
let removed = 0
|
|
221
|
-
for (const [id, entry] of
|
|
263
|
+
for (const [id, entry] of entries) {
|
|
222
264
|
if (Date.parse(entry.expiresAt) <= now) {
|
|
223
|
-
|
|
265
|
+
entries.delete(id)
|
|
224
266
|
removed += 1
|
|
225
267
|
}
|
|
226
268
|
}
|
|
227
|
-
return removed + this.#enforceMax()
|
|
269
|
+
return removed + this.#enforceMax(entries)
|
|
228
270
|
}
|
|
229
271
|
|
|
230
|
-
#enforceMax() {
|
|
272
|
+
#enforceMax(entries = this.#entries) {
|
|
231
273
|
let removed = 0
|
|
232
|
-
while (
|
|
233
|
-
|
|
274
|
+
while (entries.size > this.#maxEntries) {
|
|
275
|
+
entries.delete(entries.keys().next().value)
|
|
234
276
|
removed += 1
|
|
235
277
|
}
|
|
236
278
|
return removed
|
|
@@ -260,7 +302,7 @@ export class SnipService {
|
|
|
260
302
|
kind: KINDS.has(raw.kind) ? raw.kind : 'text',
|
|
261
303
|
text,
|
|
262
304
|
preview: previewOf(text),
|
|
263
|
-
sourceApp:
|
|
305
|
+
sourceApp: safeSourceApp(raw.sourceApp),
|
|
264
306
|
sensitivity,
|
|
265
307
|
createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : new Date(this.#now()).toISOString(),
|
|
266
308
|
expiresAt: typeof raw.expiresAt === 'string' ? raw.expiresAt : new Date(this.#now() + this.#ttlMs).toISOString(),
|
|
@@ -269,15 +311,22 @@ export class SnipService {
|
|
|
269
311
|
}
|
|
270
312
|
}
|
|
271
313
|
|
|
272
|
-
|
|
314
|
+
/** Write `next` first; only replace live state after the snapshot lands. */
|
|
315
|
+
#commit(next) {
|
|
316
|
+
this.#persist(next)
|
|
317
|
+
this.#entries = next
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
#persist(entries = this.#entries) {
|
|
273
321
|
if (!this.#stateFile) return
|
|
274
|
-
const payload = `${JSON.stringify({ version: 1, entries: [...
|
|
322
|
+
const payload = `${JSON.stringify({ version: 1, entries: [...entries.values()] }, null, 2)}\n`
|
|
275
323
|
const temp = `${this.#stateFile}.${process.pid}.${randomUUID()}.tmp`
|
|
276
324
|
try {
|
|
277
325
|
mkdirSync(dirname(this.#stateFile), { recursive: true, mode: 0o700 })
|
|
278
326
|
writeFileSync(temp, payload, { mode: 0o600 })
|
|
279
327
|
renameSync(temp, this.#stateFile)
|
|
280
328
|
} catch (error) {
|
|
329
|
+
try { rmSync(temp, { force: true }) } catch {}
|
|
281
330
|
throw fail('SNIP_STATE_WRITE_FAILED', `snip: cannot write state file: ${error.message}`)
|
|
282
331
|
}
|
|
283
332
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-snip",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Local-first, searchable clipboard ledger for DeepSeek Harness with secret exclusion and clipboard:// agent handles.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -39,15 +39,37 @@
|
|
|
39
39
|
},
|
|
40
40
|
"engines": {
|
|
41
41
|
"node": "^22.19.0 || >=24.9.0",
|
|
42
|
-
"dsh": ">=0.2.1-rc.2 <0.3.0
|
|
42
|
+
"dsh": ">=0.2.1-rc.2 <0.3.0-0"
|
|
43
43
|
},
|
|
44
44
|
"dsh": {
|
|
45
45
|
"manifestVersion": 1,
|
|
46
46
|
"bundle": {
|
|
47
47
|
"patch": "./cordis.patch.yml"
|
|
48
|
+
},
|
|
49
|
+
"os": {
|
|
50
|
+
"service": "snip",
|
|
51
|
+
"provides": [
|
|
52
|
+
"snip"
|
|
53
|
+
],
|
|
54
|
+
"capabilities": [
|
|
55
|
+
"clipboard",
|
|
56
|
+
"secret"
|
|
57
|
+
],
|
|
58
|
+
"tools": [
|
|
59
|
+
"snip_add",
|
|
60
|
+
"snip_search",
|
|
61
|
+
"snip_get",
|
|
62
|
+
"snip_list",
|
|
63
|
+
"snip_forget",
|
|
64
|
+
"snip_clear"
|
|
65
|
+
],
|
|
66
|
+
"ui": null,
|
|
67
|
+
"stability": "experimental",
|
|
68
|
+
"since": "0.1.0"
|
|
48
69
|
}
|
|
49
70
|
},
|
|
50
71
|
"publishConfig": {
|
|
51
|
-
"access": "public"
|
|
72
|
+
"access": "public",
|
|
73
|
+
"registry": "https://registry.npmjs.org/"
|
|
52
74
|
}
|
|
53
75
|
}
|