browser
React Client Components
React Server Components
Next.js Route Handlers
Next.js Middleware/Proxy
Edge runtime
Node.js runtime
BFF service
API gateway
origin API service
worker/service worker

secrets
cookies
headers
crypto APIs
network locality
caching behavior
execution time
library compatibility
observability
failure recovery
trust boundary

Do not design React auth around functions.
Design it around runtime authority.

browser: projection, interaction, intent
edge: cheap pre-route classification
server component: request-time rendering and data projection
route handler/server action: mutation boundary and cookie mutation
BFF/node: session authority, token vault, internal calls
origin API: business authorization enforcement
policy engine: final decision logic

// Smell: same name, different authority.
const session = await getSession();

Which runtime is this executing in?
What evidence is it allowed to read?
What secrets can it access?
Can it mutate cookies?
Can it refresh a token?
Can it audit?
Can it enforce authorization?

session projection
current user display name
tenant selection
permission projection
access token in memory for pure SPA mode
CSRF token if cookie auth uses synchronizer/double-submit pattern

client secret
refresh token in persistent storage
policy-engine secret
service account credential
database credential
trustworthy authorization decision
raw policy trace that reveals sensitive graph structure

Should the Save button be shown?
Should the user be redirected to login?
Should the app show an expired session banner?
Should the UI request step-up authentication?

Is this session valid?
Is this token active?
Can this subject perform this action on this resource now?
Is this tenant context valid?
Should this mutation be committed?

export type AuthProjection =
  | { status: "unknown" }
  | { status: "anonymous" }
  | {
      status: "authenticated";
      user: {
        id: string;
        displayName: string;
      };
      tenant?: {
        id: string;
        name: string;
      };
      permissionEpoch: string;
      sessionEpoch: string;
    }
  | {
      status: "degraded";
      reason: "SESSION_CHECK_FAILED" | "PERMISSION_CHECK_FAILED";
    };

refresh token
client secret
raw provider token
privileged claim set
server-only policy trace

redirecting anonymous users away from authenticated route groups
blocking obviously invalid route access
normalizing tenant route shape
adding safe request headers to internal routes
rejecting malformed return URLs
setting cache-control guardrails

refresh token rotation
expensive policy graph traversal
opaque token introspection on every request
complex audit writes
database-heavy authorization
high-cardinality logging
using Node-only auth libraries
calling too many internal services

No session cookie + /app/** route = redirect to login.

JWT claim role=admin + /admin/** route = grant admin authority.

read and write HttpOnly cookies
store OAuth tokens server-side
rotate refresh tokens
hash session IDs
call IdP/token endpoint
call token introspection endpoint
call policy engine
call origin APIs
emit durable audit logs
share a database transaction with auth-relevant writes
perform server-side encryption
use mature Node libraries

Read cookie during server render: often possible.
Set cookie during server render: framework-dependent and often not allowed directly.
Set cookie in route handler/server action: usually correct.
Set cookie in middleware/proxy: possible but should be simple and careful.

Only mutate security-sensitive cookies at explicit response boundaries.

POST /logout
GET /auth/callback
POST /session/refresh
server action with explicit mutation semantics
route handler that returns response

arbitrary shared helper during render
layout render path
client component
background utility imported by both client and server

HttpOnly
Secure
SameSite=Lax or Strict unless cross-site requirements justify None
Path scoped intentionally
Domain avoided unless needed
__Host- prefix when possible
short idle timeout
absolute timeout
server-side revocation
rotation on privilege change

The request contains something that might identify a session.

x-user-id
x-tenant-id
x-session-id
x-auth-epoch
x-request-id
x-impersonator-id
x-permission-epoch

Never trust user-controlled auth headers at the public edge.

const INTERNAL_AUTH_HEADERS = [
  "x-user-id",
  "x-tenant-id",
  "x-session-id",
  "x-auth-epoch",
  "x-impersonator-id",
];

export function stripSpoofableAuthHeaders(headers: Headers): Headers {
  const next = new Headers(headers);

  for (const name of INTERNAL_AUTH_HEADERS) {
    next.delete(name);
  }

  return next;
}

export function attachVerifiedAuthContext(
  headers: Headers,
  context: {
    userId: string;
    tenantId: string;
    sessionId: string;
    authEpoch: string;
  },
): Headers {
  const next = stripSpoofableAuthHeaders(headers);

  next.set("x-user-id", context.userId);
  next.set("x-tenant-id", context.tenantId);
  next.set("x-session-id", context.sessionId);
  next.set("x-auth-epoch", context.authEpoch);

  return next;
}

private network
mTLS or service identity
gateway strips external values
origin rejects requests without trusted gateway identity
logs include request id/session id safely

Does the library use Node Buffer?
Does it use filesystem access?
Does it use crypto.createSign?
Does it depend on process.env at runtime?
Does it use dynamic require?
Does it support Web Crypto subtle APIs?
Does it support the key algorithms your IdP uses?

export interface JwtVerifier {
  verifyAccessToken(token: string): Promise<VerifiedAccessToken>;
}

export type VerifiedAccessToken = {
  subject: string;
  issuer: string;
  audience: string;
  expiresAt: number;
  scopes: string[];
  claims: Record<string, unknown>;
};

node-jwt-verifier.ts
edge-jwt-verifier.ts
browser-token-parser.ts

Browser parser: decode for display/debug hints only.
Server verifier: validate cryptographic signature, issuer, audience, expiry, and policy preconditions.

src/auth/
  shared/
    types.ts
    errors.ts
    permission-contract.ts
  browser/
    auth-store.ts
    use-session.ts
    token-preview.ts
  server/
    require-session.ts
    verify-session.ts
    csrf.ts
  edge/
    classify-route.ts
    redirect-policy.ts
  node/
    token-vault.ts
    refresh-session.ts
    audit.ts

browser-exposed env: public configuration only
edge env: minimal secrets, short dependency chain
node env: confidential credentials, token endpoint credentials, encryption keys
API env: service credentials and policy/backend secrets

issuer URL
client ID for public OAuth client
public app URL
Sentry DSN if designed as public
feature flag client key if designed as public

client secret
private signing key
session encryption key
database URL
token introspection credential
policy service admin key
webhook signing secret

PUBLIC_AUTH_ISSUER_URL
PUBLIC_AUTH_CLIENT_ID
SERVER_SESSION_SECRET
SERVER_TOKEN_ENCRYPTION_KEY
SERVER_IDP_CLIENT_SECRET
EDGE_ROUTE_AUTH_SALT

const forbiddenClientEnvPatterns = [
  /SECRET/i,
  /PRIVATE/i,
  /TOKEN_ENCRYPTION/i,
  /DATABASE/i,
  /WEBHOOK/i,
];

Edge caches redirect after logout.
RSC caches user-specific navigation.
Browser bfcache restores protected page after logout.
Service worker serves stale authenticated API response.
CDN caches `/api/session` without Vary/Cookie controls.
React Query shows previous tenant's data after switch.

Any user-specific auth response must opt out of shared caching unless it is explicitly partitioned by session/tenant and safe to cache.

Cache-Control: no-store
Vary: Cookie, Authorization

no shared CDN cache
explicit dynamic rendering mode where framework requires it
no static generation for session-specific shells
no persisted cache across user/tenant without auth scope key

query key includes user/session/tenant/permission epoch
cache cleared on logout
cache cleared on tenant switch
permission projection invalidated on role/grant/policy change

Edge accepts token that Node rejects.
Browser thinks user has role admin; API denies.
RSC renders tenant nav from old session; client has new tenant.
Route Handler refreshes session; layout still used old snapshot.
Middleware redirects based on cookie presence; session store says revoked.
Node library validates `aud`; edge library forgets `aud`.
Browser decodes expired JWT and shows authenticated UI.

Session projection contract
Permission decision contract
Auth error contract
Route classification contract
Token verification contract
Audit event contract

export type RouteAuthClass =
  | "public"
  | "anonymous_only"
  | "authenticated"
  | "tenant_member"
  | "admin_candidate"
  | "step_up_candidate";

export function classifyPath(pathname: string): RouteAuthClass {
  if (pathname === "/" || pathname.startsWith("/docs")) return "public";
  if (pathname.startsWith("/login")) return "anonymous_only";
  if (pathname.startsWith("/app/admin")) return "admin_candidate";
  if (pathname.startsWith("/app/t/")) return "tenant_member";
  if (pathname.startsWith("/app")) return "authenticated";
  return "public";
}

export function shouldRedirectToLogin(input: {
  routeClass: RouteAuthClass;
  hasSessionCookie: boolean;
}): boolean {
  return (
    !input.hasSessionCookie &&
    ["authenticated", "tenant_member", "admin_candidate", "step_up_candidate"].includes(
      input.routeClass,
    )
  );
}

admin_candidate means: route needs admin-like evaluation later.
It does not mean: edge grants admin access.

valid session
tenant membership
resource access
permission action
workflow state
step-up freshness

token is small
JWKS can be cached safely
only coarse authentication is needed
failure result is redirect/deny
algorithm is supported by edge runtime
latency budget allows it
revocation requirements are weak or handled separately

opaque session cookie maps to server session
refresh may be needed
revocation must be strongly checked
policy engine is involved
logging/audit is required
library requires Node APIs
claims need enrichment from DB

API is independently reachable
zero-trust internal model
multiple clients call API
BFF is not the only caller
business authorization is API-owned

edge: route classification and cookie presence
BFF: session validation and token refresh
API: business authorization enforcement

export type AuthenticatedRequestContext = {
  requestId: string;
  actor: {
    subjectId: string;
    sessionId: string;
    authTime?: string;
    assuranceLevel?: string;
  };
  tenant?: {
    id: string;
    membershipId: string;
  };
  impersonation?: {
    impersonatorId: string;
    reason: string;
  };
  epochs: {
    session: string;
    permission: string;
    policy: string;
  };
};

export type ClientSessionProjection = Pick<
  AuthenticatedRequestContext,
  "tenant" | "epochs"
> & {
  user: {
    id: string;
    displayName: string;
  };
};

Do not let the browser construct `AuthenticatedRequestContext`.

export type AuthBoundaryError =
  | { type: "NO_SESSION"; recovery: "LOGIN" }
  | { type: "INVALID_SESSION"; recovery: "LOGIN" }
  | { type: "EXPIRED_SESSION"; recovery: "REFRESH_OR_LOGIN" }
  | { type: "TENANT_REQUIRED"; recovery: "SELECT_TENANT" }
  | { type: "TENANT_FORBIDDEN"; recovery: "SWITCH_TENANT_OR_REQUEST_ACCESS" }
  | { type: "PERMISSION_DENIED"; recovery: "REQUEST_ACCESS" }
  | { type: "STEP_UP_REQUIRED"; recovery: "REAUTHENTICATE" }
  | { type: "AUTH_SERVICE_DEGRADED"; recovery: "RETRY_OR_READ_ONLY" };

shared auth.ts imports cookies, localStorage, crypto, database, and React hooks.

unknown state renders safe fallback
logout clears query/cache/store state
tenant switch clears tenant-scoped cache
403 mutation rollback works
permission projection stale state fails closed

public routes pass without session cookie
protected routes redirect without session cookie
login route avoids redirect loop
return URL is normalized and internal-only
client-spoofed internal headers are stripped

invalid session cookie rejected
revoked session rejected
refresh rotation handles concurrency
CSRF required for cookie-auth mutation
session projection excludes secrets
logout revokes server state and clears cookie

object-level authorization enforced
tenant mismatch denied
workflow transition permission enforced
internal headers require trusted source
permission decision emits audit event

JWT verifier supports configured algorithm in target runtime
bundle analysis proves server code not shipped to browser
edge function does not import Node-only modules
cookie set/delete behavior works in deployed framework
cache headers are present on auth responses

request_id
session_hash, not raw session id
user_id if allowed by privacy policy
tenant_id
auth_epoch
permission_epoch
route_auth_class
runtime=edge|node|browser|api
error_type
recovery_type

edge redirect rate
edge route classification mismatch
BFF session lookup latency
refresh token rotation conflict rate
API 401/403 rate by endpoint
permission cache invalidation lag
client auth reconciliation failure
RSC hydration auth mismatch

Which runtime can read session evidence?
Which runtime can mutate session cookies?
Which runtime can refresh tokens?
Which runtime can call the policy engine?
Which runtime owns final authorization?
Which runtime owns audit events?
Which data is projected to the browser?
Which headers are trusted, stripped, and reattached?
Which caches are allowed to store auth-sensitive responses?
Which code is guaranteed not to enter the client bundle?

Browser: intent + projection
Edge: route classification + cheap rejection
Server render: safe request-time projection
Route handler/server action: response mutation boundary
BFF/Node: session authority + token vault
Origin API: business authorization enforcement
Policy engine: decision authority
Audit pipeline: evidence authority

Can I call getSession here?

What authority does this runtime have, and what is the safest contract it can return?