@tpsdev-ai/agent 0.6.0 → 0.8.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/src/io/mail.ts CHANGED
@@ -14,6 +14,50 @@ export interface MailMessage {
14
14
  from: string;
15
15
  }
16
16
 
17
+ /**
18
+ * The mailbox reject classes this path can emit. It uses the SHARED class NAMES
19
+ * (`invalid`, `unresolvable-principal`, `wrong-recipient`) so a dlq sidecar it
20
+ * writes is readable by the shared tooling. It is NOT the full shared class set:
21
+ * this path emits only TERMINAL classes — an outage is refused, not
22
+ * dead-lettered (the record stays in `new/`), so no retryable class is written
23
+ * here.
24
+ */
25
+ type MailboxRejectClass = "invalid" | "unresolvable-principal" | "wrong-recipient";
26
+
27
+ type VerifyOutcome =
28
+ | { pass: true }
29
+ | { pass: false; class: MailboxRejectClass; reason: string; from?: string };
30
+
31
+ /**
32
+ * The stable reason string `verifyEnvelope` returns when an agent-kind chain
33
+ * entry or `envelope.from` cannot be resolved from the LOCAL Flair. An ABSENT
34
+ * principal is a topology condition, not a forgery verdict, so it is labelled
35
+ * `unresolvable-principal` rather than `invalid`. Duplicated from the shared
36
+ * promotion boundary because `@tpsdev-ai/agent` cannot import `packages/cli`
37
+ * (the dependency runs the other way: cli → agent).
38
+ */
39
+ const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
40
+
41
+ /**
42
+ * Write the dlq sidecar for a TERMINAL rejection.
43
+ *
44
+ * It mirrors the shared mail convention's FORMAT — file name `<record>.reason`
45
+ * and a first line `class: <class>`, the shape the shared re-drive's
46
+ * `readReasonSidecar` parses — and reuses the shared class NAMES. It does NOT
47
+ * reproduce the shared reject boundary: only the terminal classes above are
48
+ * emitted, and a retryable outcome (Flair unreachable) writes NO sidecar at all
49
+ * (the record is left in `new/`). So it is "format + the terminal class names
50
+ * this path emits", not the full boundary. (This path previously wrote
51
+ * `${file}.reject` with a bare reason, which no shared reader scans.)
52
+ */
53
+ function writeRejectSidecar(dlqDir: string, filename: string, cls: MailboxRejectClass, reason: string): void {
54
+ writeFileSync(
55
+ join(dlqDir, `${filename}.reason`),
56
+ `class: ${cls}\nPromote rejected at ${new Date().toISOString()}\nReason: ${reason}\n`,
57
+ "utf-8",
58
+ );
59
+ }
60
+
17
61
  /**
18
62
  * Maildir-compatible mail client.
19
63
  * Reads from mailDir/inbox/new and moves processed messages to mailDir/inbox/cur.
@@ -24,6 +68,8 @@ export class MailClient {
24
68
  private inboxCur: string;
25
69
  private inboxDlq: string;
26
70
  private outboxNew: string;
71
+ /** One-shot guard so a misconfigured (verifier-less) mailbox warns once, not per poll. */
72
+ private warnedNoVerifier = false;
27
73
 
28
74
  constructor(
29
75
  public readonly mailDir: string,
@@ -41,9 +87,16 @@ export class MailClient {
41
87
  }
42
88
 
43
89
  /**
44
- * Return all messages in inbox/new and move them to inbox/cur.
45
- * When a FlairClient is provided, signed envelopes are verified
46
- * before promotion; invalid/malformed messages go to dlq/.
90
+ * Return all messages in inbox/new and move them to inbox/cur/.
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.
47
100
  */
48
101
  async checkNewMail(): Promise<MailMessage[]> {
49
102
  if (!existsSync(this.inboxNew)) return [];
@@ -51,32 +104,89 @@ export class MailClient {
51
104
  const files = readdirSync(this.inboxNew).filter((f) => !f.startsWith(".") && !f.includes("/") && !f.includes("\\"));
52
105
  const messages: MailMessage[] = [];
53
106
 
107
+ // No verifier → NOTHING is promotable. Refuse (never rename into cur/) and
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
+ }
130
+
54
131
  for (const file of files) {
55
132
  const started = Date.now();
56
133
  const srcPath = join(this.inboxNew, file);
134
+
135
+ let body: string;
136
+ try {
137
+ body = readFileSync(srcPath, "utf-8");
138
+ } catch (err) {
139
+ this.events?.emit({
140
+ type: "mail.receive",
141
+ agent: this.agentId,
142
+ status: "error",
143
+ from: "unknown",
144
+ durationMs: Date.now() - started,
145
+ error: sanitizeError(err),
146
+ });
147
+ continue; // leave in new/ — a later check retries
148
+ }
149
+
150
+ // Verify. A THROW is a refusal, not a pass: leave the record in new/ for a
151
+ // later check (a Flair outage self-heals) and never promote it.
152
+ let verifyResult: VerifyOutcome;
57
153
  try {
58
- const body = readFileSync(srcPath, "utf-8");
59
-
60
- // Envelope verification (strict when FlairClient is available).
61
- if (this.flairClient) {
62
- const verifyResult = await this.verifyMailBody(body, file);
63
- if (!verifyResult.pass) {
64
- const dlqPath = join(this.inboxDlq, file);
65
- renameSync(srcPath, dlqPath);
66
- writeFileSync(join(this.inboxDlq, `${file}.reject`), verifyResult.reason, "utf-8");
67
- this.events?.emit({
68
- type: "mail.receive",
69
- agent: this.agentId,
70
- status: "rejected",
71
- from: verifyResult.from ?? "unknown",
72
- durationMs: Date.now() - started,
73
- error: verifyResult.reason,
74
- });
75
- continue;
76
- }
154
+ verifyResult = await this.verifyMailBody(body);
155
+ } catch (err) {
156
+ const detail = sanitizeError(err);
157
+ this.events?.emit({
158
+ type: "mail.receive",
159
+ agent: this.agentId,
160
+ status: "error",
161
+ from: "unknown",
162
+ durationMs: Date.now() - started,
163
+ error: detail,
164
+ });
165
+ console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`);
166
+ continue; // leave in new/
167
+ }
168
+
169
+ if (!verifyResult.pass) {
170
+ const dlqPath = join(this.inboxDlq, file);
171
+ try {
172
+ if (srcPath !== dlqPath) renameSync(srcPath, dlqPath);
173
+ writeRejectSidecar(this.inboxDlq, file, verifyResult.class, verifyResult.reason);
174
+ } catch (err) {
175
+ console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`);
77
176
  }
177
+ this.events?.emit({
178
+ type: "mail.receive",
179
+ agent: this.agentId,
180
+ status: "rejected",
181
+ from: verifyResult.from ?? "unknown",
182
+ durationMs: Date.now() - started,
183
+ error: verifyResult.reason,
184
+ });
185
+ continue;
186
+ }
78
187
 
79
- // Promote to cur/
188
+ // Promote to cur/ — verified, and addressed to this mailbox.
189
+ try {
80
190
  const dstPath = join(this.inboxCur, file);
81
191
  renameSync(srcPath, dstPath);
82
192
  let headers: Record<string, string> = {};
@@ -163,14 +273,17 @@ export class MailClient {
163
273
  }
164
274
 
165
275
  /**
166
- * Verify a mail body against the v1 signed envelope spec.
167
- * Returns { pass: true } if verified, or { pass: false, reason: "..." } on failure.
168
- * Requires flairClient to be set.
276
+ * Verify a mail body against the v1 signed envelope spec AND this mailbox's
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
+ *
282
+ * Returns a terminal `{ pass: false, class, reason }` on a deterministic
283
+ * rejection. Called ONLY when a verifier is configured; a THROW (Flair
284
+ * unreachable) is a refusal the caller acts on, never a pass.
169
285
  */
170
- private async verifyMailBody(
171
- body: string,
172
- filename: string,
173
- ): Promise<{ pass: true } | { pass: false; reason: string; from?: string }> {
286
+ private async verifyMailBody(body: string): Promise<VerifyOutcome> {
174
287
  const client = this.flairClient!;
175
288
 
176
289
  // 1. Parse the mail file as JSON
@@ -178,11 +291,11 @@ export class MailClient {
178
291
  try {
179
292
  mailMsg = JSON.parse(body);
180
293
  } catch {
181
- return { pass: false, reason: "json parse error: invalid JSON" };
294
+ return { pass: false, class: "invalid", reason: "json parse error: invalid JSON" };
182
295
  }
183
296
 
184
297
  if (!mailMsg.body || typeof mailMsg.body !== "string") {
185
- return { pass: false, reason: "json parse error: missing body field" };
298
+ return { pass: false, class: "invalid", reason: "json parse error: missing body field" };
186
299
  }
187
300
 
188
301
  // 2. Parse the body field as an envelope
@@ -190,11 +303,11 @@ export class MailClient {
190
303
  try {
191
304
  envelope = JSON.parse(mailMsg.body);
192
305
  } catch {
193
- return { pass: false, reason: "json parse error: invalid envelope body", from: mailMsg.from };
306
+ return { pass: false, class: "invalid", reason: "json parse error: invalid envelope body", from: mailMsg.from };
194
307
  }
195
308
 
196
309
  if (envelope == null || typeof envelope !== "object" || Array.isArray(envelope)) {
197
- return { pass: false, reason: "unsigned envelope (v1 required)", from: mailMsg.from };
310
+ return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
198
311
  }
199
312
 
200
313
  const env = envelope as Record<string, unknown>;
@@ -203,19 +316,63 @@ export class MailClient {
203
316
  !Array.isArray(env.delegationChain) ||
204
317
  typeof env.signature !== "string"
205
318
  ) {
206
- return { pass: false, reason: "unsigned envelope (v1 required)", from: mailMsg.from };
319
+ return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
207
320
  }
208
321
 
209
- // 3. Verify the envelope using the canonical verifyEnvelope
210
- try {
211
- const vr = await verifyEnvelope(env as any, client);
212
- if (!vr.ok) {
213
- return { pass: false, reason: vr.reason, from: mailMsg.from };
214
- }
215
- } catch (err: any) {
216
- // verifyEnvelope threw (e.g. Flair network error).
217
- // Don't drop the message — pass it through and log.
218
- console.warn(`[MailClient] verifyEnvelope error for ${filename}: ${err?.message ?? err}`);
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
+ }
333
+
334
+ // 4. The wrapper `from` is what consumers route by, and it is unverified; a
335
+ // wrapper/envelope mismatch is itself a reject.
336
+ if (mailMsg.from !== env.from) {
337
+ return {
338
+ pass: false,
339
+ class: "invalid",
340
+ reason: `wrapper/envelope from mismatch (wrapper.from=${String(mailMsg.from)}, envelope.from=${String(env.from)})`,
341
+ from: mailMsg.from,
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
+ };
219
376
  }
220
377
 
221
378
  return { pass: true };
@@ -34,6 +34,16 @@ export interface Envelope {
34
34
  body: string;
35
35
  messageId: string;
36
36
  timestamp: string;
37
+ /**
38
+ * cli#429: the signed `messageId` of the mail this one replies to (threading).
39
+ * It is a top-level envelope field, so it is covered by the envelope
40
+ * signature exactly like `body`: JCS canonicalization of the whole envelope
41
+ * includes it, and `verifyEnvelope` re-canonicalizes the received envelope
42
+ * (which carries it) — so a reply-to cannot be added, changed or stripped in
43
+ * transit without invalidating the outer signature. Optional: absent for a
44
+ * message that is not a reply.
45
+ */
46
+ replyToId?: string;
37
47
  delegationChain: ChainEntry[];
38
48
  signature?: string; // populated by signEnvelope
39
49
  }
@@ -25,7 +25,10 @@ export class AgentRuntime {
25
25
  );
26
26
  this.flair = config.flair ? new FlairContextProvider(config.agentId, config.flair) : null;
27
27
 
28
- // Build FlairClient adapter for envelope verification
28
+ // Build FlairClient adapter for envelope verification. The provider's
29
+ // getAgent() disambiguates a Flair outage (throws → retryable) from an
30
+ // absent principal (null → terminal), so a signature verifier built on it
31
+ // does not dead-letter every message while Flair is down.
29
32
  let flairClient: FlairClient | undefined;
30
33
  if (this.flair) {
31
34
  flairClient = {
package/test/io.test.ts CHANGED
@@ -31,17 +31,16 @@ describe("MailClient", () => {
31
31
  expect(msgs).toEqual([]);
32
32
  });
33
33
 
34
- test("checkNewMail returns and moves messages from new to cur", async () => {
35
- const { writeFileSync } = await import("node:fs");
34
+ test("checkNewMail refuses to promote when no verifier is configured (cli#380 F1)", async () => {
35
+ const { writeFileSync, existsSync } = await import("node:fs");
36
36
  writeFileSync(join(tmpDir, "testagent", "new", "test-1.json"), "hello world", "utf-8");
37
37
 
38
+ // No FlairClient → verification cannot run. An absent verifier must never
39
+ // mean "promote without verifying": the record is NOT moved.
38
40
  const msgs = await client.checkNewMail();
39
- expect(msgs.length).toBe(1);
40
- expect(msgs[0]!.body).toBe("hello world");
41
-
42
- const { existsSync } = await import("node:fs");
43
- expect(existsSync(join(tmpDir, "testagent", "new", "test-1.json"))).toBe(false);
44
- expect(existsSync(join(tmpDir, "testagent", "cur", "test-1.json"))).toBe(true);
41
+ expect(msgs.length).toBe(0);
42
+ expect(existsSync(join(tmpDir, "testagent", "new", "test-1.json"))).toBe(true);
43
+ expect(existsSync(join(tmpDir, "testagent", "cur", "test-1.json"))).toBe(false);
45
44
  });
46
45
 
47
46
  test("sendMail writes a file to outbox/new", async () => {