@mgcrea/mcp-apple-messages 1.3.1 → 1.6.0

package/README.md

@@ -68,6 +68,9 @@ That is a capability downgrade reported through `diagnostics`, never a throw.
 
 Read: `diagnostics`, `list_chats`, `list_messages`, `search_messages`, `get_message`.
 
+Opt-in read: `find_codes`, behind `APPLE_MESSAGES_ALLOW_CODES` — see [Configuration](#configuration).
+Off by default, and not covered by the write gate.
+
 Write: `send_message`, and that is the whole dictionary. `sdef` lists three commands — `send`,
 `login` and `logout` — and the other two would sign the user out of iMessage on every device they
 own. There is no edit, delete, mark-as-read or reaction verb to expose, so **everything this server
@@ -110,8 +113,23 @@ records exactly what that leaves open; the safe way to measure it is a message t
 | `APPLE_MESSAGES_DEFAULT_RANGE_DAYS` | `30`    | Window when only a start is given.      |
 | `APPLE_MESSAGES_MAX_RESULTS`        | `50`    | Default page size.                      |
 | `APPLE_MESSAGES_ALLOW_WRITES`       | off     | Register `send_message` at all.         |
+| `APPLE_MESSAGES_ALLOW_CODES`        | off     | Register `find_codes` at all.           |
 | `APPLE_MESSAGES_SEND_RECONCILE_MS`  | `5000`  | How long to wait for the sent row.      |
 
+`APPLE_MESSAGES_ALLOW_CODES` gates `find_codes`, which extracts one-time 2FA codes from recently
+received messages. It is a **read**, and it is deliberately not folded into `ALLOW_WRITES`: reaching
+a read through the write gate would mean granting the right to send a message in order to get it.
+
+It is gated at all because of what it combines with. This server already holds the conversation
+history and `@mgcrea/mcp-apple-mail` holds the inbox — between them, the password-_reset_ channel.
+Adding live authentication codes completes an account-takeover primitive out of parts that were each
+individually reasonable, so it defaults off and the two gates are independent in both directions.
+
+Codes are matched by signal rather than by a `\d{4,8}` regex, and every result carries a
+`confidence` and a `matched` saying how it was found; anything below `high` should be checked
+against the message body before use. See `src/client/codes.ts`, and `docs/passwords.md` in the
+repo for why the Passwords app itself is unreachable and this is what ships in its place.
+
 ## Notes that will bite you
 
 - **Dates do not fit in a JavaScript number.** Every date column is nanoseconds since 2001 —

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { A as MESSAGES_SURFACE, V as BUILD_INFO, a as loadConfig, r as createServer } from "./server-Bp7LsHS8.js";
+import { A as MESSAGES_SURFACE, V as BUILD_INFO, a as loadConfig, r as createServer } from "./server-C_7IK_LY.js";
 import { runStdioServer } from "@mgcrea/mcp-apple-core";
 //#region src/cli.ts
 const LOG_PREFIX = "apple-messages-mcp";

package/dist/index.d.ts

@@ -40,6 +40,7 @@ declare const ConfigSchema: z.ZodObject<{
   attachmentDir: z.ZodDefault<z.ZodString>;
   defaultRangeDays: z.ZodDefault<z.ZodNumber>;
   sendReconcileMs: z.ZodDefault<z.ZodNumber>;
+  allowCodes: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 type Config = z.infer<typeof ConfigSchema>;
 declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
@@ -788,6 +789,11 @@ type ToolContext = {
    * survives it intact.
    */
   allowWrites: boolean;
+  /**
+   * Gates `find_codes` alone, and is independent of `allowWrites` on purpose —
+   * see `config.ts` for why a read got a switch of its own.
+   */
+  allowCodes: boolean;
 };
 /**
  * Register the Apple Messages tools.
@@ -796,9 +802,17 @@ type ToolContext = {
  * surface the flag carries a permission claim as well as a safety one: with it
  * off no Apple Event is ever sent, so no Automation grant is ever requested.
  * What is needed either way is Full Disk Access, absolutely — see `diagnostics`.
+ * One further read, `find_codes`, only when `allowCodes` is on.
+ *
+ * The registered set is a pure function of STATIC CONFIGURATION, never of
+ * runtime state. In particular it does NOT vary with whether the store is
+ * readable: MCP clients cache the tool list, so a set that shrank when a grant
+ * was missing would stay shrunk after the grant arrived.
  *
- * The registered set does NOT vary with whether the store is readable. That is a
- * runtime condition, and MCP clients cache the tool list.
+ * That invariant used to read "a pure function of `allowWrites` and nothing
+ * else". `allowCodes` widened the input without weakening the guarantee, which
+ * was always about runtime conditions rather than about there being exactly one
+ * flag. `test/tools.test.ts` asserts each arm separately.
  */
 declare const registerTools: (server: McpServer, client: AppleMessagesClient, ctx: ToolContext) => void;
 //#endregion

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/config.ts","../src/client/locate.ts","../src/client/store.ts","../src/client/messages.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/ref.ts","../src/client/typedstream.ts","../src/client/jxa/core.ts","../src/client/jxa/write.ts","../src/server.ts","../src/tools/index.ts"],"mappings":";;;;;;cAkBa,YAAY;;;;;;;;;;;;;;;;;;cCSnB,cAAY,EAAA;;;;;;;;;;;;;;;;;;GAmCP,EAAA,KAAA;KAEC,SAAS,EAAE,aAAa;cAEvB,aAAU,MAAS,OAAO,eAA2B;;;;;;;;;;;;;cClDrD;;cAGA;KAaD,eAAe;EACzB;EACA;;EAEA;EACA;;cAGW,mBAAgB;cAQhB,cAAW;EACd;EAAgC;MACvC;;;cCiBU,gBAAa;KAMd;EACV;EACA,gBAAgB;EAChB,aAAa;EACb,eAAe;EACf,mBAAmB;EACnB;EACA;EACA;EACA;;KAGU;EACV;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;;EAEA;EACA;;EAEA;;EAEA;;KAGU;EACV;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA;EACA;EACA;EACA;;cAOW;;WACF,IAAI;WACJ;WACA,MAAM;EAEf,YAAY,IAAI,cAAc,cAAc,MAAM;;;;;;;;EAsGlD,MAAM,GAAG,aAAa;;;;;;;;;;;;;;EA6CtB,OAAO,eAAe,eAAe,6BAA2B;EA4ChE,OAAO,eAAe;;EActB,aAAa;IAAiB;IAAc;IAAe;;;;;;;;;;;;;;;;EAkC3D,eAAe;IACb;IACA;IACA;IACA;IACA;IACA;;;EA6BF,eAAe;IACb;IACA;IACA;IACA;IACA;;EAyBF,MAAM,gBAAgB;;EAKtB,WAAW,eAAe;;;;;;;;;;;;;;EAiB1B,gBAAgB,4BAA4B,iBAAa;;;;;;;;;;;;EAyBzD,UAAU,8BAA8B,oBAAoB,iBAAa;;EAqFzE;EAUA;IAAY;IAAkB;IAAe;IAAiB;;EAgB9D;;cASW,aAAU,IAAQ,iBAAe;cAgCjC,YAAS,qBACD,MACb,cAAY,SACT,WACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KCvkBS;EACV,QAAQ;EACR,SAAS;;EAET;;EAEA,WAAW;;EAEX,YAAY;;;;;;;;;;KAWF;EACV;;EAEA;EACA;;EAEA;EACA;EACA,IAAI;;EAEJ;;EAEA;EACA,SAAS;EACT;;KAGU;;EAEV;;EAEA;;EAEA;;KAGU;EACV;EACA;EACA;EACA,MAAM;EACN;EACA;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;KAGU;EACV;EACA;EACA;EACA;EACA,cAAc;EACd;EACA;;cAGW;;EAuBX,YAAY,MAAM;MAiBd,UAAU;EAId,WAAW;EAQX,SAAS;EAiHT,aAAa;IACX;IACA;IACA;IACA;IACA;MACE;EAYJ,eAAe,eAAe,iBAAiB;EAI/C,WAAW,gBACN;IACC;MAAa;MAAe,MAAM;;IAClC,aAAa,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;EAuCxB,eACJ,sBACA;IAAQ;IAAgC;MACvC;IAAU;IAAc;IAAe;IAAgB;;EA4D1D,UAAU,iBAAiB;;;;;;;EA2HrB,YAAY;IAChB;IACA;IACA;IACA;MACE,QAAQ;;EAyDZ,OAAO,OAAO,MAAM,KAAK;IAAS;IAAoB;;EAOtD;IACE,SAAS;IACT;MAAS;MAAiB;MAAqB;;IAC/C,QAAQ,WAAW;IACnB;MAAY;MAAkB;MAAoB;;;EAmBpD;;;;;;;;;;cC/lBW,kBAAe;;cAMf,mBAAgB,yBAA2B;;cAM3C,iBAAc,MAAU;;cAIxB,gBAAa;;;cCrDb,kBAAkB;;;;;;;;;;;;;;cAkBlB;;cAaA,6BAA6B;WACtB;EAElB,YAAY;;;cAUD,0BAA0B;WACnB;EAElB,YAAY;;;;;;;;;;;cAcD,iCAAiC;WAC1B;EAElB,YAAY;;;;;;;;;;;;cAeD,gCAAgC;WACzB;EAElB,YAAY,mBAAmB;;;cAYpB,wBAAwB;WACjB;EAElB,YAAY,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;cC7ElB;cACA;cAmBA,+BAA+B;WACxB;EAElB,YAAY,aAAa;;cAUd,mBAAgB;cAChB,gBAAa;cAEb,mBAAgB;cAMhB,gBAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KC6Od;EAEN;EACA;EACA;;EAEA;EACA;;EAEA;EAAW;EAAkB;EAAoB;EAA2B;;cAErE,uBAAoB,QAAY,kCAAgC;;;;;;;;cA6BhE,UAAO,QAAY,YAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cC/Q7B;;;;;;;;;;;;;;;;;;;;;;;;;;cClDA;;;cCVA;cACA;KAED;EACV,QAAQ;EACR,SAAS;;EAET,YAAY;;EAEZ;;EAEA,WAAW,6BAA6B;;KAG9B;EACV,QAAQ;EACR,QAAQ;;;;;;;cAQG,eAAY,MAAU,wBAAsB;;;KC9B7C;;;;;;;;;;;;;;;EAeV;;;;;;;;;;;;;cAcW,gBAAa,QAChB,WAAS,QACT,qBAAmB,KACtB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/config.ts","../src/client/locate.ts","../src/client/store.ts","../src/client/messages.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/ref.ts","../src/client/typedstream.ts","../src/client/jxa/core.ts","../src/client/jxa/write.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,2 +1,2 @@
-import { A as MESSAGES_SURFACE, B as toAppleSeconds, C as locateStore, D as ChatNotFoundError, E as AppleMessagesError, F as SendTargetNotFoundError, I as CORE_DATA_EPOCH_OFFSET, L as appleSecondsSql, M as MessagesUnavailableError, N as SchemaDriftError, O as IndexUnavailableError, P as SendFailedError, R as fromAppleSeconds, S as defaultStorePath, T as PRELUDE, V as BUILD_INFO, _ as decodeMessageRef, a as loadConfig, b as ATTACHMENTS_RELATIVE, c as introspect, d as decodeAttributedBody, f as outline, g as decodeChatRef, h as MESSAGE_REF_VERSION, i as registerTools, j as MessageNotFoundError, k as MESSAGES_BUNDLE_ID, l as openStore, m as InvalidMessageRefError, n as SERVER_VERSION, o as AppleMessagesClient, p as CHAT_REF_VERSION, r as createServer, s as MessagesStore, t as SERVER_NAME, u as reactionLabel, v as encodeChatRef, w as SEND_MESSAGE, x as STORE_RELATIVE, y as encodeMessageRef, z as renderInstant } from "./server-Bp7LsHS8.js";
+import { A as MESSAGES_SURFACE, B as toAppleSeconds, C as locateStore, D as ChatNotFoundError, E as AppleMessagesError, F as SendTargetNotFoundError, I as CORE_DATA_EPOCH_OFFSET, L as appleSecondsSql, M as MessagesUnavailableError, N as SchemaDriftError, O as IndexUnavailableError, P as SendFailedError, R as fromAppleSeconds, S as defaultStorePath, T as PRELUDE, V as BUILD_INFO, _ as decodeMessageRef, a as loadConfig, b as ATTACHMENTS_RELATIVE, c as introspect, d as decodeAttributedBody, f as outline, g as decodeChatRef, h as MESSAGE_REF_VERSION, i as registerTools, j as MessageNotFoundError, k as MESSAGES_BUNDLE_ID, l as openStore, m as InvalidMessageRefError, n as SERVER_VERSION, o as AppleMessagesClient, p as CHAT_REF_VERSION, r as createServer, s as MessagesStore, t as SERVER_NAME, u as reactionLabel, v as encodeChatRef, w as SEND_MESSAGE, x as STORE_RELATIVE, y as encodeMessageRef, z as renderInstant } from "./server-C_7IK_LY.js";
 export { ATTACHMENTS_RELATIVE, AppleMessagesClient, AppleMessagesError, BUILD_INFO, CHAT_REF_VERSION, CORE_DATA_EPOCH_OFFSET, ChatNotFoundError, IndexUnavailableError, InvalidMessageRefError, MESSAGES_BUNDLE_ID, MESSAGES_SURFACE, MESSAGE_REF_VERSION, MessageNotFoundError, MessagesStore, MessagesUnavailableError, PRELUDE, SEND_MESSAGE, SERVER_NAME, SERVER_VERSION, STORE_RELATIVE, SchemaDriftError, SendFailedError, SendTargetNotFoundError, appleSecondsSql, createServer, decodeAttributedBody, decodeChatRef, decodeMessageRef, defaultStorePath, encodeChatRef, encodeMessageRef, fromAppleSeconds, introspect, loadConfig, locateStore, openStore, outline, reactionLabel, registerTools, renderInstant, toAppleSeconds };

package/dist/{server-Bp7LsHS8.js → server-C_7IK_LY.js}

@@ -13,8 +13,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 const BUILD_INFO = {
 	name: pkg.name,
 	version: pkg.version,
-	gitCommit: "312147f",
-	gitCommitDate: "2026-08-27T16:06:37+02:00"
+	gitCommit: "90f269d",
+	gitCommitDate: "2026-09-01T00:21:33+02:00"
 };
 //#endregion
 //#region src/client/dates.ts
@@ -1733,7 +1733,23 @@ const ConfigSchema = BaseConfigSchema.extend({
 	* network; a miss is reported as `pending`, never as a failure. Zero means one
 	* immediate check and no polling, which is what the test suite uses.
 	*/
-	sendReconcileMs: z.number().int().min(0).max(6e4).default(5e3)
+	sendReconcileMs: z.number().int().min(0).max(6e4).default(5e3),
+	/**
+	* Gates `find_codes`, and deliberately NOT folded into `allowWrites`.
+	*
+	* Two reasons, and the second is the real one. It is a read, so putting it
+	* behind a write gate would mean granting the right to send a message in
+	* order to get a read tool — the two are unrelated and bundling them makes
+	* both switches mean less.
+	*
+	* And it is a read of a different tier. This server already holds the
+	* conversation history; a sibling holds Mail. Between them that is the
+	* password-RESET channel, and adding live authentication codes to the same
+	* process completes an account-takeover primitive out of parts that were each
+	* individually reasonable. That is a real change in what a leaked transcript
+	* costs, so it gets a switch of its own and defaults off.
+	*/
+	allowCodes: z.boolean().default(false)
 }).strict();
 const loadConfig$1 = (env = process.env) => parseConfig(ConfigSchema, {
 	allowWrites: parseBool(env.APPLE_MESSAGES_ALLOW_WRITES),
@@ -1745,6 +1761,7 @@ const loadConfig$1 = (env = process.env) => parseConfig(ConfigSchema, {
 	attachmentDir: trimmed(env.APPLE_MESSAGES_ATTACHMENT_DIR),
 	defaultRangeDays: parseIntOpt(env.APPLE_MESSAGES_DEFAULT_RANGE_DAYS),
 	sendReconcileMs: parseIntOpt(env.APPLE_MESSAGES_SEND_RECONCILE_MS),
+	allowCodes: parseBool(env.APPLE_MESSAGES_ALLOW_CODES),
 	osascriptPath: trimmed(env.APPLE_MESSAGES_OSASCRIPT_PATH),
 	osascriptTimeoutMs: parseIntOpt(env.APPLE_MESSAGES_OSASCRIPT_TIMEOUT_MS),
 	maxResults: parseIntOpt(env.APPLE_MESSAGES_MAX_RESULTS)
@@ -2027,6 +2044,319 @@ const registerChatTools = (server, client) => {
 	}, async ({ limit }) => wrap(async () => client.listChats(limit)));
 };
 //#endregion
+//#region src/client/codes.ts
+/**
+* One-time-code extraction, as a pure function over message text.
+*
+* No I/O by design: everything here is decided from a string plus one bit about
+* the sender, so the whole thing tests offline against a table. That also keeps
+* it liftable to Mail, where the same problem exists with messier input.
+*
+* ── WHY THIS IS NOT A REGEX ──────────────────────────────────────────────────
+*
+* The obvious implementation is `/\b\d{4,8}\b/` and it is wrong in a way that
+* matters more than usual: a caller asks for a login code, gets the last four
+* digits of an order number, and pastes it into an auth prompt. The failure is
+* silent and the retry costs the user an account lockout. So the digit run is
+* the CANDIDATE here, never the answer — it has to survive disqualification and
+* then earn a score.
+*
+* The false positives are not hypothetical. A real inbox carries order numbers,
+* tracking numbers, prices, street numbers, years, flight numbers and phone
+* numbers, and every one of them is a 4-to-8 digit run in a message that also
+* contains the word "code" somewhere.
+*
+* ── THE SIGNALS, STRONGEST FIRST ─────────────────────────────────────────────
+*
+*   domain-bound   `@example.com #123456` — the WebOTP/AutoFill convention
+*                  Apple and Chrome both parse. Unambiguous by construction:
+*                  the origin is bound to the code, so there is nothing to
+*                  guess. When present it wins outright.
+*   keyword        A code word adjacent to the digits. "adjacent" is measured
+*                  in characters, not words, because the two orders both occur
+*                  ("your code is 123456" and "123456 is your code") and a word
+*                  window would need two passes.
+*   shortcode      Sender is a shortcode — a bank, a courier, a 2FA sender,
+*                  never a person. Corroborating only: it raises a weak match
+*                  to usable, never creates one on its own.
+*
+* ── WHAT `confidence` IS FOR ─────────────────────────────────────────────────
+*
+* The tool reports it, and the tool description tells the model to check the
+* body on anything below "high". This mirrors `apple_safari_list_tabs`'
+* `historyMatch`: say how the match was made so the caller is never guessing
+* whether to trust it.
+*/
+/** A code word. "code" carries both English and French, conveniently. */
+const KEYWORDS = [
+	"code",
+	"verification",
+	"verify",
+	"one-time",
+	"onetime",
+	"one time",
+	"otp",
+	"passcode",
+	"pin",
+	"2fa",
+	"two-factor",
+	"authentication",
+	"authenticate",
+	"security",
+	"log in",
+	"login",
+	"sign in",
+	"signin",
+	"confirm",
+	"verification",
+	"usage unique",
+	"mot de passe",
+	"connexion",
+	"identification",
+	"securite",
+	"sécurité",
+	"vérification"
+];
+/**
+* Phrases where "code" means something else entirely.
+*
+* This is a denylist and `docs/surfaces.md` warns that a denylist can never be
+* finished — correctly, and it is used narrowly here because of that. It only
+* ever SUPPRESSES the keyword signal; it never decides the outcome by itself,
+* and a message carrying both "promo code" and a real domain-bound code still
+* resolves through the stronger signal.
+*/
+const ANTI_KEYWORDS = [
+	"promo code",
+	"promotional code",
+	"discount code",
+	"coupon code",
+	"referral code",
+	"invite code",
+	"area code",
+	"zip code",
+	"postal code",
+	"qr code",
+	"barcode",
+	"bar code",
+	"country code",
+	"code promo",
+	"code postal",
+	"code de reduction",
+	"code de réduction",
+	"code parrainage"
+];
+/** How far from the digits a keyword still counts, in characters. */
+const NEAR = 32;
+const ADJACENT = 12;
+/**
+* The WebOTP format: a last line of `@host #code`, optionally with `?` params.
+* Anchored to a `@host` so a bare `#1234` (an order number, a hashtag) does not
+* qualify.
+*/
+const DOMAIN_BOUND = /@([a-z0-9][a-z0-9.-]*\.[a-z]{2,})\s+#([0-9]{4,8})\b/i;
+/**
+* A maximal run of digits and the separators a phone number or a formatted
+* quantity is allowed to contain. Used to reject, not to match: a span holding
+* more than 8 digits in total is a phone number, an account number or an
+* amount, and every digit run inside it is disqualified along with it.
+*/
+const NUMBER_SPAN = /\d[\d\s().+-]*\d|\d+/g;
+const DIGIT_RUN = /\d{4,8}/g;
+const normalise = (s) => s.toLowerCase().replace(/ /g, " ");
+/** Spans that hold too many digits to be a code. Returns [start, end) pairs. */
+const disqualifiedSpans = (text) => {
+	const out = [];
+	for (const m of text.matchAll(NUMBER_SPAN)) if (m[0].replace(/\D/g, "").length > 8) out.push([m.index, m.index + m[0].length]);
+	return out;
+};
+const inSpan = (spans, start, end) => spans.some(([a, b]) => start >= a && end <= b);
+/**
+* Rejections that look at the characters touching the digits.
+*
+* Each of these was a real false positive shape before it was a rule; see
+* `test/codes.test.ts`, where every one has a case.
+*/
+const looksLikeSomethingElse = (text, start, end) => {
+	const before = text.slice(Math.max(0, start - 12), start);
+	const after = text.slice(end, end + 12);
+	if (/[$€£¥]\s*$/.test(before)) return true;
+	if (/^[.,]\d/.test(after)) return true;
+	if (/\d[.,]$/.test(before)) return true;
+	if (/[a-z]$/i.test(before)) return true;
+	if (/^[a-z]/i.test(after) && !/^[a-z]{0,2}\b/i.test(after)) return true;
+	if (/^\s*%/.test(after)) return true;
+	return false;
+};
+/** 1900-2099. Rejected unless a keyword sits right against it. */
+const looksLikeYear = (digits) => digits.length === 4 && /^(19|20)\d{2}$/.test(digits);
+/**
+* Distance in characters from a digit run to the nearest keyword, or null.
+*
+* Both directions are searched because both orders are common in the wild:
+* "your code is 123456" and "123456 is your Google verification code".
+*
+* The slice is widened by the longest keyword before searching, and the
+* distance checked afterwards. Slicing to exactly NEAR instead is wrong in a
+* way that is easy to miss: it cuts the keyword in half at the boundary, so
+* "authentication" (14 chars) would need to sit 14 characters closer than
+* "otp" to register at all. The window bounds the GAP, not the keyword.
+*/
+const LONGEST_KEYWORD = Math.max(...KEYWORDS.map((k) => k.length));
+const keywordDistance = (lower, start, end) => {
+	const from = Math.max(0, start - NEAR - LONGEST_KEYWORD);
+	const before = lower.slice(from, start);
+	const after = lower.slice(end, end + NEAR + LONGEST_KEYWORD);
+	let best = null;
+	for (const kw of KEYWORDS) {
+		const b = before.lastIndexOf(kw);
+		if (b !== -1) {
+			const d = before.length - (b + kw.length);
+			if (d <= NEAR && (best === null || d < best)) best = d;
+		}
+		const a = after.indexOf(kw);
+		if (a !== -1 && a <= NEAR && (best === null || a < best)) best = a;
+	}
+	return best;
+};
+/** True when a code word near the digits is one of the decoy phrases. */
+const LONGEST_ANTI = Math.max(...ANTI_KEYWORDS.map((k) => k.length));
+const suppressedByAntiKeyword = (lower, start, end) => {
+	const window = lower.slice(Math.max(0, start - NEAR - LONGEST_ANTI), end + NEAR + LONGEST_ANTI);
+	return ANTI_KEYWORDS.some((k) => window.includes(k));
+};
+/**
+* Pull the one-time code out of a message, or return null.
+*
+* Null is the common and correct answer for most messages, and callers must
+* treat it as "no code here" rather than retrying with something looser.
+*/
+const extractCode = (text, { fromShortcode = false } = {}) => {
+	if (!text) return null;
+	if (text.length > 400) return null;
+	const lower = normalise(text);
+	const bound = DOMAIN_BOUND.exec(text);
+	const boundHost = bound?.[1];
+	const boundCode = bound?.[2];
+	if (boundHost && boundCode) return {
+		code: boundCode,
+		confidence: "high",
+		matched: "domain-bound",
+		boundTo: boundHost
+	};
+	const dead = disqualifiedSpans(text);
+	const candidates = [];
+	for (const m of text.matchAll(DIGIT_RUN)) {
+		const digits = m[0];
+		const start = m.index;
+		const end = start + digits.length;
+		if (inSpan(dead, start, end)) continue;
+		if (looksLikeSomethingElse(text, start, end)) continue;
+		const distance = keywordDistance(lower, start, end);
+		const suppressed = distance !== null && suppressedByAntiKeyword(lower, start, end);
+		const keyword = distance !== null && !suppressed;
+		if (looksLikeYear(digits) && !(keyword && distance <= ADJACENT)) continue;
+		if (keyword) {
+			const adjacent = distance <= ADJACENT;
+			candidates.push({
+				code: digits,
+				confidence: adjacent ? "high" : "medium",
+				matched: "keyword",
+				rank: adjacent ? 0 : 1
+			});
+			continue;
+		}
+		if (fromShortcode && text.length <= 120) candidates.push({
+			code: digits,
+			confidence: "low",
+			matched: "shortcode",
+			rank: 2
+		});
+	}
+	candidates.sort((a, b) => a.rank - b.rank);
+	const [best, second] = candidates;
+	if (!best) return null;
+	const ambiguous = second !== void 0 && second.rank === best.rank && second.code !== best.code;
+	return {
+		code: best.code,
+		confidence: ambiguous && best.confidence === "high" ? "medium" : best.confidence,
+		matched: ambiguous ? `${best.matched}-ambiguous` : best.matched
+	};
+};
+//#endregion
+//#region src/tools/codes.ts
+/**
+* The one-time-code tool, registered only when `allowCodes` is on.
+*
+* It exists because the Passwords app cannot be reached at all — every lane is
+* closed, see `docs/passwords.md` — while the channel 2FA codes actually arrive
+* on is a store this server already reads under a grant the user has already
+* given. The value it adds over `apple_messages_search_messages` is not access,
+* which was never missing; it is EXTRACTION, which is where the mistakes live.
+* See `client/codes.ts` for why that is not a regex.
+*
+* The window defaults tight on purpose. A one-time code is only interesting
+* while it is live, and a generous default turns this into a tool that reads
+* months of authentication history for no benefit.
+*/
+const MAX_WINDOW_MINUTES = 60;
+const DEFAULT_WINDOW_MINUTES = 10;
+const registerCodeTools = (server, client) => {
+	server.registerTool("apple_messages_find_codes", {
+		description: `Find one-time authentication codes (2FA/OTP) in recently received messages. Looks back ${DEFAULT_WINDOW_MINUTES} minutes by default, ${MAX_WINDOW_MINUTES} at most, and only at messages you received — never at ones you sent.
+
+CHECK \`ageSeconds\` BEFORE USING A CODE. An expired code is still in the store and reads exactly like a live one; most issuers expire them within 5-10 minutes, and this tool cannot tell which have. If the newest match is older than the window the user expected, say so rather than offering it.
+
+\`confidence\` says how the match was made and is not decoration. "high" means the code was bound to a domain (\`@site.com #123456\`) or sat directly against a word like "verification code" — safe to use. "medium" means the keyword was further away, or two candidates tied. "low" means there was no keyword at all and only the sender being a shortcode suggested it. On anything below high, read the message with apple_messages_get_message and confirm against the body before using the digits.
+
+A \`matched\` value ending in \`-ambiguous\` means the message held more than one plausible code and this tool did not guess — confirm which one is wanted.
+
+Returning nothing is the normal result when no code has arrived. It does NOT mean the code was missed, and it is not a reason to re-run with a longer window: if a code was sent it is in the store within seconds. Prefer asking the user to trigger a new one.`,
+		inputSchema: {
+			service: z.string().optional().describe("Narrow to one issuer by matching the sender or the message text — \"Google\", \"bank\", \"Github\". Case-insensitive substring. Omit to see every recent code."),
+			withinMinutes: z.number().int().min(1).max(MAX_WINDOW_MINUTES).optional().describe(`How far back to look, in minutes. Default ${DEFAULT_WINDOW_MINUTES}, max ${MAX_WINDOW_MINUTES}. Keep it short: a code older than a few minutes has usually expired, and a wide window just returns history.`),
+			limit: limitArg
+		},
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false
+		}
+	}, async ({ service, withinMinutes, limit }) => wrap(async () => {
+		const minutes = withinMinutes ?? DEFAULT_WINDOW_MINUTES;
+		const since = /* @__PURE__ */ new Date(Date.now() - minutes * 6e4);
+		const { fromApple } = client.window(since);
+		const needle = service?.trim().toLowerCase();
+		const codes = client.listMessages({
+			...fromApple === void 0 ? {} : { fromApple },
+			limit
+		}).filter((m) => !m.fromMe).filter((m) => {
+			if (!needle) return true;
+			return `${m.from.name ?? ""} ${m.from.handle ?? ""} ${m.text ?? ""}`.toLowerCase().includes(needle);
+		}).flatMap((m) => {
+			const match = extractCode(m.text, { fromShortcode: m.from.resolution === "shortcode" });
+			if (!match) return [];
+			const sentAtMs = m.sentAt ? Date.parse(m.sentAt) : NaN;
+			return [{
+				code: match.code,
+				confidence: match.confidence,
+				matched: match.matched,
+				...match.boundTo ? { boundTo: match.boundTo } : {},
+				from: m.from,
+				sentAt: m.sentAt,
+				ageSeconds: Number.isNaN(sentAtMs) ? null : Math.max(0, Math.round((Date.now() - sentAtMs) / 1e3)),
+				ref: m.ref,
+				chat: m.chat
+			}];
+		});
+		return {
+			windowMinutes: minutes,
+			searchedSince: since.toISOString(),
+			count: codes.length,
+			codes
+		};
+	}));
+};
+//#endregion
 //#region src/tools/messages.ts
 /** ISO-8601 in, or a clear refusal. No relative grammar on this surface yet. */
 const parseBound = (raw, field) => {
@@ -2082,14 +2412,23 @@ const registerMessageTools = (server, client) => {
 * surface the flag carries a permission claim as well as a safety one: with it
 * off no Apple Event is ever sent, so no Automation grant is ever requested.
 * What is needed either way is Full Disk Access, absolutely — see `diagnostics`.
+* One further read, `find_codes`, only when `allowCodes` is on.
 *
-* The registered set does NOT vary with whether the store is readable. That is a
-* runtime condition, and MCP clients cache the tool list.
+* The registered set is a pure function of STATIC CONFIGURATION, never of
+* runtime state. In particular it does NOT vary with whether the store is
+* readable: MCP clients cache the tool list, so a set that shrank when a grant
+* was missing would stay shrunk after the grant arrived.
+*
+* That invariant used to read "a pure function of `allowWrites` and nothing
+* else". `allowCodes` widened the input without weakening the guarantee, which
+* was always about runtime conditions rather than about there being exactly one
+* flag. `test/tools.test.ts` asserts each arm separately.
 */
 const registerTools = (server, client, ctx) => {
 	registerDiagnosticsTools(server, client);
 	registerChatTools(server, client);
 	registerMessageTools(server, client);
+	if (ctx.allowCodes) registerCodeTools(server, client);
 	if (!ctx.allowWrites) return;
 	registerActionTools(server, client);
 	registerAttachmentTools(server, client);
@@ -2116,7 +2455,10 @@ const createServer = (opts) => {
 		...opts.home ? { home: opts.home } : {},
 		...opts.contacts === void 0 ? {} : { contacts: opts.contacts }
 	});
-	registerTools(server, client, { allowWrites: config.allowWrites });
+	registerTools(server, client, {
+		allowWrites: config.allowWrites,
+		allowCodes: config.allowCodes
+	});
 	if (config.exposePrompts) {
 		registerPrompts(server, config.allowWrites);
 		registerSurfaceResources(server, {
@@ -2134,4 +2476,4 @@ const createServer = (opts) => {
 //#endregion
 export { MESSAGES_SURFACE as A, toAppleSeconds as B, locateStore as C, ChatNotFoundError as D, AppleMessagesError as E, SendTargetNotFoundError as F, CORE_DATA_EPOCH_OFFSET as I, appleSecondsSql as L, MessagesUnavailableError as M, SchemaDriftError$1 as N, IndexUnavailableError$1 as O, SendFailedError as P, fromAppleSeconds as R, defaultStorePath as S, PRELUDE as T, BUILD_INFO as V, decodeMessageRef as _, loadConfig$1 as a, ATTACHMENTS_RELATIVE as b, introspect as c, decodeAttributedBody as d, outline as f, decodeChatRef as g, MESSAGE_REF_VERSION as h, registerTools as i, MessageNotFoundError as j, MESSAGES_BUNDLE_ID as k, openStore as l, InvalidMessageRefError as m, SERVER_VERSION as n, AppleMessagesClient as o, CHAT_REF_VERSION as p, createServer as r, MessagesStore as s, SERVER_NAME as t, reactionLabel as u, encodeChatRef as v, SEND_MESSAGE as w, STORE_RELATIVE as x, encodeMessageRef as y, renderInstant as z };
 
-//# sourceMappingURL=server-Bp7LsHS8.js.map
+//# sourceMappingURL=server-C_7IK_LY.js.map