@tpsdev-ai/agent 0.7.0 → 0.9.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.
- package/bun.lock +27 -15
- package/bunfig.toml +17 -0
- package/dist/bin.js +4 -3
- package/dist/bin.js.map +1 -1
- package/dist/config.d.ts +8 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +38 -3
- package/dist/config.js.map +1 -1
- package/dist/home.d.ts +3 -0
- package/dist/home.d.ts.map +1 -0
- package/dist/home.js +18 -0
- package/dist/home.js.map +1 -0
- package/dist/index.d.ts +16 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +12 -1
- package/dist/index.js.map +1 -1
- package/dist/io/flair.d.ts +1 -10
- package/dist/io/flair.d.ts.map +1 -1
- package/dist/io/flair.js +29 -28
- package/dist/io/flair.js.map +1 -1
- package/dist/io/mail.d.ts +184 -30
- package/dist/io/mail.d.ts.map +1 -1
- package/dist/io/mail.js +944 -185
- package/dist/io/mail.js.map +1 -1
- package/dist/lib/agent-keys.d.ts +106 -0
- package/dist/lib/agent-keys.d.ts.map +1 -0
- package/dist/lib/agent-keys.js +298 -0
- package/dist/lib/agent-keys.js.map +1 -0
- package/dist/lib/bridge-identity.d.ts +10 -0
- package/dist/lib/bridge-identity.d.ts.map +1 -0
- package/dist/lib/bridge-identity.js +56 -0
- package/dist/lib/bridge-identity.js.map +1 -0
- package/dist/lib/mail-lock-namespace.d.ts +19 -0
- package/dist/lib/mail-lock-namespace.d.ts.map +1 -0
- package/dist/lib/mail-lock-namespace.js +58 -0
- package/dist/lib/mail-lock-namespace.js.map +1 -0
- package/dist/lib/mail-lock.d.ts +81 -0
- package/dist/lib/mail-lock.d.ts.map +1 -0
- package/dist/lib/mail-lock.js +319 -0
- package/dist/lib/mail-lock.js.map +1 -0
- package/dist/lib/mailbox-filename.d.ts +2 -0
- package/dist/lib/mailbox-filename.d.ts.map +1 -0
- package/dist/lib/mailbox-filename.js +4 -0
- package/dist/lib/mailbox-filename.js.map +1 -0
- package/dist/lib/mailbox-policy.d.ts +245 -0
- package/dist/lib/mailbox-policy.d.ts.map +1 -0
- package/dist/lib/mailbox-policy.js +949 -0
- package/dist/lib/mailbox-policy.js.map +1 -0
- package/dist/lib/public-key.d.ts +6 -0
- package/dist/lib/public-key.d.ts.map +1 -0
- package/dist/lib/public-key.js +45 -0
- package/dist/lib/public-key.js.map +1 -0
- package/dist/lib/registry-key.d.ts +2 -0
- package/dist/lib/registry-key.d.ts.map +1 -0
- package/dist/lib/registry-key.js +10 -0
- package/dist/lib/registry-key.js.map +1 -0
- package/dist/lib/relay-lock.d.ts +7 -0
- package/dist/lib/relay-lock.d.ts.map +1 -0
- package/dist/lib/relay-lock.js +19 -0
- package/dist/lib/relay-lock.js.map +1 -0
- package/dist/lib/signEnvelope.d.ts +12 -0
- package/dist/lib/signEnvelope.d.ts.map +1 -1
- package/dist/lib/signEnvelope.js.map +1 -1
- package/dist/lib/signing-key.d.ts +2 -0
- package/dist/lib/signing-key.d.ts.map +1 -0
- package/dist/lib/signing-key.js +9 -0
- package/dist/lib/signing-key.js.map +1 -0
- package/dist/lib/topic-recipient.d.ts +2 -0
- package/dist/lib/topic-recipient.d.ts.map +1 -0
- package/dist/lib/topic-recipient.js +2 -0
- package/dist/lib/topic-recipient.js.map +1 -0
- package/dist/llm/provider.d.ts.map +1 -1
- package/dist/llm/provider.js +9 -7
- package/dist/llm/provider.js.map +1 -1
- package/dist/runtime/agent.d.ts.map +1 -1
- package/dist/runtime/agent.js +32 -25
- package/dist/runtime/agent.js.map +1 -1
- package/dist/runtime/event-loop.d.ts +21 -2
- package/dist/runtime/event-loop.d.ts.map +1 -1
- package/dist/runtime/event-loop.js +199 -54
- package/dist/runtime/event-loop.js.map +1 -1
- package/dist/runtime/types.d.ts +11 -0
- package/dist/runtime/types.d.ts.map +1 -1
- package/dist/runtime/types.js +13 -1
- package/dist/runtime/types.js.map +1 -1
- package/package.json +3 -4
- package/src/bin.ts +4 -3
- package/src/config.ts +46 -3
- package/src/home.ts +18 -0
- package/src/index.ts +33 -2
- package/src/io/flair.ts +23 -28
- package/src/io/mail.ts +1007 -200
- package/src/lib/agent-keys.ts +308 -0
- package/src/lib/bridge-identity.ts +49 -0
- package/src/lib/mail-lock-namespace.ts +64 -0
- package/src/lib/mail-lock.ts +337 -0
- package/src/lib/mailbox-filename.ts +3 -0
- package/src/lib/mailbox-policy.ts +1085 -0
- package/src/lib/public-key.ts +49 -0
- package/src/lib/registry-key.ts +8 -0
- package/src/lib/relay-lock.ts +20 -0
- package/src/lib/signEnvelope.ts +12 -0
- package/src/lib/signing-key.ts +8 -0
- package/src/lib/topic-recipient.ts +1 -0
- package/src/llm/provider.ts +9 -7
- package/src/runtime/agent.ts +30 -27
- package/src/runtime/event-loop.ts +221 -68
- package/src/runtime/types.ts +14 -0
- package/test/config.test.ts +85 -2
- package/test/core-loop.test.ts +6 -4
- package/test/governance.test.ts +4 -1
- package/test/helpers/event-loop-child.mjs +50 -0
- package/test/helpers/mail-delivery-worker.mjs +16 -0
- package/test/helpers/mail-kill-child.mjs +104 -0
- package/test/helpers/signed-relay-record.ts +31 -0
- package/test/home-per-call.test.ts +72 -0
- package/test/io.test.ts +81 -14
- package/test/mail-client-lock-namespace.test.ts +155 -0
- package/test/mail-client-repoint-root.test.ts +368 -0
- package/test/mail-delivery-at-least-once.test.ts +1238 -0
- package/test/mail-event-loop-delivery.test.ts +769 -0
- package/test/mail-intent-phases.test.ts +304 -0
- package/test/mail-interrupted-recovery.test.ts +393 -0
- package/test/mail-lock-pid-state.test.ts +238 -0
- package/test/mail-lock.test.ts +96 -0
- package/test/mail-partial-flair.test.ts +102 -0
- package/test/mail-placement-replay.test.ts +116 -0
- package/test/mail-promote-guard.test.ts +305 -21
- package/test/mail-relay-reservation.test.ts +60 -0
- package/test/mailbox-filename.test.ts +16 -0
- package/test/public-key.test.ts +108 -0
- package/test/runtime-key-encoding.test.ts +105 -0
- package/test/runtime-pending-key.test.ts +117 -0
- package/test/security/mail-trust.test.ts +406 -109
package/src/io/mail.ts
CHANGED
|
@@ -1,17 +1,40 @@
|
|
|
1
|
-
import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync, writeFileSync } from "node:fs";
|
|
1
|
+
import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { isMailboxMessageFile } from "../lib/mailbox-filename.js";
|
|
2
3
|
import { join } from "node:path";
|
|
4
|
+
import { randomUUID } from "node:crypto";
|
|
3
5
|
import type { EventLogger } from "../telemetry/events.js";
|
|
4
6
|
import { sanitizeError } from "../telemetry/events.js";
|
|
5
|
-
import {
|
|
7
|
+
import { signEnvelope, type ChainEntry, type Envelope, type FlairClient } from "../lib/signEnvelope.js";
|
|
8
|
+
import { PublicKeyFormatError } from "../lib/public-key.js";
|
|
9
|
+
import { agentKeyCandidates, readAgentPrivateKey } from "../lib/agent-keys.js";
|
|
10
|
+
import { tryAcquireRelayMoveLock } from "../lib/relay-lock.js";
|
|
11
|
+
import { canonicalMailboxRoot, canonicalMailRoot } from "../lib/mail-lock-namespace.js";
|
|
12
|
+
import { acquireMailLock, acquireMailLockSync, type MailLock, processIsGone, processStartToken } from "../lib/mail-lock.js";
|
|
13
|
+
import {
|
|
14
|
+
DELIVERY_PRESENTATION_TTL_MS,
|
|
15
|
+
PlacementDurabilityError,
|
|
16
|
+
decideEnvelopeForMailbox,
|
|
17
|
+
type MailboxPolicyRejectClass,
|
|
18
|
+
mailboxReplayStore,
|
|
19
|
+
parseSignedEnvelope,
|
|
20
|
+
pendingPlacementEntries,
|
|
21
|
+
type PlacementPhase,
|
|
22
|
+
placeCurRecord, fileIdentity, matchesFileIdentity,
|
|
23
|
+
type PresentationClaim,
|
|
24
|
+
} from "../lib/mailbox-policy.js";
|
|
25
|
+
import { verifiedMailTier } from "../lib/bridge-identity.js";
|
|
6
26
|
|
|
7
27
|
export interface MailMessage {
|
|
8
28
|
filename: string;
|
|
9
29
|
body: string;
|
|
10
30
|
receivedAt: Date;
|
|
11
|
-
/**
|
|
31
|
+
/** Untrusted transport metadata. Never grants authority. */
|
|
12
32
|
headers: Record<string, string>;
|
|
13
|
-
/** Sender
|
|
33
|
+
/** Sender from the verified envelope when received through MailClient. */
|
|
14
34
|
from: string;
|
|
35
|
+
/** Present only after signature and mailbox policy both passed. */
|
|
36
|
+
verifiedEnvelope?: Envelope;
|
|
37
|
+
trustTier?: "user" | "internal" | "external";
|
|
15
38
|
}
|
|
16
39
|
|
|
17
40
|
/**
|
|
@@ -22,21 +45,151 @@ export interface MailMessage {
|
|
|
22
45
|
* dead-lettered (the record stays in `new/`), so no retryable class is written
|
|
23
46
|
* here.
|
|
24
47
|
*/
|
|
25
|
-
type MailboxRejectClass =
|
|
48
|
+
type MailboxRejectClass = MailboxPolicyRejectClass;
|
|
26
49
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
50
|
+
/** A handoff token issued by deliverNext(); pass it to completeDelivery() or releaseDelivery(). */
|
|
51
|
+
export interface MailDelivery {
|
|
52
|
+
readonly message: MailMessage;
|
|
53
|
+
/** JSON-encoded [canonical mailbox path, messageId]; stable across presentations at that path. */
|
|
54
|
+
readonly deliveryKey: string;
|
|
55
|
+
/** This hand-over's presentation number; 1 for the first. */
|
|
56
|
+
readonly presentation: number;
|
|
57
|
+
}
|
|
30
58
|
|
|
31
59
|
/**
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
60
|
+
* Why deliverNext() handed nothing over although work may be waiting:
|
|
61
|
+
* - `lock-busy`: the mailbox lock was unavailable.
|
|
62
|
+
* - `active`: this module copy holds the token, or another copy/process has
|
|
63
|
+
* a claim whose process is not provably gone and whose lease has not expired.
|
|
64
|
+
* No presentation is counted.
|
|
65
|
+
* - `cli-record`: a `placing` record verifies only as CLI-promoted.
|
|
66
|
+
* The CLI lease sweep requires an expired or absent checkout; direct bridge
|
|
67
|
+
* and plugin startup recovery does not check lease expiry.
|
|
68
|
+
* - `pending-record-invalid` / `pending-record-ambiguous`: a `placing` record
|
|
69
|
+
* verified as neither format or both, was quarantined and its intent cleared.
|
|
70
|
+
* - `verification-failed` / `verification-unavailable`: the pending cur/ copy
|
|
71
|
+
* did not re-verify, or it verified but its envelope names a different message
|
|
72
|
+
* than the intent; or the verifier (or the trust-tier read) did not answer.
|
|
73
|
+
* - `record-changed`: the pending cur/ copy is missing (a `placing` intent whose
|
|
74
|
+
* copy is gone can instead be resolved as gone), its recorded identity is
|
|
75
|
+
* absent or mismatched, or its bytes changed during re-verification.
|
|
76
|
+
* - `storage-error`: resolving roots or listing new/ threw, or a history, cur/, quarantine or
|
|
77
|
+
* placement-state operation threw while pending placements were processed.
|
|
78
|
+
* Quarantine may have moved the payload and unlinked the intent before sync failed.
|
|
79
|
+
* - `new-mail-deferred`: one new/ file's attempt did not complete: reading it,
|
|
80
|
+
* verifying it (including the verifier or trust-tier read not answering), a
|
|
81
|
+
* history read or a commit operation threw, or a placement appeared before
|
|
82
|
+
* its commit lock. A storage failure may follow a commit. A listed file that
|
|
83
|
+
* disappears before it is read is skipped, and the scan continues.
|
|
38
84
|
*/
|
|
39
|
-
|
|
85
|
+
export type DeliveryDeferral =
|
|
86
|
+
| "lock-busy"
|
|
87
|
+
| "active"
|
|
88
|
+
| "cli-record"
|
|
89
|
+
| "pending-record-invalid"
|
|
90
|
+
| "pending-record-ambiguous"
|
|
91
|
+
| "verification-failed"
|
|
92
|
+
| "verification-unavailable"
|
|
93
|
+
| "record-changed"
|
|
94
|
+
| "storage-error"
|
|
95
|
+
| "new-mail-deferred";
|
|
96
|
+
|
|
97
|
+
/** What MailClient.deliverNext() returns (cli#617 slice b). */
|
|
98
|
+
export type DeliverNextResult =
|
|
99
|
+
| { status: "delivered"; delivery: MailDelivery }
|
|
100
|
+
/** No deliverable mail found during this scan; rejected mail may have been moved to `dlq/`. */
|
|
101
|
+
| { status: "idle" }
|
|
102
|
+
/** Work may be waiting; nothing was handed over. */
|
|
103
|
+
| { status: "deferred"; reason: DeliveryDeferral; detail: string; file?: string };
|
|
104
|
+
|
|
105
|
+
/** What MailClient.completeDelivery() returns (cli#617 slice b). */
|
|
106
|
+
export type DeliveryCompletion =
|
|
107
|
+
/** This call removed the message's `in_progress` intent. */
|
|
108
|
+
| { status: "completed" }
|
|
109
|
+
/** An earlier call with this delivery removed it. */
|
|
110
|
+
| { status: "already-completed" }
|
|
111
|
+
| { status: "quarantined" }
|
|
112
|
+
| { status: "deferred"; reason: "lock-busy" | "storage-error"; detail: string }
|
|
113
|
+
/**
|
|
114
|
+
* Not this hand-over's to finalize: a refusal finalizes no intent (one may
|
|
115
|
+
* already be absent). Only a locally issued `stale` or `identity` refusal
|
|
116
|
+
* releases the client's local token (its issued state becomes `released`);
|
|
117
|
+
* a `foreign` refusal changes no local state. `foreign`: not a
|
|
118
|
+
* delivery this MailClient issued. `stale`: no matching live intent and claim
|
|
119
|
+
* in the currently resolved mailbox. `identity`:
|
|
120
|
+
* recorded cur/ identity is absent or mismatched.
|
|
121
|
+
*/
|
|
122
|
+
| { status: "refused"; reason: "foreign" | "stale" | "identity"; detail: string };
|
|
123
|
+
|
|
124
|
+
export type DeliveryRelease =
|
|
125
|
+
| { status: "released" }
|
|
126
|
+
| { status: "quarantined" }
|
|
127
|
+
| { status: "refused"; reason: "foreign" | "stale" }
|
|
128
|
+
| { status: "deferred"; reason: "lock-busy" | "storage-error"; detail: string };
|
|
129
|
+
|
|
130
|
+
type DeferredResult = Extract<DeliverNextResult, { status: "deferred" }>;
|
|
131
|
+
/** A pending placement this call resolved without presenting (gone, terminal, or another writer's phase). */
|
|
132
|
+
type PendingOutcome = DeliverNextResult | { status: "resolved" };
|
|
133
|
+
const RESOLVED: PendingOutcome = { status: "resolved" };
|
|
134
|
+
|
|
135
|
+
function report(fn: () => void): void {
|
|
136
|
+
try { fn(); } catch {}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function deferred(reason: DeliveryDeferral, detail: string, file?: string): DeferredResult {
|
|
140
|
+
return { status: "deferred", reason, detail, ...(file === undefined ? {} : { file }) };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Tokens held by the MailClients of this module copy. Other copies in the same
|
|
145
|
+
* process are treated as live until process exit or lease expiry.
|
|
146
|
+
*/
|
|
147
|
+
const activePresentations = new Set<string>();
|
|
148
|
+
const moduleNonce = randomUUID();
|
|
149
|
+
let ownStartToken: string | null | undefined;
|
|
150
|
+
|
|
151
|
+
function ownClaim(token: string): PresentationClaim {
|
|
152
|
+
if (ownStartToken === undefined) ownStartToken = processStartToken(process.pid);
|
|
153
|
+
return { token, pid: process.pid, start: ownStartToken, moduleNonce };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function claimIsLive(claim: PresentationClaim | undefined, firstPresentedAt: string | undefined): boolean {
|
|
157
|
+
if (!claim) return false;
|
|
158
|
+
const own = ownClaim(claim.token);
|
|
159
|
+
if (claim.pid === own.pid && claim.start === own.start) {
|
|
160
|
+
if (claim.moduleNonce === moduleNonce) return activePresentations.has(claim.token);
|
|
161
|
+
return firstPresentedAt === undefined || Date.now() - Date.parse(firstPresentedAt) <= DELIVERY_PRESENTATION_TTL_MS;
|
|
162
|
+
}
|
|
163
|
+
if (firstPresentedAt !== undefined && Date.now() - Date.parse(firstPresentedAt) > DELIVERY_PRESENTATION_TTL_MS) return false;
|
|
164
|
+
return !processIsGone(claim.pid, claim.start);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function isCliPromotedRecord(record: unknown): record is {
|
|
168
|
+
id: string; from: string; to: string; body: string; timestamp: string; read: boolean;
|
|
169
|
+
envelopeId: string; envelope: Envelope; trustTier?: string;
|
|
170
|
+
checkedOutAt: string; checkedOutBy: string; deliveryAttempts: number; replyToId?: string;
|
|
171
|
+
} {
|
|
172
|
+
if (record === null || typeof record !== "object" || Array.isArray(record)) return false;
|
|
173
|
+
const r = record as Record<string, unknown>;
|
|
174
|
+
return typeof r.id === "string" && r.id.length > 0 &&
|
|
175
|
+
typeof r.from === "string" && typeof r.to === "string" && typeof r.body === "string" &&
|
|
176
|
+
typeof r.timestamp === "string" && typeof r.read === "boolean" &&
|
|
177
|
+
typeof r.envelopeId === "string" && r.envelopeId.length > 0 &&
|
|
178
|
+
r.envelope !== null && typeof r.envelope === "object" && !Array.isArray(r.envelope) &&
|
|
179
|
+
parseSignedEnvelope(JSON.stringify(r.envelope)).ok &&
|
|
180
|
+
(r.trustTier === undefined || r.trustTier === "user" || r.trustTier === "internal" || r.trustTier === "external") &&
|
|
181
|
+
typeof r.checkedOutAt === "string" && typeof r.checkedOutBy === "string" &&
|
|
182
|
+
Number.isInteger(r.deliveryAttempts) && (r.deliveryAttempts as number) >= 1 &&
|
|
183
|
+
(r.replyToId === undefined || typeof r.replyToId === "string");
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function isMissing(err: unknown): boolean {
|
|
187
|
+
return (err as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
type VerifyOutcome =
|
|
191
|
+
| { pass: true; envelope: Envelope }
|
|
192
|
+
| { pass: false; class: MailboxRejectClass; reason: string; from?: string };
|
|
40
193
|
|
|
41
194
|
/**
|
|
42
195
|
* Write the dlq sidecar for a TERMINAL rejection.
|
|
@@ -58,92 +211,125 @@ function writeRejectSidecar(dlqDir: string, filename: string, cls: MailboxReject
|
|
|
58
211
|
);
|
|
59
212
|
}
|
|
60
213
|
|
|
214
|
+
function sameFileIdentity(a: string, b: string): boolean {
|
|
215
|
+
const sa = lstatOrAbsent(a);
|
|
216
|
+
const sb = lstatOrAbsent(b);
|
|
217
|
+
return sa !== null && sb !== null && sa.isFile() && sb.isFile()
|
|
218
|
+
&& matchesFileIdentity(sa, fileIdentity(sb, readFileSync(b)), readFileSync(a));
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* cli#617 slice (a): recovery resumes only an intent whose phase resolves to
|
|
223
|
+
* `placing` (phaseOf). One that resolves to any other phase (`in_progress`, or
|
|
224
|
+
* `unknown`: an unsupported value in a recognized field) is never presented or
|
|
225
|
+
* finished. A phase seen in the listing skips the record before its payload
|
|
226
|
+
* is read, and the under-lock recheck catches a phase that changed after the
|
|
227
|
+
* payload was read and verified.
|
|
228
|
+
*
|
|
229
|
+
* This is the BATCH reader (`checkNewMail`), which stays at-most-once until
|
|
230
|
+
* slice (c) wires the per-message delivery API. Slice (b)'s `deliverNext`
|
|
231
|
+
* presents an `in_progress` intent again through its own completion-gated path
|
|
232
|
+
* (`presentPending`), not this one.
|
|
233
|
+
*/
|
|
234
|
+
function resumableOnRecovery(phase: PlacementPhase | null): boolean {
|
|
235
|
+
return phase === "placing";
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* cli#636: resolve both roots to canonical path strings once per operation;
|
|
240
|
+
* derive subsequent paths, including locks, by joining those strings.
|
|
241
|
+
*/
|
|
242
|
+
interface OperationRoots {
|
|
243
|
+
/** Canonical mail-root string: bridge-principal trust, acceptance stripes, recipient inboxes. */
|
|
244
|
+
readonly mailRoot: string;
|
|
245
|
+
/** Canonical mailbox string: the mailbox lock, maildir paths and replay state. */
|
|
246
|
+
readonly mailbox: string;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
function lstatOrAbsent(path: string): import("node:fs").BigIntStats | null {
|
|
250
|
+
try {
|
|
251
|
+
return lstatSync(path, { bigint: true });
|
|
252
|
+
} catch (err) {
|
|
253
|
+
if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
|
|
254
|
+
throw err;
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
61
258
|
/**
|
|
62
259
|
* Maildir-compatible mail client.
|
|
63
260
|
* Reads from mailDir/inbox/new and moves processed messages to mailDir/inbox/cur.
|
|
64
261
|
* Writes outgoing mail to mailDir/outbox/new.
|
|
65
262
|
*/
|
|
66
263
|
export class MailClient {
|
|
67
|
-
private
|
|
68
|
-
|
|
69
|
-
private
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
264
|
+
private readonly flairClient: FlairClient;
|
|
265
|
+
/** cli#617 slice (b): the deliveries this client issued, keyed by the delivery object itself. */
|
|
266
|
+
private readonly issued = new WeakMap<MailDelivery, {
|
|
267
|
+
token: string;
|
|
268
|
+
messageId: string;
|
|
269
|
+
file: string;
|
|
270
|
+
mailbox: string;
|
|
271
|
+
state: "active" | "released" | "completed";
|
|
272
|
+
}>();
|
|
73
273
|
|
|
74
274
|
constructor(
|
|
75
275
|
public readonly mailDir: string,
|
|
76
276
|
private readonly events?: EventLogger,
|
|
77
277
|
private readonly agentId = "unknown",
|
|
78
|
-
|
|
278
|
+
flairClient?: FlairClient,
|
|
279
|
+
/** Configured Flair signing key, checked against both standard locations. */
|
|
280
|
+
private readonly signingKeyPath?: string,
|
|
79
281
|
) {
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
282
|
+
// cli#380: construction without a verifier throws.
|
|
283
|
+
if (!flairClient) {
|
|
284
|
+
throw new Error(
|
|
285
|
+
`MailClient requires a Flair verifier for "${agentId}": refusing to construct a mailbox that ` +
|
|
286
|
+
`could promote unverified mail (cli#380).`,
|
|
287
|
+
);
|
|
86
288
|
}
|
|
289
|
+
this.flairClient = flairClient;
|
|
290
|
+
// cli#636: no resolved canonical root is cached at construction.
|
|
291
|
+
this.operationRoots();
|
|
87
292
|
}
|
|
88
293
|
|
|
89
294
|
/**
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
* Verification is MANDATORY — a record is promoted ONLY after its signed
|
|
93
|
-
* envelope verifies against the local Flair. There is no unverified path:
|
|
94
|
-
* - NO verifier configured → refuse; the record stays in new/ (an absent
|
|
95
|
-
* client must never mean "promote without verifying");
|
|
96
|
-
* - the verifier THROWS (Flair unreachable) → refuse; the record stays in
|
|
97
|
-
* new/ for a later check (a throw must never mean "pass");
|
|
98
|
-
* - the verifier REJECTS → dead-letter to dlq/ with a `.reason` sidecar.
|
|
99
|
-
* Unverified input must never reach the tool-holding model.
|
|
295
|
+
* Resolve `mailDir` and `<mail root>/<agentId>` to canonical path strings;
|
|
296
|
+
* create maildir subdirectories beneath the mailbox string.
|
|
100
297
|
*/
|
|
101
|
-
|
|
102
|
-
|
|
298
|
+
private operationRoots(): OperationRoots {
|
|
299
|
+
const mailRoot = canonicalMailRoot(this.mailDir);
|
|
300
|
+
// Create the mailbox with the default mode first (canonicalMailboxRoot
|
|
301
|
+
// would create it 0700); resolving it then creates nothing.
|
|
302
|
+
mkdirSync(join(mailRoot, this.agentId), { recursive: true });
|
|
303
|
+
const mailbox = canonicalMailboxRoot(join(mailRoot, this.agentId));
|
|
304
|
+
for (const dir of ["new", "cur", "dlq", "outbox"]) mkdirSync(join(mailbox, dir), { recursive: true });
|
|
305
|
+
return { mailRoot, mailbox };
|
|
306
|
+
}
|
|
103
307
|
|
|
104
|
-
|
|
308
|
+
async checkNewMail(): Promise<MailMessage[]> {
|
|
105
309
|
const messages: MailMessage[] = [];
|
|
310
|
+
const roots = this.operationRoots();
|
|
311
|
+
await this.recoverInterruptedPlacements(messages, roots);
|
|
312
|
+
const inboxNew = join(roots.mailbox, "new");
|
|
313
|
+
if (!existsSync(inboxNew)) return messages;
|
|
106
314
|
|
|
107
|
-
|
|
108
|
-
// leave the records in new/ so a later check with a verifier — or the
|
|
109
|
-
// shared promote() path — can process them.
|
|
110
|
-
if (!this.flairClient) {
|
|
111
|
-
if (files.length === 0) return [];
|
|
112
|
-
this.events?.emit({
|
|
113
|
-
type: "mail.receive",
|
|
114
|
-
agent: this.agentId,
|
|
115
|
-
status: "rejected",
|
|
116
|
-
from: "unknown",
|
|
117
|
-
durationMs: 0,
|
|
118
|
-
error: "no verifier configured — refusing to promote unverified mail",
|
|
119
|
-
});
|
|
120
|
-
if (!this.warnedNoVerifier) {
|
|
121
|
-
this.warnedNoVerifier = true;
|
|
122
|
-
console.error(
|
|
123
|
-
`[MailClient] no Flair verifier configured for "${this.agentId}": refusing to promote ` +
|
|
124
|
-
`${files.length} unverified message(s) from new/. Unverified input must never reach the ` +
|
|
125
|
-
`model — configure flair (url + key) or promote through the shared promote() lifecycle.`,
|
|
126
|
-
);
|
|
127
|
-
}
|
|
128
|
-
return [];
|
|
129
|
-
}
|
|
315
|
+
const files = readdirSync(inboxNew).filter(isMailboxMessageFile);
|
|
130
316
|
|
|
131
317
|
for (const file of files) {
|
|
132
318
|
const started = Date.now();
|
|
133
|
-
const srcPath = join(
|
|
319
|
+
const srcPath = join(inboxNew, file);
|
|
134
320
|
|
|
135
321
|
let body: string;
|
|
136
322
|
try {
|
|
137
323
|
body = readFileSync(srcPath, "utf-8");
|
|
138
324
|
} catch (err) {
|
|
139
|
-
this.events?.emit({
|
|
325
|
+
report(() => this.events?.emit({
|
|
140
326
|
type: "mail.receive",
|
|
141
327
|
agent: this.agentId,
|
|
142
328
|
status: "error",
|
|
143
329
|
from: "unknown",
|
|
144
330
|
durationMs: Date.now() - started,
|
|
145
331
|
error: sanitizeError(err),
|
|
146
|
-
});
|
|
332
|
+
}));
|
|
147
333
|
continue; // leave in new/ — a later check retries
|
|
148
334
|
}
|
|
149
335
|
|
|
@@ -154,115 +340,811 @@ export class MailClient {
|
|
|
154
340
|
verifyResult = await this.verifyMailBody(body);
|
|
155
341
|
} catch (err) {
|
|
156
342
|
const detail = sanitizeError(err);
|
|
157
|
-
this.events?.emit({
|
|
343
|
+
report(() => this.events?.emit({
|
|
158
344
|
type: "mail.receive",
|
|
159
345
|
agent: this.agentId,
|
|
160
346
|
status: "error",
|
|
161
347
|
from: "unknown",
|
|
162
348
|
durationMs: Date.now() - started,
|
|
163
349
|
error: detail,
|
|
164
|
-
});
|
|
165
|
-
console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`);
|
|
350
|
+
}));
|
|
351
|
+
report(() => console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`));
|
|
166
352
|
continue; // leave in new/
|
|
167
353
|
}
|
|
168
354
|
|
|
169
355
|
if (!verifyResult.pass) {
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
356
|
+
this.deadLetter(file, srcPath, verifyResult, started, roots);
|
|
357
|
+
continue;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
let trustTier: MailMessage["trustTier"];
|
|
361
|
+
try {
|
|
362
|
+
trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
|
|
363
|
+
} catch (err) {
|
|
364
|
+
const detail = sanitizeError(err);
|
|
365
|
+
report(() => this.events?.emit({
|
|
178
366
|
type: "mail.receive",
|
|
179
367
|
agent: this.agentId,
|
|
180
|
-
status: "
|
|
181
|
-
from: verifyResult.from
|
|
368
|
+
status: "error",
|
|
369
|
+
from: verifyResult.envelope.from,
|
|
182
370
|
durationMs: Date.now() - started,
|
|
183
|
-
error:
|
|
184
|
-
});
|
|
185
|
-
|
|
371
|
+
error: detail,
|
|
372
|
+
}));
|
|
373
|
+
report(() => console.error(`[MailClient] trust tier could not be resolved for ${file} — NOT promoting: ${detail}`));
|
|
374
|
+
continue; // leave in new/
|
|
186
375
|
}
|
|
187
376
|
|
|
188
|
-
// Promote to cur/ — verified, and addressed to this mailbox.
|
|
189
377
|
try {
|
|
190
|
-
const
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
378
|
+
const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope);
|
|
379
|
+
// "live-placement" is returned only to the delivery API (a claim was passed).
|
|
380
|
+
if (committed === "already-delivered" || committed === "live-placement") continue;
|
|
381
|
+
if (committed) {
|
|
382
|
+
this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
|
|
383
|
+
continue;
|
|
384
|
+
}
|
|
385
|
+
const from = verifyResult.envelope.from;
|
|
386
|
+
messages.push({
|
|
387
|
+
filename: file, body, receivedAt: new Date(), headers: {}, from,
|
|
388
|
+
verifiedEnvelope: verifyResult.envelope,
|
|
389
|
+
trustTier,
|
|
390
|
+
});
|
|
391
|
+
report(() => this.events?.emit({
|
|
201
392
|
type: "mail.receive",
|
|
202
393
|
agent: this.agentId,
|
|
203
394
|
status: "ok",
|
|
204
395
|
from,
|
|
205
396
|
durationMs: Date.now() - started,
|
|
206
|
-
});
|
|
397
|
+
}));
|
|
207
398
|
} catch (err) {
|
|
208
|
-
this.events?.emit({
|
|
399
|
+
report(() => this.events?.emit({
|
|
209
400
|
type: "mail.receive",
|
|
210
401
|
agent: this.agentId,
|
|
211
402
|
status: "error",
|
|
212
403
|
from: "unknown",
|
|
213
404
|
durationMs: Date.now() - started,
|
|
214
405
|
error: sanitizeError(err),
|
|
215
|
-
});
|
|
406
|
+
}));
|
|
216
407
|
}
|
|
217
408
|
}
|
|
218
409
|
|
|
219
410
|
return messages;
|
|
220
411
|
}
|
|
221
412
|
|
|
413
|
+
/**
|
|
414
|
+
* Present verified, unclaimed pending work before committing new mail.
|
|
415
|
+
* Unresolved placing/in_progress work defers deliverNext() commits. The token
|
|
416
|
+
* set covers MailClients of this module copy; claims from other copies in the
|
|
417
|
+
* same process are treated as live until process exit or lease expiry.
|
|
418
|
+
* Retry deferred completion or release on the same hand-over.
|
|
419
|
+
*/
|
|
420
|
+
async deliverNext(): Promise<DeliverNextResult> {
|
|
421
|
+
let roots: OperationRoots;
|
|
422
|
+
try {
|
|
423
|
+
roots = this.operationRoots();
|
|
424
|
+
} catch (err) {
|
|
425
|
+
this.emitRecoveryError(err);
|
|
426
|
+
return deferred("storage-error", `mailbox roots unavailable: ${sanitizeError(err)}`);
|
|
427
|
+
}
|
|
428
|
+
let pending: Array<{ messageId: string; file: string; phase: PlacementPhase }>;
|
|
429
|
+
const listing = await this.lockOrDefer(roots, "pending placements not listed");
|
|
430
|
+
if ("status" in listing) return listing;
|
|
431
|
+
try {
|
|
432
|
+
pending = pendingPlacementEntries(roots.mailbox);
|
|
433
|
+
} catch (err) {
|
|
434
|
+
this.emitRecoveryError(err);
|
|
435
|
+
return deferred("storage-error", `pending placements unavailable: ${sanitizeError(err)}`);
|
|
436
|
+
} finally {
|
|
437
|
+
listing.release();
|
|
438
|
+
}
|
|
439
|
+
pending.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
|
|
440
|
+
let firstDeferral: DeferredResult | null = null;
|
|
441
|
+
for (const { messageId, file, phase } of pending) {
|
|
442
|
+
if (phase === "unknown") continue; // another writer's phase: preserved, never presented (slice a)
|
|
443
|
+
let outcome: PendingOutcome;
|
|
444
|
+
try {
|
|
445
|
+
outcome = await this.presentPending(roots, messageId, file);
|
|
446
|
+
} catch (err) {
|
|
447
|
+
this.emitRecoveryError(err);
|
|
448
|
+
outcome = deferred("storage-error", sanitizeError(err), file);
|
|
449
|
+
}
|
|
450
|
+
if (outcome.status === "delivered") return outcome;
|
|
451
|
+
if (outcome.status === "deferred") firstDeferral ??= outcome;
|
|
452
|
+
}
|
|
453
|
+
if (firstDeferral) return firstDeferral;
|
|
454
|
+
return this.commitNextForDelivery(roots);
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
/** Finalize only this client's issued claim, with its recorded cur/ file identity, under the mailbox lock. */
|
|
458
|
+
async completeDelivery(delivery: MailDelivery): Promise<DeliveryCompletion> {
|
|
459
|
+
const issued = this.issued.get(delivery);
|
|
460
|
+
if (!issued) return { status: "refused", reason: "foreign", detail: "not a delivery this MailClient handed over" };
|
|
461
|
+
if (issued.state === "completed") return { status: "already-completed" };
|
|
462
|
+
let roots: OperationRoots;
|
|
463
|
+
try {
|
|
464
|
+
roots = this.operationRoots();
|
|
465
|
+
} catch (err) {
|
|
466
|
+
this.emitRecoveryError(err);
|
|
467
|
+
return { status: "deferred", reason: "storage-error", detail: `mailbox roots unavailable (${sanitizeError(err)}); delivery not finalized` };
|
|
468
|
+
}
|
|
469
|
+
const lock = await this.lockOrDefer(roots, "delivery not finalized; intent state unknown, retry");
|
|
470
|
+
if ("status" in lock) return { status: "deferred", reason: "lock-busy", detail: lock.detail };
|
|
471
|
+
let result: ReturnType<ReturnType<typeof mailboxReplayStore>["completePlacement"]>;
|
|
472
|
+
try {
|
|
473
|
+
if (this.expireIssuedDelivery(roots.mailbox, issued)) return { status: "quarantined" };
|
|
474
|
+
result = mailboxReplayStore(roots.mailbox).completePlacement(issued.messageId, issued.file, issued.token);
|
|
475
|
+
} catch (err) {
|
|
476
|
+
this.emitRecoveryError(err);
|
|
477
|
+
const detail = err instanceof PlacementDurabilityError
|
|
478
|
+
? err.message
|
|
479
|
+
: err instanceof Error && err.name === "MalformedPlacementIntentError"
|
|
480
|
+
? "quarantined placement intent needs repair before a retry can complete"
|
|
481
|
+
: `placement state unavailable (${sanitizeError(err)}); completion state unknown`;
|
|
482
|
+
return { status: "deferred", reason: "storage-error", detail };
|
|
483
|
+
} finally {
|
|
484
|
+
lock.release();
|
|
485
|
+
}
|
|
486
|
+
activePresentations.delete(issued.token);
|
|
487
|
+
if (result === "completed") {
|
|
488
|
+
issued.state = "completed";
|
|
489
|
+
return { status: "completed" };
|
|
490
|
+
}
|
|
491
|
+
issued.state = "released";
|
|
492
|
+
if (result === "identity") {
|
|
493
|
+
return { status: "refused", reason: "identity", detail: `cur/${issued.file} recorded identity is absent or mismatched; not finalized` };
|
|
494
|
+
}
|
|
495
|
+
return {
|
|
496
|
+
status: "refused",
|
|
497
|
+
reason: "stale",
|
|
498
|
+
detail: `message ${issued.messageId}: no matching live intent and claim in the currently resolved mailbox`,
|
|
499
|
+
};
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
/** Persist matching claim release under the issued mailbox's lock; contention and storage errors defer. */
|
|
503
|
+
releaseDelivery(delivery: MailDelivery): DeliveryRelease {
|
|
504
|
+
const issued = this.issued.get(delivery);
|
|
505
|
+
if (!issued) return { status: "refused", reason: "foreign" };
|
|
506
|
+
if (issued.state !== "active") return { status: "refused", reason: "stale" };
|
|
507
|
+
try {
|
|
508
|
+
const lock = acquireMailLockSync(issued.mailbox, { timeoutMs: 0 });
|
|
509
|
+
if (!lock) return { status: "deferred", reason: "lock-busy", detail: "delivery not released; retry" };
|
|
510
|
+
let released: boolean;
|
|
511
|
+
try {
|
|
512
|
+
if (this.expireIssuedDelivery(issued.mailbox, issued)) return { status: "quarantined" };
|
|
513
|
+
released = mailboxReplayStore(issued.mailbox).releasePlacement(issued.messageId, issued.file, issued.token);
|
|
514
|
+
} finally {
|
|
515
|
+
lock.release();
|
|
516
|
+
}
|
|
517
|
+
if (!released) return { status: "refused", reason: "stale" };
|
|
518
|
+
issued.state = "released";
|
|
519
|
+
activePresentations.delete(issued.token);
|
|
520
|
+
return { status: "released" };
|
|
521
|
+
} catch (err) {
|
|
522
|
+
this.emitRecoveryError(err);
|
|
523
|
+
return { status: "deferred", reason: "storage-error", detail: `release persistence failed (${sanitizeError(err)}); retry` };
|
|
524
|
+
}
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
/** Called under the mailbox lock; only this issued claim may hit the deadline. */
|
|
528
|
+
private expireIssuedDelivery(mailbox: string, issued: { messageId: string; file: string; token: string; state: string }): boolean {
|
|
529
|
+
const replay = mailboxReplayStore(mailbox);
|
|
530
|
+
const state = replay.placementState(issued.file);
|
|
531
|
+
if (state?.claim?.token !== issued.token) return false;
|
|
532
|
+
const expiry = replay.expireOverdue(issued.messageId, issued.file, new Date().toISOString());
|
|
533
|
+
if (expiry.status !== "failed") return false;
|
|
534
|
+
issued.state = "released";
|
|
535
|
+
activePresentations.delete(issued.token);
|
|
536
|
+
this.logQuarantine(issued.messageId, expiry.presentations, "deadline");
|
|
537
|
+
return true;
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
/** Record a hand-over: the token is already held in this module copy; bind it to the delivery object. */
|
|
541
|
+
private issue(roots: OperationRoots, token: string, messageId: string, file: string, presentation: number, message: MailMessage): MailDelivery {
|
|
542
|
+
const delivery: MailDelivery = Object.freeze({ message, deliveryKey: JSON.stringify([roots.mailbox, messageId]), presentation });
|
|
543
|
+
this.issued.set(delivery, { token, messageId, file, mailbox: roots.mailbox, state: "active" });
|
|
544
|
+
return delivery;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
/**
|
|
548
|
+
* Present one pending placement: inspect it under the lock, re-verify its
|
|
549
|
+
* cur/ copy outside the lock, then re-check and advance under the lock.
|
|
550
|
+
*/
|
|
551
|
+
private async presentPending(roots: OperationRoots, messageId: string, file: string): Promise<PendingOutcome> {
|
|
552
|
+
const inspected = await this.inspectPending(roots, messageId, file);
|
|
553
|
+
if (inspected.status !== "read") return inspected;
|
|
554
|
+
let outcome: VerifyOutcome;
|
|
555
|
+
try {
|
|
556
|
+
if (inspected.phase === "placing") {
|
|
557
|
+
const classified = await this.classifyPending(inspected.bytes);
|
|
558
|
+
if (classified.kind === "cli") return deferred("cli-record", `cur/${file} verifies only as CLI-promoted; awaiting CLI recovery`, file);
|
|
559
|
+
if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
|
|
560
|
+
return this.quarantinePending(roots, messageId, file, inspected.bytes, classified.kind);
|
|
561
|
+
}
|
|
562
|
+
outcome = classified.outcome;
|
|
563
|
+
} else {
|
|
564
|
+
outcome = await this.verifyMailBody(inspected.bytes.toString("utf8"));
|
|
565
|
+
}
|
|
566
|
+
} catch (err) {
|
|
567
|
+
return deferred("verification-unavailable", `re-verification could not run: ${sanitizeError(err)}`, file);
|
|
568
|
+
}
|
|
569
|
+
if (!outcome.pass) return deferred("verification-failed", `the cur/ copy did not re-verify (${outcome.class}): ${outcome.reason}`, file);
|
|
570
|
+
if (outcome.envelope.messageId !== messageId) {
|
|
571
|
+
return deferred("verification-failed", "the cur/ copy's envelope names another message than the intent", file);
|
|
572
|
+
}
|
|
573
|
+
let trustTier: MailMessage["trustTier"];
|
|
574
|
+
try {
|
|
575
|
+
trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
|
|
576
|
+
} catch (err) {
|
|
577
|
+
return deferred("verification-unavailable", `trust tier unavailable: ${sanitizeError(err)}`, file);
|
|
578
|
+
}
|
|
579
|
+
return this.presentUnderLock(roots, messageId, file, inspected.bytes, outcome.envelope, trustTier);
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
private async classifyPending(bytes: Buffer): Promise<
|
|
583
|
+
| { kind: "raw"; outcome: Extract<VerifyOutcome, { pass: true }> }
|
|
584
|
+
| { kind: "cli" }
|
|
585
|
+
| { kind: "pending-record-invalid" }
|
|
586
|
+
| { kind: "pending-record-ambiguous" }
|
|
587
|
+
> {
|
|
588
|
+
const body = bytes.toString("utf8");
|
|
589
|
+
const raw = await this.verifyMailBody(body);
|
|
590
|
+
let record: unknown;
|
|
591
|
+
try { record = JSON.parse(body); } catch { record = null; }
|
|
592
|
+
let cli: VerifyOutcome | undefined;
|
|
593
|
+
if (isCliPromotedRecord(record)) {
|
|
594
|
+
const env = record.envelope;
|
|
595
|
+
if (record.from === env.from && record.to === env.to && record.body === env.body &&
|
|
596
|
+
record.timestamp === env.timestamp && record.envelopeId === env.messageId && record.replyToId === env.replyToId) {
|
|
597
|
+
cli = await this.verifyMailBody(JSON.stringify({ from: record.from, body: JSON.stringify(env) }));
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
if (raw.pass && cli?.pass) return { kind: "pending-record-ambiguous" };
|
|
601
|
+
if (raw.pass) return { kind: "raw", outcome: raw };
|
|
602
|
+
if (cli?.pass) return { kind: "cli" };
|
|
603
|
+
return { kind: "pending-record-invalid" };
|
|
604
|
+
}
|
|
605
|
+
|
|
606
|
+
private async quarantinePending(
|
|
607
|
+
roots: OperationRoots,
|
|
608
|
+
messageId: string, file: string, bytes: Buffer,
|
|
609
|
+
reason: "pending-record-invalid" | "pending-record-ambiguous",
|
|
610
|
+
): Promise<PendingOutcome> {
|
|
611
|
+
const lock = await this.lockOrDefer(roots, "pending record not quarantined", file);
|
|
612
|
+
if ("status" in lock) return lock;
|
|
613
|
+
try {
|
|
614
|
+
const replay = mailboxReplayStore(roots.mailbox);
|
|
615
|
+
const state = replay.placementState(file);
|
|
616
|
+
if (!state || state.messageId !== messageId || state.phase !== "placing") return RESOLVED;
|
|
617
|
+
if (!replay.ownsPendingPlacement(messageId, file) || !readFileSync(join(roots.mailbox, "cur", file)).equals(bytes)) {
|
|
618
|
+
return deferred("record-changed", `cur/${file} identity absent or mismatched, or bytes changed; not quarantined`, file);
|
|
619
|
+
}
|
|
620
|
+
mkdirSync(join(roots.mailbox, "dlq"), { recursive: true });
|
|
621
|
+
writeRejectSidecar(join(roots.mailbox, "dlq"), file, "invalid", reason);
|
|
622
|
+
renameSync(join(roots.mailbox, "cur", file), join(roots.mailbox, "dlq", file));
|
|
623
|
+
replay.finishPlacement(messageId, file);
|
|
624
|
+
return deferred(reason, `cur/${file} quarantined: ${reason}; intent cleared`, file);
|
|
625
|
+
} finally {
|
|
626
|
+
lock.release();
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
private async inspectPending(roots: OperationRoots, messageId: string, file: string): Promise<PendingOutcome | { status: "read"; bytes: Buffer; phase: PlacementPhase }> {
|
|
631
|
+
const lock = await this.lockOrDefer(roots, "pending placement not inspected", file);
|
|
632
|
+
if ("status" in lock) return lock;
|
|
633
|
+
try {
|
|
634
|
+
const replay = mailboxReplayStore(roots.mailbox);
|
|
635
|
+
const state = replay.placementState(file);
|
|
636
|
+
if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown") return RESOLVED;
|
|
637
|
+
if (state.phase === "in_progress") {
|
|
638
|
+
if (claimIsLive(state.claim, state.firstPresentedAt)) {
|
|
639
|
+
return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
|
|
640
|
+
}
|
|
641
|
+
const expiry = replay.expireOverdue(messageId, file, new Date().toISOString());
|
|
642
|
+
if (expiry.status === "absent") return RESOLVED;
|
|
643
|
+
if (expiry.status === "failed") {
|
|
644
|
+
this.logQuarantine(messageId, expiry.presentations, "deadline");
|
|
645
|
+
return RESOLVED;
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
const curPath = join(roots.mailbox, "cur", file);
|
|
649
|
+
let bytes: Buffer;
|
|
650
|
+
try {
|
|
651
|
+
bytes = readFileSync(curPath);
|
|
652
|
+
} catch (err) {
|
|
653
|
+
if (!isMissing(err)) throw err;
|
|
654
|
+
if (state.phase === "placing" && lstatOrAbsent(curPath) === null) {
|
|
655
|
+
replay.finishPlacement(messageId, file);
|
|
656
|
+
return RESOLVED;
|
|
657
|
+
}
|
|
658
|
+
return deferred("record-changed", `cur/${file} is missing for a ${state.phase} intent`, file);
|
|
659
|
+
}
|
|
660
|
+
return { status: "read", bytes, phase: state.phase };
|
|
661
|
+
} finally {
|
|
662
|
+
lock.release();
|
|
663
|
+
}
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* Re-read the intent, its claim, the recorded identity and the raw bytes
|
|
668
|
+
* under the lock (all may have changed during re-verification), then advance
|
|
669
|
+
* the presentation with a new claim and hand the message over. A bound hit
|
|
670
|
+
* writes the terminal `failed` phase and presents nothing.
|
|
671
|
+
*/
|
|
672
|
+
private async presentUnderLock(
|
|
673
|
+
roots: OperationRoots,
|
|
674
|
+
messageId: string,
|
|
675
|
+
file: string,
|
|
676
|
+
bytes: Buffer,
|
|
677
|
+
envelope: Envelope,
|
|
678
|
+
trustTier: MailMessage["trustTier"],
|
|
679
|
+
): Promise<PendingOutcome> {
|
|
680
|
+
const lock = await this.lockOrDefer(roots, "pending placement not presented", file);
|
|
681
|
+
if ("status" in lock) return lock;
|
|
682
|
+
try {
|
|
683
|
+
const replay = mailboxReplayStore(roots.mailbox);
|
|
684
|
+
const state = replay.placementState(file);
|
|
685
|
+
if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown") return RESOLVED;
|
|
686
|
+
if (state.phase === "in_progress" && claimIsLive(state.claim, state.firstPresentedAt)) {
|
|
687
|
+
return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
|
|
688
|
+
}
|
|
689
|
+
if (!replay.ownsPendingPlacement(messageId, file)) {
|
|
690
|
+
return deferred("record-changed", `cur/${file} recorded identity is absent or mismatched`, file);
|
|
691
|
+
}
|
|
692
|
+
let current: Buffer;
|
|
693
|
+
try {
|
|
694
|
+
current = readFileSync(join(roots.mailbox, "cur", file));
|
|
695
|
+
} catch (err) {
|
|
696
|
+
if (isMissing(err)) return deferred("record-changed", `cur/${file} disappeared during re-verification`, file);
|
|
697
|
+
throw err;
|
|
698
|
+
}
|
|
699
|
+
if (!current.equals(bytes)) return deferred("record-changed", `cur/${file} changed during re-verification`, file);
|
|
700
|
+
if (!replay.isConsumed(messageId, file)) replay.recordConsumed(messageId);
|
|
701
|
+
const token = randomUUID();
|
|
702
|
+
const advance = replay.advancePresentation(messageId, file, new Date().toISOString(), ownClaim(token));
|
|
703
|
+
if (advance.status === "absent") return RESOLVED;
|
|
704
|
+
if (advance.status === "failed") {
|
|
705
|
+
this.logQuarantine(messageId, advance.presentations, "count");
|
|
706
|
+
return RESOLVED;
|
|
707
|
+
}
|
|
708
|
+
// Hold the token before releasing the lock so another local call defers.
|
|
709
|
+
activePresentations.add(token);
|
|
710
|
+
const message: MailMessage = {
|
|
711
|
+
filename: file,
|
|
712
|
+
body: bytes.toString("utf8"),
|
|
713
|
+
receivedAt: new Date(),
|
|
714
|
+
headers: {},
|
|
715
|
+
from: envelope.from,
|
|
716
|
+
verifiedEnvelope: envelope,
|
|
717
|
+
trustTier,
|
|
718
|
+
};
|
|
719
|
+
return { status: "delivered", delivery: this.issue(roots, token, messageId, file, advance.presentations, message) };
|
|
720
|
+
} finally {
|
|
721
|
+
lock.release();
|
|
722
|
+
}
|
|
723
|
+
}
|
|
724
|
+
|
|
725
|
+
/**
|
|
726
|
+
* The bound's log line. It is written after the durable `failed` write, so a
|
|
727
|
+
* kill between the two leaves the `failed` intent (the durable record) and
|
|
728
|
+
* no line.
|
|
729
|
+
*/
|
|
730
|
+
private logQuarantine(messageId: string, presentations: number, cause: "count" | "deadline"): void {
|
|
731
|
+
const why = cause === "deadline"
|
|
732
|
+
? `the deadline (${DELIVERY_PRESENTATION_TTL_MS / 3_600_000} h after the first presentation) passed`
|
|
733
|
+
: "the presentation bound was reached";
|
|
734
|
+
report(() => console.warn(
|
|
735
|
+
`[MailClient] placement quarantined for mailbox ${this.agentId}: message ${messageId} not completed ` +
|
|
736
|
+
`after ${presentations} presentation(s); ${why}; failure transition does not delete an existing payload`,
|
|
737
|
+
));
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
/**
|
|
741
|
+
* Commit the next verifiable new/ message to cur/ with a live `in_progress`
|
|
742
|
+
* intent. Under the commit lock it re-checks that no `placing` or
|
|
743
|
+
* `in_progress` placement is pending, so a concurrent call cannot add a
|
|
744
|
+
* second message in flight.
|
|
745
|
+
*/
|
|
746
|
+
private async commitNextForDelivery(roots: OperationRoots): Promise<DeliverNextResult> {
|
|
747
|
+
let files: string[];
|
|
748
|
+
try {
|
|
749
|
+
files = existsSync(join(roots.mailbox, "new"))
|
|
750
|
+
? readdirSync(join(roots.mailbox, "new")).filter(isMailboxMessageFile).sort()
|
|
751
|
+
: [];
|
|
752
|
+
} catch (err) {
|
|
753
|
+
this.emitRecoveryError(err);
|
|
754
|
+
return deferred("storage-error", `new/ unavailable: ${sanitizeError(err)}`);
|
|
755
|
+
}
|
|
756
|
+
let skipped: { file: string; detail: string } | null = null;
|
|
757
|
+
for (const file of files) {
|
|
758
|
+
const started = Date.now();
|
|
759
|
+
const srcPath = join(roots.mailbox, "new", file);
|
|
760
|
+
let body: string;
|
|
761
|
+
try {
|
|
762
|
+
body = readFileSync(srcPath, "utf-8");
|
|
763
|
+
} catch (err) {
|
|
764
|
+
if (!isMissing(err)) {
|
|
765
|
+
this.emitRecoveryError(err);
|
|
766
|
+
skipped ??= { file, detail: `unreadable: ${sanitizeError(err)}` };
|
|
767
|
+
}
|
|
768
|
+
continue;
|
|
769
|
+
}
|
|
770
|
+
let verifyResult: VerifyOutcome;
|
|
771
|
+
try {
|
|
772
|
+
verifyResult = await this.verifyMailBody(body);
|
|
773
|
+
} catch (err) {
|
|
774
|
+
this.emitRecoveryError(err); // left in new/ for a later call
|
|
775
|
+
skipped ??= { file, detail: `verification could not run: ${sanitizeError(err)}` };
|
|
776
|
+
continue;
|
|
777
|
+
}
|
|
778
|
+
if (!verifyResult.pass) {
|
|
779
|
+
this.deadLetter(file, srcPath, verifyResult, started, roots);
|
|
780
|
+
continue;
|
|
781
|
+
}
|
|
782
|
+
let trustTier: MailMessage["trustTier"];
|
|
783
|
+
try {
|
|
784
|
+
trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
|
|
785
|
+
} catch (err) {
|
|
786
|
+
this.emitRecoveryError(err);
|
|
787
|
+
skipped ??= { file, detail: `trust tier unavailable: ${sanitizeError(err)}` };
|
|
788
|
+
continue;
|
|
789
|
+
}
|
|
790
|
+
const token = randomUUID();
|
|
791
|
+
// Live before the commit writes the claim (see presentUnderLock).
|
|
792
|
+
activePresentations.add(token);
|
|
793
|
+
let delivered = false;
|
|
794
|
+
try {
|
|
795
|
+
const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope, ownClaim(token));
|
|
796
|
+
if (committed === "already-delivered") continue;
|
|
797
|
+
if (committed === "live-placement") {
|
|
798
|
+
return deferred("new-mail-deferred", "a placement became pending before the commit; nothing committed", file);
|
|
799
|
+
}
|
|
800
|
+
if (committed) {
|
|
801
|
+
this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
|
|
802
|
+
continue;
|
|
803
|
+
}
|
|
804
|
+
const from = verifyResult.envelope.from;
|
|
805
|
+
report(() => this.events?.emit({
|
|
806
|
+
type: "mail.receive", agent: this.agentId, status: "ok", from, durationMs: Date.now() - started,
|
|
807
|
+
}));
|
|
808
|
+
delivered = true;
|
|
809
|
+
const message: MailMessage = {
|
|
810
|
+
filename: file, body, receivedAt: new Date(), headers: {}, from,
|
|
811
|
+
verifiedEnvelope: verifyResult.envelope, trustTier,
|
|
812
|
+
};
|
|
813
|
+
return { status: "delivered", delivery: this.issue(roots, token, verifyResult.envelope.messageId, file, 1, message) };
|
|
814
|
+
} catch (err) {
|
|
815
|
+
this.emitRecoveryError(err);
|
|
816
|
+
skipped ??= { file, detail: `delivery attempt failed: ${sanitizeError(err)}` };
|
|
817
|
+
} finally {
|
|
818
|
+
if (!delivered) activePresentations.delete(token);
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
return skipped ? deferred("new-mail-deferred", `new/${skipped.file} ${skipped.detail}`, skipped.file) : { status: "idle" };
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
/** The mailbox lock, or a `lock-busy` deferral (contention, or an acquisition that threw). */
|
|
825
|
+
private async lockOrDefer(roots: OperationRoots, what: string, file?: string): Promise<MailLock | DeferredResult> {
|
|
826
|
+
try {
|
|
827
|
+
return (await acquireMailLock(roots.mailbox)) ?? deferred("lock-busy", `mailbox lock busy; ${what}`, file);
|
|
828
|
+
} catch (err) {
|
|
829
|
+
return deferred("lock-busy", `mailbox lock unavailable (${sanitizeError(err)}); ${what}`, file);
|
|
830
|
+
}
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
private emitRecoveryError(err: unknown): void {
|
|
834
|
+
report(() => this.events?.emit({
|
|
835
|
+
type: "mail.receive", agent: this.agentId, status: "error", from: "unknown", durationMs: 0, error: sanitizeError(err),
|
|
836
|
+
}));
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
/** Commit under the mailbox lock; attempt placement rollback on append failure. */
|
|
840
|
+
private async commitToCur(
|
|
841
|
+
roots: OperationRoots,
|
|
842
|
+
file: string,
|
|
843
|
+
srcPath: string,
|
|
844
|
+
body: string,
|
|
845
|
+
envelope: Envelope,
|
|
846
|
+
/** cli#617 slice (b): the delivery API's presentation claim; absent for the batch checkNewMail() path. */
|
|
847
|
+
claim?: PresentationClaim,
|
|
848
|
+
): Promise<{ pass: false; class: MailboxRejectClass; reason: string } | "already-delivered" | "live-placement" | null> {
|
|
849
|
+
const lock: MailLock | null = await acquireMailLock(roots.mailbox);
|
|
850
|
+
if (!lock) throw new Error("mailbox lock busy; not promoted");
|
|
851
|
+
let relayLock: MailLock | null;
|
|
852
|
+
try { relayLock = tryAcquireRelayMoveLock(JSON.parse(body), roots.mailRoot); }
|
|
853
|
+
catch (error) { lock.release(); throw error; }
|
|
854
|
+
if (!relayLock) { lock.release(); throw new Error("relay acceptance busy; not promoted"); }
|
|
855
|
+
try {
|
|
856
|
+
if (readFileSync(srcPath, "utf-8") !== body) throw new Error("source changed during promotion; not promoted");
|
|
857
|
+
const replay = mailboxReplayStore(roots.mailbox);
|
|
858
|
+
if (replay.hasPendingFile(file)) throw new Error(`pending placement unresolved: ${file}`);
|
|
859
|
+
if (claim && pendingPlacementEntries(roots.mailbox).some((e) => e.phase === "placing" || e.phase === "in_progress")) {
|
|
860
|
+
return "live-placement";
|
|
861
|
+
}
|
|
862
|
+
const dstPath = join(roots.mailbox, "cur", file);
|
|
863
|
+
if (sameFileIdentity(srcPath, dstPath)) {
|
|
864
|
+
replay.isConsumed(envelope.messageId);
|
|
865
|
+
unlinkSync(srcPath);
|
|
866
|
+
return "already-delivered";
|
|
867
|
+
}
|
|
868
|
+
const consumed = replay.isConsumed(envelope.messageId);
|
|
869
|
+
if (consumed) {
|
|
870
|
+
return { pass: false, class: "replay", reason: `replay (envelope messageId ${envelope.messageId} already consumed)` };
|
|
871
|
+
}
|
|
872
|
+
const sourceFd = openSync(srcPath, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
873
|
+
try {
|
|
874
|
+
replay.beginPlacement(envelope.messageId, file, sourceFd);
|
|
875
|
+
const placement = placeCurRecord(srcPath, dstPath);
|
|
876
|
+
if (placement.status === "exists") {
|
|
877
|
+
replay.finishPlacement(envelope.messageId, file);
|
|
878
|
+
throw new Error(`destination already exists: ${file}`);
|
|
879
|
+
}
|
|
880
|
+
try {
|
|
881
|
+
unlinkSync(srcPath);
|
|
882
|
+
} catch (err) {
|
|
883
|
+
unlinkSync(dstPath);
|
|
884
|
+
replay.finishPlacement(envelope.messageId, file);
|
|
885
|
+
throw err;
|
|
886
|
+
}
|
|
887
|
+
try {
|
|
888
|
+
if (!replay.ownsPendingPlacement(envelope.messageId, file)) throw new Error("placement identity changed");
|
|
889
|
+
replay.recordConsumed(envelope.messageId);
|
|
890
|
+
} catch (err) {
|
|
891
|
+
try {
|
|
892
|
+
renameSync(dstPath, srcPath);
|
|
893
|
+
replay.finishPlacement(envelope.messageId, file);
|
|
894
|
+
} catch (rollbackErr) {
|
|
895
|
+
throw new AggregateError([err, rollbackErr],
|
|
896
|
+
`mail commit failed: ${sanitizeError(err)}; rollback failed: ${sanitizeError(rollbackErr)}`);
|
|
897
|
+
}
|
|
898
|
+
throw err;
|
|
899
|
+
}
|
|
900
|
+
if (claim) {
|
|
901
|
+
const advance = replay.advancePresentation(envelope.messageId, file, new Date().toISOString(), claim);
|
|
902
|
+
if (advance.status !== "presented") throw new Error(`placement not advanced after commit: ${advance.status}`);
|
|
903
|
+
} else {
|
|
904
|
+
replay.finishPlacement(envelope.messageId, file);
|
|
905
|
+
}
|
|
906
|
+
return null;
|
|
907
|
+
} finally { closeSync(sourceFd); }
|
|
908
|
+
} finally {
|
|
909
|
+
relayLock.release();
|
|
910
|
+
lock.release();
|
|
911
|
+
}
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
/**
|
|
915
|
+
* Recover verified cur copies matching the intent's recorded identity (cli#600).
|
|
916
|
+
* Verification or lock failure defers recovery. A present mismatched copy,
|
|
917
|
+
* including an older intent without identity, leaves the intent pending and
|
|
918
|
+
* withholds delivery; the new/ scan cannot replace that intent.
|
|
919
|
+
*/
|
|
920
|
+
private async recoverInterruptedPlacements(messages: MailMessage[], roots: OperationRoots): Promise<void> {
|
|
921
|
+
const root = roots.mailbox;
|
|
922
|
+
let pending: Array<{ messageId: string; file: string; phase: PlacementPhase }>;
|
|
923
|
+
let listing: MailLock | null = null;
|
|
924
|
+
try {
|
|
925
|
+
listing = await acquireMailLock(root);
|
|
926
|
+
if (!listing) return; // lock unavailable; defer recovery
|
|
927
|
+
pending = pendingPlacementEntries(root);
|
|
928
|
+
} catch (err) {
|
|
929
|
+
report(() => this.events?.emit({
|
|
930
|
+
type: "mail.receive",
|
|
931
|
+
agent: this.agentId,
|
|
932
|
+
status: "error",
|
|
933
|
+
from: "unknown",
|
|
934
|
+
durationMs: 0,
|
|
935
|
+
error: sanitizeError(err),
|
|
936
|
+
}));
|
|
937
|
+
return; // a later check retries
|
|
938
|
+
} finally {
|
|
939
|
+
listing?.release();
|
|
940
|
+
}
|
|
941
|
+
|
|
942
|
+
for (const { messageId, file, phase } of pending) {
|
|
943
|
+
if (!resumableOnRecovery(phase)) continue;
|
|
944
|
+
const curPath = join(root, "cur", file);
|
|
945
|
+
try {
|
|
946
|
+
let bytes: Buffer;
|
|
947
|
+
try {
|
|
948
|
+
bytes = readFileSync(curPath);
|
|
949
|
+
} catch (err) {
|
|
950
|
+
if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
|
|
951
|
+
// Observed absent; re-check under the lock before finishing the intent.
|
|
952
|
+
await this.finishUnlinkedPlacement(messageId, file, root);
|
|
953
|
+
continue;
|
|
954
|
+
}
|
|
955
|
+
const classified = await this.classifyPending(bytes);
|
|
956
|
+
if (classified.kind === "cli") continue;
|
|
957
|
+
if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
|
|
958
|
+
await this.quarantinePending(roots, messageId, file, bytes, classified.kind);
|
|
959
|
+
continue;
|
|
960
|
+
}
|
|
961
|
+
const outcome = classified.outcome;
|
|
962
|
+
const trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
|
|
963
|
+
const delivered = await this.completeInterruptedPlacement(messageId, file, root, bytes, outcome.envelope, trustTier);
|
|
964
|
+
if (delivered) messages.push(delivered);
|
|
965
|
+
} catch (err) {
|
|
966
|
+
report(() => this.events?.emit({
|
|
967
|
+
type: "mail.receive",
|
|
968
|
+
agent: this.agentId,
|
|
969
|
+
status: "error",
|
|
970
|
+
from: "unknown",
|
|
971
|
+
durationMs: 0,
|
|
972
|
+
error: sanitizeError(err),
|
|
973
|
+
}));
|
|
974
|
+
}
|
|
975
|
+
}
|
|
976
|
+
}
|
|
977
|
+
|
|
978
|
+
/** Finish a still-pending intent only when cur/ is absent under the lock. */
|
|
979
|
+
private async finishUnlinkedPlacement(messageId: string, file: string, root: string): Promise<void> {
|
|
980
|
+
const lock = await acquireMailLock(root);
|
|
981
|
+
if (!lock) return;
|
|
982
|
+
try {
|
|
983
|
+
const replay = mailboxReplayStore(root);
|
|
984
|
+
if (!replay.hasPendingPlacement(messageId, file)) return;
|
|
985
|
+
if (!resumableOnRecovery(replay.placementPhase(file))) return;
|
|
986
|
+
if (lstatOrAbsent(join(root, "cur", file)) !== null) return;
|
|
987
|
+
replay.finishPlacement(messageId, file);
|
|
988
|
+
} finally {
|
|
989
|
+
lock.release();
|
|
990
|
+
}
|
|
991
|
+
}
|
|
992
|
+
|
|
993
|
+
/**
|
|
994
|
+
* Re-check the intent, recorded identity and raw bytes under the lock.
|
|
995
|
+
*/
|
|
996
|
+
private async completeInterruptedPlacement(
|
|
997
|
+
messageId: string,
|
|
998
|
+
file: string,
|
|
999
|
+
root: string,
|
|
1000
|
+
bytes: Buffer,
|
|
1001
|
+
envelope: Envelope,
|
|
1002
|
+
trustTier: MailMessage["trustTier"],
|
|
1003
|
+
): Promise<MailMessage | null> {
|
|
1004
|
+
const lock = await acquireMailLock(root);
|
|
1005
|
+
if (!lock) throw new Error("mailbox lock busy; interrupted placement recovery deferred");
|
|
1006
|
+
try {
|
|
1007
|
+
const replay = mailboxReplayStore(root);
|
|
1008
|
+
// Match the intent, recorded identity and pre-verification raw bytes.
|
|
1009
|
+
if (!replay.hasPendingPlacement(messageId, file)) return null;
|
|
1010
|
+
if (!resumableOnRecovery(replay.placementPhase(file))) return null;
|
|
1011
|
+
if (envelope.messageId !== messageId) return null;
|
|
1012
|
+
if (!replay.ownsPendingPlacement(messageId, file)) return null;
|
|
1013
|
+
let current: Buffer;
|
|
1014
|
+
try {
|
|
1015
|
+
current = readFileSync(join(root, "cur", file));
|
|
1016
|
+
} catch (err) {
|
|
1017
|
+
if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
|
|
1018
|
+
throw err;
|
|
1019
|
+
}
|
|
1020
|
+
if (!current.equals(bytes)) return null;
|
|
1021
|
+
if (!replay.isConsumed(messageId, file)) replay.recordConsumed(messageId);
|
|
1022
|
+
replay.finishPlacement(messageId, file);
|
|
1023
|
+
return {
|
|
1024
|
+
filename: file,
|
|
1025
|
+
body: bytes.toString("utf8"),
|
|
1026
|
+
receivedAt: new Date(),
|
|
1027
|
+
headers: {},
|
|
1028
|
+
from: envelope.from,
|
|
1029
|
+
verifiedEnvelope: envelope,
|
|
1030
|
+
trustTier,
|
|
1031
|
+
};
|
|
1032
|
+
} finally {
|
|
1033
|
+
lock.release();
|
|
1034
|
+
}
|
|
1035
|
+
}
|
|
1036
|
+
|
|
1037
|
+
/** Attempt the dlq/ move and sidecar write, then emit the rejection. */
|
|
1038
|
+
private deadLetter(
|
|
1039
|
+
file: string,
|
|
1040
|
+
srcPath: string,
|
|
1041
|
+
rejected: { class: MailboxRejectClass; reason: string; from?: string },
|
|
1042
|
+
started: number,
|
|
1043
|
+
roots: OperationRoots,
|
|
1044
|
+
): void {
|
|
1045
|
+
const dlqDir = join(roots.mailbox, "dlq");
|
|
1046
|
+
const dlqPath = join(dlqDir, file);
|
|
1047
|
+
let relayLock: MailLock | null = null;
|
|
1048
|
+
try {
|
|
1049
|
+
let record: unknown;
|
|
1050
|
+
try { record = JSON.parse(readFileSync(srcPath, "utf-8")); } catch {}
|
|
1051
|
+
relayLock = tryAcquireRelayMoveLock(record, roots.mailRoot);
|
|
1052
|
+
if (!relayLock) return;
|
|
1053
|
+
if (srcPath !== dlqPath) renameSync(srcPath, dlqPath);
|
|
1054
|
+
writeRejectSidecar(dlqDir, file, rejected.class, rejected.reason);
|
|
1055
|
+
} catch (err) {
|
|
1056
|
+
report(() => console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`));
|
|
1057
|
+
} finally { relayLock?.release(); }
|
|
1058
|
+
report(() => this.events?.emit({
|
|
1059
|
+
type: "mail.receive",
|
|
1060
|
+
agent: this.agentId,
|
|
1061
|
+
status: "rejected",
|
|
1062
|
+
from: rejected.from ?? "unknown",
|
|
1063
|
+
durationMs: Date.now() - started,
|
|
1064
|
+
error: rejected.reason,
|
|
1065
|
+
}));
|
|
1066
|
+
}
|
|
1067
|
+
|
|
222
1068
|
/** Write a message to outbox/new for relay delivery. */
|
|
223
1069
|
async sendMail(to: string, body: string): Promise<void> {
|
|
224
1070
|
const started = Date.now();
|
|
225
1071
|
try {
|
|
1072
|
+
const { mailbox } = this.operationRoots();
|
|
226
1073
|
const { writeFileSync } = await import("node:fs");
|
|
1074
|
+
// Sign the body as this agent — the v1 envelope a promote() reader
|
|
1075
|
+
// verifies. signMailBody THROWS when no key exists, so an unsigned body
|
|
1076
|
+
// is never written.
|
|
1077
|
+
const signed = this.signMailBody(to, body);
|
|
227
1078
|
const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
|
|
228
1079
|
writeFileSync(
|
|
229
|
-
join(
|
|
230
|
-
JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2),
|
|
1080
|
+
join(mailbox, "outbox", filename),
|
|
1081
|
+
JSON.stringify({ from: this.agentId, to, body: signed, sentAt: new Date().toISOString() }, null, 2),
|
|
231
1082
|
"utf-8"
|
|
232
1083
|
);
|
|
233
|
-
this.events?.emit({
|
|
1084
|
+
report(() => this.events?.emit({
|
|
234
1085
|
type: "mail.send",
|
|
235
1086
|
agent: this.agentId,
|
|
236
1087
|
to,
|
|
237
1088
|
status: "ok",
|
|
238
1089
|
durationMs: Date.now() - started,
|
|
239
|
-
});
|
|
1090
|
+
}));
|
|
240
1091
|
} catch (err) {
|
|
241
|
-
this.events?.emit({
|
|
1092
|
+
report(() => this.events?.emit({
|
|
242
1093
|
type: "mail.send",
|
|
243
1094
|
agent: this.agentId,
|
|
244
1095
|
to,
|
|
245
1096
|
status: "error",
|
|
246
1097
|
durationMs: Date.now() - started,
|
|
247
1098
|
error: sanitizeError(err),
|
|
248
|
-
});
|
|
1099
|
+
}));
|
|
249
1100
|
throw err;
|
|
250
1101
|
}
|
|
251
1102
|
}
|
|
252
1103
|
|
|
1104
|
+
/**
|
|
1105
|
+
* Sign `body` as this agent into a v1 signed envelope. Throws a named error
|
|
1106
|
+
* when no signing key exists — the same refusal condition as the CLI path,
|
|
1107
|
+
* so an unsigned body a promote() reader would dead-letter is never written.
|
|
1108
|
+
*/
|
|
1109
|
+
private signMailBody(to: string, body: string): string {
|
|
1110
|
+
const seed = readAgentPrivateKey(this.agentId, this.signingKeyPath);
|
|
1111
|
+
if (!seed) {
|
|
1112
|
+
const paths = this.signingKeyPath ? [this.signingKeyPath] : agentKeyCandidates(this.agentId);
|
|
1113
|
+
throw new Error(`no Ed25519 private key for agent "${this.agentId}" — refusing to send unsigned mail. Looked at ${paths.join(", then ")}. Provision the agent's key.`);
|
|
1114
|
+
}
|
|
1115
|
+
const now = new Date().toISOString();
|
|
1116
|
+
const chain: ChainEntry[] = [
|
|
1117
|
+
{ agent: "system", kind: "human", timestamp: now, rationale: "agent runtime sendMail", signature: null },
|
|
1118
|
+
{ agent: this.agentId, kind: "agent", timestamp: now, rationale: `agent ${this.agentId} sendMail`, signature: null },
|
|
1119
|
+
];
|
|
1120
|
+
const envelope: Envelope = {
|
|
1121
|
+
v: 1,
|
|
1122
|
+
from: this.agentId,
|
|
1123
|
+
to,
|
|
1124
|
+
subject: `mail to ${to}`,
|
|
1125
|
+
body,
|
|
1126
|
+
messageId: randomUUID(),
|
|
1127
|
+
timestamp: now,
|
|
1128
|
+
delegationChain: chain,
|
|
1129
|
+
};
|
|
1130
|
+
return JSON.stringify(signEnvelope(envelope, { [this.agentId]: Buffer.from(seed) }));
|
|
1131
|
+
}
|
|
1132
|
+
|
|
253
1133
|
/** Deliver all messages in outbox to recipient inboxes (local relay). */
|
|
254
1134
|
deliverOutbox(): void {
|
|
255
|
-
|
|
256
|
-
const
|
|
1135
|
+
const roots = this.operationRoots();
|
|
1136
|
+
const outboxNew = join(roots.mailbox, "outbox");
|
|
1137
|
+
if (!existsSync(outboxNew)) return;
|
|
1138
|
+
const files = readdirSync(outboxNew).filter(f => !f.startsWith("."));
|
|
257
1139
|
for (const file of files) {
|
|
258
|
-
const srcPath = join(
|
|
1140
|
+
const srcPath = join(outboxNew, file);
|
|
259
1141
|
try {
|
|
260
1142
|
const raw = readFileSync(srcPath, "utf-8");
|
|
261
1143
|
const msg = JSON.parse(raw) as { to: string; body: string; sentAt: string };
|
|
262
1144
|
if (!msg.to || !/^[a-zA-Z0-9_-]{1,64}$/.test(msg.to)) {
|
|
263
1145
|
continue; // skip invalid recipients
|
|
264
1146
|
}
|
|
265
|
-
const recipientInbox = join(
|
|
1147
|
+
const recipientInbox = join(roots.mailRoot, msg.to, "new");
|
|
266
1148
|
mkdirSync(recipientInbox, { recursive: true });
|
|
267
1149
|
const destFile = `${msg.sentAt.replace(/[:.]/g, "-")}-${file}`;
|
|
268
1150
|
renameSync(srcPath, join(recipientInbox, destFile));
|
|
@@ -273,108 +1155,33 @@ export class MailClient {
|
|
|
273
1155
|
}
|
|
274
1156
|
|
|
275
1157
|
/**
|
|
276
|
-
*
|
|
277
|
-
* policy: signature, wrapper→envelope `from` binding, recipient binding
|
|
278
|
-
* (`envelope.to` must be this mailbox's agent), and `messageId`/`timestamp`
|
|
279
|
-
* shape. These are the checks the shared `promote()` applies, so this path
|
|
280
|
-
* cannot present mail the shared path would reject.
|
|
281
|
-
*
|
|
1158
|
+
* Parse a mail file and run the shared mailbox policy on its signed envelope.
|
|
282
1159
|
* Returns a terminal `{ pass: false, class, reason }` on a deterministic
|
|
283
|
-
* rejection
|
|
284
|
-
*
|
|
1160
|
+
* rejection; a THROW (Flair unreachable) is a refusal the caller acts on,
|
|
1161
|
+
* never a pass.
|
|
285
1162
|
*/
|
|
286
1163
|
private async verifyMailBody(body: string): Promise<VerifyOutcome> {
|
|
287
|
-
const client = this.flairClient!;
|
|
288
|
-
|
|
289
|
-
// 1. Parse the mail file as JSON
|
|
290
1164
|
let mailMsg: { from?: string; body: string };
|
|
291
1165
|
try {
|
|
292
1166
|
mailMsg = JSON.parse(body);
|
|
1167
|
+
if (mailMsg === null || typeof mailMsg !== "object" || Array.isArray(mailMsg) || typeof mailMsg.body !== "string") {
|
|
1168
|
+
return { pass: false, class: "invalid", reason: "invalid raw mail wrapper" };
|
|
1169
|
+
}
|
|
293
1170
|
} catch {
|
|
294
1171
|
return { pass: false, class: "invalid", reason: "json parse error: invalid JSON" };
|
|
295
1172
|
}
|
|
296
1173
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
}
|
|
300
|
-
|
|
301
|
-
// 2. Parse the body field as an envelope
|
|
302
|
-
let envelope: unknown;
|
|
303
|
-
try {
|
|
304
|
-
envelope = JSON.parse(mailMsg.body);
|
|
305
|
-
} catch {
|
|
306
|
-
return { pass: false, class: "invalid", reason: "json parse error: invalid envelope body", from: mailMsg.from };
|
|
307
|
-
}
|
|
308
|
-
|
|
309
|
-
if (envelope == null || typeof envelope !== "object" || Array.isArray(envelope)) {
|
|
310
|
-
return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
|
|
311
|
-
}
|
|
312
|
-
|
|
313
|
-
const env = envelope as Record<string, unknown>;
|
|
314
|
-
if (
|
|
315
|
-
typeof env.v !== "number" ||
|
|
316
|
-
!Array.isArray(env.delegationChain) ||
|
|
317
|
-
typeof env.signature !== "string"
|
|
318
|
-
) {
|
|
319
|
-
return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
|
|
320
|
-
}
|
|
321
|
-
|
|
322
|
-
// 3. Verify the signature. A THROW here (Flair unreachable) is NOT a pass —
|
|
323
|
-
// it propagates to checkNewMail(), which refuses to promote and leaves
|
|
324
|
-
// the record in new/ for a later check. The verifier adapter throws on an
|
|
325
|
-
// outage, so an outage is RETRYABLE rather than a terminal "not found".
|
|
326
|
-
const vr = await verifyEnvelope(env as any, client);
|
|
327
|
-
if (!vr.ok) {
|
|
328
|
-
const cls: MailboxRejectClass = UNRESOLVABLE_PRINCIPAL_REASON_RE.test(vr.reason)
|
|
329
|
-
? "unresolvable-principal"
|
|
330
|
-
: "invalid";
|
|
331
|
-
return { pass: false, class: cls, reason: vr.reason, from: mailMsg.from };
|
|
332
|
-
}
|
|
1174
|
+
const parsed = parseSignedEnvelope(mailMsg.body);
|
|
1175
|
+
if (!parsed.ok) return { pass: false, class: parsed.class, reason: parsed.reason, from: mailMsg.from };
|
|
333
1176
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
}
|
|
344
|
-
|
|
345
|
-
// 5. Recipient binding. A signature is NOT recipient-bound, so a correctly
|
|
346
|
-
// signed envelope addressed to another principal must not be presented
|
|
347
|
-
// here (deliverOutbox writes into any recipient's new/).
|
|
348
|
-
if (env.to !== this.agentId) {
|
|
349
|
-
return {
|
|
350
|
-
pass: false,
|
|
351
|
-
class: "wrong-recipient",
|
|
352
|
-
reason: `wrong-recipient (envelope.to=${String(env.to)}, mailbox=${this.agentId})`,
|
|
353
|
-
from: mailMsg.from,
|
|
354
|
-
};
|
|
355
|
-
}
|
|
356
|
-
|
|
357
|
-
// 6. `messageId` shape.
|
|
358
|
-
if (typeof env.messageId !== "string" || env.messageId.trim() === "") {
|
|
359
|
-
return {
|
|
360
|
-
pass: false,
|
|
361
|
-
class: "invalid",
|
|
362
|
-
reason: `invalid messageId (must be a non-empty string, got ${JSON.stringify(env.messageId)})`,
|
|
363
|
-
from: mailMsg.from,
|
|
364
|
-
};
|
|
365
|
-
}
|
|
366
|
-
|
|
367
|
-
// 7. `timestamp` shape — a malformed/absent timestamp must not be silently
|
|
368
|
-
// accepted (the shared path rejects it too).
|
|
369
|
-
if (typeof env.timestamp !== "string" || Number.isNaN(Date.parse(env.timestamp))) {
|
|
370
|
-
return {
|
|
371
|
-
pass: false,
|
|
372
|
-
class: "invalid",
|
|
373
|
-
reason: `invalid timestamp (must be an ISO-8601 string, got ${JSON.stringify(env.timestamp)})`,
|
|
374
|
-
from: mailMsg.from,
|
|
375
|
-
};
|
|
376
|
-
}
|
|
377
|
-
|
|
378
|
-
return { pass: true };
|
|
1177
|
+
const decision = await decideEnvelopeForMailbox(this.agentId, parsed.envelope, mailMsg.from, this.flairClient)
|
|
1178
|
+
.catch((err: unknown) => {
|
|
1179
|
+
if (err instanceof PublicKeyFormatError) {
|
|
1180
|
+
return { ok: false as const, class: "invalid" as const, reason: `signature verification failed: ${err.message}` };
|
|
1181
|
+
}
|
|
1182
|
+
throw err;
|
|
1183
|
+
});
|
|
1184
|
+
if (!decision.ok) return { pass: false, class: decision.class, reason: decision.reason, from: mailMsg.from };
|
|
1185
|
+
return { pass: true, envelope: decision.envelope };
|
|
379
1186
|
}
|
|
380
1187
|
}
|