dsh-vision-router 3.2.1 → 3.4.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.
Files changed (43) hide show
  1. package/README.md +5 -4
  2. package/README.zh.md +20 -3
  3. package/THIRD_PARTY_NOTICES.md +60 -0
  4. package/assets/licenses/llvm-mingw-LICENSE.txt +279 -0
  5. package/assets/licenses/mingw-w64-runtime-COPYING.txt +265 -0
  6. package/assets/licenses/ncnn-LICENSE.txt +86 -0
  7. package/docs/architecture/dsh-support-window.md +25 -6
  8. package/docs/compatibility/dsh-0.2.2-rc3-audit.md +131 -0
  9. package/docs/releases/v3.2.2.md +25 -0
  10. package/docs/releases/v3.3.0.md +34 -0
  11. package/docs/releases/v3.4.0.md +41 -0
  12. package/index.js +313 -169
  13. package/lib/client.js +4 -4
  14. package/lib/core-primitives.js +115 -56
  15. package/lib/dsh-support-window.js +6 -3
  16. package/lib/maintenance-routes.js +2 -0
  17. package/lib/managed-tesseract-child.js +33 -0
  18. package/lib/native-ocr-annotation-risk.js +33 -0
  19. package/lib/native-ocr-canary.js +156 -0
  20. package/lib/native-ocr-chemistry-review.js +37 -0
  21. package/lib/native-ocr-document.js +243 -0
  22. package/lib/native-ocr-installation.js +17 -0
  23. package/lib/native-ocr-integrity.js +93 -0
  24. package/lib/native-ocr-question-labels.js +167 -0
  25. package/lib/native-ocr-supervisor.js +268 -0
  26. package/lib/optional-ocr-engines.js +330 -0
  27. package/lib/optional-ocr-routes.js +87 -0
  28. package/lib/runtime-reliability.js +7 -0
  29. package/lib/session-query-readers.js +8 -2
  30. package/lib/session-vision-attachment-index.js +61 -14
  31. package/lib/settings-ia-client-prelude.js +56 -2
  32. package/lib/tesseract-image-preprocess.js +35 -0
  33. package/lib/trace-vtracer-process-runtime.js +133 -0
  34. package/lib/trace-vtracer-process.js +43 -0
  35. package/lib/vision-attachment-handle-runtime.js +11 -2
  36. package/lib/vision-backend-runtime-policy.js +5 -3
  37. package/lib/vision-image-input-reader.js +67 -0
  38. package/lib/vision-image-input-verdict.js +24 -3
  39. package/lib/vision-tool-runtime-boundary.js +7 -10
  40. package/lib/vision-tool-stage.js +58 -0
  41. package/lib/web-capability-boundary.js +4 -0
  42. package/package.json +5 -4
  43. package/scripts/install-native-ocr.mjs +144 -0
@@ -0,0 +1,268 @@
1
+ import { spawn } from 'node:child_process'
2
+ import { isAbsolute } from 'node:path'
3
+ import { performance } from 'node:perf_hooks'
4
+
5
+ const DEFAULT_TIMEOUT_MS = 12_000
6
+ const MAX_TIMEOUT_MS = 30_000
7
+ const MAX_INPUT_BYTES = 24 * 1024 * 1024
8
+ const MAX_OUTPUT_BYTES = 2 * 1024 * 1024
9
+ const MAX_IMAGE_PIXELS = 4_000_000
10
+ const MAX_IMAGE_SIDE = 4096
11
+ const MAX_ACTIVE_WORKERS = 2
12
+ const MAX_QUEUED_WORKERS = 16
13
+ let activeWorkers = 0
14
+ const waitingWorkers = []
15
+
16
+ function releaseNextWorker() {
17
+ while (waitingWorkers.length > 0) {
18
+ const next = waitingWorkers.shift()
19
+ if (next.finished) continue
20
+ next.finished = true
21
+ clearTimeout(next.timer)
22
+ next.signal?.removeEventListener('abort', next.abort)
23
+ activeWorkers++
24
+ next.resolve(makeReleaseWorker())
25
+ break
26
+ }
27
+ }
28
+ function makeReleaseWorker() {
29
+ let used = false
30
+ return () => {
31
+ if (used) return
32
+ used = true
33
+ activeWorkers--
34
+ releaseNextWorker()
35
+ }
36
+ }
37
+ function acquireWorker(signal, waitMs) {
38
+ if (signal?.aborted) return Promise.reject(error('OCR_CANCELLED', 'OCR cancelled'))
39
+ if (activeWorkers < MAX_ACTIVE_WORKERS) {
40
+ activeWorkers++
41
+ return Promise.resolve(makeReleaseWorker())
42
+ }
43
+ if (waitingWorkers.length >= MAX_QUEUED_WORKERS) {
44
+ return Promise.reject(error('OCR_BUSY', 'local OCR worker queue is full'))
45
+ }
46
+ return new Promise((resolve, reject) => {
47
+ const task = { resolve, reject, signal, finished: false, timer: undefined, abort: undefined }
48
+ const fail = (code, message) => {
49
+ if (task.finished) return
50
+ task.finished = true
51
+ clearTimeout(task.timer)
52
+ signal?.removeEventListener('abort', task.abort)
53
+ const index = waitingWorkers.indexOf(task)
54
+ if (index !== -1) waitingWorkers.splice(index, 1)
55
+ reject(error(code, message))
56
+ }
57
+ task.abort = () => fail('OCR_CANCELLED', 'OCR cancelled')
58
+ task.timer = setTimeout(() => fail('OCR_QUEUE_TIMEOUT', 'local OCR queue deadline exhausted'), waitMs)
59
+ task.timer.unref?.()
60
+ waitingWorkers.push(task)
61
+ signal?.addEventListener('abort', task.abort, { once: true })
62
+ if (signal?.aborted) task.abort()
63
+ })
64
+ }
65
+
66
+ /**
67
+ * In-memory, validated RGB24 transport for the native worker.
68
+ * Image decoders remain Host-owned (sharp); native inference never parses
69
+ * arbitrary PNG/JPEG/WebP bytes or reads user-controlled filesystem paths.
70
+ */
71
+ export function encodeNativeOcrRgbFrame(rgb, width, height) {
72
+ if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) ||
73
+ width < 1 || height < 1 ||
74
+ width > MAX_IMAGE_SIDE || height > MAX_IMAGE_SIDE ||
75
+ width * height > MAX_IMAGE_PIXELS) {
76
+ throw error('OCR_INVALID_DIMENSIONS', 'invalid local OCR image dimensions')
77
+ }
78
+ if (!(rgb instanceof Uint8Array) || rgb.byteLength !== width * height * 3) {
79
+ throw error('OCR_INVALID_RGB', 'invalid local OCR RGB pixel buffer')
80
+ }
81
+ const frame = Buffer.allocUnsafe(20 + rgb.byteLength)
82
+ frame.write('DVR3OCR1', 0, 'ascii')
83
+ frame.writeUInt32LE(width, 8)
84
+ frame.writeUInt32LE(height, 12)
85
+ frame.writeUInt32LE(rgb.byteLength, 16)
86
+ frame.set(rgb, 20)
87
+ return frame
88
+ }
89
+
90
+ export class LocalOcrProcessError extends Error {
91
+ constructor(code, message) {
92
+ super(message)
93
+ this.name = 'LocalOcrProcessError'
94
+ this.code = code
95
+ }
96
+ }
97
+
98
+ function error(code, message) {
99
+ return new LocalOcrProcessError(code, message)
100
+ }
101
+
102
+ function isValidOcrResult(value) {
103
+ return value !== null &&
104
+ typeof value === 'object' &&
105
+ !Array.isArray(value) &&
106
+ typeof value.text === 'string' &&
107
+ value.text.length <= 250_000 &&
108
+ (value.confidence === undefined || (
109
+ typeof value.confidence === 'number' &&
110
+ Number.isFinite(value.confidence) &&
111
+ value.confidence >= 0 && value.confidence <= 1
112
+ )) &&
113
+ (value.uncertain === undefined || typeof value.uncertain === 'boolean')
114
+ }
115
+
116
+ /**
117
+ * Experimental stability boundary. Does not enable/replace the production OCR engine.
118
+ * The caller must provide a trusted, package-owned absolute executable path.
119
+ * The native executable reads image bytes from stdin and writes one JSON result to stdout.
120
+ *
121
+ * No shell, no image path, no implicit cloud fallback, no inherited credentials.
122
+ */
123
+ function runIsolatedLocalOcrProcess(imageBytes, {
124
+ executable,
125
+ args = [],
126
+ timeoutMs = DEFAULT_TIMEOUT_MS,
127
+ signal,
128
+ maxOutputBytes = MAX_OUTPUT_BYTES,
129
+ } = {}) {
130
+ if (!Buffer.isBuffer(imageBytes) || imageBytes.length === 0 || imageBytes.length > MAX_INPUT_BYTES) {
131
+ return Promise.reject(error('OCR_INVALID_INPUT', 'invalid OCR image size'))
132
+ }
133
+ if (typeof executable !== 'string' || !isAbsolute(executable) || executable.includes('\0')) {
134
+ return Promise.reject(error('OCR_UNTRUSTED_RUNNER', 'OCR executable path must be absolute and trusted'))
135
+ }
136
+ if (!Array.isArray(args) || args.some((value) => typeof value !== 'string' || value.includes('\0'))) {
137
+ return Promise.reject(error('OCR_INVALID_ARGUMENTS', 'invalid OCR executable arguments'))
138
+ }
139
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
140
+ return Promise.reject(error('OCR_INVALID_TIMEOUT', 'invalid OCR timeout'))
141
+ }
142
+ const deadlineMs = Math.max(1, Math.min(Math.floor(timeoutMs), MAX_TIMEOUT_MS))
143
+ const limit = Number.isSafeInteger(maxOutputBytes) && maxOutputBytes > 0
144
+ ? Math.min(maxOutputBytes, MAX_OUTPUT_BYTES)
145
+ : MAX_OUTPUT_BYTES
146
+ if (signal?.aborted) return Promise.reject(error('OCR_CANCELLED', 'OCR cancelled'))
147
+
148
+ return new Promise((resolve, reject) => {
149
+ let done = false
150
+ let child
151
+ let timer
152
+ let size = 0
153
+ const buffers = []
154
+ let spawnFailure = false
155
+
156
+ const terminate = () => {
157
+ try { child?.kill('SIGKILL') } catch {}
158
+ }
159
+ const abort = () => {
160
+ terminate()
161
+ settle(error('OCR_CANCELLED', 'OCR cancelled'))
162
+ }
163
+ const settle = (failure, result) => {
164
+ if (done) return
165
+ done = true
166
+ if (timer !== undefined) clearTimeout(timer)
167
+ signal?.removeEventListener('abort', abort)
168
+ if (failure) reject(failure)
169
+ else resolve(result)
170
+ }
171
+
172
+ try {
173
+ // Limit the environment to OS runtime variables, not secrets or user-provided
174
+ // proxy/configuration variables. The executable MUST be bundled and self-contained.
175
+ const env = {}
176
+ for (const name of ['SystemRoot', 'WINDIR', 'TEMP', 'TMP', 'TMPDIR', 'HOME', 'LANG', 'LC_ALL']) {
177
+ if (typeof process.env[name] === 'string') env[name] = process.env[name]
178
+ }
179
+ // Linux worker registers PR_SET_PDEATHSIG before reading RGB input.
180
+ // A non-secret expected PID closes the fork/exec vs parent-SIGKILL race.
181
+ if (process.platform === 'linux') env.DVR_OCR_PARENT_PID = String(process.pid)
182
+ child = spawn(executable, args, {
183
+ shell: false,
184
+ windowsHide: true,
185
+ stdio: ['pipe', 'pipe', 'pipe'],
186
+ env,
187
+ })
188
+ } catch {
189
+ settle(error('OCR_SPAWN_FAILED', 'unable to start local OCR worker'))
190
+ return
191
+ }
192
+
193
+ signal?.addEventListener('abort', abort, { once: true })
194
+ timer = setTimeout(() => {
195
+ terminate()
196
+ settle(error('OCR_TIMEOUT', 'local OCR worker exceeded its deadline'))
197
+ }, deadlineMs)
198
+ timer.unref?.()
199
+
200
+ child.on('error', () => {
201
+ spawnFailure = true
202
+ settle(error('OCR_SPAWN_FAILED', 'unable to start local OCR worker'))
203
+ })
204
+ // Some platforms write EPIPE after the worker exits early. Its exit status,
205
+ // not this stream error, determines the OCR result.
206
+ child.stdin.on('error', () => {})
207
+ child.stderr.on('data', () => {}) // Never leak native stderr or sensitive images.
208
+ child.stdout.on('data', (chunk) => {
209
+ if (done) return
210
+ size += chunk.length
211
+ if (size > limit) {
212
+ terminate()
213
+ settle(error('OCR_OUTPUT_LIMIT', 'local OCR output exceeded the size limit'))
214
+ return
215
+ }
216
+ buffers.push(chunk)
217
+ })
218
+ child.on('close', (exitCode, exitSignal) => {
219
+ if (done) return
220
+ if (spawnFailure || exitCode !== 0 || exitSignal !== null) {
221
+ settle(error('OCR_WORKER_FAILED', 'local OCR worker exited unsuccessfully'))
222
+ return
223
+ }
224
+ try {
225
+ const result = JSON.parse(Buffer.concat(buffers, size).toString('utf8'))
226
+ if (!isValidOcrResult(result)) {
227
+ settle(error('OCR_INVALID_RESULT', 'local OCR returned an invalid result'))
228
+ return
229
+ }
230
+ settle(undefined, { ...result, engine: 'ncnn' })
231
+ } catch {
232
+ settle(error('OCR_INVALID_RESULT', 'local OCR returned invalid JSON'))
233
+ }
234
+ })
235
+ if (signal?.aborted) {
236
+ abort()
237
+ return
238
+ }
239
+ child.stdin.end(imageBytes)
240
+ })
241
+ }
242
+
243
+ /**
244
+ * At most two native model instances can execute simultaneously. All other
245
+ * requests wait in a bounded, abortable FIFO. This protects the Host against
246
+ * a burst of 100+ concurrent images creating hundreds of native model copies.
247
+ */
248
+ export async function runIsolatedLocalOcr(imageBytes, options = {}) {
249
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
250
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
251
+ throw error('OCR_INVALID_TIMEOUT', 'invalid OCR timeout')
252
+ }
253
+ const budgetMs = Math.max(1, Math.min(Math.floor(timeoutMs), MAX_TIMEOUT_MS))
254
+ const started = performance.now()
255
+ const release = await acquireWorker(options.signal, budgetMs)
256
+ try {
257
+ const remainingMs = budgetMs - (performance.now() - started)
258
+ if (remainingMs <= 0) {
259
+ throw error('OCR_QUEUE_TIMEOUT', 'local OCR queue deadline exhausted')
260
+ }
261
+ return await runIsolatedLocalOcrProcess(imageBytes, {
262
+ ...options,
263
+ timeoutMs: remainingMs,
264
+ })
265
+ } finally {
266
+ release()
267
+ }
268
+ }
@@ -0,0 +1,330 @@
1
+ import { createHash, randomUUID } from 'node:crypto'
2
+ import { spawn, spawnSync } from 'node:child_process'
3
+ import { lstat, mkdir, readFile, writeFile, copyFile, rename, rm, chmod } from 'node:fs/promises'
4
+ import { existsSync } from 'node:fs'
5
+ import { homedir, tmpdir } from 'node:os'
6
+ import { join, dirname, delimiter } from 'node:path'
7
+ import { fileURLToPath, pathToFileURL } from 'node:url'
8
+ import { localNativeOcrInstallPaths } from './native-ocr-installation.js'
9
+ import { verifyExperimentalNativeOcrBinary } from './native-ocr-canary.js'
10
+ import { verifyNativeOcrAssets } from './native-ocr-integrity.js'
11
+
12
+ // Optional by design. Do not modify the DSH profile or global system packages.
13
+ // npm downloads happen only after a local user explicitly selects Install.
14
+ export const OPTIONAL_TESSERACT_PACKAGES = Object.freeze({
15
+ 'tesseract.js': ['7.0.0', 'sha512-exPBkd+z+wM1BuMkx/Bjv43OeLBxhL5kKWsz/9JY+DXcXdiBjiAch0V49QR3oAJqCaL5qURE0vx9Eo+G5YE7mA=='],
16
+ '@tesseract.js-data/chi_sim': ['1.0.0', 'sha512-iuErURkPbECDUazgsLn/r3c+tU2y5o5S/w14d0A/YiagfsjYyZKgTo75RUpsGJ311qtu0dIX4hqnXAAjmqf2CA=='],
17
+ '@tesseract.js-data/eng': ['1.0.0', 'sha512-mbTumm6KQPUHyzTPQaF3ObXYnx0SqqfV2nabqFVQBwD6Kl7PhGSLSzOlfFTWy0P3BjghaSKA2W9GB19Jk+ZcTg=='],
18
+ })
19
+ const TESS_LANGUAGES = Object.freeze({
20
+ chi_sim: Object.freeze({ bytes: 1718768, sha256: 'b8a23f10c7de500891eb458a8adc9cc58ab7f242f08b7d149f5e9aea4ad5db7c' }),
21
+ eng: Object.freeze({ bytes: 2952873, sha256: '45b4cb346724ac1774f1c36f42f182b887bcdb28ebe63e6fff90ac41f3fcff91' }),
22
+ })
23
+ const MANAGED_MARK = 'dvr-tesseract-js-v1'
24
+ const TESS_VERSION = '7.0.0'
25
+ const MAX_BINARY_UPLOAD = 64 * 1024 * 1024
26
+ const TESS_INSTALL_TIMEOUT_MS = 180_000
27
+ let mutating = false
28
+ let activeManagedRuns = 0
29
+ export const managedTesseractPaths = ({ home = homedir() } = {}) => {
30
+ const root = join(home, '.dsh-vision-router', 'ocr', 'tesseract-js')
31
+ return Object.freeze({ root, manifest: join(root, 'DVR-MANAGED.json'), models: join(root, 'models') })
32
+ }
33
+ const hash = bytes => createHash('sha256').update(bytes).digest('hex')
34
+ function installedLockRow(lock, name) {
35
+ const key = 'node_modules/' + name
36
+ // npm --prefix <absolute staging directory> can write canonicalized,
37
+ // prefix-relative lockfile keys (not just 'node_modules/...'). The package
38
+ // lock is moved atomically with the staged tree; resolve by exact suffix.
39
+ const rows = Object.entries(lock?.packages ?? {}).filter(([path]) =>
40
+ path === key || path.endsWith('/' + key))
41
+ return rows.length === 1 ? rows[0][1] : undefined
42
+ }
43
+ const readJSON = async path => JSON.parse(await readFile(path, 'utf8'))
44
+ async function regularFile(path, maxBytes = 20 * 1024 * 1024) {
45
+ try {
46
+ const st = await lstat(path)
47
+ return st.isFile() && !st.isSymbolicLink() && st.size > 0 && st.size <= maxBytes
48
+ } catch { return false }
49
+ }
50
+ async function directory(path) {
51
+ try { const st = await lstat(path); return st.isDirectory() && !st.isSymbolicLink() }
52
+ catch { return false }
53
+ }
54
+ async function ownedNativeDirectory(root) {
55
+ if (!await directory(root)) return false
56
+ const notice = join(root, 'SOURCE-NOTICE.md')
57
+ if (!await regularFile(notice, 32 * 1024)) return false
58
+ try {
59
+ const contents = await readFile(notice, 'utf8')
60
+ return contents.startsWith('# Locally installed native OCR assets\n') &&
61
+ contents.includes('Runtime: Tencent/ncnn @')
62
+ } catch { return false }
63
+ }
64
+ async function verifyManaged(root) {
65
+ const manifest = join(root, 'DVR-MANAGED.json')
66
+ if (!await directory(root) || !await regularFile(manifest, 4096)) return false
67
+ let marker
68
+ try { marker = await readJSON(manifest) } catch { return false }
69
+ if (marker?.kind !== MANAGED_MARK || marker.version !== TESS_VERSION) return false
70
+ const pkgs = marker.packages
71
+ for (const [name, [version, integrity]] of Object.entries(OPTIONAL_TESSERACT_PACKAGES)) {
72
+ if (pkgs?.[name]?.version !== version || pkgs?.[name]?.integrity !== integrity) return false
73
+ const base = join(root, 'node_modules', ...name.split('/'))
74
+ if (!await directory(base) || !await regularFile(join(base, 'package.json'), 200_000)) return false
75
+ let pkg
76
+ try { pkg = await readJSON(join(base, 'package.json')) } catch { return false }
77
+ if (pkg?.name !== name || pkg?.version !== version) return false
78
+ }
79
+ const lock = await readJSON(join(root, 'package-lock.json')).catch(() => null)
80
+ if (!lock?.packages) return false
81
+ for (const [name, [version, integrity]] of Object.entries(OPTIONAL_TESSERACT_PACKAGES)) {
82
+ const row = installedLockRow(lock, name)
83
+ if (row?.version !== version || row?.integrity !== integrity) return false
84
+ }
85
+ for (const [name, expected] of Object.entries(TESS_LANGUAGES)) {
86
+ const file = join(root, 'models', name + '.traineddata.gz')
87
+ if (!await regularFile(file, 10 * 1024 * 1024)) return false
88
+ const bytes = await readFile(file)
89
+ if (bytes.length !== expected.bytes || hash(bytes) !== expected.sha256) return false
90
+ }
91
+ return true
92
+ }
93
+ export async function systemTesseract() {
94
+ const probe = spawnSync('tesseract', ['--list-langs'], { encoding: 'utf8', timeout: 3000, windowsHide: true, maxBuffer: 16384 })
95
+ const names = (probe.stdout ?? '') + '\n' + (probe.stderr ?? '')
96
+ return probe.status === 0 && /(?:^|\s)chi_sim(?:\s|$)/.test(names) && /(?:^|\s)eng(?:\s|$)/.test(names)
97
+ }
98
+ export async function optionalOcrStatus({
99
+ home = homedir(),
100
+ probeSystem = systemTesseract,
101
+ resolveNativePaths = localNativeOcrInstallPaths,
102
+ } = {}) {
103
+ const tess = managedTesseractPaths({ home })
104
+ const pp = resolveNativePaths({ home })
105
+ const [managedTesseract, nativeReady, systemReady, nativeOwned] = await Promise.all([
106
+ verifyManaged(tess.root).catch(() => false),
107
+ pp && await directory(pp.root)
108
+ ? Promise.all([verifyExperimentalNativeOcrBinary(pp.binaryPath), verifyNativeOcrAssets(pp.modelDir)]).then(() => true, () => false)
109
+ : false,
110
+ Promise.resolve().then(() => probeSystem()).catch(() => false),
111
+ pp ? ownedNativeDirectory(pp.root) : false,
112
+ ])
113
+ return {
114
+ ok: true,
115
+ busy: mutating,
116
+ tesseract: { managedInstalled: managedTesseract, systemInstalled: !!systemReady, installed: managedTesseract || !!systemReady, canInstall: !mutating && !managedTesseract && !systemReady, canUninstall: !mutating && managedTesseract && activeManagedRuns === 0 },
117
+ ppocrv6: { installed: nativeReady, damaged: nativeOwned && !nativeReady, supported: !!pp, canInstallFromFile: !mutating && !!pp, canUninstall: !mutating && nativeOwned },
118
+ }
119
+ }
120
+ export function nodeChildEnvironment({ env = process.env, electron = process.versions?.electron } = {}) {
121
+ // Electron's process.execPath is the app executable. It must be launched
122
+ // with the supported Node mode; never inherit Host runtime preload flags.
123
+ return {
124
+ ...env, NODE_OPTIONS: '',
125
+ ...(electron ? { ELECTRON_RUN_AS_NODE: '1' } : {}),
126
+ }
127
+ }
128
+ async function npmCommand() {
129
+ if (process.platform !== 'win32') return { exe: 'npm', prefix: [] }
130
+ const searchDirs = [dirname(process.execPath),
131
+ ...String(process.env.PATH ?? '').split(delimiter)
132
+ .map(path => path.replace(/^["']|["']$/g, '').trim()).filter(Boolean)]
133
+ for (const base of [...new Set(searchDirs)]) {
134
+ const candidate = join(base, 'node_modules', 'npm', 'bin', 'npm-cli.js')
135
+ if (await regularFile(candidate, 100_000))
136
+ return { exe: process.execPath, prefix: [candidate] }
137
+ }
138
+ throw Error('npm CLI unavailable for portable Tesseract installation')
139
+ }
140
+ function execBounded(exe, args, { cwd, timeout = TESS_INSTALL_TIMEOUT_MS } = {}) {
141
+ return new Promise((resolve, reject) => {
142
+ const child = spawn(exe, args, { cwd, shell: false, windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'],
143
+ env: { ...nodeChildEnvironment({ electron: exe === process.execPath ? process.versions?.electron : undefined }), npm_config_update_notifier: 'false', npm_config_audit: 'false' } })
144
+ let log = ''
145
+ let settled = false
146
+ const finish = (error) => {
147
+ if (settled) return
148
+ settled = true
149
+ clearTimeout(timer)
150
+ if (error) reject(error)
151
+ else resolve()
152
+ }
153
+ child.stderr.on('data', chunk => { log = (log + String(chunk)).slice(-1200) })
154
+ child.on('error', error => finish(Error('optional OCR installer unavailable: ' + error.message)))
155
+ child.on('close', code => finish(code === 0 ? null : Error('optional OCR install failed (' + code + '): ' + log.slice(-400))))
156
+ const timer = setTimeout(() => {
157
+ child.kill()
158
+ finish(Error('optional OCR package installation timed out'))
159
+ }, timeout)
160
+ timer.unref?.()
161
+ })
162
+ }
163
+ async function assertOwned(root) {
164
+ if (!await directory(root)) throw Error('the OCR directory is not a real managed directory')
165
+ if (!await regularFile(join(root, 'DVR-MANAGED.json'), 4096)) throw Error('refusing to remove unowned OCR directory')
166
+ const marker = await readJSON(join(root, 'DVR-MANAGED.json'))
167
+ if (marker?.kind !== MANAGED_MARK) throw Error('refusing to remove unowned OCR installation')
168
+ }
169
+ export async function installTesseract({ home = homedir(), npm = npmCommand, exec = execBounded, probeSystem = systemTesseract } = {}) {
170
+ // A valid system installation already meets this optional capability.
171
+ // Do not download a second Tesseract implementation or touch system files.
172
+ if (await probeSystem()) return { ok: true, installed: false, reusedSystem: true, engine: 'tesseract' }
173
+ const dest = managedTesseractPaths({ home })
174
+ if (await directory(dest.root)) throw Error('Tesseract managed directory already exists; refusing to overwrite')
175
+ const parent = dirname(dest.root)
176
+ await mkdir(parent, { recursive: true, mode: 0o700 })
177
+ const stage = join(parent, '.tesseract-stage-' + randomUUID())
178
+ await mkdir(stage, { mode: 0o700 })
179
+ try {
180
+ const cli = await npm()
181
+ const packages = Object.entries(OPTIONAL_TESSERACT_PACKAGES).map(([name, [version]]) => name + '@' + version)
182
+ await exec(cli.exe, [...cli.prefix, 'install', ...packages, '--prefix', stage,
183
+ '--save-exact', '--ignore-scripts', '--no-audit', '--no-fund',
184
+ '--registry=https://registry.npmjs.org/', '--no-progress'], { cwd: stage })
185
+ await mkdir(join(stage, 'models'), { mode: 0o700 })
186
+ for (const [language, expected] of Object.entries(TESS_LANGUAGES)) {
187
+ const input = join(stage, 'node_modules', '@tesseract.js-data', language,
188
+ '4.0.0_best_int', language + '.traineddata.gz')
189
+ if (!await regularFile(input, 10 * 1024 * 1024)) throw Error('missing Tesseract language model: ' + language)
190
+ const raw = await readFile(input)
191
+ if (raw.length !== expected.bytes || hash(raw) !== expected.sha256) throw Error('Tesseract model integrity mismatch: ' + language)
192
+ const out = join(stage, 'models', language + '.traineddata.gz')
193
+ await copyFile(input, out)
194
+ await chmod(out, 0o600)
195
+ }
196
+ const packagesLock = await readJSON(join(stage, 'package-lock.json'))
197
+ for (const [name, [version, integrity]] of Object.entries(OPTIONAL_TESSERACT_PACKAGES)) {
198
+ const row = installedLockRow(packagesLock, name)
199
+ if (row?.version !== version || row?.integrity !== integrity) throw Error('untrusted npm package identity: ' + name)
200
+ }
201
+ await writeFile(join(stage, 'DVR-MANAGED.json'), JSON.stringify({
202
+ kind: MANAGED_MARK, version: TESS_VERSION,
203
+ packages: Object.fromEntries(Object.entries(OPTIONAL_TESSERACT_PACKAGES).map(([name, [version, integrity]]) => [name, { version, integrity }])),
204
+ }), { mode: 0o600 })
205
+ if (!await verifyManaged(stage)) throw Error('Tesseract installation verification failed')
206
+ await rename(stage, dest.root)
207
+ return { ok: true, installed: true, engine: 'tesseract' }
208
+ } finally { await rm(stage, { recursive: true, force: true }) }
209
+ }
210
+ export async function uninstallTesseract({ home = homedir() } = {}) {
211
+ if (activeManagedRuns > 0) throw Error('Tesseract is busy; retry after OCR completes')
212
+ const dest = managedTesseractPaths({ home })
213
+ await assertOwned(dest.root)
214
+ const tomb = dest.root + '.removing-' + randomUUID()
215
+ await rename(dest.root, tomb)
216
+ await rm(tomb, { recursive: true, force: true })
217
+ return { ok: true, installed: false, engine: 'tesseract' }
218
+ }
219
+ function nativeInstallerPath() {
220
+ // source checkout: src/lib -> repo/scripts; packed runtime: lib -> repo/scripts
221
+ const adjacent = fileURLToPath(new URL('../scripts/install-native-ocr.mjs', import.meta.url))
222
+ if (existsSync(adjacent)) return adjacent
223
+ return fileURLToPath(new URL('../../scripts/install-native-ocr.mjs', import.meta.url))
224
+ }
225
+ export async function installNativeBundle(bytes, { home = homedir(), exec = execBounded } = {}) {
226
+ const dest = localNativeOcrInstallPaths({ home })
227
+ if (!dest) throw Error('PP-OCRv6 is not approved for this platform')
228
+ if (!Buffer.isBuffer(bytes) || bytes.length < 128 || bytes.length > MAX_BINARY_UPLOAD) throw Error('invalid PP-OCRv6 archive')
229
+ const archive = join(tmpdir(), 'dvr-ocr-bundle-' + randomUUID() + '.tar.gz')
230
+ try {
231
+ await writeFile(archive, bytes, { mode: 0o600, flag: 'wx' })
232
+ await exec(process.execPath, [nativeInstallerPath(), '--bundle', archive], { timeout: 180_000 })
233
+ await verifyExperimentalNativeOcrBinary(dest.binaryPath)
234
+ await verifyNativeOcrAssets(dest.modelDir)
235
+ return { ok: true, installed: true, engine: 'ppocrv6' }
236
+ } finally { await rm(archive, { force: true }) }
237
+ }
238
+ export async function uninstallNative({
239
+ home = homedir(),
240
+ resolvePaths = localNativeOcrInstallPaths,
241
+ } = {}) {
242
+ const dest = resolvePaths({ home })
243
+ if (!dest || !await directory(dest.root)) throw Error('PP-OCRv6 is not installed')
244
+ // A corrupt model/worker is precisely when the user must still be able
245
+ // to remove an optional installation. Require the installer-created
246
+ // owner notice and exact managed directory instead of full model hashes.
247
+ // Never mutate a system binary, a symlink, or an arbitrary caller path.
248
+ if (!await ownedNativeDirectory(dest.root))
249
+ throw Error('refusing to remove unowned PP-OCRv6 installation')
250
+ const tomb = dest.root + '.removing-' + randomUUID()
251
+ await rename(dest.root, tomb)
252
+ await rm(tomb, { recursive: true, force: true })
253
+ return { ok: true, installed: false, engine: 'ppocrv6' }
254
+ }
255
+ export async function mutateOptionalOcr({ engine, action, archive, adapters = {} }) {
256
+ if (mutating) throw Error('another OCR installation operation is already running')
257
+ if (!['tesseract', 'ppocrv6'].includes(engine) || !['install', 'uninstall'].includes(action)) throw Error('invalid OCR operation')
258
+ if (engine === 'ppocrv6' && action === 'install' && !Buffer.isBuffer(archive)) throw Error('a local PP-OCRv6 bundle is required')
259
+ mutating = true
260
+ try {
261
+ if (engine === 'tesseract') {
262
+ return action === 'install' ? await (adapters.installTesseract ?? installTesseract)()
263
+ : await (adapters.uninstallTesseract ?? uninstallTesseract)()
264
+ }
265
+ return action === 'install'
266
+ ? await (adapters.installNativeBundle ?? installNativeBundle)(archive)
267
+ : await (adapters.uninstallNative ?? uninstallNative)()
268
+ } finally { mutating = false }
269
+ }
270
+ export async function runManagedTesseractOcr(bytes, { timeoutMs = 12000, signal } = {}) {
271
+ const dest = managedTesseractPaths()
272
+ if (!await verifyManaged(dest.root)) throw Error('managed Tesseract unavailable')
273
+ if (!(bytes instanceof Uint8Array) || bytes.byteLength < 8 || bytes.byteLength > 24 * 1024 * 1024)
274
+ throw Error('OCR image outside managed Tesseract bounds')
275
+ if (signal?.aborted) throw Error('OCR aborted')
276
+ if (activeManagedRuns >= 2) throw Error('managed Tesseract busy')
277
+ activeManagedRuns++
278
+ try {
279
+ const script = fileURLToPath(new URL('./managed-tesseract-child.js', import.meta.url))
280
+ return await new Promise((resolve, reject) => {
281
+ const child = spawn(process.execPath, [script, dest.root], {
282
+ shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
283
+ env: { ...nodeChildEnvironment(), DVR_OCR_CHILD: '1' },
284
+ })
285
+ let output = ''
286
+ let expired = false
287
+ let done = false
288
+ const finish = (error, result) => {
289
+ if (done) return
290
+ done = true
291
+ clearTimeout(timer)
292
+ signal?.removeEventListener('abort', onAbort)
293
+ if (error) reject(error)
294
+ else resolve(result)
295
+ }
296
+ const onAbort = () => {
297
+ expired = true
298
+ child.kill()
299
+ finish(Error('OCR aborted'))
300
+ }
301
+ const timer = setTimeout(() => {
302
+ expired = true
303
+ child.kill()
304
+ finish(Error('managed Tesseract timeout'))
305
+ }, Math.max(1, Math.min(120000, timeoutMs)))
306
+ timer.unref?.()
307
+ signal?.addEventListener('abort', onAbort, { once: true })
308
+ child.stdout.on('data', part => {
309
+ output += String(part)
310
+ if (output.length > 128 * 1024) {
311
+ child.kill()
312
+ finish(Error('managed Tesseract output too large'))
313
+ }
314
+ })
315
+ child.stderr.resume()
316
+ child.on('error', () => finish(Error('managed Tesseract could not start')))
317
+ child.on('close', code => {
318
+ if (expired || done) return
319
+ if (code !== 0) return finish(Error('managed Tesseract worker failed'))
320
+ try {
321
+ const data = JSON.parse(output)
322
+ if (typeof data?.text !== 'string' || !Number.isFinite(data.confidence)) throw Error('invalid result')
323
+ finish(null, { engine: 'tesseract', text: data.text.trim(), confidence: data.confidence })
324
+ } catch { finish(Error('managed Tesseract output invalid')) }
325
+ })
326
+ child.stdin.on('error', () => {})
327
+ child.stdin.end(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength))
328
+ })
329
+ } finally { activeManagedRuns-- }
330
+ }