Authentication + Security

Implement signup/login, JWT issuance, and route protection in a production-friendly way.

Signup + Login Flow

What is a JWT? A JSON Web Token (JWT) is a securely signed string that the server generates upon successful login. The client stores this token and sends it back in the Authorization: Bearer <token> header with every subsequent request to prove their identity statelessly.

auth-routes
1import io.github.jhanvi857.nioflow.auth.PasswordHasher;
2import io.github.jhanvi857.nioflow.auth.JwtProvider;
3
4app.post("/api/auth/signup", ctx -> {
5    SignupRequest req = ctx.body(SignupRequest.class);
6    String hash = PasswordHasher.hash(req.getPassword());
7    // save user + hash into repository
8    ctx.status(201).json(java.util.Map.of("message", "user created"));
9});
10
11app.post("/api/auth/login", ctx -> {
12    LoginRequest req = ctx.body(LoginRequest.class);
13    boolean ok = PasswordHasher.verify(req.getPassword(), storedHash);
14    if (!ok) {
15        ctx.status(401).json(java.util.Map.of("error", "Invalid credentials"));
16        return;
17    }
18    String token = JwtProvider.generateToken(userEmail, "USER");
19    ctx.status(200).json(java.util.Map.of("token", token));
20});

Protect Route Groups

protected-routes
1app.group("/api/tasks", tasks -> {
2    tasks.use(new io.github.jhanvi857.nioflow.middleware.AuthMiddleware());
3
4    tasks.get("/", taskController::list).rateLimit(30, 10_000);
5    tasks.post("/", taskController::create);
6    tasks.get("/:id", ctx -> {
7        long id = ctx.pathParamAsLong("id"); // Type-safe parameter extraction
8        // ...
9    });
10});

JWT Hardening (v1.4.0)

NioFlow v1.4.0 implements several enterprise-grade security controls for JWT issuance and validation:

  • Issuer Pinning: All tokens are pinned to the nioflow issuer. Validation fails if the iss claim is missing or mismatched.
  • Entropy Enforcement: The framework validates the Shannon entropy of your JWT_SECRET at startup to prevent weak keys.
  • Short-lived Tokens: Default expiration is reduced to 15 minutes (configurable via NIOFLOW_JWT_EXPIRATION_MS).
  • Replay Protection: Every token includes a unique jti (JWT ID) claim.

Security Baseline

CRITICAL: Never disable auth in production

The NIOFLOW_DISABLE_AUTH=true flag is for development only. As of v1.4.0, the framework will refuse to start with this flag enabled unless bound to a loopback address (127.0.0.1/localhost).

env-security
1JWT_SECRET=replace-with-32-plus-char-secret
2NIOFLOW_CORS_ORIGIN=https://your-frontend.app
3NIOFLOW_ENABLE_DB=false
4NIOFLOW_CHAOS_ENABLED=false
5NIOFLOW_REPLAY_ENABLED=false
6NIOFLOW_EXPOSE_ERROR_DETAILS=false

Error Handling Policy

global-errors
1app.exception(IllegalArgumentException.class, (e, ctx) -> {
2    ctx.status(400).json(java.util.Map.of("error", "Bad Request"));
3});
4
5app.onError((err, ctx) -> {
6    ctx.status(500).json(java.util.Map.of("error", "Internal Server Error"));
7});

HTTP Parser Hardening

The internal parser includes active defenses against common web vulnerabilities:

  • CRLF Injection: Header values containing carriage return or line feed characters are rejected with a 400 Bad Request.
  • Null Byte Defense: Null bytes (\x00) are prohibited in request paths and headers.
  • Request Smuggling: Obfuscated Transfer-Encoding headers (e.g., identity, chunked) are detected and rejected.
PreviousRouting + FrontendNextDatabase + Env