permdock 0.4.0 → 0.6.0

package/schemas/automation-event-v1.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/automation-event-v1.json",
+  "title": "PermDock automation event",
+  "description": "An AutomationEvent, wire format v1: the data of com.permdock.automation.* CloudEvents.",
+  "type": "object",
+  "required": [
+    "type",
+    "at",
+    "source",
+    "operation",
+    "automation",
+    "principal",
+    "publishedBy",
+    "permissions"
+  ],
+  "properties": {
+    "x": {
+      "type": "object",
+      "description": "The application's own data, set where the event is built: plain JSON, never read by a decision."
+    },
+    "type": {
+      "const": "automation"
+    },
+    "at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "source": {
+      "type": "string"
+    },
+    "operation": {
+      "enum": ["published", "changed", "revoked", "run"]
+    },
+    "automation": {
+      "type": "object",
+      "required": ["id", "version", "mode"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": ["integer", "string"]
+        },
+        "mode": {
+          "enum": ["publisher", "service"]
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "principal": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "publishedBy": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tenant": {
+      "type": "string"
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "permissions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "run": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "by": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/capability-v1.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/capability-v1.json",
+  "title": "PermDock capability v1",
+  "description": "The JWT claims set of a vnd.permdock.capability+jwt. sub is the capability id an application revokes, exp its expiry, and jti the per-token id a once capability claims. Unknown claims are allowed so a v1 minor release can add one.",
+  "type": "object",
+  "required": ["iss", "aud", "iat", "exp", "jti", "sub", "capability"],
+  "properties": {
+    "iss": { "type": "string", "minLength": 1 },
+    "aud": {
+      "anyOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      ]
+    },
+    "iat": { "$ref": "#/$defs/numericDate" },
+    "exp": { "$ref": "#/$defs/numericDate" },
+    "jti": { "type": "string", "minLength": 1 },
+    "sub": { "type": "string", "minLength": 1 },
+    "cnf": {
+      "description": "RFC 7800: the RFC 7638 SHA-256 JWK thumbprint of the key whose RFC 9449 DPoP proof must accompany the token.",
+      "type": "object",
+      "required": ["jkt"],
+      "properties": {
+        "jkt": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": ["v", "holder", "on", "roles"],
+      "properties": {
+        "v": { "const": 1 },
+        "holder": { "enum": ["link", "key"] },
+        "on": {
+          "type": "object",
+          "required": ["resource", "id"],
+          "properties": {
+            "resource": { "type": "string", "minLength": 1 },
+            "id": { "type": "string", "minLength": 1 }
+          }
+        },
+        "roles": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "permissions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "redeemer": {
+          "anyOf": [
+            { "enum": ["anyone", "signed-in"] },
+            {
+              "type": "object",
+              "required": ["user"],
+              "properties": { "user": { "type": "string", "minLength": 1 } }
+            },
+            {
+              "type": "object",
+              "required": ["scope", "id"],
+              "properties": {
+                "scope": { "type": "string", "minLength": 1 },
+                "id": { "type": "string", "minLength": 1 }
+              }
+            }
+          ]
+        },
+        "once": { "const": true }
+      }
+    }
+  },
+  "$defs": {
+    "numericDate": {
+      "description": "RFC 7519 NumericDate: seconds since the epoch.",
+      "type": "number",
+      "minimum": 0
+    }
+  }
+}

package/schemas/catalog-event-v1.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/catalog-event-v1.json",
+  "title": "PermDock catalog event",
+  "description": "The data of com.permdock.catalog.* CloudEvents, wire format v1: a catalog publish or a drift against live hosted grants.",
+  "type": "object",
+  "required": ["kind", "fingerprint"],
+  "properties": {
+    "kind": {
+      "enum": ["publish", "drift"]
+    },
+    "fingerprint": {
+      "type": "string",
+      "minLength": 1
+    },
+    "previous": {
+      "type": "string"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["code", "permission"],
+            "properties": {
+              "code": {
+                "enum": [
+                  "permission-removed",
+                  "not-hostable",
+                  "grantee-removed",
+                  "approval-tightened"
+                ]
+              },
+              "permission": {
+                "type": "string"
+              },
+              "grant": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["code", "permission", "operation", "previous", "risk"],
+            "properties": {
+              "code": {
+                "const": "operation-risk-raised"
+              },
+              "permission": {
+                "type": "string"
+              },
+              "operation": {
+                "type": "string"
+              },
+              "previous": {
+                "enum": ["low", "medium", "high", "critical"]
+              },
+              "risk": {
+                "enum": ["low", "medium", "high", "critical"]
+              }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["code", "permission", "operation"],
+            "properties": {
+              "code": {
+                "const": "operation-approval-removed"
+              },
+              "permission": {
+                "type": "string"
+              },
+              "operation": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/catalog-v1.json

@@ -39,6 +39,36 @@
           "definedIn": {
             "type": "string"
           },
+          "parent": {
+            "type": "object",
+            "required": ["field", "resource"],
+            "properties": {
+              "field": {
+                "type": "string"
+              },
+              "resource": {
+                "type": "string"
+              }
+            }
+          },
+          "links": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": ["field", "resource"],
+              "properties": {
+                "field": {
+                  "type": "string"
+                },
+                "resource": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "disclosure": {
+            "const": "hide"
+          },
           "relations": {
             "type": "object"
           },
@@ -113,7 +143,8 @@
             "required": ["justification"],
             "properties": {
               "maxDuration": {
-                "type": "string"
+                "type": "integer",
+                "minimum": 1
               },
               "justification": {
                 "enum": ["required", "optional"]
@@ -139,7 +170,8 @@
               "durations": {
                 "type": "array",
                 "items": {
-                  "type": "string"
+                  "type": "integer",
+                  "minimum": 1
                 }
               }
             }
@@ -287,14 +319,16 @@
                       "minimum": 1
                     },
                     "ttl": {
-                      "type": "string"
+                      "type": "integer",
+                      "minimum": 1
                     },
                     "escalation": {
                       "type": "object",
                       "required": ["after", "to"],
                       "properties": {
                         "after": {
-                          "type": "string"
+                          "type": "integer",
+                          "minimum": 1
                         },
                         "to": {}
                       }
@@ -324,7 +358,8 @@
                 "type": "boolean"
               },
               "maxDuration": {
-                "type": "string"
+                "type": "integer",
+                "minimum": 1
               },
               "obligations": {
                 "type": "array",
@@ -415,14 +450,16 @@
                     "minimum": 1
                   },
                   "ttl": {
-                    "type": "string"
+                    "type": "integer",
+                    "minimum": 1
                   },
                   "escalation": {
                     "type": "object",
                     "required": ["after", "to"],
                     "properties": {
                       "after": {
-                        "type": "string"
+                        "type": "integer",
+                        "minimum": 1
                       },
                       "to": {}
                     }
@@ -441,10 +478,14 @@
             "type": "object",
             "properties": {
               "from": {
-                "type": "integer"
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
               },
               "until": {
-                "type": "integer"
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
               }
             }
           },
@@ -479,7 +520,8 @@
                 "minimum": 1
               },
               "per": {
-                "type": "string"
+                "type": "integer",
+                "minimum": 1
               },
               "mode": {
                 "enum": ["hard", "soft"]
@@ -527,15 +569,84 @@
             "type": "object",
             "properties": {
               "from": {
-                "type": "integer"
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
               },
               "until": {
-                "type": "integer"
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
               }
             }
           }
         }
       }
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "permission", "meta"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.-]{1,128}$"
+          },
+          "permission": {
+            "type": "string"
+          },
+          "results": {
+            "type": "string"
+          },
+          "meta": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "risk": {
+                "enum": ["low", "medium", "high", "critical"]
+              },
+              "effects": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "enum": [
+                    "read",
+                    "write",
+                    "delete",
+                    "send",
+                    "spend",
+                    "external"
+                  ]
+                }
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "oauthScopes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["scope", "permissions"],
+        "properties": {
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          },
+          "permissions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
     }
   }
 }

package/schemas/cli-commands-v1.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/cli-commands-v1.json",
+  "title": "PermDock CLI commands v1",
+  "description": "What `permdock --help --json` prints: every command with its arguments, options, examples, side effects and docs page, read from the same manifest the parser uses. `permdock <command> --help --json` prints the same document with that command only. The shape follows better-supabase's `cli-commands-v1`; `docs` and `config` are PermDock's own. Fields are only added within v1.",
+  "type": "object",
+  "required": ["$schema", "name", "version", "options", "commands"],
+  "properties": {
+    "$schema": {
+      "const": "https://permdock.com/schemas/cli-commands-v1.json"
+    },
+    "name": {
+      "const": "permdock"
+    },
+    "version": {
+      "type": "string",
+      "description": "The installed permdock version."
+    },
+    "options": {
+      "description": "The global options every command accepts.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/option"
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/command"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "command": {
+      "type": "object",
+      "required": [
+        "name",
+        "path",
+        "description",
+        "docs",
+        "examples",
+        "effects",
+        "config",
+        "arguments",
+        "options"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The last word of `path`."
+        },
+        "path": {
+          "type": "string",
+          "description": "The words after `permdock`, such as `rls generate`."
+        },
+        "description": {
+          "type": "string"
+        },
+        "docs": {
+          "type": "string",
+          "format": "uri"
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Complete command lines, starting with `permdock`."
+        },
+        "effects": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "files",
+              "rewrite",
+              "database:read",
+              "database:write",
+              "network",
+              "cloud:write",
+              "install"
+            ]
+          },
+          "description": "What the command may change. Empty means it only reads and prints. In agent mode, `rewrite`, `cloud:write`, and `files` with `--force` need a `--confirm` token."
+        },
+        "config": {
+          "type": "boolean",
+          "description": "Whether the command reads permdock.config.ts."
+        },
+        "arguments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "description", "required", "variadic"],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "variadic": {
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "option": {
+      "type": "object",
+      "required": ["name", "type", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Written `--<name>` on the command line."
+        },
+        "type": {
+          "enum": ["boolean", "string", "enum"]
+        },
+        "description": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]$"
+          }
+        },
+        "choices": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "default": {
+          "type": ["boolean", "string"]
+        },
+        "list": {
+          "const": true,
+          "description": "Takes several values, repeated."
+        },
+        "valueHint": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}