From 77d347c3dafbd7543e663ab5e707b11eb8836b08 Mon Sep 17 00:00:00 2001
From: Akshay Shah <akshay@akshayshah.org>
Date: Thu, 11 Jan 2024 14:50:01 -0800
Subject: [PATCH] Add RFC-002: CORS and authn for Go

Add an RFC for creating CORS and authentication packages for users of
Connect in Go.
---
 docs/governance/rfc/002-go-cors-authn.md | 56 ++++++++++++++++++++++++
 docs/governance/rfc/_category_.yml       |  1 +
 2 files changed, 57 insertions(+)
 create mode 100644 docs/governance/rfc/002-go-cors-authn.md
 create mode 100644 docs/governance/rfc/_category_.yml

diff --git a/docs/governance/rfc/002-go-cors-authn.md b/docs/governance/rfc/002-go-cors-authn.md
new file mode 100644
index 00000000..a4be384a
--- /dev/null
+++ b/docs/governance/rfc/002-go-cors-authn.md
@@ -0,0 +1,56 @@
+# 002: CORS and authn for Go
+
+This RFC proposes adding two ancillary Go projects to the Connect Github
+organization:
+
+* `connectrpc.com/cors`, which eases server-side CORS configuration, and
+* `connectrpc.com/authn`, which provides flexible server-side authentication
+  middleware.
+
+## CORS
+
+[Cross-origin resource sharing][cors], commonly called CORS, allows servers to
+indicate whether web browsers should allow scripts to load resources from other
+domains. This is a common concern for single-page web applications, where the
+API and app are often hosted on different origins &mdash; for example,
+`app.acme.com` may need to call APIs hosted on `api.acme.com`. As part of its
+security model, CORS requires servers to allowlist individual request and
+response headers. 
+
+For backend-to-backend communication, the Connect runtime abstracts away
+protocol-specific headers. But to correctly configure header allowlists for
+CORS, server authors must first understand quite a bit of the gRPC, gRPC-Web,
+and Connect protocols. The [resulting configuration][explicit-cors] is verbose
+and difficult to evolve with the underlying protocols.
+
+To make development of browser-facing Connect APIs easier in Go, we propose
+creating a small Go package of CORS helpers. This package will help users
+configure existing CORS packages (for example, [`github.com/rs/cors`][rs-cors]) without
+needing to explicitly list all the HTTP headers used by each RPC protocol.
+
+## Authentication
+
+HTTP servers use a variety of authentication schemes: mutual TLS, cookies,
+and various types of bearer tokens are particularly common. Often, the
+authentication logic also requires some knowledge of the service schema &mdash;
+at least the name of the service and method, but sometimes more detailed
+information too.
+
+In Go, authentication checks are best implemented as `net/http` middleware.
+This approach lets servers reject unauthenticated requests early, before
+spending cycles decompressing and unmarshaling the payload, and it works
+equally well for all authentication schemes. However, experience has shown that
+many users attempt to implement their checks using Connect interceptors, which
+run _after_ decompression and unmarshaling and don't have access to transport
+details like TLS state.
+
+To make it easier for users to secure their servers, we propose creating a Go
+package for authenticating requests. Users will supply the actual
+authentication function, which will have access to both low-level transport
+information and some high-level RPC information. Additionally, it will
+standardize a mechanism for propagating authenticated callers' identity to
+subsequent middlewares, interceptors, and service implementations.
+
+[cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+[explicit-cors]: https://connectrpc.com/docs/cors/#allowing-methods-and-headers
+[rs-cors]: https://github.com/rs/cors
diff --git a/docs/governance/rfc/_category_.yml b/docs/governance/rfc/_category_.yml
new file mode 100644
index 00000000..013895e9
--- /dev/null
+++ b/docs/governance/rfc/_category_.yml
@@ -0,0 +1 @@
+label: "RFCs"