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