CIRCLE
Concepts

Security model

The protections built into the SDK, the error policy that keeps details out of responses, and what remains your responsibility.

Built in

ProtectionHow
Tokens stay on the serverThe browser holds an opaque session cookie. SessionUser and /auth/me carry no token, no sid and no timestamps.
Hardened cookiesHttpOnly, Secure, SameSite=Lax, Path=/, and the __Host- prefix on HTTPS so a cookie cannot be set from a sibling subdomain. Lax is required: the provider returns to /auth/callback with a top-level GET. Over http://localhost the Secure flag and the prefix are dropped.
Session ids are hashedThe store key is the SHA-256 of the cookie value, so a leaked store cannot be replayed as cookies.
Sealed handshakestate, nonce, the PKCE verifier and next travel in an AES-256-GCM encrypted cookie that expires after 10 minutes. A tampered, expired or foreign cookie is refused.
PKCE, state and nonceAlways on; the ID token's nonce is checked again after verification.
Verified tokensSignatures are checked against the provider's JWKS with the algorithms the provider declares. none and HMAC never qualify. Issuer, audience and expiry are checked, with clockToleranceSeconds (5 by default).
Same-origin redirectsnext is reduced to a path on your origin. Absolute URLs, //host, backslashes and control characters fall back to defaultRedirect.
URLs on the registered originThe callback URL is rebuilt from redirectUri, and the Fastify adapter builds the Web Request on that origin: the Host header is never trusted.
Cross-site logout refusedPOST /auth/logout answers 403 SES_004 when Origin differs from your origin or Sec-Fetch-Site is neither same-origin nor none. Requests without either header (non-browser clients) carry no ambient cookie and pass.
Logout tokensThe back-channel handler requires a logout+jwt with the logout event, a jti and sid, no nonce, a lifetime of at most 600 seconds, and claims each jti once.
No leaking fetchgateway.fetch refuses any origin other than the gateway's, so the user's token cannot be sent elsewhere. The wallet, machine and gateway helpers refuse HTTP redirects.
Bearer verificationOnly JWT access tokens whose aud contains your audience are accepted. Opaque tokens are refused.

Error policy

Every failure is an AuthAiError with a stable code.

  • message and details carry what a developer needs (a provider's description, a missing scope) and belong in your logs.
  • toPublicJSON() returns only the code and the registry's generic message. Every HTTP response uses it, in the same { "error": { "code", "message" } } envelope as auth-service. Do the same in your own routes.
  • toJSON() includes message and details: use it for logging, never in a response.
import { AuthAiError } from "@circle-rd/auth-ai";

function logAndAnswer(err: unknown, log: (entry: object) => void) {
  if (err instanceof AuthAiError) {
    log({ error: err.toJSON() }); // detailed: for operators
    return { error: err.toPublicJSON() }; // generic: for the user
  }
  throw err;
}

One answer for every sign-in failure

Whatever fails in /auth/callback (a forged state, a rejected code, a wrong client secret, a missing sid, an error=access_denied from the provider), the browser gets the same 403 with SES_005 "Sign-in failed", or a redirect to errorRedirect?error=SES_005. Telling a rejected client secret from a forged state would only help whoever probes the callback. The real cause reaches onError.

Your responsibility

  • Secrets from the environment. The SDK reads none: it takes the client secret and the cookie secret as parameters. Never commit them. The cookie secret must be at least 32 random characters (CFG_001 otherwise).
  • Your own state-changing routes. The SDK enforces the same-origin rule on logout only. Apply an Origin check to your other POST, PUT, PATCH and DELETE routes, as the example app does.
  • Logs. The callback URL carries the authorization code in its query string: do not log query strings.
  • Back-channel route. The endpoint is called by auth-service without cookies or credentials: keep it outside any session or CSRF protection, and reachable over HTTPS.
  • Fastify version. Keep fastify at 5.12.6 or later: several 2026 advisories are fixed there.

To report a vulnerability in the SDK, see SECURITY.md.

Copyright © 2026