permdock 0.0.0 → 0.2.0

package/schemas/openapi/overlay-1.1.json

@@ -0,0 +1,79 @@
+{
+  "$id": "https://spec.openapis.org/overlay/1.1/schema/2026-04-01",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "The description of Overlay v1.1.x documents",
+  "type": "object",
+  "properties": {
+    "overlay": {
+      "type": "string",
+      "pattern": "^1\\.1\\.\\d+$"
+    },
+    "info": {
+      "$ref": "#/$defs/info-object"
+    },
+    "extends": {
+      "type": "string",
+      "format": "uri-reference"
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/action-object"
+      }
+    }
+  },
+  "required": ["overlay", "info", "actions"],
+  "$ref": "#/$defs/specification-extensions",
+  "unevaluatedProperties": false,
+  "$defs": {
+    "info-object": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": ["title", "version"],
+      "$ref": "#/$defs/specification-extensions",
+      "unevaluatedProperties": false
+    },
+    "action-object": {
+      "type": "object",
+      "properties": {
+        "target": {
+          "type": "string",
+          "pattern": "^\\$"
+        },
+        "description": {
+          "type": "string"
+        },
+        "update": {
+          "type": ["string", "boolean", "object", "array", "number", "null"]
+        },
+        "copy": {
+          "type": "string"
+        },
+        "remove": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "required": ["target"],
+      "$ref": "#/$defs/specification-extensions",
+      "unevaluatedProperties": false
+    },
+    "specification-extensions": {
+      "patternProperties": {
+        "^x-": true
+      }
+    }
+  }
+}

package/schemas/supabase-claims-v1.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/supabase-claims-v1.json",
+  "title": "PermDock claims in a Supabase access token",
+  "description": "The claims the permdock supabase hook writes and the SQL helpers and subjectFromSupabase read, plus the OAuth claims subjectFromSupabase maps to the actor and delegation. Other claims pass through. Each hook claim may also sit under app_metadata. supabaseClaims() in permdock/supabase validates the same shape; tenant_id is the default rls.tenantClaim.",
+  "type": "object",
+  "allOf": [{ "$ref": "#/$defs/permdockClaims" }],
+  "properties": {
+    "client_id": {
+      "description": "The OAuth client of a third-party app; becomes actor.id when there is no act claim.",
+      "type": "string"
+    },
+    "scope": {
+      "description": "OAuth scopes, space-separated or as a list; becomes delegation.scopes.",
+      "anyOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "act": { "$ref": "#/$defs/act" },
+    "app_metadata": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/permdockClaims" }]
+    }
+  },
+  "$defs": {
+    "permdockClaims": {
+      "type": "object",
+      "properties": {
+        "user_role": {
+          "description": "Global roles: one name, a list, or null for none.",
+          "anyOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "null" }
+          ]
+        },
+        "roles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "memberships": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/membership" }
+        },
+        "memberships_truncated": {
+          "description": "true when the size budget cut memberships or attrs.",
+          "type": "boolean"
+        },
+        "tenant_id": {
+          "description": "The active tenant (the default rls.tenantClaim): the canonical text of one instance of the first scope.",
+          "type": "string"
+        },
+        "attrs": {
+          "description": "Allow-listed server-owned attributes, read as principal.claims.attrs.<key>.",
+          "type": "object"
+        },
+        "authz_ver": {
+          "description": "The principal's authorization version.",
+          "type": "integer"
+        }
+      }
+    },
+    "act": {
+      "description": "RFC 8693 actor chain: the outermost sub is the current actor, each nested act a prior one. The outermost kind names the actor: none is an OAuth client or agent, support a support session (needs session_id), impersonation an admin acting as the user.",
+      "type": "object",
+      "required": ["sub"],
+      "properties": {
+        "sub": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["support", "impersonation"] },
+        "session_id": { "type": "string", "minLength": 1 },
+        "read_only": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "act": { "$ref": "#/$defs/act" }
+      },
+      "if": {
+        "required": ["kind"],
+        "properties": { "kind": { "const": "support" } }
+      },
+      "then": { "required": ["session_id"] }
+    },
+    "membership": {
+      "type": "object",
+      "required": ["roles"],
+      "properties": {
+        "scope": { "type": "string" },
+        "id": {
+          "description": "Canonical text of the scope instance id (uuid::text for a uuid column); compared exactly, never lower-cased.",
+          "type": "string"
+        },
+        "within": {
+          "description": "The id of every ancestor scope instance, by scope name.",
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "on": {
+          "type": "object",
+          "required": ["resource", "id"],
+          "properties": {
+            "resource": { "type": "string" },
+            "id": { "type": "string" }
+          }
+        },
+        "tenant": { "type": "string" },
+        "team": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "via": { "type": "string" },
+        "expiresAt": {
+          "description": "Seconds since the epoch.",
+          "type": "number"
+        },
+        "grantedBy": { "type": "string" },
+        "reason": { "type": "string" },
+        "member": {
+          "description": "The subgroup a membership source's group fills.",
+          "type": "object",
+          "required": ["group"],
+          "properties": { "group": { "type": "string", "minLength": 1 } }
+        },
+        "managedBy": { "const": "idp" },
+        "entitlements": { "type": "array", "items": { "type": "string" } },
+        "keep": {
+          "description": "Set when the instance or an ancestor is suspended: the permission keys the membership still grants.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "grants": {
+          "description": "Custom roles in compact form, read by the helpers in jwt mode.",
+          "type": "object"
+        }
+      },
+      "anyOf": [
+        { "required": ["scope", "id"] },
+        { "required": ["tenant"] },
+        { "required": ["team"] },
+        { "required": ["on"] }
+      ]
+    }
+  }
+}

package/schemas/supabase-manifest-v1.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/supabase-manifest-v1.json",
+  "title": "PermDock Supabase hook manifest v1",
+  "description": "What `permdock supabase inspect --json` prints and `--out` writes: the generated hook, the SQL helpers, the claims, the membership sources and the columns that decide them. Fields are only added within v1.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "version",
+    "hook",
+    "helpers",
+    "tenantClaim",
+    "budget",
+    "claims",
+    "authzVersion",
+    "memberships",
+    "rls",
+    "decidingColumns",
+    "markers"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://permdock.com/schemas/supabase-manifest-v1.json"
+    },
+    "version": { "const": 1 },
+    "hook": {
+      "type": "object",
+      "required": ["schema", "function", "out"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "function": { "const": "custom_access_token_hook" },
+        "out": { "type": "string" },
+        "before": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+          }
+        }
+      }
+    },
+    "helpers": {
+      "type": "object",
+      "required": ["schema", "functions"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "functions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/helperName" }
+        }
+      }
+    },
+    "tenantClaim": { "$ref": "#/$defs/identifier" },
+    "budget": {
+      "type": "object",
+      "required": ["bytes", "measure"],
+      "properties": {
+        "bytes": { "type": "integer", "minimum": 1 },
+        "measure": { "type": "string" }
+      }
+    },
+    "claims": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "source", "budget"],
+        "properties": {
+          "name": { "$ref": "#/$defs/identifier" },
+          "source": {
+            "type": "string",
+            "pattern": "^(permdock|[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*)$"
+          },
+          "budget": { "type": "boolean" }
+        }
+      }
+    },
+    "authzVersion": { "type": "boolean" },
+    "authzVersionBump": {
+      "type": "object",
+      "required": ["schema", "function", "args"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "function": { "const": "permdock_bump_authz_version_for" },
+        "args": { "const": "p_users uuid[]" }
+      }
+    },
+    "memberships": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/membership" }
+    },
+    "rls": {
+      "type": "object",
+      "required": [
+        "schema",
+        "mode",
+        "tenantClaim",
+        "scopes",
+        "helpers",
+        "memberships"
+      ],
+      "properties": {
+        "schema": { "$ref": "#/$defs/identifier" },
+        "mode": { "enum": ["jwt", "database"] },
+        "tenantClaim": { "$ref": "#/$defs/identifier" },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "type"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+              "type": { "type": "string" },
+              "within": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }
+            }
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "args", "returns", "execute"],
+            "properties": {
+              "name": { "$ref": "#/$defs/helperName" },
+              "args": { "type": "string" },
+              "returns": { "type": "string" },
+              "execute": {
+                "type": "array",
+                "items": {
+                  "enum": ["anon", "authenticated", "supabase_auth_admin"]
+                }
+              }
+            }
+          }
+        },
+        "memberships": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/membership" }
+        },
+        "customRoles": { "type": "boolean" },
+        "roles": {
+          "type": "object",
+          "required": ["table", "user", "role"],
+          "additionalProperties": false,
+          "properties": {
+            "table": { "type": "string" },
+            "user": { "$ref": "#/$defs/column" },
+            "role": {
+              "oneOf": [
+                { "$ref": "#/$defs/role" },
+                {
+                  "type": "array",
+                  "minItems": 2,
+                  "items": { "$ref": "#/$defs/role" }
+                }
+              ]
+            }
+          }
+        },
+        "suspension": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "users": { "$ref": "#/$defs/activeRow" },
+            "scopes": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/activeRow" }
+            },
+            "memberships": {
+              "type": "object",
+              "required": ["keep"],
+              "additionalProperties": false,
+              "properties": {
+                "keep": {
+                  "description": "The permission keys a membership whose disabledAt column is set still holds.",
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "assignments": {
+          "type": "object",
+          "required": ["tables"],
+          "additionalProperties": false,
+          "properties": {
+            "tables": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "apiKeys": {
+          "type": "object",
+          "required": ["claim", "scopes", "tenant", "roles", "serviceRoles"],
+          "additionalProperties": false,
+          "properties": {
+            "claim": { "type": "string" },
+            "scopes": { "type": "string" },
+            "tenant": { "type": "string" },
+            "roles": { "type": "string" },
+            "serviceRoles": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "decidingColumns": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+      }
+    },
+    "markers": {
+      "type": "object",
+      "required": ["hook", "grants"],
+      "properties": {
+        "hook": { "const": "v1" },
+        "grants": { "const": "v1" }
+      }
+    },
+    "requires": {
+      "description": "The supabase/sdk capability-matrix feature ids the hook, the helpers and subjectFromSupabase depend on, as of the matrix release tag.",
+      "type": "object",
+      "required": ["matrix", "capabilities"],
+      "additionalProperties": false,
+      "properties": {
+        "matrix": {
+          "type": "string",
+          "pattern": "^capability-matrix-v1\\.[0-9]+\\.[0-9]+$"
+        },
+        "capabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*\\.[a-z0-9_]+\\.[a-z0-9_]+$"
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "membership": {
+      "type": "object",
+      "required": ["table", "user", "scope", "id", "role", "columns"],
+      "properties": {
+        "table": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "user": { "$ref": "#/$defs/user" },
+        "scope": { "$ref": "#/$defs/value" },
+        "id": { "$ref": "#/$defs/column" },
+        "role": {
+          "oneOf": [
+            { "$ref": "#/$defs/role" },
+            {
+              "type": "array",
+              "minItems": 2,
+              "items": { "$ref": "#/$defs/role" }
+            }
+          ]
+        },
+        "within": {
+          "oneOf": [
+            { "$ref": "#/$defs/column" },
+            {
+              "type": "object",
+              "required": ["columns"],
+              "additionalProperties": false,
+              "properties": {
+                "columns": {
+                  "type": "object",
+                  "additionalProperties": { "$ref": "#/$defs/identifier" }
+                }
+              }
+            }
+          ]
+        },
+        "via": { "$ref": "#/$defs/value" },
+        "expiresAt": { "$ref": "#/$defs/column" },
+        "disabledAt": { "$ref": "#/$defs/column" },
+        "columns": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/identifier" }
+        }
+      }
+    },
+    "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "activeRow": {
+      "type": "object",
+      "required": ["table", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "table": { "type": "string" },
+        "id": { "$ref": "#/$defs/identifier" },
+        "disabledAt": { "$ref": "#/$defs/identifier" },
+        "status": { "$ref": "#/$defs/identifier" },
+        "active": { "type": "array", "items": { "type": "string" } },
+        "keep": {
+          "description": "A scope only: the permission keys members of a suspended instance still hold.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "helperName": {
+      "type": "string",
+      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_user_id)$"
+    },
+    "column": {
+      "type": "object",
+      "required": ["column"],
+      "additionalProperties": false,
+      "properties": { "column": { "$ref": "#/$defs/identifier" } }
+    },
+    "role": {
+      "oneOf": [{ "$ref": "#/$defs/value" }, { "$ref": "#/$defs/through" }]
+    },
+    "user": {
+      "oneOf": [{ "$ref": "#/$defs/column" }, { "$ref": "#/$defs/through" }]
+    },
+    "through": {
+      "type": "object",
+      "required": ["column", "through"],
+      "additionalProperties": false,
+      "properties": {
+        "column": { "$ref": "#/$defs/identifier" },
+        "through": {
+          "type": "object",
+          "required": ["table", "id", "column"],
+          "additionalProperties": false,
+          "properties": {
+            "table": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "id": { "$ref": "#/$defs/identifier" },
+            "column": { "$ref": "#/$defs/identifier" }
+          }
+        }
+      }
+    },
+    "value": {
+      "oneOf": [
+        { "$ref": "#/$defs/column" },
+        {
+          "type": "object",
+          "required": ["value"],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/permdock/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: permdock
+description: Explains how PermDock decides and routes to the right PermDock skill. Use first for any work with permdock, typed permissions, roles or access control in a TypeScript app, when a check is denied and the reason is unclear, when reading a Decision, denial reason or doctor code, when looking up current PermDock identifiers through the docs MCP, or when choosing between the permdock-wire, permdock-audit, permdock-agents, permdock-approvals, permdock-tenancy, permdock-data and permdock-credentials skills.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/for-ai-agents
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock
+
+PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents. Permissions are defined once, decided in process, compiled to queries and RLS, and serialised to client snapshots ([for AI agents](https://permdock.com/docs/for-ai-agents)). This skill holds the model every other PermDock skill assumes, and says which one to load.
+
+## Inputs (find out before starting)
+
+- Whether the app already has `permissions.ts`, `policy.ts` and a `createPermDock` factory file. None means start with `permdock-wire`.
+- The task: set up, review, or one area (agents, approvals, tenants, queries and RLS, tokens and keys).
+- Whether the `permdock` binary runs in the repo (`pnpm exec permdock doctor`).
+
+## Invariants
+
+1. **Fail-closed.** Anything unknown, invalid or thrown denies. `can()` never throws. A `Decision` is only `granted`, `denied` or `approval-required`.
+2. **Deny overrides allow.** Allows OR together; any matching `deny` wins.
+3. **References, not strings.** Pass `permissions.post.update`; strings appear only as `.key` / `.scope` on the wire, in catalogs and in audit.
+4. **Authentication is upstream.** Core never verifies a token. The subject comes from a `subjectFrom*` resolver or the server session, never from a request body, an unsigned header, a CLI flag or model output.
+5. **Server and client stay apart.** `policy.ts` and `createPermDock` never reach a client entry (doctor PD001); clients read snapshots, and a client check is a hint the server repeats.
+6. **Portable first.** Conditions that the in-memory evaluator, `where()` and RLS all understand beat closures.
+7. **The Cloud is optional.** No decision waits on PermDock Cloud; every hosted feature is an interface with an in-process default.
+
+## Workflow
+
+1. **Pick the skill.** Install the one the task needs with `npx skills add ScaleDockHQ/PermDock --skill <name>` (or all of them with `npx skills add ScaleDockHQ/PermDock`, or `pnpm exec permdock skills install` to match the installed package version):
+
+   | Task                                                    | Skill                  |
+   | ------------------------------------------------------- | ---------------------- |
+   | Add PermDock, first guard, limits, plans, CLI checks    | `permdock-wire`        |
+   | Review an app or a pull request                         | `permdock-audit`       |
+   | Agent tool calls, actors, delegation, A2A, WebMCP       | `permdock-agents`      |
+   | Human approval, approvers, quorum, resume               | `permdock-approvals`   |
+   | Named scopes, memberships, ownership, custom roles      | `permdock-tenancy`     |
+   | ORM queries, generated RLS, relationship graphs, parity | `permdock-data`        |
+   | Access tokens, API keys, service accounts, share links  | `permdock-credentials` |
+
+   ✓ The skill for the task is loaded, and `permdock-wire` has run first if the app has no factory file.
+
+2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.com/docs/...` URL. Every public name follows the [naming convention](https://permdock.com/docs/getting-started/naming).
+   ✓ Each identifier written into the app appears on a docs page or in `node_modules/permdock`.
+3. **Read a decision.** `decide()` returns `{ outcome, denials: [{ reason, ... }], alternatives }`. `reason` is one of the closed list on [decisions](https://permdock.com/docs/concepts/decisions); `alternatives` are permissions on the same resource the subject does hold. HTTP adapters answer RFC 9457 Problem Details ([errors](https://permdock.com/docs/concepts/errors)); for the format, defer to the `problem-details` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill problem-details`).
+   ✓ Each denial the user asked about is named by its reason.
+4. **Explain an unexpected denial.** Run `permdock.explain(permission, data)` in a test or a script. `trace.denies[0]` is the deny that won (give denies a `name` so it reads as a rule), `trace.allows` the allows it overrode, `trace.skipped` the grants passed over and why ([explain](https://permdock.com/docs/concepts/decisions#explain)). The trace never reaches the decision log. To preview a plan before acting, `simulate([[permission, data], ...])` returns every decision.
+   ✓ The cause is a named grant, condition or missing input, not a guess.
+5. **Check the project.** Run `pnpm exec permdock doctor` (`--json` for machine output). Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.com/docs/cli/doctor)); the topic skills name the codes for their area.
+   ✓ `permdock doctor` reports no error.
+
+## Verify before done
+
+- [ ] No identifier was written from memory; each one is on a docs page or in the package.
+- [ ] Nothing reads a subject, tenant, membership or approval token from model output, a request body or an unsigned header.
+- [ ] `policy.ts` is imported only from server code.
+- [ ] The topic skill used for the task has its Verify list passing.
+
+## Reference index
+
+- Skills: `permdock-wire`, `permdock-audit`, `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data`, `permdock-credentials`, all from `npx skills add ScaleDockHQ/PermDock --skill <name>`.
+- Docs: [for AI agents](https://permdock.com/docs/for-ai-agents), [naming](https://permdock.com/docs/getting-started/naming), [policies](https://permdock.com/docs/concepts/policies), [decisions](https://permdock.com/docs/concepts/decisions), [threat model](https://permdock.com/docs/security/threat-model), [doctor](https://permdock.com/docs/cli/doctor), `https://permdock.com/llms.txt`.