advisers 0.4.1 → 0.4.2
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/README-zh.md +3 -3
- package/README.md +16 -13
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +187 -25
- package/index.js +1 -1
- package/lib/fact-entry.js +320 -0
- package/lib/mail-probe.js +307 -0
- package/lib/mail-watch.js +287 -0
- package/lib/sync.js +37 -2
- package/package.json +4 -4
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Manual fact entry for the SQLite ledger (0.4.x, write side of the facts table).
|
|
3
|
+
*
|
|
4
|
+
* The audit finding this closes: before this module a user could not record a
|
|
5
|
+
* fact directly -- facts only arrived as agent/mail candidates plus `memory
|
|
6
|
+
* accept`. This module is the library layer only: the caller owns HOME handling,
|
|
7
|
+
* migration, CLI output and the model. There is no model call, no console output,
|
|
8
|
+
* no table creation and no network here.
|
|
9
|
+
*
|
|
10
|
+
* Contract:
|
|
11
|
+
* - subject/predicate/object are required, non-empty, single-line and length
|
|
12
|
+
* capped (FACT_ENTRY_LIMITS); a quote is required evidence for a manual fact
|
|
13
|
+
* (evidence: [{ quote, source? }] -- the repo SourceRef shape);
|
|
14
|
+
* - the written row is always a user-authority confirmed fact:
|
|
15
|
+
* authority='user', status='confirmed', confidence=1, recordedAt=now,
|
|
16
|
+
* validFrom=input.validFrom ?? now, id='fact_'+16 hex chars;
|
|
17
|
+
* - every write goes through store.mutate(): insertFact (plus the optional
|
|
18
|
+
* supersede update / KB link insert) and exactly one audit row commit or roll
|
|
19
|
+
* back together. A rejected or deduped call writes no facts row and no audit
|
|
20
|
+
* row (invariant I1, and `fact add` must not claim a write that did not happen);
|
|
21
|
+
* - duplicate semantics (explicit, idempotent): the same ACTIVE fact -- same
|
|
22
|
+
* subject/predicate/matter/object with status='confirmed', expired_at IS NULL
|
|
23
|
+
* and deleted_at IS NULL -- is returned unchanged as
|
|
24
|
+
* { ok:true, fact, deduped:true }. The check runs inside the same BEGIN
|
|
25
|
+
* IMMEDIATE as the insert, so two writers can never both insert it. Evidence
|
|
26
|
+
* is NOT merged and recordedAt is NOT refreshed: a repeat entry is the same
|
|
27
|
+
* assertion, not a new observation. Different objects/identities are new rows;
|
|
28
|
+
* pass `supersedes` to replace the current fact for one identity;
|
|
29
|
+
* - optional `supersedes: factId` replaces the current fact for the same
|
|
30
|
+
* subject/predicate/matter: the new row carries facts.supersedes and the old
|
|
31
|
+
* row becomes status='superseded', supersededBy=new.id, validTo=new.validFrom,
|
|
32
|
+
* expiredAt=now (the core applyRemember supersede shape). A fact is not a
|
|
33
|
+
* "relation" in this repo -- the relation vocabulary below is the KB link
|
|
34
|
+
* vocabulary -- so the supersede target is a separate input;
|
|
35
|
+
* - optional `relation: 'source'|'mentions'` + `docId` writes one explicit
|
|
36
|
+
* fact <-> KB document link (kb_fact_links; the same vocabulary as lib/kb.js
|
|
37
|
+
* KB_RELATIONS and `kb link --relation`). docId without relation defaults to
|
|
38
|
+
* 'source' (the kbLink default); relation without docId is rejected. This is
|
|
39
|
+
* provenance only: the quote is never copied into the KB;
|
|
40
|
+
* - audit rows carry ids/counts only (never the quote, subject, predicate or
|
|
41
|
+
* object), matching the other write paths.
|
|
42
|
+
*/
|
|
43
|
+
import { randomBytes } from 'node:crypto'
|
|
44
|
+
import { entityError } from './sqlite.js'
|
|
45
|
+
import { stripBidiControls, stripControlChars, stripTerminalSequences } from './text-safe.js'
|
|
46
|
+
|
|
47
|
+
/** Relations accepted by a fact <-> KB document link (mirrors KB_RELATIONS). */
|
|
48
|
+
export const FACT_ENTRY_RELATIONS = Object.freeze(['source', 'mentions'])
|
|
49
|
+
/** Audit action of one committed manual fact entry. */
|
|
50
|
+
export const FACT_ENTRY_ACTION = 'fact.add'
|
|
51
|
+
/** Input caps (code points for text, UTF-8 bytes for the evidence source). */
|
|
52
|
+
export const FACT_ENTRY_LIMITS = Object.freeze({
|
|
53
|
+
subject: 200,
|
|
54
|
+
predicate: 200,
|
|
55
|
+
object: 2000,
|
|
56
|
+
quote: 500,
|
|
57
|
+
sourceBytes: 2048,
|
|
58
|
+
})
|
|
59
|
+
|
|
60
|
+
const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/
|
|
61
|
+
const FACT_ID_RE = /^fact_[0-9a-f]{16}$/
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Control-flow signal: the duplicate row is thrown from inside mutate() so the
|
|
65
|
+
* BEGIN IMMEDIATE rolls back before mutate() would append the audit row. It
|
|
66
|
+
* never escapes factAdd(); the caller only ever sees the deduped result.
|
|
67
|
+
*/
|
|
68
|
+
class DuplicateFactSignal extends Error {
|
|
69
|
+
constructor(fact) {
|
|
70
|
+
super('fact entry duplicate')
|
|
71
|
+
this.name = 'DuplicateFactSignal'
|
|
72
|
+
this.fact = fact
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function assertStore(store) {
|
|
77
|
+
if (!store || typeof store !== 'object' || typeof store.db?.prepare !== 'function') {
|
|
78
|
+
throw new TypeError('fact entry requires an opened SqliteStore')
|
|
79
|
+
}
|
|
80
|
+
for (const method of ['mutate', 'insertFact', 'updateFact', 'getFact', 'getMatter']) {
|
|
81
|
+
if (typeof store[method] !== 'function') {
|
|
82
|
+
throw new TypeError('fact entry requires a writable SqliteStore (missing ' + method + ')')
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Sanitize one operator-entered identity field / quote into a single safe line. */
|
|
88
|
+
function singleLine(value, field, max) {
|
|
89
|
+
if (typeof value !== 'string') throw entityError('E_USAGE', 'fact ' + field + ' must be a string')
|
|
90
|
+
const text = stripControlChars(stripBidiControls(stripTerminalSequences(value)), { keepNewlines: false, keepTabs: false, replacement: ' ' })
|
|
91
|
+
.replace(/\s+/gu, ' ')
|
|
92
|
+
.trim()
|
|
93
|
+
if (!text) throw entityError('E_USAGE', 'fact ' + field + ' is required and must not be empty')
|
|
94
|
+
const chars = Array.from(text)
|
|
95
|
+
if (chars.length > max) {
|
|
96
|
+
throw entityError('E_USAGE', 'fact ' + field + ' is too long (' + chars.length + ' > ' + max + ' characters)')
|
|
97
|
+
}
|
|
98
|
+
return text
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Optional evidence provenance object: stored verbatim as JSON, bounded in size. */
|
|
102
|
+
function normalizeSource(value) {
|
|
103
|
+
if (value === undefined || value === null) return null
|
|
104
|
+
if (typeof value !== 'object' || Array.isArray(value)) {
|
|
105
|
+
throw entityError('E_USAGE', 'evidence source must be a plain object')
|
|
106
|
+
}
|
|
107
|
+
let text
|
|
108
|
+
try { text = JSON.stringify(value) } catch {
|
|
109
|
+
throw entityError('E_USAGE', 'evidence source must be JSON-serializable')
|
|
110
|
+
}
|
|
111
|
+
if (typeof text !== 'string') throw entityError('E_USAGE', 'evidence source must be a plain object')
|
|
112
|
+
if (Buffer.byteLength(text, 'utf8') > FACT_ENTRY_LIMITS.sourceBytes) {
|
|
113
|
+
throw entityError('E_USAGE', 'evidence source is too large (max ' + FACT_ENTRY_LIMITS.sourceBytes + ' bytes)')
|
|
114
|
+
}
|
|
115
|
+
const clone = JSON.parse(text)
|
|
116
|
+
if (clone === null || typeof clone !== 'object' || Array.isArray(clone)) {
|
|
117
|
+
throw entityError('E_USAGE', 'evidence source must be a plain object')
|
|
118
|
+
}
|
|
119
|
+
return clone
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function normalizeMatterId(value) {
|
|
123
|
+
if (value === undefined || value === null) return null
|
|
124
|
+
if (typeof value !== 'string') throw entityError('E_USAGE', 'matterId must be a string')
|
|
125
|
+
const id = value.trim()
|
|
126
|
+
return id || null
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function normalizeSupersedes(value) {
|
|
130
|
+
if (value === undefined || value === null) return null
|
|
131
|
+
if (typeof value !== 'string') throw entityError('E_USAGE', 'supersedes must be a fact id string')
|
|
132
|
+
const id = value.trim()
|
|
133
|
+
if (!id) throw entityError('E_USAGE', 'supersedes must be a non-empty fact id')
|
|
134
|
+
return id
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function normalizeNow(value) {
|
|
138
|
+
if (value === undefined || value === null) return new Date().toISOString()
|
|
139
|
+
const date = value instanceof Date ? value : new Date(value)
|
|
140
|
+
if (!Number.isFinite(date.getTime())) throw entityError('E_USAGE', 'now must be a valid date')
|
|
141
|
+
return date.toISOString()
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** validFrom: an ISO instant normalized to UTC, a date-only string kept as-is
|
|
145
|
+
* (the ledger reads YYYY-MM-DD as the Asia/Shanghai day start), or absent. */
|
|
146
|
+
function normalizeValidFrom(value) {
|
|
147
|
+
if (value === undefined || value === null) return null
|
|
148
|
+
if (value instanceof Date) {
|
|
149
|
+
if (!Number.isFinite(value.getTime())) throw entityError('E_USAGE', 'validFrom is not a valid date')
|
|
150
|
+
return value.toISOString()
|
|
151
|
+
}
|
|
152
|
+
if (typeof value !== 'string') {
|
|
153
|
+
throw entityError('E_USAGE', 'validFrom must be an ISO 8601 date/datetime or a Date')
|
|
154
|
+
}
|
|
155
|
+
const text = value.trim()
|
|
156
|
+
if (!text) return null
|
|
157
|
+
if (DATE_ONLY_RE.test(text)) {
|
|
158
|
+
const parsed = Date.parse(text + 'T00:00:00.000Z')
|
|
159
|
+
if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== text) {
|
|
160
|
+
throw entityError('E_USAGE', 'validFrom is not a valid calendar date: ' + text)
|
|
161
|
+
}
|
|
162
|
+
return text
|
|
163
|
+
}
|
|
164
|
+
const parsed = Date.parse(text)
|
|
165
|
+
if (!Number.isFinite(parsed)) {
|
|
166
|
+
throw entityError('E_USAGE', 'validFrom is not a valid ISO 8601 instant: ' + text)
|
|
167
|
+
}
|
|
168
|
+
return new Date(parsed).toISOString()
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Optional relation link. Returns null (no link), { docId, relation } otherwise.
|
|
173
|
+
* The relation vocabulary is the KB link vocabulary; a supersede is NOT passed
|
|
174
|
+
* here (see the header) because the repo models it as facts.supersedes.
|
|
175
|
+
*/
|
|
176
|
+
function normalizeLink(input) {
|
|
177
|
+
const relationRaw = input.relation
|
|
178
|
+
const docRaw = input.docId
|
|
179
|
+
const hasRelation = relationRaw !== undefined && relationRaw !== null && String(relationRaw).trim() !== ''
|
|
180
|
+
const docId = docRaw === undefined || docRaw === null ? '' : String(docRaw).trim()
|
|
181
|
+
if (!hasRelation && !docId) return null
|
|
182
|
+
if (!hasRelation) return { docId, relation: 'source' }
|
|
183
|
+
const relation = String(relationRaw).trim()
|
|
184
|
+
if (!FACT_ENTRY_RELATIONS.includes(relation)) {
|
|
185
|
+
throw entityError('E_KB_INVALID', 'unknown relation: ' + relation, 'use one of ' + FACT_ENTRY_RELATIONS.join(', ') + '; to replace an older fact pass supersedes')
|
|
186
|
+
}
|
|
187
|
+
if (!docId) throw entityError('E_USAGE', 'relation requires a docId (a link is stored per KB document)')
|
|
188
|
+
return { docId, relation }
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** The ledger's definition of the current row for one identity (same rule as
|
|
192
|
+
* SqliteStore.findFactCurrent; predicate 'said' is only special there for
|
|
193
|
+
* supersede bookkeeping, manual entry dedupes it like any other identity). */
|
|
194
|
+
function findActiveFact(store, { subject, predicate, matterId, object }) {
|
|
195
|
+
const row = store.db.prepare(
|
|
196
|
+
"SELECT id FROM facts WHERE status = 'confirmed' AND expired_at IS NULL AND deleted_at IS NULL" +
|
|
197
|
+
' AND subject = ? AND predicate = ? AND (matter_id IS ?) AND object = ? ORDER BY rowid LIMIT 1',
|
|
198
|
+
).get(subject, predicate, matterId, object)
|
|
199
|
+
return row ? store.getFact(row.id) : undefined
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** Fail closed when the optional KB link target is absent, stale or not active. */
|
|
203
|
+
function assertLinkTarget(store, { docId, relation }) {
|
|
204
|
+
const hasTable = store.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'kb_fact_links'").get()
|
|
205
|
+
if (!hasTable) {
|
|
206
|
+
throw entityError('E_SCHEMA_STALE', 'fact <-> document links need the v22 schema (kb_fact_links is missing)', 'upgrade the ledger and run advisers doctor')
|
|
207
|
+
}
|
|
208
|
+
const doc = store.db.prepare('SELECT id, status, deleted_at FROM kb_documents WHERE id = ?').get(docId)
|
|
209
|
+
if (!doc || doc.status !== 'active' || doc.deleted_at !== null) {
|
|
210
|
+
throw entityError('E_KB_NOT_FOUND', 'unknown document: ' + docId, 'advisers kb ls')
|
|
211
|
+
}
|
|
212
|
+
return relation
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function newFactId() {
|
|
216
|
+
return 'fact_' + randomBytes(8).toString('hex')
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Record one manually entered fact and return the persisted row.
|
|
221
|
+
*
|
|
222
|
+
* @param {object} store an opened writable SqliteStore
|
|
223
|
+
* @param {{subject: string, predicate: string, object: string, quote: string,
|
|
224
|
+
* source?: object, matterId?: string, validFrom?: string|Date,
|
|
225
|
+
* relation?: 'source'|'mentions', docId?: string,
|
|
226
|
+
* supersedes?: string}} input
|
|
227
|
+
* @param {{now?: string|Date}} [options] injectable clock (tests/imports)
|
|
228
|
+
* @returns {{ok: true, fact: object, deduped: boolean, audit: object|null}}
|
|
229
|
+
*/
|
|
230
|
+
export function factAdd(store, input = {}, options = {}) {
|
|
231
|
+
assertStore(store)
|
|
232
|
+
if (!input || typeof input !== 'object' || Array.isArray(input)) {
|
|
233
|
+
throw entityError('E_USAGE', 'fact input must be an object')
|
|
234
|
+
}
|
|
235
|
+
const opts = options && typeof options === 'object' ? options : {}
|
|
236
|
+
const recordedAt = normalizeNow(opts.now)
|
|
237
|
+
const subject = singleLine(input.subject, 'subject', FACT_ENTRY_LIMITS.subject)
|
|
238
|
+
const predicate = singleLine(input.predicate, 'predicate', FACT_ENTRY_LIMITS.predicate)
|
|
239
|
+
const object = singleLine(input.object, 'object', FACT_ENTRY_LIMITS.object)
|
|
240
|
+
const quote = singleLine(input.quote, 'quote', FACT_ENTRY_LIMITS.quote)
|
|
241
|
+
const source = normalizeSource(input.source)
|
|
242
|
+
const matterId = normalizeMatterId(input.matterId)
|
|
243
|
+
const validFrom = normalizeValidFrom(input.validFrom) ?? recordedAt
|
|
244
|
+
const link = normalizeLink(input)
|
|
245
|
+
const supersedesId = normalizeSupersedes(input.supersedes)
|
|
246
|
+
const id = newFactId()
|
|
247
|
+
if (!FACT_ID_RE.test(id)) throw new Error('generated fact id is malformed: ' + id)
|
|
248
|
+
const audit = { actor: 'local', action: FACT_ENTRY_ACTION, allowed: true, reason: id }
|
|
249
|
+
let outcome
|
|
250
|
+
try {
|
|
251
|
+
outcome = store.mutate((s) => {
|
|
252
|
+
const existing = findActiveFact(s, { subject, predicate, matterId, object })
|
|
253
|
+
if (existing) throw new DuplicateFactSignal(existing)
|
|
254
|
+
if (matterId !== null && !s.getMatter(matterId)) {
|
|
255
|
+
throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + matterId, 'advisers matter ls')
|
|
256
|
+
}
|
|
257
|
+
let previous = null
|
|
258
|
+
if (supersedesId !== null) {
|
|
259
|
+
previous = s.getFact(supersedesId)
|
|
260
|
+
if (!previous || previous.deletedAt !== undefined) {
|
|
261
|
+
throw entityError('E_FACT_NOT_FOUND', 'unknown fact: ' + supersedesId, 'advisers fact ls')
|
|
262
|
+
}
|
|
263
|
+
if (previous.status !== 'confirmed' || previous.expiredAt !== undefined) {
|
|
264
|
+
throw entityError('E_USAGE', 'cannot supersede fact ' + supersedesId + ': it is not an active confirmed fact (status=' + previous.status + ')', 'only the current confirmed fact for the same identity can be superseded')
|
|
265
|
+
}
|
|
266
|
+
const sameMatter = (previous.matterId ?? null) === matterId
|
|
267
|
+
if (previous.subject !== subject || previous.predicate !== predicate || !sameMatter) {
|
|
268
|
+
throw entityError('E_USAGE', 'cannot supersede fact ' + supersedesId + ': subject/predicate/matter differ from this entry', 'a supersede replaces the current fact for the same subject/predicate/matter')
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
if (link !== null) assertLinkTarget(s, link)
|
|
272
|
+
const row = {
|
|
273
|
+
id,
|
|
274
|
+
...(matterId === null ? {} : { matterId }),
|
|
275
|
+
subject,
|
|
276
|
+
predicate,
|
|
277
|
+
object,
|
|
278
|
+
recordedAt,
|
|
279
|
+
authority: 'user',
|
|
280
|
+
confidence: 1,
|
|
281
|
+
evidence: [{ quote, ...(source === null ? {} : { source }) }],
|
|
282
|
+
status: 'confirmed',
|
|
283
|
+
validFrom,
|
|
284
|
+
...(previous === null ? {} : { supersedes: previous.id }),
|
|
285
|
+
}
|
|
286
|
+
s.insertFact(row)
|
|
287
|
+
if (previous !== null) {
|
|
288
|
+
s.updateFact(previous.id, { status: 'superseded', supersededBy: id, validTo: validFrom, expiredAt: recordedAt })
|
|
289
|
+
}
|
|
290
|
+
if (link !== null) {
|
|
291
|
+
s.db.prepare('INSERT OR REPLACE INTO kb_fact_links(fact_id, doc_id, chunk_id, relation, created_at) VALUES(?,?,?,?,?)')
|
|
292
|
+
.run(id, link.docId, null, link.relation, recordedAt)
|
|
293
|
+
}
|
|
294
|
+
audit.reason = id +
|
|
295
|
+
(matterId === null ? '' : ' matter ' + matterId) +
|
|
296
|
+
(previous === null ? '' : ' supersedes ' + previous.id) +
|
|
297
|
+
(link === null ? '' : ' link ' + link.docId + ' (' + link.relation + ')')
|
|
298
|
+
const stored = s.getFact(id)
|
|
299
|
+
if (!stored) throw new Error('fact ' + id + ' was not persisted')
|
|
300
|
+
return stored
|
|
301
|
+
}, audit)
|
|
302
|
+
} catch (error) {
|
|
303
|
+
if (error instanceof DuplicateFactSignal) {
|
|
304
|
+
return { ok: true, fact: error.fact, deduped: true, audit: null }
|
|
305
|
+
}
|
|
306
|
+
throw error
|
|
307
|
+
}
|
|
308
|
+
return { ok: true, fact: outcome.result, deduped: false, audit: outcome.audit }
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/** Alias matching the file name; the repo's other write modules use <entity>Add. */
|
|
312
|
+
export const factEntry = factAdd
|
|
313
|
+
|
|
314
|
+
export default Object.freeze({
|
|
315
|
+
FACT_ENTRY_RELATIONS,
|
|
316
|
+
FACT_ENTRY_ACTION,
|
|
317
|
+
FACT_ENTRY_LIMITS,
|
|
318
|
+
factAdd,
|
|
319
|
+
factEntry,
|
|
320
|
+
})
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read-only IMAP connectivity probe behind `advisers mail account test` (0.4.x).
|
|
3
|
+
*
|
|
4
|
+
* The command exists so a user can validate an account before syncing: it opens
|
|
5
|
+
* ONE session to the configured host/port with the configured transport (implicit
|
|
6
|
+
* TLS on 993 or STARTTLS on 143, never cleartext), logs in, asks CAPABILITY and
|
|
7
|
+
* runs EXAMINE on the account mailbox (or an explicit --mailbox override). It
|
|
8
|
+
* never fetches message data and never writes the ledger:
|
|
9
|
+
*
|
|
10
|
+
* - no FETCH / UID SEARCH / STORE; no message body or header is read;
|
|
11
|
+
* - no mail row, cursor, sync run or audit row is written (lib/mail.js owns writes);
|
|
12
|
+
* - no message content is part of the result and the password is never echoed.
|
|
13
|
+
*
|
|
14
|
+
* The result has a small, frozen-shape contract (see mailAccountTest):
|
|
15
|
+
* { ok, command, accountId, host, port, tls, mailbox, latencyMs,
|
|
16
|
+
* uidValidity, messages, capabilities }
|
|
17
|
+
* where capabilities is a summary { count, list, flags, auth } of the post-LOGIN
|
|
18
|
+
* CAPABILITY tokens (unique, upper-cased, sorted; unknown tokens dropped).
|
|
19
|
+
*
|
|
20
|
+
* The whole probe has ONE deadline, DEFAULT_MAIL_PROBE_TIMEOUT_MS (30 s); a caller
|
|
21
|
+
* may pass a shorter timeoutMs (tests do). An injected `openSession` lets tests
|
|
22
|
+
* supply a fake session and never touch the network - the product path always
|
|
23
|
+
* uses lib/mail-imap.js. Failures map to the EXISTING registered codes
|
|
24
|
+
* (lib/error-codes.js); this module introduces no new error code:
|
|
25
|
+
*
|
|
26
|
+
* E_MAIL_CONFIG unsupported account/transport, bad probe option
|
|
27
|
+
* E_MAIL_ACCOUNT_NOT_FOUND the account ref does not resolve
|
|
28
|
+
* E_MAIL_CREDENTIALS_MISSING no stored credential for the account
|
|
29
|
+
* E_CREDENTIALS_INSECURE from lib/credentials.js (unsafe credential file)
|
|
30
|
+
* E_IMAP_AUTH login rejected / authentication error
|
|
31
|
+
* E_IMAP_TLS TLS handshake, certificate or STARTTLS failure
|
|
32
|
+
* E_IMAP_TIMEOUT the probe deadline elapsed
|
|
33
|
+
* E_IMAP_PROTOCOL anything else (bad status line, rejected EXAMINE)
|
|
34
|
+
*/
|
|
35
|
+
import { readImapCredential } from './credentials.js'
|
|
36
|
+
import { isMailError, mailError, MAIL_ERROR_CODES } from './mail-errors.js'
|
|
37
|
+
import { openMailImapSession } from './mail-imap.js'
|
|
38
|
+
import { assertMailTables, getMailAccount } from './mail-store.js'
|
|
39
|
+
import { sanitizeConsoleText } from './text-safe.js'
|
|
40
|
+
|
|
41
|
+
/** Default total deadline for one probe (the documented CLI contract is 30 s). */
|
|
42
|
+
export const DEFAULT_MAIL_PROBE_TIMEOUT_MS = 30_000
|
|
43
|
+
const MAX_MAIL_PROBE_TIMEOUT_MS = 300_000
|
|
44
|
+
const MAIL_PROBE_MAX_MAILBOX_CHARS = 200
|
|
45
|
+
const MAIL_PROBE_MAX_CAPABILITIES = 64
|
|
46
|
+
const MAIL_PROBE_MAX_CAPABILITY_CHARS = 64
|
|
47
|
+
const CLEANUP_GRACE_MS = 1_000
|
|
48
|
+
const CLEANUP_GRACE_AFTER_TIMEOUT_MS = 250
|
|
49
|
+
const IMAP_TLS_MODES = Object.freeze(['tls', 'starttls'])
|
|
50
|
+
|
|
51
|
+
function probeTimeoutError(timeoutMs) {
|
|
52
|
+
return mailError(
|
|
53
|
+
MAIL_ERROR_CODES.IMAP_TIMEOUT,
|
|
54
|
+
'IMAP probe timed out after ' + timeoutMs + 'ms',
|
|
55
|
+
'check the network, the account host/port and the server certificate; this probe never fetches message data',
|
|
56
|
+
)
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function normalizeTimeoutMs(value) {
|
|
60
|
+
if (value == null) return DEFAULT_MAIL_PROBE_TIMEOUT_MS
|
|
61
|
+
const timeoutMs = Number(value)
|
|
62
|
+
if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_MAIL_PROBE_TIMEOUT_MS) {
|
|
63
|
+
throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe timeout must be an integer between 1 and ' + MAX_MAIL_PROBE_TIMEOUT_MS + 'ms')
|
|
64
|
+
}
|
|
65
|
+
return timeoutMs
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function normalizeMailbox(value, fallback) {
|
|
69
|
+
const raw = value == null ? fallback : value
|
|
70
|
+
if (typeof raw !== 'string') throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe mailbox must be a string')
|
|
71
|
+
if (/[\u0000-\u001f\u007f]/.test(raw)) {
|
|
72
|
+
throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe mailbox must be a single line without control characters')
|
|
73
|
+
}
|
|
74
|
+
const mailbox = raw.trim()
|
|
75
|
+
if (!mailbox) throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe mailbox must not be empty')
|
|
76
|
+
if (Array.from(mailbox).length > MAIL_PROBE_MAX_MAILBOX_CHARS) {
|
|
77
|
+
throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe mailbox must be at most ' + MAIL_PROBE_MAX_MAILBOX_CHARS + ' characters')
|
|
78
|
+
}
|
|
79
|
+
return mailbox
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function resolveOpener(openSession) {
|
|
83
|
+
if (openSession == null) return openMailImapSession
|
|
84
|
+
if (typeof openSession !== 'function') {
|
|
85
|
+
throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail probe openSession must be a function (test injection point)')
|
|
86
|
+
}
|
|
87
|
+
return openSession
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Bound one clean-up await without leaving a timer behind (both outcomes). */
|
|
91
|
+
async function settleWithin(promise, timeoutMs) {
|
|
92
|
+
let timer = null
|
|
93
|
+
const timeout = new Promise((resolve, reject) => {
|
|
94
|
+
timer = setTimeout(() => reject(new Error('IMAP clean-up timed out')), timeoutMs)
|
|
95
|
+
})
|
|
96
|
+
timeout.catch(() => {})
|
|
97
|
+
try {
|
|
98
|
+
await Promise.race([promise, timeout])
|
|
99
|
+
} finally {
|
|
100
|
+
if (timer) clearTimeout(timer)
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function createDeadline(timeoutMs) {
|
|
105
|
+
const expiresAt = Date.now() + timeoutMs
|
|
106
|
+
let timer = null
|
|
107
|
+
let expired = false
|
|
108
|
+
let rejectDeadline
|
|
109
|
+
const deadlinePromise = new Promise((resolve, reject) => { rejectDeadline = reject })
|
|
110
|
+
deadlinePromise.catch(() => {})
|
|
111
|
+
timer = setTimeout(() => {
|
|
112
|
+
timer = null
|
|
113
|
+
expired = true
|
|
114
|
+
rejectDeadline(probeTimeoutError(timeoutMs))
|
|
115
|
+
}, timeoutMs)
|
|
116
|
+
return {
|
|
117
|
+
expired: () => expired,
|
|
118
|
+
remaining: () => Math.max(0, expiresAt - Date.now()),
|
|
119
|
+
race: (promise) => Promise.race([promise, deadlinePromise]),
|
|
120
|
+
dispose: () => { if (timer) { clearTimeout(timer); timer = null } },
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function destroySessionQuietly(session) {
|
|
125
|
+
if (!session) return
|
|
126
|
+
try { session.destroy?.() } catch {}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
async function closeSession(session, graceMs) {
|
|
130
|
+
if (!session) return
|
|
131
|
+
try {
|
|
132
|
+
if (typeof session.logout === 'function') {
|
|
133
|
+
await settleWithin(Promise.resolve().then(() => session.logout()), graceMs)
|
|
134
|
+
}
|
|
135
|
+
} catch {}
|
|
136
|
+
destroySessionQuietly(session)
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
async function openProbeSession(openSession, params, deadline, timeoutMs) {
|
|
140
|
+
const opened = Promise.resolve().then(() => openSession(params))
|
|
141
|
+
const guarded = opened.then((session) => {
|
|
142
|
+
if (deadline.expired()) {
|
|
143
|
+
destroySessionQuietly(session)
|
|
144
|
+
throw probeTimeoutError(timeoutMs)
|
|
145
|
+
}
|
|
146
|
+
return session
|
|
147
|
+
})
|
|
148
|
+
return deadline.race(guarded)
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
function assertProbeSession(session) {
|
|
152
|
+
if (!session || typeof session !== 'object') {
|
|
153
|
+
throw mailError(MAIL_ERROR_CODES.IMAP_PROTOCOL, 'the IMAP session was not created')
|
|
154
|
+
}
|
|
155
|
+
if (typeof session.capability !== 'function' || typeof session.examine !== 'function') {
|
|
156
|
+
throw mailError(MAIL_ERROR_CODES.IMAP_PROTOCOL, 'the IMAP session does not expose CAPABILITY/EXAMINE')
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function summarizeCapabilities(rawCapabilities) {
|
|
161
|
+
if (!Array.isArray(rawCapabilities)) {
|
|
162
|
+
throw mailError(MAIL_ERROR_CODES.IMAP_PROTOCOL, 'the IMAP CAPABILITY response was not understood')
|
|
163
|
+
}
|
|
164
|
+
const names = []
|
|
165
|
+
for (const raw of rawCapabilities.slice(0, 512)) {
|
|
166
|
+
if (typeof raw !== 'string') continue
|
|
167
|
+
const name = sanitizeConsoleText(raw, { max: MAIL_PROBE_MAX_CAPABILITY_CHARS }).trim().toUpperCase()
|
|
168
|
+
if (!name || !/^[A-Z0-9]/.test(name) || !/^[A-Z0-9._=+-]+$/.test(name)) continue
|
|
169
|
+
if (!names.includes(name)) names.push(name)
|
|
170
|
+
if (names.length >= MAIL_PROBE_MAX_CAPABILITIES) break
|
|
171
|
+
}
|
|
172
|
+
names.sort()
|
|
173
|
+
return {
|
|
174
|
+
count: names.length,
|
|
175
|
+
list: names,
|
|
176
|
+
flags: {
|
|
177
|
+
starttls: names.includes('STARTTLS'),
|
|
178
|
+
uidplus: names.includes('UIDPLUS'),
|
|
179
|
+
idle: names.includes('IDLE'),
|
|
180
|
+
move: names.includes('MOVE'),
|
|
181
|
+
},
|
|
182
|
+
auth: names.filter((name) => name.startsWith('AUTH=')).map((name) => name.slice('AUTH='.length)),
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function normalizeUidValidity(value) {
|
|
187
|
+
if (value == null) return null
|
|
188
|
+
const text = String(value).trim()
|
|
189
|
+
return /^[0-9]+$/.test(text) ? text : null
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
function normalizeMessageCount(value) {
|
|
193
|
+
const count = Number(value)
|
|
194
|
+
return Number.isInteger(count) && count >= 0 ? count : null
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function mapProbeError(error, timeoutMs) {
|
|
198
|
+
if (isMailError(error)) return error
|
|
199
|
+
const rawCode = typeof error?.code === 'string' ? error.code : ''
|
|
200
|
+
const rawMessage = String(error?.message ?? error ?? '')
|
|
201
|
+
const detail = rawCode + ' ' + rawMessage
|
|
202
|
+
if (error?.imapTimeout || rawCode === 'ETIMEDOUT' || /timed out|timeout/i.test(rawMessage)) {
|
|
203
|
+
return probeTimeoutError(timeoutMs)
|
|
204
|
+
}
|
|
205
|
+
if (/auth|login|credential|password|AUTHENTICATIONFAILED/i.test(detail)) {
|
|
206
|
+
return mailError(
|
|
207
|
+
MAIL_ERROR_CODES.IMAP_AUTH,
|
|
208
|
+
'IMAP authentication failed',
|
|
209
|
+
'check the account username and app password; modern providers may require OAuth (not supported)',
|
|
210
|
+
)
|
|
211
|
+
}
|
|
212
|
+
if (/tls|ssl|certificate|handshake|self.signed|unable to verify|EPROTO/i.test(detail)) {
|
|
213
|
+
return mailError(
|
|
214
|
+
MAIL_ERROR_CODES.IMAP_TLS,
|
|
215
|
+
'IMAP TLS connection failed: ' + sanitizeConsoleText(rawMessage, { max: 300 }),
|
|
216
|
+
'the server certificate must be valid for the configured host; advisers never falls back to cleartext',
|
|
217
|
+
)
|
|
218
|
+
}
|
|
219
|
+
return mailError(MAIL_ERROR_CODES.IMAP_PROTOCOL, 'IMAP probe failed: ' + (sanitizeConsoleText(rawMessage, { max: 300 }) || 'unknown error'))
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Probe one configured IMAP account read-only: connect (TLS/STARTTLS) + LOGIN +
|
|
224
|
+
* CAPABILITY + EXAMINE, then log out. Nothing is fetched and nothing is written.
|
|
225
|
+
*
|
|
226
|
+
* @param {{ db: any }} store open ledger (SQLite)
|
|
227
|
+
* @param {string} accountRef account id or (case-insensitive) account name
|
|
228
|
+
* @param {{ home?: string, timeoutMs?: number, mailbox?: string, openSession?: Function }} [options]
|
|
229
|
+
* @returns {Promise<{
|
|
230
|
+
* ok: true, command: 'mail account test', accountId: string, host: string,
|
|
231
|
+
* port: number, tls: 'tls' | 'starttls', mailbox: string, latencyMs: number,
|
|
232
|
+
* uidValidity: string | null, messages: number | null,
|
|
233
|
+
* capabilities: {
|
|
234
|
+
* count: number,
|
|
235
|
+
* list: string[],
|
|
236
|
+
* flags: { starttls: boolean, uidplus: boolean, idle: boolean, move: boolean },
|
|
237
|
+
* auth: string[],
|
|
238
|
+
* },
|
|
239
|
+
* }>}
|
|
240
|
+
*/
|
|
241
|
+
export async function mailAccountTest(store, accountRef, options = {}) {
|
|
242
|
+
const startedMs = Date.now()
|
|
243
|
+
assertMailTables(store)
|
|
244
|
+
if (options == null || typeof options !== 'object') {
|
|
245
|
+
throw mailError(MAIL_ERROR_CODES.CONFIG, 'mail account test options must be an object')
|
|
246
|
+
}
|
|
247
|
+
const timeoutMs = normalizeTimeoutMs(options.timeoutMs)
|
|
248
|
+
const account = getMailAccount(store, accountRef)
|
|
249
|
+
if (!IMAP_TLS_MODES.includes(account.tls)) {
|
|
250
|
+
throw mailError(
|
|
251
|
+
MAIL_ERROR_CODES.CONFIG,
|
|
252
|
+
'account ' + account.name + ' is not an IMAP account',
|
|
253
|
+
'the local .eml import account has no server to probe; add an IMAP account with `advisers mail account add`',
|
|
254
|
+
)
|
|
255
|
+
}
|
|
256
|
+
const mailbox = normalizeMailbox(options.mailbox, account.mailbox)
|
|
257
|
+
const openSession = resolveOpener(options.openSession)
|
|
258
|
+
const credential = readImapCredential(account.id, { home: options.home })
|
|
259
|
+
if (!credential) {
|
|
260
|
+
throw mailError(
|
|
261
|
+
MAIL_ERROR_CODES.CREDENTIALS_MISSING,
|
|
262
|
+
'no stored credential for mail account ' + account.name,
|
|
263
|
+
'run `advisers mail account add` again and provide the password through the TTY prompt or --pass-stdin',
|
|
264
|
+
)
|
|
265
|
+
}
|
|
266
|
+
const deadline = createDeadline(timeoutMs)
|
|
267
|
+
let session
|
|
268
|
+
try {
|
|
269
|
+
const remaining = Math.max(1, deadline.remaining())
|
|
270
|
+
session = await openProbeSession(openSession, {
|
|
271
|
+
host: account.host,
|
|
272
|
+
port: account.port,
|
|
273
|
+
tls: account.tls,
|
|
274
|
+
user: credential.user || account.username,
|
|
275
|
+
pass: credential.pass,
|
|
276
|
+
timeoutMs: remaining,
|
|
277
|
+
idleTimeoutMs: remaining,
|
|
278
|
+
}, deadline, timeoutMs)
|
|
279
|
+
assertProbeSession(session)
|
|
280
|
+
const rawCapabilities = await deadline.race(Promise.resolve().then(() => session.capability()))
|
|
281
|
+
const capabilities = summarizeCapabilities(rawCapabilities)
|
|
282
|
+
const box = await deadline.race(Promise.resolve().then(() => session.examine(mailbox)))
|
|
283
|
+
if (!box || typeof box !== 'object') {
|
|
284
|
+
throw mailError(MAIL_ERROR_CODES.IMAP_PROTOCOL, 'the IMAP EXAMINE response was not understood')
|
|
285
|
+
}
|
|
286
|
+
return {
|
|
287
|
+
ok: true,
|
|
288
|
+
command: 'mail account test',
|
|
289
|
+
accountId: account.id,
|
|
290
|
+
host: account.host,
|
|
291
|
+
port: account.port,
|
|
292
|
+
tls: account.tls,
|
|
293
|
+
mailbox,
|
|
294
|
+
latencyMs: Math.max(0, Date.now() - startedMs),
|
|
295
|
+
uidValidity: normalizeUidValidity(box.uidValidity),
|
|
296
|
+
messages: normalizeMessageCount(box.exists),
|
|
297
|
+
capabilities,
|
|
298
|
+
}
|
|
299
|
+
} catch (error) {
|
|
300
|
+
throw mapProbeError(error, timeoutMs)
|
|
301
|
+
} finally {
|
|
302
|
+
deadline.dispose()
|
|
303
|
+
if (session) {
|
|
304
|
+
await closeSession(session, deadline.expired() ? CLEANUP_GRACE_AFTER_TIMEOUT_MS : CLEANUP_GRACE_MS)
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
}
|