Authentication and Identity: Verifying Who Is Talking

Identity Is the Second Line of Defense

In earlier chapters we treated the content of an inbound message as hostile. But there is a prior question that vulnerable assistants never ask: who sent this message in the first place? If your assistant will act on a Slack event, a GitHub comment, or an email webhook, the very first thing it must establish is that the message genuinely came from the party it claims to be from.

A personal AI assistant that reads inbound messages is, by construction, reachable. It has an endpoint, and events arrive there unsolicited. That is fundamentally different from a program that only makes outbound calls: an API is request-response (your code asks, the other system answers), while a webhook is event-driven (the other system pushes an HTTP POST when something happens). Because events arrive on their own, you cannot control when — or, without verification, who — is calling you.

The consequence is blunt: without verification, anyone who guesses your endpoint URL can send fake events. An attacker who discovers the URL can inject forged events — a fake "new email from your boss," a spoofed "payment confirmed," a bogus chat command — and the assistant, holding the operator's credentials and tools, will dutifully act on them. Identity verification is the gate that decides whether a stranger gets to reach for that blast radius at all.

Authentication vs. authorization vs. identity mapping

Three related ideas are constantly confused. Authentication verifies identity — confirming who is making the request. Authorization determines what that authenticated party is permitted to do. A third step sits between them for assistants: identity mapping, translating an external channel identity (a Slack user ID, an email address) into an internal principal your permission system understands.

Threats: spoofing, impersonation, and forged webhooks

The threat that authentication defends against is spoofing — an attacker pretending to be a legitimate source. Webhook endpoints accept HTTP requests from the open internet, so they face spoofing risk. Signature verification ensures only the legitimate provider can trigger your handlers, preventing attackers from injecting fake events such as false login notifications or forged payment confirmations.

Analogy: a webhook endpoint without signature verification is like an office with an unlocked back door and a sign reading "Deliveries — walk right in." Legitimate couriers use it, but so does anyone who wanders by. A signed webhook is that same door with a lock whose key only the real courier company holds. The lock does not care how convincing the visitor looks — it only opens for the key.

Note carefully what is not trustworthy: display names, From: headers, and other easily-forged metadata. An email's From: field and a chat message's display name are attacker-controllable. Impersonation — sending a message that merely claims to be from your boss — is trivial when identity rests on such fields. Real authentication rests on a cryptographic proof the attacker cannot produce.

Verifying Webhook Signatures

The standard mechanism providers use to prove a webhook is authentic is the HMAC signature. HMAC (Hash-based Message Authentication Code) combines the message with a shared secret — a key known only to the provider and your server — and runs both through a hash function such as SHA-256 to produce a fixed-size tag. The provider computes this tag over the request body and sends it in a header; your server, holding the same secret, recomputes it and checks that they match.

The security property that makes this work: the HMAC signature is tied to the specific payload — change one byte in the body and the signature is invalid; an attacker would need the shared secret to forge a valid one, and the secret never leaves your server. Because HMAC is symmetric, anyone with the secret can forge a valid signature, so the secret must be protected like any other credential.

Every HMAC-SHA256 webhook verifier follows the same four steps:

1. Read the RAW request body in bytes, not parsed JSON.
2. Compute HMAC-SHA256(body, secret) to produce 32 bytes.
3. Hex-encode or base64-encode the 32 bytes to match the provider's format.
4. Compare to the signature header using constant-time comparison.

Why the raw body matters. This is the single most frequent verification bug. Always compute the HMAC over the raw body exactly as received; never compute HMAC against re-parsed/re-serialized JSON, because parsing and re-serialization can introduce subtle differences in whitespace, key ordering, or encoding that invalidate the signature. For example, Express's body-parser rebuilds the JSON, then your HMAC computes against the rebuilt string — which differs by even one whitespace character from the original. Capture the body as bytes before any JSON middleware runs:

• Node.js: express.raw({ type: "application/json" }) captures the body as a Buffer.
• Python: await request.body() (FastAPI) or request.get_data() (Flask).
• Ruby: request.raw_post before Rails deserializes.

Encoding and header quirks vary by provider. Most providers (Stripe, GitHub, Slack) use hexadecimal encoding, while Shopify and Square use base64; changing .digest('hex') to .digest('base64') (or the reverse) is a common copy-paste bug.

A worked example: verifying a GitHub-style HMAC-SHA256 signature

Suppose GitHub delivers a webhook. It sends the header X-Hub-Signature-256: sha256=<hex>, computed as HMAC-SHA256 over the exact bytes of the request body using your configured secret. Here is a correct Python verifier, with the security-critical points annotated:

import hmac, hashlib

def verify_github_signature(raw_body: bytes, header_value: str, secret: str) -> bool:
    # header_value looks like "sha256=abc123..." — strip the scheme prefix.
    if not header_value or not header_value.startswith("sha256="):
        return False
    sent_sig = header_value.split("=", 1)[1]

    # Step 2: HMAC over the RAW body bytes (never re-serialized JSON).
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,               # bytes exactly as received
        hashlib.sha256,
    ).hexdigest()               # Step 3: hex to match GitHub's format

    # Step 4: constant-time comparison — NOT ==
    return hmac.compare_digest(expected, sent_sig)

This mirrors the recommended sketch: hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() compared with hmac.compare_digest(). The Node.js equivalent uses crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex') to produce the expected signature, then crypto.timingSafeEqual() on Buffer versions of the two signatures.

Timing-safe comparison and constant-time verification

Step 4 deserves its own explanation. You must use a constant-time compare, never a plain === / ==. A regular string comparison returns false at the first mismatched byte, allowing an attacker to measure response times and guess the signature one byte at a time. A constant-time comparison always takes the same time regardless of where the mismatch occurs, defeating this attack.

Analogy: imagine a combination lock that clicks audibly the instant a wrong digit is entered. An attacker turns the first dial, listens for the click, and knows when the first digit is right because the click comes later. Digit by digit, they open the lock without ever knowing the whole combination. An ordinary == on strings behaves like that clicking lock. A constant-time comparison examines every byte regardless, so the timing reveals nothing.

Two practical notes. First, crypto.timingSafeEqual() requires Buffers of equal length and throws otherwise, so guard the lengths first. Second, wherever a provider ships an official SDK, prefer it: never hand-roll HMAC verification when an official SDK exists. The SDK already handles encoding, header parsing, constant-time comparison, and replay protection.

Timestamp checks and nonce/replay protection

Signature verification proves a request is authentic and untampered. It does not prove the request is fresh. Pure HMAC signature verification has a gap: an attacker who captures a legitimate, correctly-signed request can simply re-send ("replay") it, and signature verification alone will accept it because the signature is genuine. This is a replay attack, and closing it is a separate, required layer.

Analogy: a signed webhook is like a check with a valid signature. The signature proves you wrote it — but nothing stops someone who intercepts the check from cashing the same check twice. Replay protection is the "void after 5 minutes" stamp and the running list of check numbers you have already cashed.

There are three complementary defenses:

• Signed timestamp + tolerance window. The provider includes a timestamp inside the signed payload, so it cannot be altered without breaking the signature. The consumer checks it falls within an acceptable window (typically 3–5 minutes) of current server time. This is Stripe's scheme: it signs the payload as timestamp.body and rejects anything older than five minutes.
• Nonces (one-time identifiers). Some providers include a unique nonce or notification ID with each delivery. By storing which nonces you have processed and rejecting reuse, you catch replays even within the tolerance window.
• Idempotency (the primary defense). Make the endpoint idempotent by tracking processed webhook IDs and skipping duplicates. A replayed webhook is then processed only once, and this also handles legitimate provider retries.

Two operational prerequisites make timestamp checks work: consumer and provider clocks must be synchronized (use NTP), and both parties must use the same timestamp format (UNIX epoch vs. RFC 3339). Beware that timestamp validation can conflict with provider retries after the tolerance window — tune the tolerance or rely on idempotency as the primary protection. Extending the earlier example with a timestamp check:

import time

MAX_AGE_SECONDS = 300  # 5-minute tolerance

def verify_with_replay_protection(raw_body, timestamp_str, sent_sig, secret, seen_ids, event_id):
    # 1. Freshness: reject stale requests.
    try:
        ts = int(timestamp_str)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > MAX_AGE_SECONDS:
        return False

    # 2. Sign timestamp.body so the timestamp cannot be forged.
    signed_payload = timestamp_str.encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sent_sig):
        return False

    # 3. Idempotency / nonce: reject already-seen deliveries.
    if event_id in seen_ids:
        return False
    seen_ids.add(event_id)
    return True

The layered minimum is HTTPS + HMAC signatures + timestamp validation, rejecting requests older than your tolerance threshold.

Common Authentication Pitfalls

Skipping verification in development and shipping it to production

The most common way an assistant ships without authentication is that verification was turned off for convenience during development and never turned back on. Signature checks are annoying while iterating: you have to craft valid signatures for test payloads, keep clocks in sync, and juggle secrets. So developers add an if DEBUG: skip_verification() branch, or comment out the check, and the guardrail quietly evaporates by the time the code reaches production.

The fix is to make verification the default path, not an opt-in. Verification should be structurally impossible to bypass in production: fail closed (reject when a signature is missing or unverifiable rather than allowing through), and never gate the check behind an environment flag that could be misconfigured. If you need a local testing shortcut, use the provider's own tooling to generate genuinely-signed test events rather than disabling the check. The layered minimum — HTTPS + HMAC + timestamp validation — is the baseline for every environment that is reachable, not a production-only feature.

Trusting easily-forged headers and display names

A second class of failure is authenticating on the wrong thing. Signature verification exists precisely because the visible content of a request is forgeable: an attacker would need the shared secret to forge a valid signature — meaning anything not covered by the signature is fair game. A From: email header, a chat display name, a custom X-User-Id header, or a "verified" flag in the JSON body all travel with the request and can be set to anything. Trusting them is identity theater.

The rule is: only trust fields that are inside the signed payload, verified against the shared secret. The signature covers the raw body, so a sender_id inside that body — for a genuine, signature-passing request — is trustworthy; an arbitrary HTTP header outside the signed content is not. Concretely, do not let the assistant decide "this is from the operator, grant full access" based on a display name any sender can type. Establish the sender's identity from signed, provider-attested fields, then map that identity to a principal via allowlist mechanisms. Note too that the same HMAC signature that authenticates the source can carry an API key to identify which tenant the webhook belongs to for routing — but routing metadata is not the same as an authorization decision.

Leaking or hardcoding signing secrets

Because HMAC is symmetric, the shared secret is the ability to forge valid requests. Anyone who obtains it can impersonate the provider perfectly — the signatures they produce will verify. The safety of the whole scheme rests on the fact that the secret never leaves your server. The common ways that promise gets broken:

• Hardcoding the secret in source and committing it to version control, where it lives in git history forever even after removal.
• Logging the secret — or logging full request headers/bodies that contain it — into log aggregators many people can read.
• Baking it into a container image or client-side bundle, shipping it to anywhere the artifact is distributed.

The remedy is the discipline of secrets management: inject signing secrets at runtime from environment variables or a secret manager, never commit them, scan for accidental leaks, and rotate them if exposure is suspected. A leaked signing secret defeats every control in this chapter at once — the attacker's forged requests will pass signature verification, freshness checks, and nonce checks, because to your server they are indistinguishable from the real provider. Treat the signing secret as a crown-jewel credential.