Csrf Handler

Author: jknack

docs/asciidoc/handlers.adoc

@@ -6,6 +6,8 @@ include::handlers/access-log.adoc[]
 
 include::handlers/cors.adoc[]
 
+include::handlers/csrf.adoc[]
+
 include::handlers/head.adoc[]
 
 include::handlers/rate-limit.adoc[]

docs/asciidoc/handlers/csrf.adoc

@@ -0,0 +1,38 @@
+=== CsrfHandler
+
+The javadoc:CsrfHandler[text="Cross Site Request Forgery Handler"] helps to protect from (CSRF) 
+attacks. Cross-site request forgeries are a type of malicious exploit whereby unauthorized commands
+are performed on behalf of an authenticated user.
+
+Jooby automatically generates a CSRF "token" for each active user session managed by the 
+application. This token is used to verify that the authenticated user is the one actually making 
+the requests to the application.
+
+Anytime you define an HTML form in your application, you should include a hidden CSRF token 
+field in the form so that the CSRF protection middleware can validate the request
+
+.CSRF
+[source, html]
+----
+<form method="POST" action="...">
+    <input name="csrf" value="{{csrf}}" type="hidden" />
+    ...
+</form>
+----
+
+The `csrf` is a request attribute created by the javadoc:CsrfHandler[] handler and rendered by a
+template engine. Here `{{csrf}}` we use Handlebars template engine (as example).
+
+The javadoc:CsrfHandler[] handler, will automatically verify that the token in the request input 
+matches the token stored in the session.
+
+The token defaults name is `csrf` and can be provided as:
+
+- header
+- cookie
+- form parameter
+
+Configuration methods:
+
+- javadoc:CsrfHandler["setTokenGenerator", java.util.Function]: Set a custom token generator. Defaults uses a random UUID.
+- javadoc:CsrfHandler["setRequestFilter", java.util.Predicate]: Set a custom request filter. Defaults is to process `POST`, `PUT`, `PATCH` and `DELETE`.

jooby/src/main/java/io/jooby/CsrfHandler.java

@@ -0,0 +1,153 @@
+package io.jooby;
+
+import io.jooby.exception.InvalidCsrfToken;
+
+import javax.annotation.Nonnull;
+import java.util.Objects;
+import java.util.UUID;
+import java.util.function.Function;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+/**
+ * <h1>Cross Site Request Forgery handler</h1>
+ *
+ * <pre>
+ * {
+ *   before(new CsrfHandler());
+ * }
+ * </pre>
+ *
+ * <p>
+ * This filter require a token on <code>POST</code>, <code>PUT</code>, <code>PATCH</code> and
+ * <code>DELETE</code> requests. A custom policy might be provided via:
+ * {@link #setRequestFilter(Predicate)}.
+ * </p>
+ *
+ * <p>
+ * Default token generator, use a {@link UUID#randomUUID()}. A custom token generator might be
+ * provided via: {@link #setTokenGenerator(Function)}.
+ * </p>
+ *
+ * <p>
+ * Default token name is: <code>csrf</code>. If you want to use a different name, just pass the name
+ * to the {@link #CsrfHandler(String)} constructor.
+ * </p>
+ *
+ * <h2>Token verification</h2>
+ * <p>
+ * The {@link CsrfHandler} handler will read an existing token from {@link Session} (or created a
+ * new one is necessary) and make available as a request local variable via:
+ * {@link Context#attribute(String, Object)}.
+ * </p>
+ *
+ * <p>
+ * If the incoming request require a token verification, it will extract the token from:
+ * </p>
+ * <ol>
+ * <li>HTTP header</li>
+ * <li>HTTP cookie</li>
+ * <li>HTTP parameter (query or form)</li>
+ * </ol>
+ *
+ * <p>
+ * If the extracted token doesn't match the existing token (from {@link Session}) a <code>403</code>
+ * will be thrown.
+ * </p>
+ *
+ * @author edgar
+ * @since 2.5.2
+ */
+public class CsrfHandler implements Route.Before {
+
+  /**
+   * Default request filter. Requires an existing session and only check for POST, DELETE, PUT and
+   * PATCH methods.
+   */
+  public static final Predicate<Context> DEFAULT_FILTER = ctx -> {
+    return Router.POST.equals(ctx.getMethod())
+        || Router.DELETE.equals(ctx.getMethod())
+        || Router.PATCH.equals(ctx.getMethod())
+        || Router.PUT.equals(ctx.getMethod());
+  };
+
+  /**
+   * UUID token generator.
+   */
+  public static final Function<Context, String> DEFAULT_GENERATOR = ctx -> UUID.randomUUID()
+      .toString();
+
+  private String name;
+
+  private Function<Context, String> generator = DEFAULT_GENERATOR;
+
+  private Predicate<Context> filter = DEFAULT_FILTER;
+
+  /**
+   * Creates a new {@link CsrfHandler} handler and use the given name to save the token in the
+   * {@link Session} and or extract the token from incoming requests.
+   *
+   * @param name Token's name.
+   */
+  public CsrfHandler(String name) {
+    this.name = name;
+  }
+
+  /**
+   * Creates a new {@link CsrfHandler} handler and use the given name to save the token in the
+   * {@link Session} and or extract the token from incoming requests.
+   */
+  public CsrfHandler() {
+    this("csrf");
+  }
+
+  @Override public void apply(@Nonnull Context ctx) throws Exception {
+
+    Session session = ctx.session();
+    String token = session.get(name).toOptional().orElseGet(() -> {
+      String newToken = generator.apply(ctx);
+      session.put(name, newToken);
+      return newToken;
+    });
+
+    ctx.attribute(name, token);
+
+    if (filter.test(ctx)) {
+      String clientToken = Stream.of(
+          ctx.header(name).valueOrNull(),
+          ctx.cookie(name).valueOrNull(),
+          ctx.form(name).valueOrNull(),
+          ctx.query(name).valueOrNull()
+      ).filter(Objects::nonNull)
+          .findFirst()
+          .orElse(null);
+      if (!token.equals(clientToken)) {
+        throw new InvalidCsrfToken(clientToken);
+      }
+    }
+  }
+
+  /**
+   * Set a custom token generator. Default generator use: {@link UUID#randomUUID()}.
+   *
+   * @param generator A custom token generator.
+   * @return This filter.
+   */
+  public @Nonnull CsrfHandler setTokenGenerator(@Nonnull Function<Context, String> generator) {
+    this.generator = generator;
+    return this;
+  }
+
+  /**
+   * Decided whenever or not an incoming request require token verification. Default predicate
+   * requires verification on: <code>POST</code>, <code>PUT</code>, <code>PATCH</code> and
+   * <code>DELETE</code> requests.
+   *
+   * @param filter Predicate to use.
+   * @return This filter.
+   */
+  public @Nonnull CsrfHandler setRequestFilter(@Nonnull Predicate<Context> filter) {
+    this.filter = filter;
+    return this;
+  }
+}

jooby/src/main/java/io/jooby/exception/InvalidCsrfToken.java

@@ -0,0 +1,21 @@
+package io.jooby.exception;
+
+import javax.annotation.Nullable;
+
+/**
+ * Generate by CSRF handler.
+ *
+ * @author edgar
+ * @since 2.5.2
+ */
+public class InvalidCsrfToken extends ForbiddenException {
+
+  /**
+   * Creates a new exception.
+   *
+   * @param token Token or <code>null</code>.
+   */
+  public InvalidCsrfToken(@Nullable String token) {
+    super(token);
+  }
+}

tests/src/test/java/io/jooby/FeaturedTest.java

@@ -16,6 +16,7 @@
 import okhttp3.MediaType;
 import okhttp3.MultipartBody;
 import okhttp3.RequestBody;
+import okhttp3.Response;
 import okhttp3.ResponseBody;
 import org.apache.commons.io.IOUtils;
 import org.junit.jupiter.api.DisplayName;
@@ -51,6 +52,7 @@
 import java.util.Properties;
 import java.util.Scanner;
 import java.util.Set;
+import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.Function;
@@ -2873,6 +2875,50 @@ public void accessLog(ServerTestRunner runner) {
     });
   }
 
+  @ServerTest
+  public void csrf(ServerTestRunner runner) {
+    String token = UUID.randomUUID().toString();
+    runner.define(app -> {
+      app.before(new CsrfHandler().setTokenGenerator(ctx -> token));
+
+      app.post("/form", Context::getRequestPath);
+
+    }).ready(client -> {
+      client.post("/form", new FormBody.Builder()
+          .add("foo", "bar")
+          .build(), rsp -> {
+        assertEquals(StatusCode.FORBIDDEN.value(), rsp.code());
+      });
+
+      client.post("/form", new FormBody.Builder()
+          .add("foo", "bar")
+          .add("csrf", token)
+          .build(), rsp -> {
+        assertEquals(200, rsp.code());
+      });
+
+      client.post("/form?csrf=" + token, new FormBody.Builder()
+          .add("foo", "bar")
+          .build(), rsp -> {
+        assertEquals(200, rsp.code());
+      });
+
+      client.header("csrf", token);
+      client.post("/form", new FormBody.Builder()
+          .add("foo", "bar")
+          .build(), rsp -> {
+        assertEquals(200, rsp.code());
+      });
+
+      client.header("Cookie", "csrf=" + token);
+      client.post("/form", new FormBody.Builder()
+          .add("foo", "bar")
+          .build(), rsp -> {
+        assertEquals(200, rsp.code());
+      });
+    });
+  }
+
   private byte[][] partition(byte[] bytes, int size) {
     List<byte[]> result = new ArrayList<>();
     int offset = 0;
@@ -2920,4 +2966,11 @@ private Map<String, Object> mapOf(String... values) {
     }
     return hash;
   }
+
+  private String sid(Response rsp, String prefix) {
+    String setCookie = rsp.header("Set-Cookie");
+    assertNotNull(setCookie);
+    assertTrue(setCookie.startsWith(prefix));
+    return setCookie.substring(prefix.length(), setCookie.indexOf(";"));
+  }
 }