contrib: add first draft of ACL docs

contributing/INTERNALS.md

@@ -36,7 +36,6 @@ There are several other top-level packages used internally by Consul as well as
 
 | Directory | Contents |
 | --------- | -------- |
-| [acl](https://github.com/hashicorp/consul/tree/main/api) | This supports the underlying policy engine for Consul's [ACL](https://www.consul.io/docs/guides/acl.html) system. |
 | [api](https://github.com/hashicorp/consul/tree/main/api) | This `api` package provides an official Go API client for Consul, which is also used by Consul's [CLI](https://www.consul.io/docs/commands/index.html) commands to communicate with the local Consul agent. |
 | [api/watch](https://github.com/hashicorp/consul/tree/main/api/watch) | This has implementation details for Consul's [watches](https://www.consul.io/docs/agent/watches.html), used both internally to Consul and by the [watch CLI command](https://www.consul.io/docs/commands/watch.html). |
 | [website](https://github.com/hashicorp/consul/tree/main/website) | This has the full source code for [consul.io](https://www.consul.io/). Pull requests can update the source code and Consul's documentation all together. |

contributing/acl/README.md

@@ -0,0 +1,35 @@
+# ACL
+
+This section is a work in progress.
+
+The ACL subsystem is responsible for authenticating and authorizing access to Consul
+operations ([HTTP API], and [RPC]). 
+
+[HTTP API]: ../http-api
+[RPC]: ../rpc
+
+## ACL Entities
+
+There are many entities in the ACL subsystem. The diagram below shows the relationship
+between the entities.
+
+![Entity Relationship Diagram](./erd.svg)
+
+<sup>[source](./erd.mmd)</sup>
+
+ACL Tokens are at the center of the ACL system. Tokens are associated with a set of
+Policies, and Roles.
+
+AuthMethods, which consist of BindingRules, are a mechanism for creating ACL Tokens from
+policies stored in external systems (ex: kubernetes, JWT, or OIDC).
+
+Roles are a set of policies associated with a named role, and ServiceIdentity and
+NodeIdentity are policy templates that are associated with a specific service or node and
+can be rendered into a full policy.
+
+Each Policy contains a set of rules. Each rule relates to a specific resource, and
+includes an AccessLevel (read, write, list or deny).
+
+An ACL Token can be resolved into an Authorizer. The Authorizer is what is used by the
+[HTTP API], and [RPC] endpoints to determine if an operation is allowed or forbidden (the
+enforcement decision).

contributing/acl/erd.mmd

@@ -7,9 +7,10 @@ erDiagram
     NodeIdentity
     AuthMethod
     BindingRule
-    Rule
-    // TODO: rules are made up of resources and x (enforcement decision or permission?)
-    // TODO: add Authorizer and Enforcement Decision
+    Rule {
+        string Resource
+        enum AccessLevel
+    }
 
     Policy ||--|{ Rule: grants
     Role ||--|{ Policy: includes
@@ -26,3 +27,7 @@ erDiagram
 
     ServiceIdentity ||--|{ Rule: implies
     NodeIdentity ||--|{ Rule: implies
+
+    Token ||--|| Authorizer: "resolves to"
+    Authorizer ||--|{ EnforcementDecision: produces
+

contributing/consul-mermaid-theme.json

@@ -1,4 +1,4 @@
 {
   "theme": "default",
-  "themeCSS": ".node rect { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }"
+  "themeCSS": ".node rect, .er.entityBox { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }; .er.entityBox + .er.entityLabel { fill: white }; .er.attributeBoxEven, .er.attributeBoxOdd { fill: #fff; stroke: #777 }"
 }