apple-tools-mcp 3.3.0 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -326,7 +326,11 @@ Every write tool accepts:
326
326
 
327
327
  Deletes need `confirm: true`: `mail_trash`, `calendar_remove`, `contacts_remove`, and `contacts_edit` when it clears every email or phone. These take one id per call, except `mail_trash`, which also takes a list (`message_ids`).
328
328
 
329
- `mail_send` supports a stable `idempotency_key` per intended delivery. Reuse it after a disconnect or timeout. An accepted send is replayed without sending again; changed content with the same key is refused. Without a key, identical accepted content is suppressed without expiry. Use a new key for an intentional repeat. Uncertain sends remain blocked without expiry: check Sent and Outbox before making any new delivery. A missing Sent result alone cannot prove a queued send will not complete. Claims persist across processes/restarts in the private `~/.apple-tools-mcp/mail-send-claims` directory, containing only SHA-256 hashes and outcome metadata. Dry runs create no claims. Only explicit pre-send failures allow a retry.
329
+ `mail_send` supports a stable `idempotency_key` per intended delivery. Accepted delivery is replayed without sending again; changed content with the same key is refused. Without a key, identical accepted content is suppressed without expiry. A new key can name an intentional new delivery only after accepted or proven-unstarted outcomes; changing/removing keys cannot bypass identical pending or terminal `not_sent` content. Uncertain sends never expire or automatically retry. Missing Sent rows cannot prove a queued send will not finish. Claims persist across processes/restarts in the private `~/.apple-tools-mcp/mail-send-claims` directory, containing only hashes and outcome metadata. Dry runs create no claims.
330
+
331
+ `mail_send_reconcile` is a separate **no-send** operation with exact claim/attempt/revision/content identity, protected administrator-issued authority, a persistent cross-process writer fence, and fresh complete Sent **and** Outbox evidence collected after fencing. It preserves original attempts and appends authoritative audit/state records. `not_sent` is terminal, not retryable: any later retry requires a separate single-use authorization consumed durably before the existing transport handler. Legacy claims are always ineligible. Installation does not create authority, resolve any historical claim, retry mail, or alter a page ledger. By default, reconciliation refuses without the independently established administrative exclusion/evidence boundary. See the [full protocol and transition table](docs/mail-send-reconciliation.md).
332
+
333
+ Send and reconciliation results expose `structuredContent.mail_send` (schema version 1), separating suppression without current handler entry, attempted-but-unresolved transport, accepted historical replay, terminal suppression, identity/writer/evidence refusal and uncertain bridge handoff. Suppression and uncertainty authorize no retry or page-ledger update. Historical send replay also sets MCP `isError` so text-only clients cannot mistake it for a newly sent message. Global writer locks/fences do not expire or auto-recover after a crash; availability recovery requires a separate explicit maintenance decision.
330
334
 
331
335
  A bridge request that expires before execution is rejected. After a handoff with an unknown outcome, local fallback is suppressed. The System Events preflight allows 10 seconds (12-second process cap); timeout reports `probe_timeout` and unknown permission status, separately from an explicit permission denial.
332
336
 
@@ -343,6 +347,7 @@ A missing or malformed id or recipient is refused. Calendar times are local date
343
347
  | Tool | Arguments | Confirm |
344
348
  |------|-----------|---------|
345
349
  | `mail_send` | `to[]` (required), `cc[]`, `bcc[]`, `subject` (required), `body` (required), `body_format` (`plain` or `html`), `idempotency_key` | when recipients > 1 |
350
+ | `mail_send_reconcile` | `action` (`begin`/`commit`), exact claim binding, `deployment_ref`, `approval_ref`; commit also needs `fence_id`, `evidence_ref`, outcome and reason code | protected authority, not `confirm` |
346
351
  | `mail_draft` | `to[]` (required), `cc[]`, `bcc[]`, `subject`, `body`, `body_format` | no (saved to Drafts) |
347
352
  | `mail_reply` | `message_id` or `file_path`, `body` (required), `reply_all`, `save_as_draft` | when `reply_all` is true |
348
353
  | `mail_forward` | `message_id` or `file_path`, `to[]` (required), `body`, `save_as_draft` | when recipients > 1 |
@@ -0,0 +1,264 @@
1
+ # Mail send reconciliation protocol v1
2
+
3
+ ## Boundary and deployment
4
+
5
+ This is a **no-send** operation, not a Mail transport or a locked-screen
6
+ workaround. It imports no Mail, shell, UI, wake, clipboard or page-ledger code.
7
+ Installation does not adjudicate claims, create authority, authorize a retry,
8
+ change a page ledger or deliver historical mail. All legacy records are
9
+ ineligible, regardless of age, mailbox observations or missing metadata. No
10
+ legacy migration or adjudication is implemented.
11
+
12
+ The default deployment is closed. Positive reconciliation needs an external
13
+ administrator-controlled authority described below. This package does **not**
14
+ create that authority, manufacture verification evidence, stop old writers or
15
+ disable their launch sources. Without proven exclusion of nonparticipating
16
+ writers, it refuses. Do not create an authority manifest simply to bypass this
17
+ refusal. Establishing the privileged operational boundary and collecting real
18
+ evidence require their own approved operational work; offline fixtures are not
19
+ live evidence. No live claim or Mail operation is needed to install or smoke-test
20
+ the package.
21
+
22
+ ## Identity and delivery lineage
23
+
24
+ `claim_id` is the existing claim-directory digest. The request binds the exact
25
+ `attempt`, `revision`, `fingerprint_algorithm: sha256-mail-content-v1` and
26
+ `fingerprint`. The fingerprint preserves the existing algorithm: SHA-256 of
27
+ the JSON array containing sorted/lowercased/trimmed To, Cc, Bcc, exact subject,
28
+ exact body and body format (default plain). It does not equate different HTML
29
+ or body strings. A supplied idempotency key must hash to that same directory;
30
+ it is never stored. Missing or conflicting identities do not create a claim.
31
+ The public `mail_send` structured result supplies modern claim bindings.
32
+
33
+ The latest attempt is authoritative. Changing or removing a key cannot escape
34
+ an unresolved or terminal not_sent claim with identical content, including a
35
+ legacy pending claim. A new key can name a genuinely new intended delivery
36
+ only after all identical-content lineages are accepted or proven not_started.
37
+ This retains the existing intentional-new-delivery convention for successful
38
+ sends, not for uncertain ones. Changing actual content defines another
39
+ fingerprint; callers must not disguise a retry by modifying a payload.
40
+
41
+ ## Trusted references and authority
42
+
43
+ Tool arguments accept **references**, not caller-authored checked strings,
44
+ scripts, raw evidence or authority objects. A reference is the SHA-256 of the
45
+ exact UTF-8 bytes of an administrator-provisioned JSON file:
46
+
47
+ `/Library/Application Support/AppleTools/Reconciliation/<kind>/<ref>.json`
48
+
49
+ Kinds are `deployment`, `approval`, `evidence`, `authorization`. The root,
50
+ every ancestor, every file and `revocations.json` must be root-owned, not
51
+ group/world-writable and not a symlink. Files must be regular and bounded to
52
+ 64 KiB. Content hashes must match. Missing, corrupt, unprotected or revoked
53
+ references refuse. These checks establish administrative provenance; a tool
54
+ caller with the ordinary user identity cannot issue proofs. Root is the
55
+ authorized issuer. The protocol does not claim protection against a malicious
56
+ administrator, kernel, or a Mail user independently sending messages.
57
+
58
+ `revocations.json` has `schema_version: 1`, `references: [<hash>...]` and
59
+ `ids: [<hash>...]`. It is reread on every authority lookup; a missing list is
60
+ not an empty list. References or authority IDs can be revoked. Revocation
61
+ before durable consumption prevents a retry; revocation cannot undo a consumed
62
+ permission or an already invoked transport. Expiration is checked again before
63
+ transport entry. Neither age nor revoked permission restores permission.
64
+
65
+ All authority records have `schema_version: 1`, integer epoch-millisecond
66
+ `issued_at`, `expires_at`, and `revoked: false`. The entire validity interval
67
+ is at most 60 seconds, with no future issue time and no clock uncertainty.
68
+ Authority records are immutable-by-reference. Replacing a record needs a new
69
+ reference. Operation IDs, fingerprints and protected references are bounded
70
+ hashes; operator/epoch IDs are bounded lowercase codes, not names or free text.
71
+
72
+ A deployment proof has `kind: deployment`, an epoch code, the complete list
73
+ of account hashes, authorized operator codes, `clock_uncertainty_ms: 0`,
74
+ `nonparticipating_launch_disabled: true`, and true exclusion assertions for
75
+ **all** of `daemon`, `local_fallback`, `accepted_bridge`, `scripts_appleevents`,
76
+ `old_processes`, `outstanding_effects`. The administrative issuer must actually
77
+ disable nonparticipating launch sources for the validity window and drain
78
+ already accepted requests/scripts/AppleEvents, not infer exclusion from a PID,
79
+ reused PID, heartbeat, lease, socket closure or timeout. The deployment proof
80
+ is the trusted administrative attestation of that operational enforcement,
81
+ not an automatic discovery mechanism. If it cannot be established, refuse.
82
+
83
+ Reconciliation approval has `kind: reconcile`, a unique hash ID, the full
84
+ claim binding, epoch and an operator code from that deployment proof. Retry
85
+ authorization is a separate record with `kind: retry`, a separate unique ID,
86
+ the **terminal** binding, operator, epoch and `single_use: true`. Reconciliation
87
+ neither issues nor consumes retry authorization. `confirm: true` is not
88
+ authority. There is no automatic approval, retry, requeue or ledger reset.
89
+
90
+ ## Writer fence and fresh evidence
91
+
92
+ 1. `mail_send_reconcile(action: begin, <binding>, deployment_ref, approval_ref)`
93
+ validates an existing modern pending claim and protected authority under
94
+ the global `.writer-lock`. It exclusively creates and synchronizes a
95
+ persistent `.reconciliation-fence.json`, then returns a random hash
96
+ `fence_id`. Repeating begin with the same identity and references returns
97
+ that fence. No transport is invoked.
98
+ 2. Every participating `mail_send` and other Mail write (reply, forward,
99
+ draft, mark, archive, trash) takes the same cross-process lock and refuses
100
+ while the fence exists. A bridge request accepted before begin still
101
+ checks it when its handler executes. Nonparticipating versions/scripts
102
+ are excluded only by the administrative boundary, never by pretending
103
+ they honor this lock. The deployment epoch cannot change mid-operation.
104
+ 3. Only **after** the fence exists, the authorized operator obtains complete
105
+ exact-content Sent **and** Outbox observations from the accepted source,
106
+ `complete_exact_mail_snapshot_v1`. This name denotes a privileged,
107
+ administrator-validated complete snapshot; it does not bless an arbitrary
108
+ client claiming that source. This build ships no snapshot collector.
109
+ The administrator provisions the protected evidence record with its
110
+ provenance and explicit adjudication. Caller-created artifacts are not
111
+ accepted. Negative observations alone do not decide an outcome.
112
+ 4. Commit rechecks authority, exclusion, binding, freshness and both mailbox
113
+ observations under the lock. It appends one authoritative terminal
114
+ state/audit record, synchronizes it, then removes/synchronizes the fence.
115
+ It never enters Mail. Refusals retain an existing fence; they never make
116
+ a claim retryable. An expired fence has **no automatic release**.
117
+
118
+ Evidence has `kind: mail_verification`, a unique hash ID, exact binding,
119
+ fence ID, epoch, authorized operator, source, zero clock uncertainty,
120
+ `effects_drained: true`, explicit `outcome: sent | not_sent`, and the matching
121
+ reason code `operator_verified_sent | operator_verified_not_sent`.
122
+
123
+ Separate `sent` and `outbox` observations each require `completed: true`,
124
+ `error: null`, `index_used: false`, the complete deployment `accounts` list,
125
+ `exact_fingerprint`, integer `observed_at` **after** fence creation, integer
126
+ `search_from` no later than attempt creation, `search_to` equal to the
127
+ observation time, and `matches: []`. Both observations must be at most 60
128
+ seconds old, not in the future, and no later than the evidence issue time.
129
+ Partial scans, unavailable accounts, stale indexes, errors, incomplete history,
130
+ unknown clocks, ambiguity or any queued Outbox match refuse. A sent decision
131
+ requires exactly one Sent match with an account from the covered set, exact
132
+ fingerprint, protected `message_ref`, and `message_id_hash` matching the
133
+ evidence-level exact Message-ID hash. Not_sent requires zero matches in both
134
+ mailboxes **plus** the explicit protected operator decision.
135
+
136
+ ## Authoritative audit/state transaction and failure recovery
137
+
138
+ New attempts keep their original `<attempt>.json` pending record forever.
139
+ Immutable, exclusively created `<attempt>.events/<revision>.json` records
140
+ are the **only** outcome state; there is no separate mutable state file to
141
+ update ahead of the audit. Records include schema version, binding, revision,
142
+ previous hash, integrity hash and bounded metadata. Initial attempts also
143
+ have an integrity hash. Hashes detect accidental corruption, not same-user
144
+ forgery: the user's claim storage is not immutable against that user.
145
+
146
+ Ordering: create initial attempt exclusively, write, file fsync, parent
147
+ directory fsync, claim-root fsync, then handler entry. For outcomes, create
148
+ the journal directory, synchronize its parent, exclusively create the next
149
+ event, write, file fsync and journal-directory fsync before returning a
150
+ committed receipt. The appended record is simultaneously audit and state.
151
+ No terminal or retryable state is published by a separate write.
152
+
153
+ Torn, missing-sequence, divergent, corrupt or unsynchronized writes fail
154
+ closed. Disk-full and failed fsync never permit transport or a second
155
+ transport invocation. A crash or unknown durability failure retains the
156
+ global lock, without expiry, PID-based takeover or automatic repair. Recovery
157
+ of that availability requires a separate explicit maintenance decision;
158
+ this API does not remove an orphan lock. An already committed identical
159
+ reconciliation can return its immutable receipt read-only even with an orphan
160
+ lock or lost reply. A complete record surviving an interrupted synchronization
161
+ is revalidated and synchronized (file and parent directories) before replay;
162
+ an unavailable disk cannot produce a successful receipt. No missing or torn
163
+ record is synthesized. A leftover fence after a commit is not automatically
164
+ cleared by replay. It cannot unlock mail. Original attempts are never deleted,
165
+ rewritten or retroactively annotated.
166
+
167
+ Allowlisted reconciliation audit fields are request hash, receipt hash,
168
+ evidence/approval references, reason code, operator code, optional protected
169
+ message reference and commit time, plus structural binding/hash fields.
170
+ No raw key, addresses, subject, body, clipboard, scripts, free-text reason,
171
+ raw error or tool-result text is persisted.
172
+
173
+ ## Transition table
174
+
175
+ | Current state | Operation | Result |
176
+ |---|---|---|
177
+ | Absent | ordinary send | Durable new pending attempt, then one handler invocation |
178
+ | Modern pending | another ordinary send, any key | Suppressed; no new attempt or handler |
179
+ | Modern pending | valid reconciliation | Append done or terminal not_sent; no handler |
180
+ | Legacy pending | reconciliation | Always ineligible; no migration or new metadata |
181
+ | Legacy pending | ordinary send, any key | Suppressed |
182
+ | Done | same delivery send | Accepted historical replay, not a new delivery |
183
+ | Done | genuinely new intentional key | New delivery, unless another identical-content lineage blocks it |
184
+ | Not_started | ordinary send | Existing proven-unstarted behavior; new pending attempt |
185
+ | Not_sent | ordinary send, changed/removed key, confirm | Terminal suppression; no attempt allocation |
186
+ | Not_sent | separate valid single-use retry approval | Durable consumption, then one new pending attempt |
187
+ | Terminal | identical reconciliation | Return the committed receipt |
188
+ | Terminal | conflicting outcome, stale binding or revision | Refuse |
189
+ | Consumed retry | timeout, crash, lost reply, proven-unstarted | Permission remains spent; no automatic recovery |
190
+
191
+ Retry consumption exclusively creates and synchronizes a global
192
+ `.authorizations/<authorization-id>.json` audit binding the grant to one
193
+ claim/fingerprint and one new retry attempt **before** that attempt enters
194
+ the existing transport handler. The new attempt also stores the authorization
195
+ ID. Concurrent/replayed consumers cannot invoke another handler. A crash
196
+ after consumption but before transport sacrifices permission and may sacrifice
197
+ delivery. V1 does **not** allow another authorization after a consumed,
198
+ proven-unstarted retry; a separately reviewed future protocol would be needed.
199
+ Admission checks both the attempt's authorization provenance and all durable
200
+ consumption records for its claim lineage, including a consumption whose crash
201
+ prevented creation of the retry attempt. A different grant cannot restore it.
202
+ The complete consumption record has a verified integrity hash before any lineage
203
+ field is trusted. Missing hashes and valid-shape corruption refuse closed. As
204
+ with claim/event hashes, this detects corruption, not malicious same-user edits.
205
+ This promises at-most-once authorized handler invocation, not exactly-once
206
+ delivery by Mail or a remote mail server.
207
+
208
+ Page-ledger reconciliation is a separate workflow. Every machine result says
209
+ `ledger_action: none` and `retry_authorized: false` (no permission for a future
210
+ invocation). A claim receipt cannot reset or advance the page ledger. A caller
211
+ observing disagreement must report that mismatch; it cannot partially reset
212
+ two systems. This operation never imports or touches a ledger.
213
+
214
+ ## External results and safe logs
215
+
216
+ MCP exposes `structuredContent.mail_send` with `schema_version: 1`, `code`,
217
+ `current_invocation_transport: none | entered | unknown`,
218
+ `historical_effects`, `ledger_action`, `retry_authorized`, and applicable
219
+ binding/fence/receipt fields. `entered` means this invocation entered the
220
+ existing synchronous transport **handler**, not proof that Mail acknowledged
221
+ a send. Lower-level dispatch remains unknown unless independently observed.
222
+
223
+ Important codes: `pending_suppressed`, `transport_unresolved`,
224
+ `transport_accepted`, `accepted_replay`, `not_sent_suppressed`,
225
+ `identity_refused`, `legacy_ineligible`, `active_writer_refused`,
226
+ `evidence_refused`, `authorization_refused`, `durability_refused`,
227
+ `revision_refused`, `outcome_conflict`, `bridge_uncertain`,
228
+ `evidence_required`, `reconciled`, `reconciliation_replayed`.
229
+ `authorization_spent` distinguishes a consumed approval whose handler proved
230
+ it never started sending; that result still grants no future attempt.
231
+ Suppression has no handler entry this invocation, but earlier effects may
232
+ still finish. An uncertain bridge handoff reports unknown entry for send;
233
+ reconciliation always reports none. It never locally replays a possibly
234
+ accepted bridge operation. Text-only clients also get `isError: true` for
235
+ historical send replay, preventing them mistaking suppression for a newly sent
236
+ message. All callers must honor `ledger_action: none` on suppression and
237
+ uncertainty, not scrape text or treat `ok` as a new delivery.
238
+
239
+ Allowlisted stage records are `handler_entered`, `handler_completed` and
240
+ `verification_completed`, with
241
+ entered/completed semantics, bounded hash operation ID, numeric attempt,
242
+ local-handler route, protocol version, monotonic elapsed milliseconds, and
243
+ explicit unknown dispatch-attempted/acknowledged fields. A completion marker
244
+ for the handler means only it returned. Verification outcomes are allowlisted
245
+ as sent, outbox, accepted, not_started, unresolved or unknown, never raw tool
246
+ text. Bridge outcome codes also record verification
247
+ results without claiming that suppressed mail was sent. Logging failure
248
+ does not change state or grant permission. No sender changes or timeout
249
+ increases are part of this contract.
250
+
251
+ ## Offline verification and smoke
252
+
253
+ `tests/unit/mail-reconciliation.test.js` uses fresh temporary directories,
254
+ synthetic manifests, injected authority/IO and independent processes with
255
+ controlled start barriers. It never calls Mail, a page ledger, an existing
256
+ claim or a real verification collector. It covers identity, evidence,
257
+ mailbox/account ambiguity, exclusion, persistence/fault boundaries, immutable
258
+ replay, terminal suppression, authorization and structured external results.
259
+ Existing mail-send and bridge tests cover late completion and fallback rules.
260
+
261
+ Installation smoke can list the tool schema and call a synthetic
262
+ `dry_run: true` reconciliation with an isolated home. Preview creates no
263
+ claim, fence, audit or authority. It is not an adjudication or a delivery
264
+ verification. Never use a historical claim for smoke testing.
@@ -1,13 +1,7 @@
1
1
  import fs from "fs";
2
2
  import path from "path";
3
- import { createHash } from "crypto";
4
3
  import { getAppleToolsDir } from "./config.js";
5
-
6
- const digest = (value) => createHash("sha256").update(value).digest("hex");
7
- const uncertain = () => ({
8
- ok: false, unconfirmed: true, sendStarted: true,
9
- message: "mail_send: unconfirmed. An earlier identical send may still complete. Check Sent and Outbox; do not resend."
10
- });
4
+ import { FINGERPRINT_ALGORITHM, mailFingerprint, mailClaimId, mailOutcome, readMailClaim, appendMailOutcome, durableCreate, syncDirectory, withMailWriterLock, reconciliationFencePath, protectedMailAuthority, validateRetryAuthorization, assertUnspentRetryLineage, refuse, claimBinding, mailRecordHash, mailAttempts } from "./mailReconciliation.js";
11
5
 
12
6
  /** Cross-process, restart-safe send claims. Only hashes and outcome metadata
13
7
  * are stored. A crash or corrupt record fails closed, including an empty file
@@ -15,56 +9,91 @@ const uncertain = () => ({
15
9
  * expires: a missing Sent row cannot prove a queued send will not run later.
16
10
  */
17
11
  export function idempotentMailSend(args, run, {
18
- directory = path.join(getAppleToolsDir(), "mail-send-claims"), now = Date.now
12
+ directory = path.join(getAppleToolsDir(), "mail-send-claims"), now = Date.now,
13
+ authority = protectedMailAuthority(), io = fs, log = record => console.error(JSON.stringify(record)), monotonic = () => process.hrtime.bigint()
19
14
  } = {}) {
20
15
  if (args.dry_run === true) return run();
21
16
  const key = args.idempotency_key;
22
17
  if (key !== undefined && (typeof key !== "string" || !key.trim() || key.length > 256)) {
23
- return { ok: false, sendStarted: false, message: "mail_send refused: idempotency_key must be a nonempty string of at most 256 characters." };
18
+ return mailOutcome("identity_refused");
24
19
  }
25
- const addresses = (values) => (Array.isArray(values) ? values.map(v => String(v).trim().toLowerCase()).sort() : values);
26
- const fingerprint = digest(JSON.stringify([
27
- addresses(args.to), addresses(args.cc || []), addresses(args.bcc || []),
28
- args.subject, args.body, args.body_format || "plain"
29
- ]));
30
- const dir = path.join(directory, digest(key === undefined ? fingerprint : `key:${key}`));
20
+ const fingerprint = mailFingerprint(args);
21
+ const id = mailClaimId(fingerprint, key);
22
+ const dir = path.join(directory, id);
23
+ let entered = false;
31
24
  try {
32
- fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
33
- fs.chmodSync(directory, 0o700);
34
- fs.chmodSync(dir, 0o700);
35
- const attempts = fs.readdirSync(dir).filter(n => /^\d+\.json$/.test(n)).map(n => Number(n.slice(0, -5)));
36
- const last = attempts.length ? Math.max(...attempts) : 0;
37
- if (last) {
38
- const previous = JSON.parse(fs.readFileSync(path.join(dir, `${last}.json`), "utf8"));
39
- if (previous.fingerprint !== fingerprint) {
40
- return { ok: false, sendStarted: false, message: "mail_send refused: idempotency_key was already used with different message content." };
25
+ return withMailWriterLock(directory, () => {
26
+ if (fs.existsSync(reconciliationFencePath(directory))) return mailOutcome("active_writer_refused");
27
+ for (const candidate of fs.readdirSync(directory).filter(name => /^[a-f0-9]{64}$/.test(name) && name !== id)) {
28
+ const attempts = mailAttempts(directory, candidate);
29
+ if (!attempts.length) continue;
30
+ const previous = readMailClaim(directory, candidate, Math.max(...attempts));
31
+ if (previous.fingerprint === fingerprint && !["done", "not_started"].includes(previous.state)) {
32
+ return mailOutcome(previous.state === "not_sent" ? "not_sent_suppressed" : "pending_suppressed", { historical: previous.state, ...(previous.legacy ? { legacy: true } : claimBinding(previous)) });
33
+ }
34
+ }
35
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
36
+ fs.chmodSync(directory, 0o700);
37
+ fs.chmodSync(dir, 0o700);
38
+ const attempts = mailAttempts(directory, id);
39
+ const last = attempts.length ? Math.max(...attempts) : 0;
40
+ let authorizationId;
41
+ let authorizationBinding;
42
+ if (last) {
43
+ const previous = readMailClaim(directory, id, last);
44
+ if (previous.fingerprint !== fingerprint) {
45
+ return mailOutcome("identity_refused");
46
+ }
47
+ if (previous.state === "done") {
48
+ if (previous.legacy && previous.result?.ok !== true) return mailOutcome("pending_suppressed");
49
+ return { ...mailOutcome("accepted_replay", { ok: true, historical: "accepted", ...(previous.legacy ? { legacy: true } : claimBinding(previous)) }), deduplicated: true };
50
+ }
51
+ if (previous.state === "not_sent" && args.retry_authorization_ref !== undefined && !previous.legacy) {
52
+ assertUnspentRetryLineage(directory, previous);
53
+ authorizationId = validateRetryAuthorization(authority, args.retry_authorization_ref, args.deployment_ref, previous, now());
54
+ authorizationBinding = claimBinding(previous);
55
+ for (const attempt of attempts) {
56
+ const original = JSON.parse(fs.readFileSync(path.join(dir, `${attempt}.json`), "utf8"));
57
+ if (original.authorization_id === authorizationId) refuse("authorization_refused");
58
+ }
59
+ } else if (previous.state !== "not_started") {
60
+ return mailOutcome(previous.state === "not_sent" ? "not_sent_suppressed" : "pending_suppressed", { historical: previous.state, ...(previous.legacy ? { legacy: true } : claimBinding(previous)) });
61
+ }
41
62
  }
42
- if (previous.state === "done") {
43
- if (previous.result?.ok !== true) return uncertain();
44
- return { ...previous.result, deduplicated: true };
63
+ const file = path.join(dir, `${last + 1}.json`);
64
+ if (args.retry_authorization_ref !== undefined && !authorizationId) refuse("authorization_refused");
65
+ if (authorizationId) {
66
+ const consumed = path.join(directory, ".authorizations");
67
+ io.mkdirSync(consumed, { recursive: true, mode: 0o700 });
68
+ syncDirectory(directory, io);
69
+ if (fs.existsSync(path.join(consumed, `${authorizationId}.json`))) refuse("authorization_refused");
70
+ const consumption = { schema_version: 1, authorization_id: authorizationId, authorization_ref: args.retry_authorization_ref, ...authorizationBinding, retry_attempt: last + 1, consumed_at: now() };
71
+ consumption.integrity_hash = mailRecordHash(consumption);
72
+ durableCreate(path.join(consumed, `${authorizationId}.json`), consumption, io);
45
73
  }
46
- if (previous.state !== "not_started") return uncertain();
47
- }
48
- // Atomic exclusive create arbitrates concurrent retries, even in different processes.
49
- const file = path.join(dir, `${last + 1}.json`);
50
- const fd = fs.openSync(file, "wx", 0o600);
51
- const claim = { fingerprint, createdAt: now(), state: "pending" };
52
- try {
53
- fs.writeFileSync(fd, JSON.stringify(claim));
54
- fs.fsyncSync(fd);
55
- } finally { fs.closeSync(fd); }
56
- let result;
57
- try { result = run(); } catch { return uncertain(); }
58
- const safe = result?.sendStarted === false || result?.planned === true || /^mail_send refused:/.test(result?.message || "");
59
- const state = result?.ok === true ? "done" : safe ? "not_started" : "pending";
60
- const cached = result?.ok === true ? {
61
- ok: true, delivered: result.delivered === true, mailbox: result.mailbox,
62
- message: "mail_send: previous send already accepted; duplicate suppressed."
63
- } : undefined;
64
- // Torn writes remain blocked on the next call. Never persist message content.
65
- fs.writeFileSync(file, JSON.stringify({ ...claim, state, result: cached }), { mode: 0o600 });
66
- return result;
67
- } catch {
68
- return uncertain();
74
+ const claim = { protocol_version: 1, claim_id: id, attempt: last + 1, revision: 1, fingerprint_algorithm: FINGERPRINT_ALGORITHM, fingerprint, createdAt: now(), state: "pending", ...(authorizationId ? { authorization_id: authorizationId } : {}) };
75
+ claim.integrity_hash = mailRecordHash(claim);
76
+ durableCreate(file, claim, io);
77
+ syncDirectory(directory, io);
78
+ if (authorizationId) validateRetryAuthorization(authority, args.retry_authorization_ref, args.deployment_ref, readMailClaim(directory, id, last), now());
79
+ const started = monotonic();
80
+ const stage = (code, verification = "unknown") => {
81
+ try { log({ schema_version: 1, stage: code, semantics: code.endsWith("completed") ? "completed" : "entered", attempt: claim.attempt, operation_id: id, route: "local_handler", protocol_version: 1, elapsed_ms: Math.max(0, Number(monotonic() - started) / 1e6), dispatch_attempted: "unknown", dispatch_acknowledged: "unknown", verification }); } catch {}
82
+ };
83
+ stage("handler_entered");
84
+ entered = true;
85
+ let result;
86
+ try { result = run(); } catch { return mailOutcome("transport_unresolved", { entry: "entered", ...claimBinding(claim) }); }
87
+ stage("handler_completed");
88
+ const safe = result?.sendStarted === false || result?.planned === true || /^mail_send refused:/.test(result?.message || "");
89
+ stage("verification_completed", result?.ok === true ? ["sent", "outbox"].includes(result.mailbox) ? result.mailbox : "accepted" : safe ? "not_started" : "unresolved");
90
+ const state = result?.ok === true ? "done" : safe && !authorizationId ? "not_started" : "pending";
91
+ let finalClaim = readMailClaim(directory, id, last + 1);
92
+ if (state !== "pending") finalClaim = appendMailOutcome(directory, finalClaim, { state, committed_at: now() }, io);
93
+ const code = result?.ok === true ? "transport_accepted" : safe ? authorizationId ? "authorization_spent" : "not_started" : "transport_unresolved";
94
+ return { ...result, ...mailOutcome(code, { ok: result?.ok === true, entry: "entered", historical: state, ...claimBinding(finalClaim) }), ...(safe ? { sendStarted: false } : {}), message: result?.message || mailOutcome(code).message };
95
+ });
96
+ } catch (error) {
97
+ return mailOutcome(error.mailCode || "durability_refused", { entry: entered ? "entered" : "none" });
69
98
  }
70
99
  }
@@ -0,0 +1,341 @@
1
+ import fs from "fs";
2
+ import path from "path";
3
+ import { createHash, randomUUID } from "crypto";
4
+ import { getAppleToolsDir } from "./config.js";
5
+
6
+ export const FINGERPRINT_ALGORITHM = "sha256-mail-content-v1";
7
+ export const RECONCILIATION_VERSION = 1;
8
+ const digest = value => createHash("sha256").update(value).digest("hex");
9
+ const hashPattern = /^[a-f0-9]{64}$/;
10
+ const codePattern = /^[a-z][a-z0-9_-]{0,63}$/;
11
+ const bindingFields = ["claim_id", "attempt", "revision", "fingerprint_algorithm", "fingerprint"];
12
+ const refusals = new Set(["identity_refused", "legacy_ineligible", "active_writer_refused", "evidence_refused", "authorization_refused", "durability_refused", "revision_refused", "outcome_conflict"]);
13
+ const reasonCodes = new Set(["operator_verified_sent", "operator_verified_not_sent"]);
14
+
15
+ export const mailRecordHash = value => digest(JSON.stringify(value));
16
+
17
+ export function mailFingerprint(args) {
18
+ const addresses = values => Array.isArray(values) ? values.map(value => String(value).trim().toLowerCase()).sort() : values;
19
+ return digest(JSON.stringify([addresses(args.to), addresses(args.cc || []), addresses(args.bcc || []), args.subject, args.body, args.body_format || "plain"]));
20
+ }
21
+
22
+ export function mailClaimId(fingerprint, key) {
23
+ return digest(key === undefined ? fingerprint : `key:${key}`);
24
+ }
25
+
26
+ export function mailOutcome(code, { ok = false, entry = "none", historical = "unknown", ...fields } = {}) {
27
+ return {
28
+ ok,
29
+ sendStarted: entry === "entered" ? true : entry === "unknown" ? undefined : false,
30
+ unconfirmed: ["pending_suppressed", "transport_unresolved", "bridge_uncertain", "active_writer_refused", "durability_refused"].includes(code),
31
+ message: `mail_send: ${code}. No automatic retry or ledger update is authorized.`,
32
+ mail_send: { schema_version: 1, code, current_invocation_transport: entry, historical_effects: historical, ledger_action: "none", retry_authorized: false, ...fields }
33
+ };
34
+ }
35
+
36
+ export function refuse(code) {
37
+ const error = new Error(refusals.has(code) ? code : "durability_refused");
38
+ error.mailCode = error.message;
39
+ throw error;
40
+ }
41
+
42
+ function regularFile(file) {
43
+ const stat = fs.lstatSync(file);
44
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536) refuse("durability_refused");
45
+ }
46
+
47
+ function readJson(file) {
48
+ regularFile(file);
49
+ return JSON.parse(fs.readFileSync(file, "utf8"));
50
+ }
51
+
52
+ export function syncDirectory(directory, io = fs) {
53
+ const descriptor = io.openSync(directory, "r");
54
+ try { io.fsyncSync(descriptor); } finally { io.closeSync(descriptor); }
55
+ }
56
+
57
+ export function durableCreate(file, value, io = fs) {
58
+ const descriptor = io.openSync(file, "wx", 0o600);
59
+ try {
60
+ io.writeFileSync(descriptor, JSON.stringify(value));
61
+ io.fsyncSync(descriptor);
62
+ } finally { io.closeSync(descriptor); }
63
+ syncDirectory(path.dirname(file), io);
64
+ }
65
+
66
+ export function withMailWriterLock(directory, work) {
67
+ const missing = [];
68
+ for (let current = directory; !fs.existsSync(current); current = path.dirname(current)) missing.push(current);
69
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
70
+ for (const created of missing) syncDirectory(path.dirname(created));
71
+ const lock = path.join(directory, ".writer-lock");
72
+ try { fs.mkdirSync(lock, { mode: 0o700 }); } catch { refuse("active_writer_refused"); }
73
+ try {
74
+ const result = work();
75
+ fs.rmdirSync(lock);
76
+ return result;
77
+ } catch (error) {
78
+ if (error.mailCode && error.mailCode !== "durability_refused") fs.rmdirSync(lock);
79
+ throw error;
80
+ }
81
+ }
82
+
83
+ export function claimBinding(claim) {
84
+ return Object.fromEntries(bindingFields.map(field => [field, claim[field]]));
85
+ }
86
+
87
+ function sameBinding(left, right) {
88
+ return bindingFields.every(field => left[field] === right[field]);
89
+ }
90
+
91
+ function validateBinding(value) {
92
+ if (!value || !hashPattern.test(value.claim_id) || !hashPattern.test(value.fingerprint) || value.fingerprint_algorithm !== FINGERPRINT_ALGORITHM ||
93
+ !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !Number.isSafeInteger(value.revision) || value.revision < 1) refuse("identity_refused");
94
+ }
95
+
96
+ export function readMailClaim(directory, id, attempt) {
97
+ if (!hashPattern.test(id) || !Number.isSafeInteger(attempt) || attempt < 1) refuse("identity_refused");
98
+ const claimDirectory = path.join(directory, id);
99
+ if (!fs.existsSync(path.join(claimDirectory, `${attempt}.json`))) refuse("identity_refused");
100
+ const stat = fs.lstatSync(claimDirectory);
101
+ if (!stat.isDirectory() || stat.isSymbolicLink()) refuse("identity_refused");
102
+ const claim = readJson(path.join(claimDirectory, `${attempt}.json`));
103
+ if (claim.protocol_version === undefined) return { ...claim, legacy: true };
104
+ if (claim.protocol_version !== 1) refuse("identity_refused");
105
+ validateBinding(claim);
106
+ const { integrity_hash: initialHash, ...initialPayload } = claim;
107
+ if (initialHash !== mailRecordHash(initialPayload) || !Number.isSafeInteger(claim.createdAt) || claim.createdAt < 0 ||
108
+ claim.claim_id !== id || claim.attempt !== attempt || claim.revision !== 1 || claim.state !== "pending") refuse("identity_refused");
109
+ let state = { ...claim, record_hash: digest(JSON.stringify(claim)) };
110
+ const initialDescriptor = fs.openSync(path.join(claimDirectory, `${attempt}.json`), "r");
111
+ try { fs.fsyncSync(initialDescriptor); } finally { fs.closeSync(initialDescriptor); }
112
+ syncDirectory(claimDirectory);
113
+ syncDirectory(directory);
114
+ const journal = path.join(claimDirectory, `${attempt}.events`);
115
+ if (!fs.existsSync(journal)) return state;
116
+ const journalStat = fs.lstatSync(journal);
117
+ if (!journalStat.isDirectory() || journalStat.isSymbolicLink()) refuse("durability_refused");
118
+ const names = fs.readdirSync(journal).sort((left, right) => Number(left.slice(0, -5)) - Number(right.slice(0, -5)));
119
+ for (let index = 0; index < names.length; index++) {
120
+ if (names[index] !== `${index + 2}.json`) refuse("durability_refused");
121
+ const event = readJson(path.join(journal, names[index]));
122
+ const { integrity_hash: eventHash, ...eventPayload } = event;
123
+ if (eventHash !== mailRecordHash(eventPayload) || event.schema_version !== 1 || event.revision !== state.revision + 1 || event.previous_hash !== state.record_hash ||
124
+ event.claim_id !== id || event.attempt !== attempt || event.fingerprint !== claim.fingerprint || event.fingerprint_algorithm !== claim.fingerprint_algorithm ||
125
+ !["done", "not_started", "not_sent"].includes(event.state) || state.state !== "pending") refuse("durability_refused");
126
+ state = { ...claim, ...event, record_hash: digest(JSON.stringify(event)) };
127
+ const descriptor = fs.openSync(path.join(journal, names[index]), "r");
128
+ try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
129
+ }
130
+ syncDirectory(journal);
131
+ syncDirectory(claimDirectory);
132
+ return state;
133
+ }
134
+
135
+ export function appendMailOutcome(directory, claim, metadata, io = fs) {
136
+ const journal = path.join(directory, claim.claim_id, `${claim.attempt}.events`);
137
+ io.mkdirSync(journal, { recursive: true, mode: 0o700 });
138
+ syncDirectory(path.dirname(journal), io);
139
+ const event = {
140
+ schema_version: 1, ...claimBinding(claim), revision: claim.revision + 1,
141
+ previous_hash: claim.record_hash, ...metadata
142
+ };
143
+ event.integrity_hash = mailRecordHash(event);
144
+ durableCreate(path.join(journal, `${event.revision}.json`), event, io);
145
+ return { ...claim, ...event, record_hash: digest(JSON.stringify(event)) };
146
+ }
147
+
148
+ const defaultAuthorityRoot = "/Library/Application Support/AppleTools/Reconciliation";
149
+
150
+ function assertProtected(file, directory = false) {
151
+ let current = path.resolve(file);
152
+ while (true) {
153
+ const stat = fs.lstatSync(current);
154
+ if (stat.isSymbolicLink() || stat.uid !== 0 || (stat.mode & 0o022) !== 0 ||
155
+ (current === path.resolve(file) && (directory ? !stat.isDirectory() : !stat.isFile()))) refuse("evidence_refused");
156
+ const parent = path.dirname(current);
157
+ if (parent === current) break;
158
+ current = parent;
159
+ }
160
+ }
161
+
162
+ export function protectedMailAuthority(root = defaultAuthorityRoot) {
163
+ return {
164
+ load(kind, reference) {
165
+ if (!["deployment", "approval", "evidence", "authorization"].includes(kind) || !hashPattern.test(reference)) refuse("evidence_refused");
166
+ try {
167
+ assertProtected(root, true);
168
+ const file = path.join(root, kind, `${reference}.json`);
169
+ assertProtected(file);
170
+ regularFile(file);
171
+ const revocationsFile = path.join(root, "revocations.json");
172
+ assertProtected(revocationsFile);
173
+ const revocations = readJson(revocationsFile);
174
+ const raw = fs.readFileSync(file, "utf8");
175
+ if (raw.length > 65536 || digest(raw) !== reference || revocations.schema_version !== 1 || !Array.isArray(revocations.references) ||
176
+ revocations.references.some(value => !hashPattern.test(value)) || !Array.isArray(revocations.ids) || revocations.ids.some(value => !hashPattern.test(value))) refuse("evidence_refused");
177
+ const record = JSON.parse(raw);
178
+ if (revocations.references.includes(reference) || revocations.ids.includes(record.id)) refuse("evidence_refused");
179
+ return record;
180
+ } catch { refuse("evidence_refused"); }
181
+ }
182
+ };
183
+ }
184
+
185
+ function fresh(record, now, maximumAge = 60000) {
186
+ if (!record || record.schema_version !== 1 || !Number.isSafeInteger(record.issued_at) || !Number.isSafeInteger(record.expires_at) ||
187
+ record.issued_at > now || now - record.issued_at > maximumAge || record.expires_at <= now || record.expires_at - record.issued_at > maximumAge || record.revoked !== false) refuse("evidence_refused");
188
+ }
189
+
190
+ function deploymentProof(authority, reference, now) {
191
+ const record = authority.load("deployment", reference);
192
+ fresh(record, now);
193
+ const required = ["daemon", "local_fallback", "accepted_bridge", "scripts_appleevents", "old_processes", "outstanding_effects"];
194
+ if (record.kind !== "deployment" || !codePattern.test(record.epoch) || !Array.isArray(record.accounts) || !record.accounts.length ||
195
+ record.accounts.some(account => !hashPattern.test(account)) || new Set(record.accounts).size !== record.accounts.length ||
196
+ !Array.isArray(record.operators) || !record.operators.length || record.operators.some(operator => !codePattern.test(operator)) ||
197
+ required.some(writer => record.excluded?.[writer] !== true) || record.nonparticipating_launch_disabled !== true || record.clock_uncertainty_ms !== 0) refuse("active_writer_refused");
198
+ return record;
199
+ }
200
+
201
+ function approvalProof(authority, reference, kind, target, deployment, now) {
202
+ const record = authority.load(kind === "retry" ? "authorization" : "approval", reference);
203
+ fresh(record, now);
204
+ if (record.kind !== kind || !sameBinding(record, target) || !codePattern.test(record.operator) ||
205
+ !deployment.operators.includes(record.operator) || record.epoch !== deployment.epoch || !hashPattern.test(record.id)) refuse("authorization_refused");
206
+ return record;
207
+ }
208
+
209
+ export function mailAttempts(directory, id) {
210
+ const names = fs.readdirSync(path.join(directory, id)).filter(name => name.endsWith(".json"));
211
+ if (names.some(name => !/^[1-9]\d*\.json$/.test(name) || !Number.isSafeInteger(Number(name.slice(0, -5))))) refuse("identity_refused");
212
+ return names.map(name => Number(name.slice(0, -5)));
213
+ }
214
+
215
+ function latestAttempt(directory, id) {
216
+ const names = mailAttempts(directory, id);
217
+ return names.length ? Math.max(...names) : 0;
218
+ }
219
+
220
+ export function reconciliationFencePath(directory) {
221
+ return path.join(directory, ".reconciliation-fence.json");
222
+ }
223
+
224
+ export function fencedMailWrite(run, { directory = path.join(getAppleToolsDir(), "mail-send-claims") } = {}) {
225
+ try {
226
+ return withMailWriterLock(directory, () => fs.existsSync(reconciliationFencePath(directory)) ? mailOutcome("active_writer_refused") : run());
227
+ } catch (error) { return mailOutcome(error.mailCode || "durability_refused"); }
228
+ }
229
+
230
+ export function mailSendReconcile(args, {
231
+ directory = path.join(getAppleToolsDir(), "mail-send-claims"), authority = protectedMailAuthority(), now = Date.now, io = fs
232
+ } = {}) {
233
+ try {
234
+ const allowed = [...bindingFields, "action", "idempotency_key", "deployment_ref", "approval_ref", "evidence_ref", "fence_id", "outcome", "reason_code", "dry_run", "confirm"];
235
+ if (!args || Object.keys(args).some(key => !allowed.includes(key)) || !["begin", "commit"].includes(args.action)) refuse("identity_refused");
236
+ validateBinding(args);
237
+ if ((args.dry_run !== undefined && typeof args.dry_run !== "boolean") || (args.confirm !== undefined && typeof args.confirm !== "boolean") ||
238
+ !hashPattern.test(args.deployment_ref) || !hashPattern.test(args.approval_ref)) refuse("identity_refused");
239
+ if (args.action === "begin" && ["outcome", "reason_code", "evidence_ref", "fence_id"].some(field => args[field] !== undefined)) refuse("identity_refused");
240
+ if (args.idempotency_key !== undefined && (typeof args.idempotency_key !== "string" || !args.idempotency_key.trim() || args.idempotency_key.length > 256 || mailClaimId(args.fingerprint, args.idempotency_key) !== args.claim_id)) refuse("identity_refused");
241
+ if (args.dry_run === true) return { ...mailOutcome("reconciliation_preview"), planned: true };
242
+ if (!fs.existsSync(directory)) refuse("identity_refused");
243
+ const initial = readMailClaim(directory, args.claim_id, args.attempt);
244
+ if (initial.legacy) refuse("legacy_ineligible");
245
+ const requestHash = digest(JSON.stringify(allowed.map(field => args[field] ?? null)));
246
+ if (initial.reconciliation?.request_hash === requestHash && latestAttempt(directory, args.claim_id) === args.attempt) {
247
+ return mailOutcome("reconciliation_replayed", { ok: true, historical: initial.state, receipt: initial.reconciliation.receipt });
248
+ }
249
+ return withMailWriterLock(directory, () => {
250
+ const claim = readMailClaim(directory, args.claim_id, args.attempt);
251
+ if (latestAttempt(directory, args.claim_id) !== args.attempt) refuse("revision_refused");
252
+ if (claim.fingerprint !== args.fingerprint) refuse("identity_refused");
253
+ if (claim.reconciliation?.request_hash === requestHash) return mailOutcome("reconciliation_replayed", { ok: true, historical: claim.state, receipt: claim.reconciliation.receipt });
254
+ if (claim.state !== "pending") refuse("outcome_conflict");
255
+ if (!sameBinding(args, claim)) refuse("revision_refused");
256
+ const observedNow = now();
257
+ const deployment = deploymentProof(authority, args.deployment_ref, observedNow);
258
+ const approval = approvalProof(authority, args.approval_ref, "reconcile", args, deployment, observedNow);
259
+ const fenceFile = reconciliationFencePath(directory);
260
+ if (args.action === "begin") {
261
+ if (fs.existsSync(fenceFile)) {
262
+ const previous = readJson(fenceFile);
263
+ if (!sameBinding(previous, args) || previous.approval_ref !== args.approval_ref || previous.deployment_ref !== args.deployment_ref) refuse("active_writer_refused");
264
+ return mailOutcome("evidence_required", { ok: true, fence_id: previous.fence_id, ...claimBinding(claim) });
265
+ }
266
+ const fence = { schema_version: 1, ...claimBinding(claim), fence_id: digest(randomUUID()), created_at: observedNow, approval_ref: args.approval_ref, deployment_ref: args.deployment_ref, epoch: deployment.epoch };
267
+ durableCreate(fenceFile, fence, io);
268
+ return mailOutcome("evidence_required", { ok: true, fence_id: fence.fence_id, ...claimBinding(claim) });
269
+ }
270
+ const fence = readJson(fenceFile);
271
+ if (!sameBinding(fence, args) || !hashPattern.test(args.fence_id) || fence.fence_id !== args.fence_id || fence.epoch !== deployment.epoch ||
272
+ fence.approval_ref !== args.approval_ref || fence.deployment_ref !== args.deployment_ref) refuse("active_writer_refused");
273
+ if (!["sent", "not_sent"].includes(args.outcome) || !reasonCodes.has(args.reason_code) || args.reason_code !== `operator_verified_${args.outcome}`) refuse("evidence_refused");
274
+ const evidence = authority.load("evidence", args.evidence_ref);
275
+ fresh(evidence, observedNow);
276
+ if (evidence.kind !== "mail_verification" || !hashPattern.test(evidence.id) || !sameBinding(evidence, args) || evidence.fence_id !== fence.fence_id ||
277
+ evidence.epoch !== deployment.epoch || evidence.operator !== approval.operator || evidence.source !== "complete_exact_mail_snapshot_v1" ||
278
+ evidence.clock_uncertainty_ms !== 0 || evidence.outcome !== args.outcome || evidence.reason_code !== args.reason_code || evidence.effects_drained !== true) refuse("evidence_refused");
279
+ for (const mailbox of ["sent", "outbox"]) {
280
+ const observation = evidence[mailbox];
281
+ if (!observation || observation.completed !== true || observation.error !== null || observation.index_used !== false ||
282
+ !Number.isSafeInteger(observation.observed_at) || observation.observed_at <= fence.created_at || observation.observed_at > observedNow ||
283
+ observedNow - observation.observed_at > 60000 || evidence.issued_at < observation.observed_at || !Number.isSafeInteger(observation.search_from) || observation.search_from > claim.createdAt ||
284
+ observation.search_to !== observation.observed_at || observation.exact_fingerprint !== claim.fingerprint ||
285
+ !Array.isArray(observation.accounts) || JSON.stringify([...observation.accounts].sort()) !== JSON.stringify([...deployment.accounts].sort()) ||
286
+ !Array.isArray(observation.matches)) refuse("evidence_refused");
287
+ }
288
+ if (evidence.outbox.matches.length !== 0 || (args.outcome === "not_sent" ? evidence.sent.matches.length !== 0 : evidence.sent.matches.length !== 1)) refuse("evidence_refused");
289
+ let messageRef;
290
+ if (args.outcome === "sent") {
291
+ const match = evidence.sent.matches[0];
292
+ if (!match || !hashPattern.test(match.message_ref) || !hashPattern.test(match.message_id_hash) || !deployment.accounts.includes(match.account) ||
293
+ match.fingerprint !== claim.fingerprint || match.message_id_hash !== evidence.message_id_hash) refuse("evidence_refused");
294
+ messageRef = match.message_ref;
295
+ }
296
+ deploymentProof(authority, args.deployment_ref, now());
297
+ approvalProof(authority, args.approval_ref, "reconcile", args, deployment, now());
298
+ const revalidated = authority.load("evidence", args.evidence_ref);
299
+ fresh(revalidated, now());
300
+ if (JSON.stringify(revalidated) !== JSON.stringify(evidence)) refuse("evidence_refused");
301
+ const receipt = digest(JSON.stringify([requestHash, claim.record_hash]));
302
+ appendMailOutcome(directory, claim, {
303
+ state: args.outcome === "sent" ? "done" : "not_sent", committed_at: observedNow,
304
+ reconciliation: { request_hash: requestHash, receipt, evidence_ref: args.evidence_ref, approval_ref: args.approval_ref, reason_code: args.reason_code, operator: approval.operator, ...(messageRef ? { message_ref: messageRef } : {}) }
305
+ }, io);
306
+ io.unlinkSync(fenceFile);
307
+ syncDirectory(directory, io);
308
+ return mailOutcome("reconciled", { ok: true, historical: args.outcome, receipt });
309
+ });
310
+ } catch (error) {
311
+ return mailOutcome(error.mailCode || "durability_refused");
312
+ }
313
+ }
314
+
315
+ export function validateRetryAuthorization(authority, reference, deploymentRef, claim, now) {
316
+ try {
317
+ const deployment = deploymentProof(authority, deploymentRef, now);
318
+ const approval = approvalProof(authority, reference, "retry", claim, deployment, now);
319
+ if (claim.state !== "not_sent" || claim.authorization_id !== undefined || approval.single_use !== true) refuse("authorization_refused");
320
+ return approval.id;
321
+ } catch { refuse("authorization_refused"); }
322
+ }
323
+
324
+ export function assertUnspentRetryLineage(directory, claim) {
325
+ const consumed = path.join(directory, ".authorizations");
326
+ if (!fs.existsSync(consumed)) return;
327
+ const stat = fs.lstatSync(consumed);
328
+ if (!stat.isDirectory() || stat.isSymbolicLink()) refuse("durability_refused");
329
+ for (const name of fs.readdirSync(consumed)) {
330
+ if (!/^[a-f0-9]{64}\.json$/.test(name)) refuse("durability_refused");
331
+ const record = readJson(path.join(consumed, name));
332
+ const { integrity_hash: integrityHash, ...payload } = record;
333
+ if (integrityHash !== mailRecordHash(payload)) refuse("durability_refused");
334
+ validateBinding(record);
335
+ if (record.schema_version !== 1 || record.authorization_id !== name.slice(0, -5) ||
336
+ !hashPattern.test(record.authorization_ref) ||
337
+ !Number.isSafeInteger(record.retry_attempt) || record.retry_attempt !== record.attempt + 1 ||
338
+ !Number.isSafeInteger(record.consumed_at) || record.consumed_at < 0) refuse("durability_refused");
339
+ if (record.claim_id === claim.claim_id) refuse("authorization_refused");
340
+ }
341
+ }
package/lib/writeTools.js CHANGED
@@ -34,6 +34,7 @@ import { planWriteRoute, planAfterDelegation, tccFallbackAdvice } from "./writeR
34
34
  import { requestWriteViaBridge, probeSocket, defaultSocketPath } from "./writeBridge.js";
35
35
  import { needsHostTccAdvice } from "./appleScript.js";
36
36
  import { idempotentMailSend } from "./mailIdempotency.js";
37
+ import { mailSendReconcile, mailOutcome, fencedMailWrite } from "./mailReconciliation.js";
37
38
 
38
39
  const CONFIRM_PROPS = {
39
40
  dry_run: { type: "boolean", description: "Preview only: report what would happen and change nothing (default false)" },
@@ -49,7 +50,7 @@ export const WRITE_TOOL_DEFINITIONS = [
49
50
  // ============ MAIL WRITES ============
50
51
  {
51
52
  name: "mail_send",
52
- description: "Send an email through Mail.app. Success means the message was verified in Sent or is still in Outbox (still sending) — AppleScript send returning is not enough. Sending to more than one recipient in total (to + cc + bcc) requires confirm=true. dry_run and unconfirmed multi-recipient calls are not deliveries (MCP isError). A send hang is a timeout, not TCC, unless Mail reports -1743/-10004; hang recover matches To+subject (Message-ID when available), never subject alone. Clients must Sent-check before retrying a timed-out send.",
53
+ description: "Send an email through Mail.app. Success requires Sent/Outbox verification, not merely an AppleScript return. Multiple recipients require confirm=true. Durable claims never expire uncertainty or automatically retry; changing/removing a key cannot bypass pending or terminal not_sent lineage. Read structuredContent.mail_send: suppression/replay is not a new delivery and cannot advance a page ledger. Legacy pending claims cannot be reconciled. A later retry after terminal not_sent needs separate protected single-use authorization, not confirm or a new key.",
53
54
  inputSchema: {
54
55
  type: "object",
55
56
  properties: {
@@ -58,13 +59,39 @@ export const WRITE_TOOL_DEFINITIONS = [
58
59
  bcc: { type: "array", items: { type: "string" }, description: "BCC email addresses" },
59
60
  subject: { type: "string", description: "Subject line (required)" },
60
61
  body: { type: "string", description: "Message body (required)" },
61
- idempotency_key: { type: "string", description: "Stable unique delivery key. Reuse for retries of the same message; a new key represents a new intended delivery. Without a key identical accepted mail is suppressed without expiry; uncertain sends stay blocked." },
62
+ idempotency_key: { type: "string", description: "Stable delivery key. A new key may name a genuinely new delivery only after an accepted or proven-unstarted outcome; changing/removing a key cannot bypass pending or terminal not_sent lineage." },
63
+ retry_authorization_ref: { type: "string", description: "Protected, separately issued single-use retry approval reference. Not issued by reconciliation; unavailable without the reviewed deployment authority." },
64
+ deployment_ref: { type: "string", description: "Protected complete-writer-exclusion deployment proof reference for an explicitly authorized retry." },
62
65
  body_format: { type: "string", enum: ["plain", "html"], description: "Plain text (default) or HTML. HTML is tag-stripped; the body is pasted into Mail's compose window (System Events focus on the message body, then Cmd-A and clipboard paste). AppleScript content/html content is not set because it quote-wraps the Sent body" },
63
66
  ...CONFIRM_PROPS
64
67
  },
65
68
  required: ["to", "subject", "body"]
66
69
  }
67
70
  },
71
+ {
72
+ name: "mail_send_reconcile",
73
+ description: "No-send claim adjudication. Legacy claims are always ineligible. begin establishes a persistent global writer fence before fresh evidence is collected; commit requires protected administrator-provisioned approval, complete Sent AND Outbox evidence, and exclusion of all old/queued/script writers. Missing authority refuses. Neither action sends, retries, wakes Mail, changes the page ledger, or issues retry permission.",
74
+ inputSchema: {
75
+ type: "object", additionalProperties: false,
76
+ properties: {
77
+ action: { type: "string", enum: ["begin", "commit"] },
78
+ claim_id: { type: "string", pattern: "^[a-f0-9]{64}$" },
79
+ attempt: { type: "integer", minimum: 1 },
80
+ revision: { type: "integer", minimum: 1 },
81
+ fingerprint_algorithm: { type: "string", enum: ["sha256-mail-content-v1"] },
82
+ fingerprint: { type: "string", pattern: "^[a-f0-9]{64}$" },
83
+ idempotency_key: { type: "string" },
84
+ deployment_ref: { type: "string", pattern: "^[a-f0-9]{64}$" },
85
+ approval_ref: { type: "string", pattern: "^[a-f0-9]{64}$" },
86
+ evidence_ref: { type: "string", pattern: "^[a-f0-9]{64}$" },
87
+ fence_id: { type: "string", pattern: "^[a-f0-9]{64}$" },
88
+ outcome: { type: "string", enum: ["sent", "not_sent"] },
89
+ reason_code: { type: "string", enum: ["operator_verified_sent", "operator_verified_not_sent"] },
90
+ ...CONFIRM_PROPS
91
+ },
92
+ required: ["action", "claim_id", "attempt", "revision", "fingerprint_algorithm", "fingerprint", "deployment_ref", "approval_ref"]
93
+ }
94
+ },
68
95
  {
69
96
  name: "mail_draft",
70
97
  description: "Save an email to Drafts without sending it. Drafts are never delivered, so no recipient confirmation is required.",
@@ -315,6 +342,7 @@ export const WRITE_TOOL_DEFINITIONS = [
315
342
  ];
316
343
 
317
344
  export const WRITE_TOOL_HANDLERS = {
345
+ mail_send_reconcile: mailSendReconcile,
318
346
  mail_send: (args) => mailCompose(args, { draft: false }),
319
347
  mail_draft: (args) => mailCompose(args, { draft: true }),
320
348
  mail_reply: mailReply,
@@ -359,7 +387,8 @@ export function mcpWriteResult(writeResult) {
359
387
  const failed = !writeResult || writeResult.ok === false;
360
388
  return {
361
389
  content: [{ type: "text", text: message }],
362
- ...((failed || planned) ? { isError: true } : {})
390
+ ...(writeResult?.mail_send ? { structuredContent: { mail_send: writeResult.mail_send } } : {}),
391
+ ...((failed || planned || writeResult?.mail_send?.code === "accepted_replay") ? { isError: true } : {})
363
392
  };
364
393
  }
365
394
 
@@ -373,9 +402,9 @@ export function executeWriteToolLocally(name, args = {}) {
373
402
  return { ok: false, message: `Unknown write tool: ${name}`, unsupported: true };
374
403
  }
375
404
  try {
376
- return name === "mail_send"
377
- ? idempotentMailSend(args || {}, () => handler(args || {}))
378
- : handler(args || {});
405
+ if (name === "mail_send") return idempotentMailSend(args || {}, () => handler(args || {}));
406
+ if (name.startsWith("mail_") && name !== "mail_send_reconcile") return fencedMailWrite(() => handler(args || {}));
407
+ return handler(args || {});
379
408
  } catch (e) {
380
409
  return { ok: false, message: `${name} failed: ${e.message}` };
381
410
  }
@@ -428,7 +457,8 @@ export function loggedBridgeHandler(run, log, now = () => Date.now()) {
428
457
  const planned = !ok && Boolean(result && result.planned);
429
458
  // Mail accepted the send but Sent/Outbox didn't show it within budget — not a failure.
430
459
  const unconfirmed = !ok && !planned && Boolean(result && result.unconfirmed);
431
- const outcome = ok ? "ok" : planned ? "planned (dry run / needs confirm)" : unconfirmed ? "unconfirmed (sent; not yet seen in Sent/Outbox)" : "failed";
460
+ const mailCode = result?.mail_send?.code;
461
+ const outcome = mailCode ? mailCode : ok ? "ok" : planned ? "planned (dry run / needs confirm)" : unconfirmed ? "unconfirmed (transport status unknown)" : "failed";
432
462
  const why = ok || planned || unconfirmed ? "" : ` (${classifyWriteFailure(result && result.message)}${result && result.unsupported ? ", unsupported" : ""})`;
433
463
  log(`${new Date(started).toISOString()} write bridge: ${tool} ${outcome} in ${now() - started}ms${why}`);
434
464
  return result;
@@ -461,12 +491,12 @@ export async function dispatchWriteTool(name, args = {}, deps = {}) {
461
491
  const { delivered, response, error, mayHaveStarted } = await request({ socketPath, tool: name, args });
462
492
  // A lost response is not evidence of a failed send. Preserve the daemon's
463
493
  // ownership after any handoff that could have reached it.
464
- if ((name === "mail_send" || name === "mail_reply" || name === "mail_forward" || name === "messages_send") &&
494
+ if ((name === "mail_send" || name === "mail_send_reconcile" || name === "mail_reply" || name === "mail_forward" || name === "messages_send") &&
465
495
  ((!delivered && mayHaveStarted !== false) ||
466
496
  (delivered && (!response || typeof response !== "object" ||
467
- (response.unsupported && response.sendStarted !== false))))) {
497
+ (response.unsupported && (name === "mail_send_reconcile" || response.sendStarted !== false)))))) {
468
498
  log(`Write bridge outcome unknown for ${name}; local fallback suppressed.`);
469
- return { ok: false, unconfirmed: true, sendStarted: true,
499
+ return { ...(name.startsWith("mail_send") ? mailOutcome("bridge_uncertain", { entry: name === "mail_send_reconcile" ? "none" : "unknown" }) : {}), ok: false, unconfirmed: true, sendStarted: name === "mail_send_reconcile" ? false : undefined,
470
500
  message: `${name}: unconfirmed. The daemon may still complete the write. Check Sent/Outbox or the destination before retrying; no local resend was started.` };
471
501
  }
472
502
  const { fallbackLocal } = planAfterDelegation({ delivered, response });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-tools-mcp",
3
- "version": "3.3.0",
3
+ "version": "3.3.1",
4
4
  "description": "MCP server for semantic search and write actions across Apple Mail, Messages, Calendar, and Contacts. Speaks stdio (local) or bearer-token-authenticated Streamable HTTP (LAN / Tailscale).",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -52,6 +52,7 @@
52
52
  "lib/",
53
53
  "bin/",
54
54
  "examples/",
55
+ "docs/mail-send-reconciliation.md",
55
56
  "scripts/audit-index.js",
56
57
  "scripts/smoke-writes.js",
57
58
  "scripts/postinstall.js",