Authentication Flow

Before You Change Anything

Security pages describe boundaries that protect shared systems and user data. Validate the boundary you are changing before you test or modify anything.

Crawbl supports two authentication paths, and they are mutually exclusive per request.

In plain language, this page answers two questions:

1. how does a request prove who the user is?
2. which layer rejects the request if that proof is wrong?

Understanding which path applies and where validation happens is essential for debugging auth issues and adding new clients.

Two Auth Paths

Click diagram to zoom

HMAC (Mobile App)

This is the primary path for the Flutter mobile app. The client sends a Firebase ID token in X-Token plus device-bound HMAC headers on every request.

You can read this as a two-part check:

• the token says who the user is
• the HMAC headers prove the request came from a client that knows the shared signing secret

1

Step 1

Send the mobile headers

The app sends X-Token, X-Timestamp, X-Signature, X-Device-Info, and X-Version.

2

Step 2

Validate the HMAC

At the Envoy edge, the WASM filter checks that the timestamp is fresh and the HMAC signature matches.

3

Step 3

Validate the Firebase token

Envoy's SecurityPolicy validates the Firebase JWT from the same X-Token header.

4

Step 4

Forward trusted identity

If both checks succeed, Envoy forwards trusted X-Firebase-* headers to the orchestrator.

5

Step 5

Resolve the user

The orchestrator reads those trusted headers and looks up the user record.

When to use it: Mobile clients and any client that can securely store a Firebase token and compute HMAC-SHA256 signatures.

JWT (Standard Clients)

This path uses a standard Firebase ID token in the Authorization header.

This is the simpler path. It is what most backend tools, scripts, or non-mobile clients should use.

1

Step 1

Send a bearer token

The client sends Authorization: Bearer <firebase-id-token>.

2

Step 2

Validate it at the edge

Envoy's SecurityPolicy validates the token against Firebase's JWKS endpoint.

3

Step 3

Forward the decoded identity

If the token is valid, Envoy forwards the trusted X-Firebase-* headers.

4

Step 4

Attach the principal

The orchestrator reads those headers and turns them into the request principal used by backend code.

When to use it: Web dashboards, backend-to-backend calls, CLI tools, and other clients that already use standard Bearer tokens.

Mutual Exclusivity

A single request uses one path or the other, never both. The WASM filter checks for the presence of an X-Token header:

• If X-Token is present, the filter enforces HMAC validation and the JWT is validated from X-Token
• If X-Token is absent, the request follows the standard Authorization: Bearer path

This means there is no ambiguity about which path applies.

Where Validation Happens

Check	Where	What Happens on Failure
HMAC signature	Envoy WASM filter (edge)	401/403 before reaching backend
Firebase JWT in X-Token or Authorization	Envoy SecurityPolicy (edge)	401 before reaching backend
Identity header extraction	Orchestrator middleware	401 from backend

The key insight is that both paths reject invalid requests at the edge. The orchestrator never sees unauthenticated traffic in production. The backend auth middleware only reads trusted headers forwarded by Envoy.

Adding A New Client

If you are building a new client, choose the auth path based on the headers it can send:

• Mobile-like clients that can compute HMAC and send X-Token should use the HMAC path
• Standard clients that already use Bearer tokens should use the JWT path

Both paths end up at the same orchestrator middleware, which attaches a Principal to the request context. From there, downstream code works the same way regardless of how the user authenticated.

Future: OAuth Integration Flow

When third-party app connections (Gmail, Slack, Calendar) ship, this is how OAuth will work:

Click diagram to zoom

Key design decisions:

• Mobile uses flutter_appauth for the OAuth flow with PKCE
• Tokens are stored server-side; agents do not receive raw provider credentials
• MCP tools call external APIs using stored tokens on the user's behalf
• Planned providers include Slack, Gmail, Calendar, Jira, Asana, Notion, Zoom, and GitHub

What's Next

Edge-side device signature validation is handled by a dedicated auth filter that runs at the ingress layer.