Security boundaries

What Wamen proves

• A WhatsApp identity sent the exact unedited, short-lived authorization message.
• The returned subject is stable for that Wamen principal and pairwise to the requesting full origin.
• An optional phone number was freshly disclosed for this login when the user consented to the phone scope.

What Wamen does not provide

• No name, picture, email, password, access token, refresh token, authorization role, or durable Wamen session.
• No guarantee that a phone number remains assigned to the same person forever.
• No official Meta or WhatsApp affiliation.
• No SLA. The skateboard uses one unofficial WhatsApp connection.

Browser boundary

The hosted module creates 256-bit random state and PKCE verifier values, uses S256, validates the callback location and state, exchanges the one-time code, and limits return paths to the same origin.

The resulting token is temporarily stored in localStorage. Treat any browser-readable token as exposed to cross-site scripting. Post it once to the backend and clear it.

Server boundary

Verify the signature and every required claim. The exact audience prevents one application from accepting a token issued for another origin. The pairwise subject prevents unrelated applications from receiving the same Wamen identifier.

Session boundary

After verification, create an opaque session owned by your application. Use Secure, HttpOnly, SameSite cookies, rotate session identifiers at authentication, enforce your own expiry, and delete the session on logout.

Operational boundary

• Transactions expire after three minutes.
• Identity tokens expire after ten minutes.
• A WhatsApp disconnect stops new transactions and makes readiness fail.
• Wamen fails closed. It does not fall back to phone-number identity, email, or SMS.
• Raw LIDs, phone numbers, messages, authorization codes, and tokens must not enter application logs.