feat(gate,sdk)!: new policy spec (#937)

#### Migration notes

* Replaced true, false, and null to ALLOW, DENY and PASS.

Composition rules:
1. On traversal order:

* `ALLOW`: allow parent and all its children (ignore inner policies)
* `DENY`: deny parent and all its children  (ignore inner policies)
* `PASS`: pass through parent and evaluate each children (no-op,
equivalent to no policies)

2. On a single type (a.with_policy(X).with_policy(Y)):

`ALLOW` and `DENY` compose the same as true and false with the AND gate,
`PASS` does not participate.
* `ALLOW` & P = P
* `DENY` & P = `DENY` (e.g. DENY & ALLOW = DENY)
* `PASS` & P = P (does not participate)

- [x] The change comes with new or modified tests
- [x] Hard-to-understand functions have explanatory comments
- [x] End-user documentation is updated to reflect the change


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

- **New Features**
- Enhanced documentation for Metatype's mental model, including clearer
policy definitions and a comparison table with classical models.
- Introduction of a comprehensive tutorial on building a Metatype API,
covering setup, CRUD operations, and security practices.

- **Bug Fixes**
- Updated policy logic to return explicit 'ALLOW' or 'DENY' strings
instead of boolean values across various components.

- **Documentation**
- Improved clarity and detail in documentation for policies and core
concepts.
	- Added new sections for policy composition rules and traversal order.

- **Refactor**
- Streamlined policy management and evaluation logic across multiple
files, enhancing clarity and maintainability.

- **Tests**
- Added tests for new policy functionalities and updated existing tests
to reflect changes in policy handling.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Natoandro <[email protected]>

docs/metatype.dev/docs/concepts/mental-model/index.mdx

@@ -91,9 +91,9 @@ Policies are a special type of function `t.func(t.struct({...}), t.boolean().opt
 
 The policy decision can be:
 
-- `true`: the access is authorized
-- `false`: the access is denied
-- `null`: the access in inherited from the parent types
+- `ALLOW`: Grants access to the current type and all its descendants.
+- `DENY`: Restricts access to the current type and all its descendants.
+- `PASS`: Grants access to the current type while requiring individual checks for all its descendants (similar to the absence of policies).
 
 <CodeBlock language="python">
   {

docs/metatype.dev/docs/reference/policies/index.mdx

@@ -17,8 +17,8 @@ The Deno runtime enable to understand the last abstraction. Policies are a way t
 
 Metatype comes with some built-in policies, but you can use the Deno runtime to define your own:
 
-- `policies.public()` is an alias for `Policy(PureFunMat("() => true"))` providing everyone open access.
-- `policies.ctx("role_value", "role_field")` is a companion policy for the authentication strategy you learned in the previous section. It will verify the context and give adequate access to the user.
+- `policies.public()` is an alias for `deno.policy("public", "() => 'PASS'")` providing everyone open access while still allowing field level custom access.
+- `Policy.context("role_value", "role_field")` is a companion policy for the authentication strategy you learned in the previous section. It will verify the context and give adequate access to the user.
 
 Policies are hierarchical in the sense that the request starts with a denial, and the root functions must explicitly provide an access or not. Once access granted, any further types can either inherit or override the access. Policies evaluate in order in case multiple ones are defined.
 
@@ -28,3 +28,17 @@ Policies are hierarchical in the sense that the request starts with a denial, an
   typescript={require("!!code-loader!../../../../../examples/typegraphs/policies.ts")}
   query={require("./policies.graphql")}
 />
+
+## Composition rules
+
+### Traversal order
+
+- `ALLOW`: Allows access to the parent and all its descendants, disregarding inner policies.
+- `DENY`: Denies access to the parent and all its descendants, disregarding inner policies.
+- `PASS`: Allows access to the parent, each descendant will still be evaluated individually (equivalent to having no policies set).
+
+### Chaining policies
+
+If you have `foo.with_policy(A, B).with_policy(C)` for example, it will evaluated in batch as `[A, B, C]`.
+
+If one or more policies fail (`DENY`), the type will be inaccessible.

docs/metatype.dev/docs/tutorials/metatype-basics/index.mdx

@@ -581,7 +581,7 @@ typegraph("roadmap", (g) => {
   const admins = deno.policy(
     "admins",
     `
-  (_args, { context }) => !!context.username
+  (_args, { context }) => !!context.username ? 'ALLOW' : 'DENY'
 `,
   );
 
@@ -619,7 +619,7 @@ def roadmap(g: Graph):
     # the username value is only available if the basic
     # extractor was successful
     admins = deno.policy("admins", """
-  (_args, { context }) => !!context.username
+  (_args, { context }) => !!context.username ? 'ALLOW' : 'DENY'
 """)
 
     g.expose(

examples/typegraphs/execute.py

@@ -53,7 +53,7 @@ def roadmap(g: Graph):
     admins = deno.policy(
         "admins",
         """
-  (_args, { context }) => !!context.username
+  (_args, { context }) => !!context.username ? 'PASS' : 'DENY'
 """,
     )
 

examples/typegraphs/execute.ts

@@ -52,7 +52,7 @@ await typegraph(
     const admins = deno.policy(
       "admins",
       `
-        (_args, { context }) => !!context.username
+        (_args, { context }) => !!context.username ? 'PASS' : 'DENY'
     `,
     );
 

examples/typegraphs/func.py

@@ -58,7 +58,7 @@ def roadmap(g: Graph):
 
     admins = deno.policy(
         "admins",
-        "(_args, { context }) => !!context.username",
+        "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     )
     # skip:end
 

examples/typegraphs/func.ts

@@ -56,7 +56,7 @@ await typegraph(
 
     const admins = deno.policy(
       "admins",
-      "(_args, { context }) => !!context.username",
+      "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     );
     // skip:end
 

examples/typegraphs/math.py

@@ -27,7 +27,7 @@ def math(g: Graph):
     # the policy implementation is based on functions as well
     restrict_referer = deno.policy(
         "restrict_referer_policy",
-        '(_, context) => context.headers.referer && ["localhost", "metatype.dev"].includes(new URL(context.headers.referer).hostname)',
+        '(_, context) => context.headers.referer && ["localhost", "metatype.dev"].includes(new URL(context.headers.referer).hostname) ? "ALLOW" : "DENY"',
     )
 
     g.expose(

examples/typegraphs/math.ts

@@ -24,7 +24,7 @@ await typegraph(
     // the policy implementation is based on functions itself
     const restrict_referer = deno.policy(
       "restrict_referer_policy",
-      '(_, context) => context.headers.referer && ["localhost", "metatype.dev"].includes(new URL(context.headers.referer).hostname)',
+      '(_, context) => context.headers.referer && ["localhost", "metatype.dev"].includes(new URL(context.headers.referer).hostname) ? "ALLOW" : "DENY"',
     );
 
     // or we can point to a local file that's accessible to the meta-cli

examples/typegraphs/policies-example.py

@@ -10,5 +10,8 @@
 def policies_example(g):
     # skip:end
     deno = DenoRuntime()
-    public = deno.policy("public", "() => true")  # noqa
-    team_only = deno.policy("team", "(ctx) => ctx.user.role === 'admin'")  # noqa
+    public = deno.policy("public", "() => 'PASS'")  # noqa
+    allow_all = deno.policy("allow_all", "() => 'ALLOW'")  # noqa
+    team_only = deno.policy(  # noqa
+        "team", "(ctx) => ctx.user.role === 'admin' ? 'ALLOW' : 'DENY' "
+    )

examples/typegraphs/policies.py

@@ -15,17 +15,17 @@ def policies(g: Graph):
     deno = DenoRuntime()
     random = RandomRuntime(seed=0, reset=None)
 
-    # `public` is sugar for to `() => true`
+    # `public` is sugar for to `(_args, _ctx) => "PASS"`
     public = Policy.public()
 
     admin_only = deno.policy(
         "admin_only",
-        # note: policies either return true | false | null
-        "(args, { context }) => context.username ? context.username === 'admin' : null",
+        # note: policies either return "ALLOW" | "DENY" | "PASS"
+        "(args, { context }) => context?.username === 'admin' ? 'ALLOW' : 'DENY'",
     )
     user_only = deno.policy(
         "user_only",
-        "(args, { context }) => context.username ? context.username === 'user' : null",
+        "(args, { context }) => context?.username === 'user' ? 'PASS' : 'DENY'",
     )
 
     g.auth(Auth.basic(["admin", "user"]))

examples/typegraphs/policies.ts

@@ -13,17 +13,17 @@ typegraph(
     // skip:end
     const deno = new DenoRuntime();
     const random = new RandomRuntime({ seed: 0 });
-    // `public` is sugar for `(_args, _ctx) => true`
+    // `public` is sugar for `(_args, _ctx) => "PASS"`
     const pub = Policy.public();
 
     const admin_only = deno.policy(
       "admin_only",
-      // note: policies either return true | false | null
-      "(args, { context }) => context.username ? context.username === 'admin' : null",
+      // note: policies either return "ALLOW" | "DENY" | "PASS"
+      "(args, { context }) => context?.username === 'admin' ? 'ALLOW' : 'DENY'",
     );
     const user_only = deno.policy(
       "user_only",
-      "(args, { context }) => context.username ? context.username === 'user' : null",
+      "(args, { context }) => context?.username === 'user' ? 'PASS' : 'DENY'",
     );
 
     g.auth(Auth.basic(["admin", "user"]));

examples/typegraphs/programmable-api-gateway.py

@@ -17,7 +17,9 @@ def programmable_api_gateway(g: Graph):
     deno = DenoRuntime()
 
     public = Policy.public()
-    roulette_access = deno.policy("roulette", "() => Math.random() < 0.5")
+    roulette_access = deno.policy(
+        "roulette", "() => Math.random() < 0.5 ? 'PASS' : 'DENY'"
+    )
 
     my_api_format = """
     static_a:

examples/typegraphs/programmable-api-gateway.ts

@@ -17,7 +17,7 @@ typegraph(
     const pub = Policy.public();
     const roulette_access = deno.policy(
       "roulette",
-      "() => Math.random() < 0.5",
+      "() => Math.random() < 0.5 ? 'PASS' : 'DENY'",
     );
 
     // skip:next-line

examples/typegraphs/reduce.py

@@ -51,7 +51,7 @@ def roadmap(g: Graph):
 
     admins = deno.policy(
         "admins",
-        "(_args, { context }) => !!context.username",
+        "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     )
 
     g.expose(

examples/typegraphs/reduce.ts

@@ -49,7 +49,7 @@ typegraph(
 
     const admins = deno.policy(
       "admins",
-      "(_args, { context }) => !!context.username",
+      "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     );
 
     g.expose(

examples/typegraphs/rest.py

@@ -51,7 +51,7 @@ def roadmap(g: Graph):
 
     admins = deno.policy(
         "admins",
-        "(_args, { context }) => !!context.username",
+        "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     )
 
     g.expose(

examples/typegraphs/rest.ts

@@ -49,7 +49,7 @@ typegraph(
 
     const admins = deno.policy(
       "admins",
-      "(_args, { context }) => !!context.username",
+      "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     );
 
     g.expose(

examples/typegraphs/roadmap-policies.py

@@ -56,7 +56,7 @@ def roadmap(g: Graph):
     # highlight-start
     admins = deno.policy(
         "admins",
-        "(_args, { context }) => !!context.username",
+        "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     )
     # highlight-end
 

examples/typegraphs/roadmap-policies.ts

@@ -50,7 +50,7 @@ typegraph(
 
     const admins = deno.policy(
       "admins",
-      "(_args, { context }) => !!context.username",
+      "(_args, { context }) => !!context.username ? 'PASS' : 'DENY'",
     );
 
     g.expose(

src/common/src/typegraph/types.rs

@@ -63,7 +63,6 @@ pub enum Injection {
 #[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct TypeNodeBase {
     pub title: String,
-    pub policies: Vec<PolicyIndices>,
     #[serde(default)]
     pub description: Option<String>,
     #[serde(default, rename = "enum")]
@@ -158,6 +157,9 @@ pub struct ObjectTypeData<Id = TypeId> {
     pub id: Vec<String>,
     #[serde(default)]
     pub required: Vec<String>,
+    #[serde(skip_serializing_if = "IndexMap::is_empty")]
+    #[serde(default)]
+    pub policies: IndexMap<String, Vec<PolicyIndices>>,
 }
 
 #[skip_serializing_none]

src/metagen/src/fdk_rust/stubs.rs

@@ -113,6 +113,7 @@ mod test {
                 TypeNode::Object {
                     data: ObjectTypeData {
                         properties: Default::default(),
+                        policies: Default::default(),
                         id: vec![],
                         required: vec![],
                     },

src/metagen/src/fdk_rust/types.rs

@@ -438,6 +438,7 @@ mod test {
                             ]
                             .into_iter()
                             .collect(),
+                            policies: Default::default(),
                             id: vec![],
                             // FIXME: remove required
                             required: vec![],
@@ -615,6 +616,7 @@ pub enum MyUnion {
                             properties: [("obj_b".to_string(), 1)].into_iter().collect(),
                             id: vec![],
                             required: ["obj_b"].into_iter().map(Into::into).collect(),
+                            policies: Default::default(),
                         },
                         base: TypeNodeBase {
                             title: "ObjA".into(),
@@ -624,6 +626,7 @@ pub enum MyUnion {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("obj_c".to_string(), 2)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["obj_c"].into_iter().map(Into::into).collect(),
                         },
@@ -635,6 +638,7 @@ pub enum MyUnion {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("obj_a".to_string(), 0)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["obj_a"].into_iter().map(Into::into).collect(),
                         },
@@ -665,6 +669,7 @@ pub struct ObjC {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("obj_b".to_string(), 1)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["obj_b"].into_iter().map(Into::into).collect(),
                         },
@@ -676,6 +681,7 @@ pub struct ObjC {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("union_c".to_string(), 2)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["union_c"].into_iter().map(Into::into).collect(),
                         },
@@ -714,6 +720,7 @@ pub enum CUnion {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("obj_b".to_string(), 1)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["obj_b"].into_iter().map(Into::into).collect(),
                         },
@@ -725,6 +732,7 @@ pub enum CUnion {
                     TypeNode::Object {
                         data: ObjectTypeData {
                             properties: [("either_c".to_string(), 2)].into_iter().collect(),
+                            policies: Default::default(),
                             id: vec![],
                             required: ["either_c"].into_iter().map(Into::into).collect(),
                         },

src/metagen/src/tests/fixtures.rs

@@ -55,6 +55,7 @@ pub fn test_typegraph_2() -> Typegraph {
             TypeNode::Object {
                 data: ObjectTypeData {
                     properties: Default::default(),
+                    policies: Default::default(),
                     id: vec![],
                     required: vec![],
                 },
@@ -99,7 +100,6 @@ pub fn test_typegraph_2() -> Typegraph {
 pub fn default_type_node_base() -> TypeNodeBase {
     TypeNodeBase {
         title: String::new(),
-        policies: vec![],
         description: None,
         enumeration: None,
     }