Securing Automated OTP Flows

Before: a signup flow stalls at "enter the code we emailed you," a human digs through a shared inbox, copies six digits, pastes them into a terminal. After: the agent owns the mailbox, a webhook fires when the verification email lands, a regex pulls the code, and the flow completes in seconds with nobody watching. Automated OTP extraction is one of the most satisfying agent patterns to build — and one of the easiest to build dangerously, because you've just turned authentication codes into machine-readable input.

The threat model

An OTP is a credential with a short fuse. The extraction recipe for Agent Accounts (currently in beta) is straightforward plumbing — webhook in, parse, return the code to whatever's blocked waiting for it. The risks live around the plumbing:

Anyone can email the inbox. Mailboxes are public endpoints. If your handler extracts codes from any message that arrives, an attacker who knows the address can feed it crafted "verification" emails and influence what your orchestrator receives.
Email content is untrusted input. The agent security guide is firm on this: agents should never execute instructions found in messages. An OTP pipeline that passes raw bodies to an LLM is exposed to whatever instructions are buried in the HTML.
Codes leak through logs. The natural debugging instinct — log the extracted value — turns your log aggregator into a credential store.

Each of these has a cheap mitigation. Take them in order.

Lock down who can reach the inbox

First line of defense: match hard on the sender before any parsing runs. The recipe's handler checks two signals — the sender domain belongs to the service being authenticated against, and the subject looks like a verification email:

app.post("/webhooks/otp", async (req, res) => {
  res.status(200).end();

  const event = req.body;
  if (event.type !== "message.created") return;

  const msg = event.data.object;
  if (msg.grant_id !== AGENT_GRANT_ID) return;

  const sender = msg.from?.[0]?.email ?? "";
  const subject = msg.subject ?? "";

  const senderMatches = sender.endsWith("@no-reply.example.com");
  const subjectLooksRight = /code|verif|one.?time|passcode/i.test(subject);
  if (!senderMatches || !subjectLooksRight) return;

  await handleOtp(msg.id);
});

You can push this below your application code entirely. Policies, Rules, and Lists let you constrain inbound so only expected senders reach the agent — unwanted mail gets handled at the mailbox layer, and your handler's sender check becomes a second layer instead of the only one. Inbound rules match sender fields (from.address, from.domain, from.tld) with operators including is_not, so a single-purpose OTP inbox can reject everything that isn't from the one service it exists to hear from:

curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer $NYLAS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "OTP inbox: only the identity provider gets in",
    "priority": 1,
    "trigger": "inbound",
    "match": {
      "conditions": [
        { "field": "from.domain", "operator": "is_not", "value": "no-reply.example.com" }
      ]
    },
    "actions": [{ "type": "block" }]
  }'

A block rejects the message at the SMTP layer — it's never stored and message.created never fires, so your extraction code never even sees the attacker's mail. For a mailbox that exists to receive from exactly one sender, that tight posture costs nothing.

Handle the code like the credential it is

The extraction itself is regex-first, with an LLM picking up messy marketing templates the patterns miss. The recipe's tiers run from most to least specific:

// Strip HTML so the regex sees plain text, not inline style / hidden pixels.
const plaintext = stripHtml(message.body);

const patterns = [
  /(?:code|passcode|one[\s-]?time)[^\d]{0,20}(\d{4,8})/i, // "Your code is: 123456"
  /\b(\d{6})\b/,                                          // bare 6-digit
  /\b(\d{4,8})\b/,                                        // bare 4–8 digit (last resort)
];

for (const p of patterns) {
  const match = p.exec(plaintext);
  if (match) return returnCode(match[1]);
}
return extractWithLlm(plaintext); // only for templates regex can't handle

Order matters: the labeled pattern can't grab a phone number or an order ID by accident, while the bare 4–8 digit fallback absolutely can — which is why it runs last, and why the sender filtering above has to happen first. Two handling rules from the recipe deserve promotion to policy:

Don't log codes. Log that a code was received and returned; never the value. If the LLM fallback is in play, remember the provider's logs too — the recipe keeps the prompt narrow (return JSON with the code or null, nothing else) partly so the model never gets asked to "understand" or act on the email, only to extract one value. Strip HTML before the body reaches either the regex or the model, which also discards hidden tracking pixels and invisible text.

Rate-limit aggressively. A retry loop that keeps requesting fresh codes looks like an attack to the service on the other side and can get the agent's address blocked. Cap retries, back off on failure. The recipe's awaitCode helper uses a 60-second timeout per attempt — a sane default that fails the run instead of hammering the provider.

Respect freshness, expect duplicates

Most services expire OTPs within 5–15 minutes, and a stale code is worse than no code — it burns an attempt and can trip the service's own velocity checks. Check message.date and refuse codes older than a few minutes rather than returning whatever parsed.

The companion failure: multiple codes in the inbox. An earlier attempt leaves a stale OTP behind, the service sends a fresh one, and a naive regex grabs the old message. Sort by message timestamp, newest first, before extracting. And since some providers deliberately rotate formats — 6 digits this session, 8 or alphanumeric the next — keep the regex permissive and let the LLM fallback absorb shape changes instead of hard-coding one pattern.

Two infrastructure leaks to close

Beyond message handling, the pipeline itself has trust boundaries:

Verify the webhook before extracting anything. Your handler is an HTTP endpoint, and a forged message.created payload is a second way to feed the pipeline a fake code — no email required. Check the x-nylas-signature HMAC on every request before touching the payload, and dedup on the message ID: webhooks can be redelivered, and a replayed event shouldn't re-trigger extraction or hand a stale code to a fresh login attempt.

Don't trust an in-memory registry in production. The recipe's promise-based pending map — awaitCode(correlationKey) resolving when the code arrives — is the right shape, but webhook handlers run on short-lived processes and an in-memory Map doesn't survive a restart. A run that loses its waiter mid-flight times out and retries, and now you're in the multiple-codes scenario above. Use a real queue or pub/sub once anything depends on it.

Wire it up, then attack it

The full implementation — webhook filter, regex tiers, LLM fallback, and the promise registry that returns codes to the caller — is in the OTP extraction cookbook. Build it on a test inbox first.

Then, before trusting it anywhere real, spend ten minutes as the attacker: email the OTP inbox from a personal address with a fake "your code is 999999" message and watch what your pipeline does. If that code reaches your orchestrator, you know exactly which check to add next.

推荐订阅源

DEV Community