diff --git a/rfcs/0000-well-known-attributes.md b/rfcs/0000-well-known-attributes.md
new file mode 100644
index 00000000..81439e51
--- /dev/null
+++ b/rfcs/0000-well-known-attributes.md
@@ -0,0 +1,725 @@
+# Well-known Attributes
+
+- Feature Name: `well-known-attributes`
+- Start Date: 2023-06-13
+- RFC PR: [Kuadrant/architecture#0000](https://github.com/Kuadrant/architecture/pull/0000)
+- Issue tracking: [Kuadrant/architecture#0000](https://github.com/Kuadrant/architecture/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Define a well-known structure for users to declare request data selectors in their RateLimitPolicies and AuthPolicies. This structure is referred to as the Kuadrant _Well-known Attributes_.
+
+# Motivation
+[motivation]: #motivation
+
+The well-known attributes let users write policy rules – conditions and, in general, dynamic values that refer to attributes in the data plane - in a concise and seamless way.
+
+Decoupled from the policy CRDs, the well-known attributes:
+1. define a common language for referring to values of the data plane in the Kuadrant policies;
+2. allow dynamically evolving the policy APIs regarding how they admit references to data plane attributes;
+3. encompass all common and component-specific selectors for data plane attributes;
+4. have a single and unified specification, although this specification may occasionally link to additional, component-specific, external docs.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+One who writes a Kuadrant policy and wants to build policy constructs such as conditions, qualifiers, variables, etc, based on dynamic values of the data plane, must refer the attributes that carry those values, using the declarative language of Kuadrant's _Well-known Attributes_.
+
+A dynamic data plane value is typically a value of an attribute of the request or an [Envoy Dynamic Metadata](https://www.envoyproxy.io/docs/envoy/latest/configuration/advanced/well_known_dynamic_metadata) entry. It can be a value of the outer request being handled by the API gatway or proxy that is managed by Kuadrant ("context request") or an attribute of the direct request to the Kuadrant component that delivers the functionality in the data plane (rate-limiting or external auth).
+
+A _Well-known Selector_ is a construct of a policy API whose value contains a direct reference to a well-known attribute. The language of the well-known attributes and therefore what one would declare within a well-known selector resembles a JSON path for navigating a possibly complex JSON object.
+
+**Example 1.** Well-known selector used in a condition
+
+```yaml
+apiGroup: examples.kuadrant.io
+kind: PaintPolicy
+spec:
+ rules:
+ - when:
+ - selector: auth.identity.group
+ operator: eq
+ value: admin
+ color: red
+```
+
+In the example, `auth.identity.group` is a well-known selector of an attribute `group`, known to be injected by the external authorization service (`auth`) to describe the group the user (`identity`) belongs to. In the data plane, whenever this value is equal to `admin`, the abstract `PaintPolicy` policy states that the traffic must be painted `red`.
+
+**Example 2.** Well-known selector used in a variable
+
+```yaml
+apiGroup: examples.kuadrant.io
+kind: PaintPolicy
+spec:
+ rules:
+ - color: red
+ alpha:
+ dynamic: request.headers.x-color-alpha
+```
+
+In the example, `request.headers.x-color-alpha` is a selector of a well-known attribute `request.headers` that gives access to the headers of the context HTTP request. The selector retrieves the value of the `x-color-alpha` request header to dynamically fill the `alpha` property of the abstract `PaintPolicy` policy at each request.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+The _Well-known Attributes_ are a compilation inspired by some of the [**Envoy attributes**](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/attributes) and Authorino's [**Authorization JSON**](https://github.com/Kuadrant/authorino/blob/main/docs/architecture.md#the-authorization-json) and its related [JSON paths](https://github.com/Kuadrant/authorino/blob/main/docs/features.md#common-feature-json-paths-valuefromauthjson).
+
+From the Envoy attributes, only attributes that are available before establishing connection with the upstream server qualify as a Kuadrant well-known attribute. This excludes attributes such as the response attributes and the upstream attributes.
+
+As for the attributes inherited from Authorino, these are either based on Envoy's [`AttributeContext`](https://pkg.go.dev/github.com/envoyproxy/go-control-plane/envoy/service/auth/v3?utm_source=gopls#AttributeContext) type of the external auth request API or from internal types defined by Authorino to fulfill the [Auth Pipeline](https://github.com/Kuadrant/authorino/blob/main/docs/architecture.md#the-auth-pipeline-aka-enforcing-protection-in-request-time).
+
+These two subsets of attributes are unified into a single set of well-known attributes. For each attribute that exists in both subsets, the name of the attribute as specified in the Envoy attributes subset prevails. Example of such is `request.id` (to refer to the ID of the request) superseding `context.request.http.id` (as the same attribute is referred in an Authorino [`AuthConfig`](https://github.com/Kuadrant/authorino/blob/main/docs/architecture.md#the-authorino-authconfig-custom-resource-definition-crd)).
+
+
+
+The next sections specify the well-known attributes organized in the following groups:
+- [Request attributes](#request-attributes)
+- [Connection attributes](#connection-attributes)
+- [Metadata and filter state attributes](#metadata-and-filter-state-attributes)
+- [Auth attributes](#auth-attributes)
+- [Rate-limit attributes](#rate-limit-attributes)
+
+## Request attributes
+
+The following attributes are related to the context HTTP request that is handled by the API gateway or proxy managed by Kuadrant.
+
+
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
request.id |
+ String |
+ Request ID corresponding to |
+ ✓ |
+ ✓ |
+
request.time |
+ Timestamp |
+ Time of the first byte received |
+ ✓ |
+ ✓ |
+
request.protocol |
+ String |
+ Request protocol (“HTTP/1.0”, “HTTP/1.1”, “HTTP/2”, or “HTTP/3”) |
+ ✓ |
+ ✓ |
+
request.scheme |
+ String |
+ The scheme portion of the URL e.g. “http” |
+ ✓ |
+ ✓ |
+
request.host |
+ String |
+ The host portion of the URL |
+ ✓ |
+ ✓ |
+
request.method |
+ String |
+ Request method e.g. “GET” |
+ ✓ |
+ ✓ |
+
request.path |
+ String |
+ The path portion of the URL |
+ ✓ |
+ ✓ |
+
request.url_path |
+ String |
+ The path portion of the URL without the query string |
+ + | ✓ |
+
request.query |
+ String |
+ The query portion of the URL in the format of “name1=value1&name2=value2” |
+ ✓ |
+ ✓ |
+
request.headers |
+ Map<String, String> |
+ All request headers indexed by the lower-cased header name |
+ ✓ |
+ ✓ |
+
request.referer |
+ String |
+ Referer request header |
+ + | ✓ |
+
request.useragent |
+ String |
+ User agent request header |
+ + | ✓ |
+
request.size |
+ Number |
+ The HTTP request size in bytes. If unknown, it must be -1 |
+ ✓ |
+ + |
request.body |
+ String |
+ The HTTP request body. (Disabled by default. Requires additional proxy configuration to enabled it.) |
+ ✓ |
+ + |
request.raw_body |
+ Array<Number> |
+ The HTTP request body in bytes. This is sometimes used instead of |
+ ✓ |
+ + |
request.context_extensions |
+ Map<String, String> |
+ This is analogous to |
+ ✓ |
+ + |
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
source.address |
+ String |
+ Downstream connection remote address |
+ ✓ |
+ ✓ |
+
source.port |
+ Number |
+ Downstream connection remote port |
+ ✓ |
+ ✓ |
+
source.service |
+ String |
+ The canonical service name of the peer |
+ ✓ |
+ + |
source.labels |
+ Map<String, String> |
+ The labels associated with the peer. These could be pod labels for Kubernetes or tags for VMs. The source of the labels could be an X.509 certificate or other configuration. |
+ ✓ |
+ + |
source.principal |
+ String |
+ The authenticated identity of this peer. If an X.509 certificate is used to assert the identity in the proxy, this field is sourced from “URI Subject Alternative Names“, “DNS Subject Alternate Names“ or “Subject“ in that order. The format is issuer specific – e.g. SPIFFE format is |
+ ✓ |
+ + |
source.certificate |
+ String |
+ The X.509 certificate used to authenticate the identify of this peer. When present, the certificate contents are encoded in URL and PEM format. |
+ ✓ |
+ + |
destination.address |
+ String |
+ Downstream connection local address |
+ ✓ |
+ ✓ |
+
destination.port |
+ Number |
+ Downstream connection local port |
+ ✓ |
+ ✓ |
+
destination.service |
+ String |
+ The canonical service name of the peer |
+ ✓ |
+ + |
destination.labels |
+ Map<String, String> |
+ The labels associated with the peer. These could be pod labels for Kubernetes or tags for VMs. The source of the labels could be an X.509 certificate or other configuration. |
+ ✓ |
+ + |
destination.principal |
+ String |
+ The authenticated identity of this peer. If an X.509 certificate is used to assert the identity in the proxy, this field is sourced from “URI Subject Alternative Names“, “DNS Subject Alternate Names“ or “Subject“ in that order. The format is issuer specific – e.g. SPIFFE format is |
+ ✓ |
+ + |
destination.certificate |
+ String |
+ The X.509 certificate used to authenticate the identify of this peer. When present, the certificate contents are encoded in URL and PEM format. |
+ ✓ |
+ + |
connection.id |
+ Number |
+ Downstream connection ID |
+ + | ✓ |
+
connection.mtls |
+ Boolean |
+ Indicates whether TLS is applied to the downstream connection and the peer ceritificate is presented |
+ + | ✓ |
+
connection.requested_server_name |
+ String |
+ Requested server name in the downstream TLS connection |
+ + | ✓ |
+
connection.tls_session.sni |
+ String |
+ SNI used for TLS session |
+ ✓ |
+ + |
connection.tls_version |
+ String |
+ TLS version of the downstream TLS connection |
+ + | ✓ |
+
connection.subject_local_certificate |
+ String |
+ The subject field of the local certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.subject_peer_certificate |
+ String |
+ The subject field of the peer certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.dns_san_local_certificate |
+ String |
+ The first DNS entry in the SAN field of the local certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.dns_san_peer_certificate |
+ String |
+ The first DNS entry in the SAN field of the peer certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.uri_san_local_certificate |
+ String |
+ The first URI entry in the SAN field of the local certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.uri_san_peer_certificate |
+ String |
+ The first URI entry in the SAN field of the peer certificate in the downstream TLS connection |
+ + | ✓ |
+
connection.sha256_peer_certificate_digest |
+ String | +SHA256 digest of the peer certificate in the downstream TLS connection if present |
+ + | ✓ |
+
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
metadata |
+ + | Dynamic request metadata |
+ ✓ |
+ ✓ |
+
filter_state |
+ Map<String, String> |
+ Mapping from a filter state name to its serialized string value |
+ + | ✓ |
+
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
auth.identity |
+ Any |
+ Single resolved identity object, post-identity verification |
+ ✓ |
+ + |
auth.metadata |
+ Map<String, Any> |
+ External metadata fetched |
+ ✓ |
+ + |
auth.authorization |
+ Map<String, Any> |
+ Authorization results resolved by each authorization rule, access granted only |
+ ✓ |
+ + |
auth.response |
+ Map<String, Any> |
+ Response objects exported by the auth service post-access granted |
+ ✓ |
+ + |
auth.callbacks |
+ Map<String, Any> |
+ Response objects returned by the callback requests issued by the auth service |
+ ✓ |
+ + |
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
ratelimit.domain |
+ String |
+ The rate limit domain. This enables the configuration to be namespaced per application (multi-tenancy). |
+ + | ✓ |
+
ratelimit.hits_addend |
+ Number |
+ Specifies the number of hits a request adds to the matched limit. Fixed value: `1`. Reserved for future usage. |
+ + | ✓ |
+
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
wasm.plugin_name |
+ String |
+ Plugin name |
+ + | ✓ |
+
wasm.plugin_root_id |
+ String |
+ Plugin root ID |
+ + | ✓ |
+
wasm.plugin_vm_id |
+ String |
+ Plugin VM ID |
+ + | ✓ |
+
wasm.node |
+ + | Local node description |
+ + | ✓ |
+
wasm.cluster_name |
+ String |
+ Upstream cluster name |
+ + | ✓ |
+
wasm.cluster_metadata |
+ + | Upstream cluster metadata |
+ + | ✓ |
+
wasm.listener_direction |
+ Number |
+ Enumeration value of the listener traffic direction |
+ + | ✓ |
+
wasm.listener_metadata |
+ + | Listener metadata |
+ + | ✓ |
+
wasm.route_name |
+ String |
+ Route name |
+ + | ✓ |
+
wasm.route_metadata |
+ + | Route metadata |
+ + | ✓ |
+
wasm.upstream_host_metadata |
+ + | Upstream host metadata |
+ + | ✓ |
+
Attribute |
+ Type |
+ Description |
+ Auth |
+ RL |
+
---|---|---|---|---|
xds.cluster_name |
+ String |
+ Upstream cluster name |
+ + | ✓ |
+
xds.cluster_metadata |
+ + | Upstream cluster metadata |
+ + | ✓ |
+
xds.route_name |
+ String |
+ Route name |
+ + | ✓ |
+
xds.route_metadata |
+ + | Route metadata |
+ + | ✓ |
+
xds.upstream_host_metadata |
+ + | Upstream host metadata |
+ + | ✓ |
+
xds.filter_chain_name |
+ String |
+ Listener filter chain name |
+ + | ✓ |
+