permdock 0.6.0 → 0.8.0

package/schemas/supabase-manifest-v1.json

@@ -7,13 +7,8 @@
   "required": [
     "$schema",
     "version",
-    "hook",
     "helpers",
     "tenantClaim",
-    "budget",
-    "claims",
-    "authzVersion",
-    "memberships",
     "rls",
     "decidingColumns",
     "markers"
@@ -22,14 +17,22 @@
     "$schema": {
       "const": "https://permdock.com/schemas/supabase-manifest-v1.json"
     },
-    "version": { "const": 1 },
+    "version": {
+      "const": 1
+    },
     "hook": {
       "type": "object",
       "required": ["schema", "function", "out"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "function": { "const": "custom_access_token_hook" },
-        "out": { "type": "string" },
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
+        "function": {
+          "const": "custom_access_token_hook"
+        },
+        "out": {
+          "type": "string"
+        },
         "schemas": {
           "enum": ["pg-delta", "migra", "migrations"],
           "description": "How the project turns SQL into migrations: pg-delta (supabase db schema declarative sync), migra (supabase db diff) or hand-written migrations. Absent means pg-delta."
@@ -47,20 +50,31 @@
       "type": "object",
       "required": ["schema", "functions"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
         "functions": {
           "type": "array",
-          "items": { "$ref": "#/$defs/helperName" }
+          "items": {
+            "$ref": "#/$defs/helperName"
+          }
         }
       }
     },
-    "tenantClaim": { "$ref": "#/$defs/identifier" },
+    "tenantClaim": {
+      "$ref": "#/$defs/identifier"
+    },
     "budget": {
       "type": "object",
       "required": ["bytes", "measure"],
       "properties": {
-        "bytes": { "type": "integer", "minimum": 1 },
-        "measure": { "type": "string" }
+        "bytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "measure": {
+          "type": "string"
+        }
       }
     },
     "claims": {
@@ -69,28 +83,60 @@
         "type": "object",
         "required": ["name", "source", "budget"],
         "properties": {
-          "name": { "$ref": "#/$defs/identifier" },
+          "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" }
+          "budget": {
+            "type": "boolean"
+          }
         }
       }
     },
-    "authzVersion": { "type": "boolean" },
+    "authzVersion": {
+      "type": "boolean"
+    },
+    "managementApi": {
+      "description": "The Management API fields that make a hosted project call the generated hook, as `permdock supabase inspect` prints and `--out` writes them.",
+      "type": "object",
+      "required": [
+        "hook_custom_access_token_enabled",
+        "hook_custom_access_token_uri",
+        "jwt_exp"
+      ],
+      "properties": {
+        "hook_custom_access_token_enabled": { "const": true },
+        "hook_custom_access_token_uri": { "type": "string" },
+        "jwt_exp": {
+          "description": "The access token lifetime in seconds: `[auth] jwt_expiry` of `supabase/config.toml`, or 3600 when it is unset.",
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false
+    },
     "authzVersionBump": {
       "type": "object",
       "required": ["schema", "function", "args"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "function": { "const": "permdock_bump_authz_version_for" },
-        "args": { "const": "p_users uuid[]" }
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
+        "function": {
+          "const": "permdock_bump_authz_version_for"
+        },
+        "args": {
+          "const": "p_users uuid[]"
+        }
       }
     },
     "memberships": {
       "type": "array",
-      "items": { "$ref": "#/$defs/membership" }
+      "items": {
+        "$ref": "#/$defs/membership"
+      }
     },
     "rls": {
       "type": "object",
@@ -103,18 +149,32 @@
         "memberships"
       ],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "mode": { "enum": ["jwt", "database"] },
-        "tenantClaim": { "$ref": "#/$defs/identifier" },
+        "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_]*$" }
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]*$"
+              },
+              "type": {
+                "type": "string"
+              },
+              "within": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]*$"
+              }
             }
           }
         },
@@ -124,9 +184,15 @@
             "type": "object",
             "required": ["name", "args", "returns", "execute"],
             "properties": {
-              "name": { "$ref": "#/$defs/helperName" },
-              "args": { "type": "string" },
-              "returns": { "type": "string" },
+              "name": {
+                "$ref": "#/$defs/helperName"
+              },
+              "args": {
+                "type": "string"
+              },
+              "returns": {
+                "type": "string"
+              },
               "execute": {
                 "type": "array",
                 "items": {
@@ -138,23 +204,35 @@
         },
         "memberships": {
           "type": "array",
-          "items": { "$ref": "#/$defs/membership" }
+          "items": {
+            "$ref": "#/$defs/membership"
+          }
+        },
+        "customRoles": {
+          "type": "boolean"
         },
-        "customRoles": { "type": "boolean" },
         "roles": {
           "type": "object",
           "required": ["table", "user", "role"],
           "additionalProperties": false,
           "properties": {
-            "table": { "type": "string" },
-            "user": { "$ref": "#/$defs/column" },
+            "table": {
+              "type": "string"
+            },
+            "user": {
+              "$ref": "#/$defs/column"
+            },
             "role": {
               "oneOf": [
-                { "$ref": "#/$defs/role" },
+                {
+                  "$ref": "#/$defs/role"
+                },
                 {
                   "type": "array",
                   "minItems": 2,
-                  "items": { "$ref": "#/$defs/role" }
+                  "items": {
+                    "$ref": "#/$defs/role"
+                  }
                 }
               ]
             }
@@ -164,10 +242,14 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "users": { "$ref": "#/$defs/activeRow" },
+            "users": {
+              "$ref": "#/$defs/activeRow"
+            },
             "scopes": {
               "type": "object",
-              "additionalProperties": { "$ref": "#/$defs/activeRow" }
+              "additionalProperties": {
+                "$ref": "#/$defs/activeRow"
+              }
             },
             "memberships": {
               "type": "object",
@@ -177,7 +259,9 @@
                 "keep": {
                   "description": "The permission keys a membership whose disabledAt column is set still holds.",
                   "type": "array",
-                  "items": { "type": "string" }
+                  "items": {
+                    "type": "string"
+                  }
                 }
               }
             }
@@ -188,19 +272,40 @@
           "required": ["tables"],
           "additionalProperties": false,
           "properties": {
-            "tables": { "type": "array", "items": { "type": "string" } }
+            "tables": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         },
+        "tokenScopes": {
+          "type": "boolean"
+        },
         "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" } }
+            "claim": {
+              "type": "string"
+            },
+            "scopes": {
+              "type": "string"
+            },
+            "tenant": {
+              "type": "string"
+            },
+            "roles": {
+              "type": "string"
+            },
+            "serviceRoles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         }
       }
@@ -216,8 +321,44 @@
       "type": "object",
       "required": ["hook", "grants"],
       "properties": {
-        "hook": { "const": "v1" },
-        "grants": { "const": "v1" }
+        "hook": {
+          "const": "v1"
+        },
+        "grants": {
+          "const": "v1"
+        }
+      }
+    },
+    "names": {
+      "description": "The SQL names the generated RLS exposes to application SQL, unqualified, in `schema`: per scope and per resource, as `resolveNames` gives them. Absent from a manifest written before 0.8.",
+      "type": "object",
+      "required": ["schema", "gucPrefix", "claims", "scopes", "resources"],
+      "properties": {
+        "schema": { "type": "string" },
+        "gucPrefix": { "type": "string" },
+        "claims": {
+          "type": "object",
+          "required": ["tenant", "role"],
+          "properties": {
+            "tenant": { "type": "string" },
+            "role": { "type": "string" }
+          }
+        },
+        "teamScope": { "type": "string" },
+        "scopes": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "resources": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        }
       }
     },
     "requires": {
@@ -250,22 +391,34 @@
           "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" },
+        "user": {
+          "$ref": "#/$defs/user"
+        },
+        "scope": {
+          "$ref": "#/$defs/value"
+        },
+        "id": {
+          "$ref": "#/$defs/column"
+        },
         "role": {
           "oneOf": [
-            { "$ref": "#/$defs/role" },
+            {
+              "$ref": "#/$defs/role"
+            },
             {
               "type": "array",
               "minItems": 2,
-              "items": { "$ref": "#/$defs/role" }
+              "items": {
+                "$ref": "#/$defs/role"
+              }
             }
           ]
         },
         "within": {
           "oneOf": [
-            { "$ref": "#/$defs/column" },
+            {
+              "$ref": "#/$defs/column"
+            },
             {
               "type": "object",
               "required": ["columns"],
@@ -273,61 +426,128 @@
               "properties": {
                 "columns": {
                   "type": "object",
-                  "additionalProperties": { "$ref": "#/$defs/identifier" }
+                  "additionalProperties": {
+                    "$ref": "#/$defs/identifier"
+                  }
                 }
               }
             }
           ]
         },
-        "via": { "$ref": "#/$defs/value" },
-        "expiresAt": { "$ref": "#/$defs/column" },
-        "disabledAt": { "$ref": "#/$defs/column" },
+        "via": {
+          "$ref": "#/$defs/value"
+        },
+        "expiresAt": {
+          "$ref": "#/$defs/column"
+        },
+        "disabledAt": {
+          "$ref": "#/$defs/column"
+        },
         "columns": {
           "type": "array",
-          "items": { "$ref": "#/$defs/identifier" }
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
         }
       }
     },
-    "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "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" } },
+        "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" }
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
     "helperName": {
       "type": "string",
-      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
+      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for|_of)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_token_scope_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
     },
     "column": {
       "type": "object",
       "required": ["column"],
       "additionalProperties": false,
-      "properties": { "column": { "$ref": "#/$defs/identifier" } }
+      "properties": {
+        "column": {
+          "$ref": "#/$defs/identifier"
+        }
+      }
     },
     "role": {
-      "oneOf": [{ "$ref": "#/$defs/value" }, { "$ref": "#/$defs/through" }]
+      "oneOf": [
+        {
+          "$ref": "#/$defs/value"
+        },
+        {
+          "$ref": "#/$defs/through"
+        },
+        {
+          "$ref": "#/$defs/mapped"
+        }
+      ]
+    },
+    "mapped": {
+      "type": "object",
+      "required": ["column", "map"],
+      "additionalProperties": false,
+      "properties": {
+        "column": {
+          "$ref": "#/$defs/identifier"
+        },
+        "map": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "null"]
+          }
+        }
+      }
     },
     "user": {
-      "oneOf": [{ "$ref": "#/$defs/column" }, { "$ref": "#/$defs/through" }]
+      "oneOf": [
+        {
+          "$ref": "#/$defs/column"
+        },
+        {
+          "$ref": "#/$defs/through"
+        }
+      ]
     },
     "through": {
       "type": "object",
       "required": ["column", "through"],
       "additionalProperties": false,
       "properties": {
-        "column": { "$ref": "#/$defs/identifier" },
+        "column": {
+          "$ref": "#/$defs/identifier"
+        },
         "through": {
           "type": "object",
           "required": ["table", "id", "column"],
@@ -337,15 +557,21 @@
               "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" }
+            "id": {
+              "$ref": "#/$defs/identifier"
+            },
+            "column": {
+              "$ref": "#/$defs/identifier"
+            }
           }
         }
       }
     },
     "value": {
       "oneOf": [
-        { "$ref": "#/$defs/column" },
+        {
+          "$ref": "#/$defs/column"
+        },
         {
           "type": "object",
           "required": ["value"],
@@ -353,8 +579,15 @@
           "properties": {
             "value": {
               "oneOf": [
-                { "type": "string" },
-                { "type": "array", "items": { "type": "string" } }
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
               ]
             }
           }

package/skills/permdock/SKILL.md

@@ -49,6 +49,7 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/docs/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`).
+   For ids without loaded rows, `await permdock.decideIds(permission, ids, { data })` loads them through `data(ids)` and decides each in its own tenant.
    ✓ 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.

package/skills/permdock-agents/references/runtimes.md

@@ -30,6 +30,8 @@ export const { toolApproval, capabilityMiddleware, needsApproval } =
 
 Pass `toolApproval` into `generateText` / `ToolLoopAgent`. Wrap the model with `wrapLanguageModel({ model, middleware: capabilityMiddleware({ user }) })` per caller. Use `needsApproval(permissions.post.delete)` only on `WorkflowAgent`. `denied` maps to `'denied'`, `approval-required` to `'user-approval'`, and `'not-applicable'` is never returned ([AI SDK adapter](https://permdock.com/docs/adapters/ai-sdk)). Tools without a permission are hidden and denied unless `unmapped: 'allow'`; to combine PermDock with the app's own confirmation, pass `composeToolApproval(appApproval)` as `toolApproval` instead of wrapping the adapter: the app's function is asked only for calls PermDock grants, and its answer passes through (`undefined` stays not applicable; an unreadable answer denies).
 
+To let the user fix a denial in the loop, pass `stepUp: { at: "https://app.example.com/reauth" }` (`at` optional). An `insufficient-user-authentication` denial, or one that activating a role the user is `eligible` for would grant, then becomes `{ type: 'user-approval', reason, stepUp }`. `stepUp` is `{ kind: 'authentication', acrValues, maxAge }` or `{ kind: 'activation', role, scope, id }`. For an activation, call `activate(permdock, { role, scope, id, reason })` and write `decision.elevation`. The SDK's re-check decides again and runs the tool only when `granted`. Never build a `withStepUp` wrapper. A step-up status has no `token`, so narrow with `'token' in status` before reading it.
+
 ## Claude Agent SDK — `permdock/claude-agent`
 
 ```ts
@@ -117,7 +119,7 @@ server.registerTool(
 );
 ```
 
-`actor.kind` is `'mcp-client'` unless `actorKind` sets another (`'oauth-client'` makes the token the same actor kind `permdock/supabase` and `permdock/jwt` give it, so one delegation covers both), and `delegation` comes from the token's scopes and `authorization_details`. Every `registerTool` / `registerResource` / `registerPrompt` needs a `permission`. Lists are filtered per caller. A missing scope is an `insufficient_scope` step-up (HTTP `403`) naming only the scope the call needs. When the authorization server issues coarse scopes (`mcp:read`), declare them in `definePolicy({ oauthScopes })` instead of expanding scopes yourself: they are expanded into the delegation and named in challenges. Set `resource` to the server's URL so tokens for another audience are refused. Denied calls return `isError: true` with Decision `structuredContent`. `approval-required` parks the call in `store` and returns `isError: true` with the token, or an `input_required` URL request when `approval.at` is set and the client declares URL elicitation; the retried call runs once after approval (token optional under `_meta["dev.permdock/approval"]`, never from tool arguments) ([MCP adapter](https://permdock.com/docs/adapters/mcp)).
+`actor.kind` is `'mcp-client'` unless `actorKind` sets another (`'oauth-client'` makes the token the same actor kind `permdock/supabase` and `permdock/jwt` give it, so one delegation covers both), and `delegation` comes from the token's scopes and `authorization_details`. Every `registerTool` / `registerResource` / `registerPrompt` needs a `permission`, except an MCP Apps `ui://` view: it takes the permission of the tool whose `_meta.ui.resourceUri` names it, and a view no tool links is refused. Never give a view a looser permission than its tool. Lists are filtered per caller. A missing scope is an `insufficient_scope` step-up (HTTP `403`) naming only the scope the call needs. When the authorization server issues coarse scopes (`mcp:read`), declare them in `definePolicy({ oauthScopes })` instead of expanding scopes yourself: they are expanded into the delegation and named in challenges. Set `resource` to the server's URL so tokens for another audience are refused. Denied calls return `isError: true` with Decision `structuredContent`. `approval-required` parks the call in `store` and returns `isError: true` with the token, or an `input_required` URL request when `approval.at` is set and the client declares URL elicitation; the retried call runs once after approval (token optional under `_meta["dev.permdock/approval"]`, never from tool arguments) ([MCP adapter](https://permdock.com/docs/adapters/mcp)).
 
 An MCP server that is not an SDK `McpServer` cannot be wrapped: narrow the tool's `meta` with `isPermission`, filter its tool list with `permdock.mayUse(permission)`, and decide each call with `permdock.decide(permission, args)` in its `authorize` hook. `mayUse` is a listing hint, never a decision.
 

package/skills/permdock-approvals/references/stores-and-resume.md

@@ -31,7 +31,8 @@ The store's `ttl` is the window a request stays open when the call sets none; `r
 - `memoryApprovalStore` is per process. On serverless or with several replicas, implement `ApprovalStore` over the app's database; the Drizzle recipe on the adapter page is the template, and `cloud().approvals` from `permdock/cloud` is the hosted implementation of the same interface. On Postgres or Supabase, set `rls.approvals: true` and use `supabaseApprovalStore(admin, { onOpen })` from `permdock/supabase` over the generated table and functions; grant the functions to the server's role, and put notifications and superseding older requests in `onOpen`.
 - A custom store calls `assertApprover(request, by, requireDistinct, now, verdict.relations)` in `resolve` and computes the next record with `applyApprovalVerdict`, which records each signature's `stage`. `verdict.relations` holds `approverRelationKey` values that the handler, or `resolveApproval(store, token, verdict, { relations, permissions })`, computed with `approverRelations`; a store never derives them. `consume` must be atomic: two concurrent calls never both succeed.
 - When the app's own rules decide who approves (a manager chain, delegates, a quorum it counts), record their verdict with `vouchApproval(store, token, { status, by, rule })` from `permdock/approvals` instead of mirroring those rules in `approvers` or copying the verdict into the request by hand. It resolves the request at once and records `vouched: rule`; the actor, requester and repeat checks still apply. Never take `vouched` from a request body.
-- Run `testApprovalStore(store, { reopen })` from `permdock/testing` on every custom store.
+- Run `testApprovalStore(store, { reopen, capabilities: { expire } })` from `permdock/testing` on every custom store. `reopen` opens a second client over the same backend; `expire(token)` ages one record so the suite checks that a new ask replaces it.
+- `create` replaces a record only when its `status` is `expired` or its `expiresAt` has passed. A pending or resolved record stays, and nothing returns to `pending`.
 - `cancelApprovals` rejects matching pending requests (for example when a session ends).
 
 ## Approval policies as data