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.
Files changed (4) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +21 -9
  3. package/index.js +77 -28
  4. 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.0 (MVP). A ledger, not a background listener.** Snip records a
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.0 has no OS clipboard polling, no `snip_capture`, no network
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.0 is a ledger, not a background listener; it excludes
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`). The snapshot is
93
- plain JSON and is **not encrypted in 0.1.0** — protect it like any local
94
- secret. A snapshot written with detection disabled is re-screened on load.
95
- - 0.1.0 performs no network I/O and does not read the OS clipboard. There is no
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.0 records explicit `add` calls only: no clipboard polling, no network,
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
- if (this.#sweep() || this.#stateFile) this.#persist()
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 rawSource = typeof args.sourceApp === 'string' ? args.sourceApp.trim() : ''
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.#sweep()
157
- this.#entries.set(entry.id, entry)
158
- this.#enforceMax()
159
- this.#persist()
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
- if (this.#sweep()) this.#persist()
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
- if (this.#sweep()) this.#persist()
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
- if (this.#sweep()) this.#persist()
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 swept = this.#sweep()
205
- const removed = this.#entries.delete(id)
206
- if (removed || swept) this.#persist()
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.#entries.clear()
214
- if (removed) this.#persist()
249
+ if (removed > 0) this.#commit(new Map())
215
250
  return removed
216
251
  }
217
252
 
218
- #sweep() {
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 this.#entries) {
263
+ for (const [id, entry] of entries) {
222
264
  if (Date.parse(entry.expiresAt) <= now) {
223
- this.#entries.delete(id)
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 (this.#entries.size > this.#maxEntries) {
233
- this.#entries.delete(this.#entries.keys().next().value)
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: typeof raw.sourceApp === 'string' ? raw.sourceApp : 'unknown',
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
- #persist() {
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: [...this.#entries.values()] }, null, 2)}\n`
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.0",
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 || >=0.2.2-0 <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
  }