permdock 0.0.0 → 0.2.0

package/skills/permdock-credentials/references/tokens-keys-links.md

@@ -0,0 +1,132 @@
+# Tokens, API keys and share links
+
+Owning pages: [JWT adapter](https://permdock.com/docs/adapters/jwt), [authentication](https://permdock.com/docs/concepts/authentication), [API keys](https://permdock.com/docs/concepts/credentials), [link capabilities](https://permdock.com/docs/concepts/capabilities).
+
+## Access tokens — `permdock/jwt`
+
+```ts
+import { subjectFromJwt } from "permdock/jwt";
+
+const subject = await subjectFromJwt(token, {
+  discovery: "https://issuer.example.com",
+  audience: "https://api.example.com",
+});
+```
+
+- Prefer `discovery: '<issuer>'` over a hand-copied `jwks` URL. Set `audience` to the resource identifier. Write algorithms as `Ed25519`, `ES256` or `PS256`; never `EdDSA`, `none` or `RSA1_5`.
+- Keep the default `accept: 'access-token'`, so an ID token never authorises an API call.
+- `jose` is an optional peer. A failure is the anonymous subject, never a throw; the cause is reported through `on('auth')`. A claimed `act` chain that does not nest is anonymous with cause `invalid-chain`.
+- When the app already called RFC 7662 or RFC 9767 introspection, pass the response JSON to `subjectFromIntrospection`. `active` other than `true` is anonymous, and the HTTP call stays the app's.
+- In CI, `subjectFromCiOidc(jwt, { provider: 'github', audience })` returns a `workload` principal, never a user.
+- A Supabase OAuth server token is an `oauth-client` actor. `subjectFromSupabase` drops the OpenID Connect identity scopes (`openid`, `profile`, `email`, `address`, `phone`, `offline_access`) from its delegation, so a token with only those reaches nothing. Let a client act for users with a policy `delegations` entry whose `to` is `{ kind: 'oauth-client', client: '<name>' }`, and map the verified id to that name with `subjectFromSupabase(claims, { clients: { <name>: env.CLIENT_ID } })` (or a function for dynamically registered clients); a literal `{ kind, id }` also works but ties the policy to one environment, never by reading identity scopes as permissions ([Supabase provider](https://permdock.com/docs/adapters/supabase#oauth-server-tokens)).
+
+## API keys and service accounts
+
+```ts
+import { decideCredential } from "permdock";
+import { generateApiKey, hashApiKey } from "permdock/server";
+
+const decision = await decideCredential(
+  permdock,
+  {
+    kind: "service", // or 'user'
+    id: "svc_01J8",
+    tenant: "o_1",
+    roles: ["developer"],
+    permissions: [permissions.repo.read],
+    expiresAt: Math.floor(Date.now() / 1000) + 30 * 86_400,
+  },
+  { settings },
+);
+if (decision.outcome === "granted") {
+  const key = generateApiKey(decision.credential.id);
+  await db.insert(apiKeys).values({
+    id: decision.credential.id,
+    hash: await hashApiKey(key),
+    credential: decision.credential,
+  });
+  return key; // shown once
+}
+```
+
+- Guard the endpoint that creates keys with its own permission (`apiKey.create`).
+- Every key lists at least one permission, with no upper bound. A `user` key is its owner's live rights narrowed to the key, and with `tenant` to the owner's memberships inside that tenant and no global role (never put a tenant id in `ids`, which holds resource ids); a `service` key is a `kind: 'service'` principal whose tenant, roles and permissions must be within the creator's `assignableRoles` / `assignablePermissions` (otherwise `exceeds-creator`). A key cannot mint keys.
+- Tenant rules come from a `SettingsSource` (`memorySettings({ o_1: { credentials: { maxTtl, kinds, approval, allowNoExpiry } } })`). A key without `expiresAt` needs `allowNoExpiry`. `approval: true` makes creation `approval-required`; after approval, call `decideCredential` again with `approved: token`.
+- Store only `hashApiKey(key)`. The key is `pdk_<id>_<secret><checksum>`; `parseApiKey` rejects a bad checksum before any lookup.
+
+Resolve keys on each request:
+
+```ts
+import { apiKeyVerifier, subjectFromApiKey } from "permdock/server";
+
+const resolveKey = subjectFromApiKey({
+  verifier: apiKeyVerifier({ find: (id) => findKeyRow(id) }), // returns { credential, hash }
+  permissions,
+  owner: (id) => loadOwner(id), // the live owner of a user key
+  revoked: (id) => isRevoked(id),
+  settings,
+  sink,
+});
+
+const subject = await resolveKey(bearer, { tenant });
+```
+
+Never pass a `memberships` source to `createPermDock` for a service-key subject: its one membership comes from the credential. `memoryCredentials()` is an in-process store for tests.
+
+When the backend then queries Postgres for the key, put the key's permission keys (and, for a service key, its tenant and roles) in an `api_key` claim and set `rls.apiKeys` in `permdock.config.ts`: the generated helpers cap every allow at the key's permissions and hold a key that names a tenant to that tenant, so RLS agrees with `can()`. The key itself never goes to the database.
+
+When the keys live in better-supabase's `api_keys` table, use `apiKeyVerifier({ keys, manifest, allPermissions })` from `permdock/better-supabase` instead, and create the keys with `createApiKeys({ transport, prefix: "pdk" })`: PermDock parses only its own prefix. A third-party token that better-supabase's `CredentialProvider` hands out goes through `credentialGuard(provider, { permdock, use, revoke? })` from the same entry, so PermDock decides each use.
+
+## Share links
+
+```ts
+import { signCapability } from "permdock";
+import { subjectFromCapability } from "permdock/jwt";
+
+// Declare the link's roles on the resource
+role("guest", [allow(permissions.quote.read, { where: { status: "sent" } })], {
+  on: permissions.quote,
+});
+
+// Mint, behind a guard of its own (quote.share)
+const token = await signCapability(
+  {
+    id: linkId,
+    on: { resource: permissions.quote, id: quote.id },
+    roles: ["guest"],
+    expiresAt,
+  },
+  signer,
+  { audience },
+);
+
+// Resolve
+const subject = await subjectFromCapability(token, {
+  jwks,
+  issuer,
+  audience,
+  revoked,
+  replay,
+  viewer,
+  linkPolicy,
+});
+```
+
+- The result is a `kind: 'link'` principal with one `{ on, roles, via: 'link' }` membership. It never holds a scope or global role.
+- `linkPolicy` returns the tenant's `LinkPolicy` (`maxLifetime`, `redeemers`, `once`). Passing the same policy to `signCapability` refuses to mint a link the resolver would refuse.
+- Never an unguessable id without expiry, and never a security-definer RPC for the guest page.
+
+With Supabase, let RLS serve the link through an exchange, never the link token itself:
+
+```ts
+import { exchangeCapability } from "permdock/supabase";
+
+const accessToken = await exchangeCapability(subject, {
+  key: signingJwk,
+  alg: "ES256",
+  kid: "permdock-links",
+  ttl: 300,
+});
+```
+
+`accessToken` is `role: 'anon'` with a `capability` claim and no `sub`, or `undefined` for anything but a live link. Generate the matching policies with `permdock rls generate --capabilities`.

package/skills/permdock-data/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: permdock-data
+description: Enforces PermDock permissions in database queries and Postgres row-level security. Use when listing rows with permdock.where() and filter(), compiling conditions with toWhere from permdock/drizzle, permdock/prisma or permdock/kysely, guarding Convex functions with permdock/convex, generating or verifying RLS with permdock rls generate, verify or migrate, modelling folders, sub-teams or reporting lines with parent and relation() through a RelationSource, loadRelations or whoCan, or proving query and database parity with ormParity and rlsParity. Also for doctor PD027, PD028, PD031 and PD032.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/adapters/rls
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock data
+
+The same portable conditions decide `can()` in memory, narrow list queries through `where()`, and compile to Postgres RLS. Keep them portable and prove the three agree ([conditions](https://permdock.com/docs/concepts/conditions), [RLS](https://permdock.com/docs/adapters/rls)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`); named scopes and memberships come from the `permdock-tenancy` skill.
+
+## Inputs (find out, or ask before starting)
+
+- The ORM or query layer: Drizzle, Prisma, Kysely, Convex, or raw SQL.
+- Whether Postgres RLS enforces access as well (clients reading tables directly, a data API), and whether the app's SQL or PermDock's policy is the authority.
+- Whether existing policies call hand-written helpers.
+- Object hierarchies: nested folders, sub-teams, reporting lines, account delegates, rows that must not inherit.
+- A test database for parity runs (a container or a branch database).
+
+## Invariants
+
+1. Portable first. Write `where` conditions with the portable operators; a closure is for checks they cannot express, and it is filtered in memory, never in SQL or RLS.
+2. A list query uses `where()` before the query and `filter()` after it. One row is loaded and checked with `assert` or the adapter's `protect`.
+3. Generated RLS never emits `service_role`, and a request runs as `authenticated` or `anon`.
+4. RLS cannot see request `context`. A condition the database must enforce compares a server-set `principal.claims.*` value, never `user_metadata`.
+5. Graph grants walk at most 32 hops (16 by default) and deny with `relation-unavailable` when the relation source is missing or unloaded.
+
+## Workflow
+
+1. **Narrow list queries.** Compile `permdock.where(permission)` with the ORM's `toWhere`, then run `filter` and `pick` on the rows. -> [references/queries-and-rls.md](references/queries-and-rls.md)
+   ✓ A user with no grant gets an empty list, and the query compiles without `non-portable-condition`.
+2. **Model hierarchies, when the product has them.** Give the resource a `parent`, declare the relations principals hold, add `restricted` where rows must not inherit, and grant with `relation(resource, name, { through: 'parent' })`. Pass a `RelationSource` as `relations` and call `loadRelations` before `can` / `filter` when it is async. Use `whoCan` for share dialogs. -> [references/relationships.md](references/relationships.md)
+   ✓ `permdock doctor --only graph` is clean, and a viewer of a parent folder can read a child document.
+3. **Generate or adopt RLS.** Run `permdock rls generate` from the policy, or keep SQL as the authority with `sqlFunction` twins and `rls.functions`, or move hand-written helpers with `permdock rls migrate`. -> [references/queries-and-rls.md](references/queries-and-rls.md#generate-and-verify-rls)
+   ✓ `permdock rls generate --check` passes in CI.
+4. **Verify against a real database.** Run `permdock rls verify --db $DATABASE_URL` with fixtures, `--tree` for graph grants, and `--introspect` against a deployed database.
+   ✓ Every verify run exits `0`.
+5. **Prove parity in tests.** Add `ormParity(policy, scenarios, { run, id })` for each list endpoint and `rlsParity(policy, options)` for RLS tables, from `permdock/testing` ([testing adapter](https://permdock.com/docs/adapters/testing)). Run `testRelationSource` on a custom `RelationSource`.
+   ✓ The query and the database return exactly the rows `filter()` keeps.
+
+## Verify before done
+
+- [ ] No closure only compares fields a portable operator covers (`eq`, `in`, `memberOf`, `sqlFunction`, …); rewrite those as JSON conditions.
+- [ ] An owner-equals-principal `where` on a resource with a matching relation uses `relation()` instead.
+- [ ] No `opaque` RLS grant wraps a named helper; use `sqlFunction` with a twin and map it in `rls.functions`.
+- [ ] No condition the database must enforce reads `context.*` (PD027); on Supabase, `supabase.hook.attrs` lists only server-owned values (PD028).
+- [ ] Graph declarations are walked by a grant (PD031) and nameable in SQL (PD032).
+- [ ] Every list endpoint has an `ormParity` run, every RLS table an `rlsParity` or `rls verify --db` run, and a custom `RelationSource` passes `testRelationSource`.
+
+## Reference index
+
+- [references/queries-and-rls.md](references/queries-and-rls.md): `toWhere` per ORM, `checkRow`, `withSubject`, Convex, `rls generate` / `import` / `verify` / `migrate` flags and config, field views, SQL as the authority.
+- [references/relationships.md](references/relationships.md): `parent`, relation kinds, `restricted`, `links`, `relation(..., { through })`, `RelationSource`, `loadRelations`, `whoCan`, the closure table and `--tree`.
+- Docs: [conditions](https://permdock.com/docs/concepts/conditions), [relationships](https://permdock.com/docs/concepts/relationships), [RLS adapter](https://permdock.com/docs/adapters/rls), [`permdock rls`](https://permdock.com/docs/cli/rls), [Postgres RLS](https://permdock.com/docs/standards/postgres-rls).

package/skills/permdock-data/references/queries-and-rls.md

@@ -0,0 +1,62 @@
+# Queries and generated RLS
+
+Owning pages: [protected queries](https://permdock.com/docs/concepts/policies#protected-queries), [RLS adapter](https://permdock.com/docs/adapters/rls), [`permdock rls`](https://permdock.com/docs/cli/rls), and the ORM pages [Drizzle](https://permdock.com/docs/adapters/drizzle), [Prisma](https://permdock.com/docs/adapters/prisma), [Kysely](https://permdock.com/docs/adapters/kysely), [Convex](https://permdock.com/docs/adapters/convex).
+
+## List queries
+
+```ts
+import { toWhere } from "permdock/drizzle"; // or permdock/prisma, permdock/kysely
+
+export async function listPosts(permdock: PermDock) {
+  const read = permissions.post.read;
+  const rows = await db
+    .select()
+    .from(posts)
+    .where(toWhere(permdock.where(read), posts));
+  return permdock.filter(read, rows).map((row) => permdock.pick(read, row));
+}
+```
+
+- `permdock.where(permission)` narrows the query before it runs. It leaves out closure grants and marks the result `partial`; `filter` then drops what a closure refuses, and `pick` redacts fields.
+- When nothing is granted, `toWhere` returns a constant false expression (no rows). A closure grant cannot compile: `toWhere` throws `PermDockValidationError`.
+- `toWhere(condition, table, { columns })` maps schema fields to differently named columns. Graph grants need `{ relations: { closure: 'permdock.permdock_closure' } }`, otherwise a `related` node throws `non-portable-condition`.
+- `checkRow` (Drizzle) answers one row as `{ found: false }` or `{ found: true, granted }`, so a handler can tell `404` from `403` with one query.
+- Prisma also exports `permdockExtension`. Drizzle, Prisma and Kysely export `withSubject`, which runs a transaction as the subject (`set local role` plus claims) so RLS sees it; its `dialect` must match `rls generate`.
+- Convex: `createPermDock` from `permdock/convex` returns `withPermDock` and `snapshotQuery`. Identity comes from `ctx` only; function arguments never influence the subject.
+
+## Generate and verify RLS
+
+```bash
+pnpm exec permdock rls generate --target sql --dialect supabase --out migrations/rls.sql
+pnpm exec permdock rls generate --target drizzle --dialect supabase
+pnpm exec permdock rls import --sql migrations/rls.sql --out src/permissions.generated.ts
+pnpm exec permdock rls verify --fixtures rls.fixtures.json
+pnpm exec permdock rls verify --db $DATABASE_URL --fixtures rls.fixtures.json
+pnpm exec permdock rls verify --introspect --db $DATABASE_URL
+```
+
+- List the scope instances a permission reaches in process with `permittedIds(permdock, permission, scope, { within })`, never a loop of `can` over memberships with a made-up row.
+- Generated policies call `permdock_has('<key>')` and one `permitted_<scope>_ids('<key>')` per declared scope, which Postgres runs once per statement. Hand-written policies that only need membership (an organization switcher) call `member_<scope>_ids()` instead of inventing a permission key. Trusted SQL that acts for a stored user (a job, a trigger, a deferred approval) calls `permdock_has_for(p_user, '<key>')` and `permitted_<scope>_ids_for(p_user, '<key>')` in `database` mode, or the generated `permitted_<resource>_rows_for`, never a hand-written function that rewrites `request.jwt.claims`. With `rls.rowHelpers`, a hand-written policy or function that needs the rows a permission reaches through the graph calls `permitted_<resource>_rows('<permission key>')` instead of restating closure walks, link hops and `includes`. A table's own `select` or `insert` policy calls the row-valued `permitted_<resource>_row(<table>, '<permission key>')` instead, so `insert ... returning` sees the new row. Hand-written policies and functions that apply no row condition call `permitted_<scope>_ids_by_permission('<permission key>')` or `permdock_has_permission('<permission key>')` instead of spelling a positional `#n` grant key. A screen or RPC that checks many permissions on one organization calls `permitted_<scope>_permission_keys(<id>)` once (or `(<id>, array['<key>', ...])` for a few keys) instead of one helper call per key. A role editor or admin screen lists a role's keys with `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)` (declared roles, and custom roles of the caller's tenant in `database` mode) and the catalog with `permdock_permission_keys()` (`permdock_permission_keys('<scope>')` for the keys a role on that scope can hold), instead of joining `role_permissions` and the custom-role tables by hand; server code reads any tenant's roles with `permdock_trusted_role_permissions`, granted through `rls.trustedReaders`. Set `--tenant-type` (or `rls.tenantType`, `rls.scopeTypes`) to the scope columns' types.
+- `--authorize database` (default) reads the membership tables per statement; map each under `rls.memberships.scopes.<scope>` with `columns` for its id and its ancestors', and `via` so roles with `for` apply: a column name, or `{ value: 'staff' }` when every row has that kind (never add a generated column for it). `--authorize jwt` reads token claims and stays stale until the token refreshes; keep the token lifetime at 3600 seconds or less (PD019).
+- The helpers narrow to the tenant claim (`rls.tenantClaim`) whenever the token carries one; the Supabase hook writes it from `activeFrom`. When the app takes the tenant from the URL and one session spans tenants, set `rls.tenants: 'all'` so the database admits every member tenant, and keep filtering each query by the URL's tenant.
+- `--policy-per-role` keeps one policy per role for review. `--custom-roles` (or `rls.customRoles: true`) resolves tenant-defined roles inside the `permdock_ceiling` view. In `database` mode, save a custom role with `permdock_replace_custom_role_grants(tenant, scope, scope_id, role, allow, deny, include)` and rename or delete it with `permdock_rename_custom_role_grants` and `permdock_delete_custom_role_grants`, never with hand-written `security definer` functions or direct writes; failures raise `22023` or `42501` with the reason as the `hint`. A platform custom role passes a null tenant and scope `global`. Seeds, jobs and backends with no member caller use the `permdock_trusted_*` variants, which keep the definition checks; grant `execute` on them to a backend role in a migration of your own, never to `authenticated`. Set `rls.customRoleWrites.requires` to the permission your role editor asserts (or `'manageRoles'`) so the database refuses members who may not manage roles (`manage-roles`).
+- `--force` (or `rls.force: true`) only when the app connects as the table owner. Create views over RLS tables `with (security_invoker = true)` (PD022).
+- When read grants set `fields` and clients read tables directly, add `--fields views --revoke-columns`: clients read `<table>_visible`, whose restricted columns are null unless a grant covers them. PD030 names columns still readable.
+- `rls.suspension` drops suspended users' roles and memberships of suspended scope instances, live in both modes. `scopes.<scope>.keep: [permissions.org.restore]` lets members of a suspended instance still hold those permissions (restore, cancel deletion, export) in the helpers, `authorize()`, the token hook and in process, where the membership carries `keep`; `doctor` PD061 lists them.
+- When support or impersonation tokens (an `act` claim) reach the Data API, set `rls.readOnlyActors: true`: each table and write command the policies grant gets a restrictive `{table}_{op}_read_only_actors` policy that refuses the write unless `act.read_only` is `false`. Never hand-write that policy per table.
+- When a backend queries Postgres for a verified API key, set `rls.apiKeys` and put the key in the `api_key` claim (`scopes` as permission keys, `tenant` and `roles` for a key that belongs to a tenant): the helpers cap every allow at the scopes and treat a tenant key without `sub` as a service principal of that tenant. A user key whose claim names a `tenant` is held to that tenant even with `rls.tenants: 'all'`, and `permdock_has` is false for it. Never write a `has_scope` check per policy.
+- On Supabase every generated helper and policy reads the subject through `permdock_user_id()`: the `sub` in `request.jwt.claims`, and null for the empty `sub` of a tenant service key. It ignores the legacy `request.jwt.claim.sub` setting; SQL that impersonates a user sets `request.jwt.claims`. A hand-written policy such a token reaches calls `(select permdock.permdock_user_id())`, never `auth.uid()`, which fails the uuid cast.
+- `rls.assignments` puts a `permdock_assignment` trigger on each mapped membership table, the global-roles table `rls.roles` and each table in `tables`; `ownRole: 'refuse'` (or a map of tables) also refuses a client write to the caller's own row. `doctor` PD064 names a guarded table no migration puts the trigger on.
+- SQL that assigns roles calls `permdock_can_assign_any(role, tenant, scope, scope_id)`, which covers declared and custom roles; SQL acting later for a stored user (an invitation accept re-checking the inviter) calls `permdock_can_assign_any_for(user, ...)`. `permdock supabase inspect` lists both in the manifest's `rls.helpers`.
+- Index suggestions (the `indexes` part of `--split`, or `index suggestion` warnings) cover only the columns the policies and helpers look rows up by. Add `--db $DATABASE_URL` to `generate` so it leaves out indexes an existing index already leads with and columns the table lacks; never hand-copy a suggestion that duplicates an existing composite index.
+- Never emit `service_role`. Fixtures may carry `memberships`, `tenant` and `customRoles`.
+
+## SQL as the authority
+
+When the database already holds the rules, skip `generate`. Map each helper in `rls.functions`, write `sqlFunction` twins in the policy, and fail CI on `rls verify --db`. `--inline-functions` inlines the twin for targets that cannot call a SQL function.
+
+When hand-written policies call the app's own helpers (`org_ids_with_permission`, `has_org_permission`), map each under `rls.migrate.helpers` with its `form` (`ids`, `row`, `scoped`, `global`, `membership`) and the legacy keys under `rls.migrate.keys` or `prefixes`. Run `permdock rls migrate`, read the skipped calls, and apply with `--write`. Generate with `--helpers-only` while the policies stay hand-written. A `row-conditions` skip means that table's policy should be generated, not migrated.
+
+## Attributes RLS cannot see
+
+A grant condition on `context.*` cannot be enforced by the database (PD027). Compare with a server-set `principal.claims.*` claim instead, never one from `user_metadata`. On Supabase, `supabase.hook.attrs` lists only server-owned columns or `app_metadata.<key>` entries clients cannot update (PD028). A check that must refuse a sign-in (single sign-on enforcement, a locked account) goes in `supabase.hook.before` as a schema-qualified `(event jsonb) returns jsonb` function the generated hook calls first; never a second hook or a hand edit of the generated one. The hook, declarative schemas (`--split`) and `fromTable` / `fromJunction` membership sources are on the [Supabase adapter](https://permdock.com/docs/adapters/supabase) and [Supabase hook](https://permdock.com/docs/adapters/supabase-hook) pages.

package/skills/permdock-data/references/relationships.md

@@ -0,0 +1,67 @@
+# Relationship graph
+
+Owning page: [relationships](https://permdock.com/docs/concepts/relationships). Named scopes are tenancy (fixed levels); the graph is the objects under them, with no fixed depth.
+
+## Declare
+
+```ts
+export const permissions = definePermissions({
+  doc: resource(Doc, {
+    actions: ["read", "update"],
+    parent: { field: "folderId", resource: "folder" },
+    relations: { owner: "ownerId" },
+  }),
+  folder: resource(Folder, {
+    actions: ["read", "share"],
+    parent: { field: "parentId", resource: "folder" },
+    relations: {
+      editor: { edge: "folder_editors" },
+      viewer: { edge: "folder_viewers", expiresAt: "expires_at" },
+    },
+    restricted: "restricted",
+  }),
+});
+```
+
+| Relation   | Declared as                                                | Held when                                                                                |
+| ---------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Field      | `owner: 'ownerId'`                                         | the row's field is the principal's id                                                    |
+| Edge table | `{ edge, object?, subject?, expiresAt?, match?, groups? }` | a row of `edge` links the object and the principal, and has not expired                  |
+| Principal  | `{ principal, period? }`                                   | the row's column is the principal's id, inside `period` (a manager, an account delegate) |
+| Implied    | `{ includes: ['editor'] }`                                 | the principal holds a listed relation                                                    |
+
+`groups` lets an edge row name a team or another group: `{ column: 'kind', resources: { team: 'member' } }` when one column names the kind, or `{ resources: { team: { relation: 'member', subject: 'team_id' } } }` when the share table keeps each subject kind in its own typed column.
+
+A resource that parents itself makes a chain. `restricted` names a boolean column: a restricted row is reached only by grants on itself, never through its ancestors or its links. `restricted: { field, stops: ['parent'] }` closes only the paths it lists (`'parent'` and link names), for example a folder hidden from shares above it but still readable by everyone with drive access; a closed link also stays closed for the rows below a restricted row, within 32 levels. `links` names to-one references a grant can cross with `through: ['folder', 'team']`.
+
+## Grant
+
+```ts
+grants: [
+  allow(permissions.doc.read, { to: relation(permissions.doc, 'owner') }),
+  allow(permissions.doc.read, {
+    to: relation(permissions.folder, 'viewer', { through: 'parent', depth: 16 }),
+  }),
+],
+```
+
+Add `requires: permissions.file.read` to a graph grant to count a share only where the user also holds that permission through a role in the row's organization; a list (`requires: [permissions.file.read, permissions.file.download]`) requires each. `to: inherit(permissions.drive.read, { through: ['drive'] })` grants on a row wherever the subject may read the drive its `drive` link points to, by any grant of `drive.read`; the source needs `row`, and `rls generate` writes the target's `permitted_<resource>_rows`. `depth` defaults to 16 and is at most 32. An array in `to:` is an intersection, so "owner or viewer" is two `allow` grants. Prefer `relation()` over `where: { authorId: principal.id }` when the resource declares the relation.
+
+## Load
+
+Pass `relations: memoryRelations(permissions, { rows, edges })` in tests, or a `RelationSource` (`ancestors`, `related`) over the app's tables, to `createPermDock`. Evaluation stays synchronous; with an async source, call `await permdock.loadRelations(permission, rows)` before `can` or `filter`. Without a source, or with one that threw, graph checks deny with `relation-unavailable`; a chain past `depth` denies with `relation-depth`. Answers are cached per instance, never at module level.
+
+## Share dialogs
+
+`const { holders, complete } = await permdock.whoCan(permission, row)` lists who holds a permission on one object and how. Show `complete: false` honestly: some holders could not be listed. `whoCan` never grants.
+
+## In Postgres
+
+`permdock rls generate` emits the `permdock_closure` table, its statement triggers and `permitted_<resource>_ids(relation)` helpers. Snapshots carry no graph: graph grants are `portable: false` on the client and go to the decision endpoint. Check with:
+
+```bash
+pnpm exec permdock rls verify --tree --db $DATABASE_URL
+pnpm exec permdock doctor --only graph
+```
+
+`--tree` seeds a generated object graph in a rolled-back transaction and compares it with `can()` per principal. PD031 flags a self-parent no `through: 'parent'` grant walks, or a `restricted` column no graph grant reaches; PD032 flags a graph resource RLS cannot name.

package/skills/permdock-tenancy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: permdock-tenancy
+description: Models tenants, memberships and role rules in PermDock. Use when declaring named scopes (organizations, workspaces, customers inside an organization), loading memberships through a MembershipSource, putting a role on one scope, keeping an owner per organization with min, max or transferOnly, controlling who hands out which role with assigns and for, checking a membership change with decideRoleChange, letting tenant admins define custom roles with customRoles and validateCustomRole, or fixing doctor PD023, PD025 or PD026 and denials such as tenant-mismatch, last-holder or not-assignable-by.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/concepts/scopes
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock tenancy
+
+A policy declares its scopes in order (an organization, the customers inside it). A role is held at one scope, a membership names one instance of that scope, and a grant reaches a row only through that scope's key. Roles never cascade between scopes ([named scopes](https://permdock.com/docs/concepts/scopes), [tenancy](https://permdock.com/docs/concepts/tenancy)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- The tenant levels, outermost first, and the row column that holds each id (`organization_id`, `customer_id`).
+- Where memberships are stored and how the app loads them: token claims from a `subjectFrom*` provider, or the app's tables.
+- The membership kinds (`via`): staff, contact, guest, partner, support.
+- Which role manages each scope, who may hand out which role, and which roles a contact or guest may never hold.
+- Whether tenant admins define their own roles.
+
+## Invariants
+
+1. Memberships and custom roles come only from a `subjectFrom*` provider, the policy's `subject` or `context` function, a `MembershipSource` or a `RoleSource`. Never from a request body, an unsigned header, a model argument or a CLI flag.
+2. A requested tenant with no matching membership is no tenant, never a default one. Team and tenant ids are identifiers, never display names.
+3. No cascade. An organization owner sees no customer portal unless they also hold a contact membership, and a global role never reaches scoped rows. An instance check without a row answers from first-scope memberships only; a nested membership needs the row or `permdock.team(id)`. A collection check (`create`, `list`) still answers from any membership in the tenant; for a staff-only guard pass `{ scope: '<first scope>' }` as the decide option.
+4. Role rules live on the role (`min`, `assigns`, `for`), not in handlers. `decideRoleChange` takes the actor from the instance and never writes.
+5. A custom role never exceeds the ceiling of declared `assignable` roles in its scope. Its grants carry no condition, approval or limit of their own; a `level` picks a condition the resource declares in code.
+
+## Workflow
+
+1. **Declare the scopes.** Add them to `definePolicy` in order, each with its row `key` and, after the first, `within`:
+
+   ```ts
+   definePolicy(
+     { permissions, roles },
+     {
+       scopes: {
+         organization: { key: "organization_id" },
+         customer: { key: "customer_id", within: "organization" },
+       },
+       roles: [
+         role(roles.admin, adminGrants, { on: "organization" }),
+         role(roles.contact, contactGrants, { on: "customer" }),
+       ],
+       subject,
+     },
+   );
+   ```
+
+   ✓ `definePolicy` accepts the scopes, and each role names one scope with `on`.
+
+2. **Give resources their scope keys.** Every resource a scoped grant touches declares a `memberOf` relation per scope key it carries, for example `relations: { organization: { field: 'organization_id', memberOf: 'organization' } }`.
+   ✓ `definePolicy` does not throw for a missing `memberOf` relation.
+3. **Load memberships.** Return memberships as `{ scope, id, within, roles, via, expiresAt }` from the subject resolver, or pass a `MembershipSource` (one, or an array) as `memberships` on `createPermDock`. A person's access ending is the membership's `expiresAt`.
+   ✓ `permdock doctor` reports no PD025 for the `doctor.memberships` fixture.
+
+   An organisation role that reaches only the principal's teams is an organisation role with `where: { team_id: { in: principal.claims.team_ids } }`, not a team role. On Supabase, write the claim with `supabase.hook.claims` ([team reach](https://permdock.com/docs/concepts/tenancy#organisation-roles-with-team-reach)).
+
+4. **Put ownership on the roles.** Set `min: 1` on the role that manages each scope, `assigns` for who hands out what, `for: ['staff']` on admin-like roles, and `meta.audience` for the surface. Every server action that changes a membership calls `permdock.decideRoleChange(...)` with the target's current membership and the holder count before it writes. -> [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md)
+   ✓ PD026 is clean, and removing the last owner is denied with `last-holder`.
+5. **Custom roles, when tenant admins define roles.** Keep declared roles small and mark them in `defineRoles` (`editor: { on: 'organization', assignable: true }`). Pass a `RoleSource` as `customRoles`, build the editor from `useAssignablePermissions()`, and save through a server action that runs `validateCustomRole`. -> [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md#custom-roles)
+   ✓ PD023 is clean, and saving a role with a permission outside the ceiling is refused.
+6. **Test.** Add `describePolicy` rows for a member of another tenant, a contact reaching an organization row, and a role change that breaks `min` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testMembershipSource` and `testRoleSource` from `permdock/testing` on custom sources. For list queries and RLS over scoped tables, follow the `permdock-data` skill.
+   ✓ The tests pass.
+
+## Verify before done
+
+- [ ] No membership, tenant or role is read from a request body, tool argument, unsigned header or `user_metadata`.
+- [ ] Each scope's managing role sets `min: 1` (PD026), and admin-like roles set `for` so contact, guest or partner memberships cannot hold them.
+- [ ] No `assigns` list lets a role appoint a role ranked above it.
+- [ ] Every server action that writes a membership role calls `decideRoleChange` with a `holders` count from the store, never a guess.
+- [ ] Every custom-role save runs `validateCustomRole` and checks `assignablePermissions()`. No single assignable `admin` role makes the ceiling the whole product.
+- [ ] Custom `MembershipSource` and `RoleSource` implementations pass `testMembershipSource` / `testRoleSource`.
+
+## Reference index
+
+- [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md): role options, `decideRoleChange` input and denial reasons, the SQL objects RLS uses, and the custom-role shape, ceiling and editor.
+- Docs: [named scopes](https://permdock.com/docs/concepts/scopes), [tenancy](https://permdock.com/docs/concepts/tenancy), [ownership](https://permdock.com/docs/concepts/ownership), [custom roles](https://permdock.com/docs/concepts/custom-roles), [extension interfaces](https://permdock.com/docs/concepts/extension-interfaces).

package/skills/permdock-tenancy/references/ownership-and-custom-roles.md

@@ -0,0 +1,89 @@
+# Ownership and custom roles
+
+Owning pages: [ownership](https://permdock.com/docs/concepts/ownership) and [custom roles](https://permdock.com/docs/concepts/custom-roles).
+
+## Role options
+
+```ts
+const staff = { for: ["staff"], meta: { audience: "staff" } } as const;
+
+roles: [
+  role(roles.owner, ownerGrants, {
+    on: "organization",
+    ...staff,
+    min: 1,
+    assigns: ["owner", "admin", "member", "viewer", "contact"],
+  }),
+  role(roles.admin, adminGrants, {
+    on: "organization",
+    ...staff,
+    assigns: ["member", "viewer", "contact"],
+  }),
+  role(roles.contact, contactGrants, {
+    on: "customer",
+    for: ["contact"],
+    meta: { audience: "portal" },
+  }),
+];
+```
+
+| Option          | Meaning                                                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`           | Fewest holders each scope instance keeps (default `0`). Removing the last owner is refused.                                              |
+| `max`           | Most holders an instance may have.                                                                                                       |
+| `transferOnly`  | Once an instance has holders, the role only moves from one holder to another.                                                            |
+| `assigns`       | Roles a holder may assign and revoke. Once any role declares `assigns`, this graph replaces the held-grant rule for `assignableRoles()`. |
+| `for`           | Membership kinds (`Membership.via`) that may hold the role. A membership with another `via`, or none, grants nothing through it.         |
+| `exclusiveWith` | Roles nobody may hold together with this one in the same instance (PD018).                                                               |
+| `meta.audience` | The surface the role's holders use; `permdock.audiences()` and `snapshot.audiences` report it and never grant.                           |
+
+`min`, `max` and `transferOnly` need a named-scope `on`.
+
+## Checking a role change
+
+```ts
+const result = permdock.decideRoleChange({
+  kind: "assign", // 'assign' | 'revoke' | 'transfer'
+  role: roles.admin,
+  scope: "organization",
+  id: "o_acme",
+  target: { id: "u_bob", via: "staff", roles: ["member"] }, // their membership there now
+  holders: await countHolders(memberships, {
+    scope: "organization",
+    id,
+    role: "owner",
+  }), // from MembershipSource.list
+});
+// { outcome: 'granted', change, role } or { outcome: 'denied', change, denials }
+```
+
+The actor is the instance's own subject; nothing in the change stands in for it. `decideRoleChange` never writes. Without a valid `holders` count, a role with `min`, `max` or `transferOnly` is denied. Denial reasons: `last-holder`, `max-holders`, `transfer-only`, `not-assignable-by`, `self-demotion`, `not-allowed-for-membership`, `conflicting-role`.
+
+For a role on a nested scope that the subject holds nothing at, pass `within` and `{ trusted: true }` only after loading the ancestors from the app's own store.
+
+Generated RLS applies the same rules at commit, with triggers on the scope's `rls.memberships` table or on the tables of its `fromTable` / `fromJunction` sources (base tables, not views). Map `rls.memberships.scopes.<scope>.via` so the helpers apply `for`, and use `permdock_can_assign(role, organization_id::text)` in the membership table's own insert policy, or `permdock_can_assign_any(role, organization_id, 'organization', organization_id::text)` when the role may be a custom one. Set `rls.assignments` to have triggers check every client write to the membership tables, the global-roles table `rls.roles` and an invitations table, and `ownRole: 'refuse'` to refuse a client write to the caller's own row; never keep a hand-written trigger for either. The SQL is owned by the `permdock-data` skill.
+
+## Custom roles
+
+```ts
+type CustomRole = {
+  tenant: string; // absent when scope is 'global'
+  scope?: string; // default: the first scope; 'global' for a platform role
+  id?: string; // pins it to one instance
+  name: string;
+  includes?: string[]; // declared roles to start from
+  grants?: { permission: string; effect?: "allow" | "deny"; level?: string }[];
+};
+```
+
+- The ceiling of a scope is the code allows of the declared roles marked `assignable` in that scope. A custom role never exceeds it, and hosted grants never widen it.
+- An own allow inherits the conditions of the ceiling grants for that permission. To keep a narrower condition ("own posts only"), include the declared role that has it.
+- A resource may declare `levels: { own: { ownerId: principal.id }, team: { teamId: { in: principal.teamIds } }, all: {} }`. A grant `{ permission: 'job.read', level: 'team' }` ANDs that condition into the ceiling grant. An undeclared level, or a level on a collection action, is dropped as `unknown-level` and removes the permission; a level on a deny is `condition-not-allowed`. `permdock.assignableLevels(leaf)` lists the levels the subject may hand out.
+- An own deny removes the permission from this custom role only. Deny it in code when it must win across roles.
+- Pass a `RoleSource` (`memoryRoleSource(roles)` in tests), or a `RoleSourceFactory` `(subject) => RoleSource` when the source reads one principal's roles, as `customRoles` on `createPermDock` or any adapter. To add every role of a tenant on a role-management request, `await permdock.derive({ customRoles })` instead of building a second instance. Build it with `customRoleSource({ rolesOf })`, where `rolesOf(tenant)` reads every custom role of the tenant, not only the held ones: `assignableRoles` and `decideRoleChange` see only what the source returns. `{ read: 'held', policy }` skips the read on requests that never manage roles. Check it with `testRoleSource(source, { every })`.
+- `permdock.assignableRoles({ tenant })` lists declared roles, then the tenant's custom roles whose every permission and level the subject may hand out at the custom role's scope. `decideRoleChange` assigns and revokes a custom role like a declared one, with no holder count; it inherits `for` and `exclusiveWith` from its included roles.
+- `permdock.assignablePermissions({ tenant })` is the ceiling intersected with what the subject holds. `useAssignablePermissions()` in `permdock/react` builds the editor from it.
+- The save action runs `validateCustomRole(policy, role)` and refuses the role when `ok` is false or `permissions` contains a key outside `assignablePermissions()`. `dropped` names each entry left out (`unknown-permission`, `outside-ceiling`, `condition-not-allowed`, `unknown-level`, `unknown-role`).
+- A platform custom role (`scope: 'global'`, no `tenant`, `team` or `id`) is held through `principal.roles` and capped by the allows of declared global roles marked `assignable`. `RoleSource.globalRoles({ held })` returns them; `customRoleSource(reader, { read: 'held', policy })` skips that read while every held global role is declared.
+- A stored grant under a key renamed with `definePermissions(..., { renamed })` still resolves; `validateCustomRole` lists it in `renamed` as `{ from, to }`, and `permdock doctor` PD055 prints the `update` that rewrites it.
+- For generated RLS, add `--custom-roles` (or `rls.customRoles: true`) to `permdock rls generate`. Platform roles are rows with `scope = 'global'` and a null `tenant_id`, or the top-level `role_grants` claim in `jwt` mode. With levels, `custom_role_permissions` gains a `level` column and the claim writes `key@level`.

package/skills/permdock-wire/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: permdock-wire
+description: Adds PermDock authorization to a TypeScript app, from definitions to the first guard. Use when installing permdock, adding permissions, roles, plans, RBAC or access control, writing definePermissions, definePolicy or createPermDock, guarding a route, Server Action, procedure or React component, adding usage limits, plan gates or time-limited grants, or running permdock collect and doctor for the first time.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.com/docs/getting-started/quick-start
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# Wire PermDock
+
+Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (rules) and the factory file, then one check on the path the user asked for ([quick start](https://permdock.com/docs/getting-started/quick-start)). Import paths and identifiers follow the [naming convention](https://permdock.com/docs/getting-started/naming).
+
+## Inputs (find out, or ask before starting)
+
+- The framework: Next.js, Hono, Express, Fastify, Elysia, Nest, Node, tRPC, oRPC, an AuthZEN PDP, Vite with React, Vue, Svelte or Solid, React Native, or a collect-only framework (Nuxt, Astro, React Router, TanStack Start, Effect).
+- The Standard Schema validator already in the repo: Zod, Valibot, ArkType, Effect Schema.
+- Where the signed-in user comes from (the session or a verified token) and which roles and plans exist.
+- The first path to guard.
+
+## Invariants
+
+1. Permissions are references (`permissions.post.update`), never strings. Roles and plans are typed leaves (`roles.owner`, `plans.pro`).
+2. Outcomes are `granted`, `denied` or `approval-required`. Anything unknown, invalid or thrown denies, and a matching `deny` wins over every `allow`.
+3. `policy.ts` is server-only. Client entries import `permissions.ts`, snapshots and hooks only.
+4. The subject comes from a trusted resolver (`subjectFrom*` or the server session), never from a request body, header the client sets, or model output.
+5. Portable `where` conditions first; a closure only when no portable operator expresses the rule.
+
+## Workflow
+
+1. **Detect.** Find the framework and the validator. Collect-only frameworks use `permdock/unplugin` for collect and `permdock/server` (or the matching HTTP adapter) at runtime; never add a per-vendor package.
+   ✓ The adapter import path (`permdock/<framework>`) and the validator import are named.
+2. **Define.** Create `src/permissions.ts`. Importable everywhere; no rules, no secrets.
+
+   ```ts
+   import {
+     definePermissions,
+     defineRoles,
+     definePlans,
+     resource,
+     crud,
+   } from "permdock";
+   import { Post } from "./schemas";
+
+   export const permissions = definePermissions({
+     post: resource(Post, crud({ relations: { author: "authorId" } })),
+   });
+   export const roles = defineRoles({ member: {}, admin: {} });
+   export const plans = definePlans({ pro: {} });
+   ```
+
+   ✓ Every resource the first guard needs has a leaf; instance actions sit in `actions`, list and create in `collection`.
+
+3. **Policy.** Create `src/policy.ts`. Prefer `grants` with `to:` selectors (`anyone()`, `authenticated()`, `relation()`, a role or plan leaf, `actor()`, `assurance()`); `role(roles.member, …)` sugar also works.
+
+   ```ts
+   import { definePolicy, role, allow, principal, relation } from "permdock";
+   import { permissions, roles } from "./permissions";
+
+   const member = role(roles.member, [
+     allow(permissions.post.read),
+     allow(permissions.post.list),
+     allow(permissions.post.create),
+     allow(permissions.post.update, {
+       to: relation(permissions.post, "author"),
+     }),
+     allow(permissions.post.delete, {
+       where: { authorId: principal.id },
+       approval: "human",
+     }),
+   ]);
+
+   export const policy = definePolicy(
+     { permissions, roles },
+     {
+       roles: [member],
+       principal: (user) => user && { id: user.id, roles: user.roles },
+     },
+   );
+   ```
+
+   Short policy features that need no other skill -> [references/policy-options.md](references/policy-options.md): usage limits, `disclosure: 'hide'`, plan gates, `validFrom` / `validUntil`, step-up with `assurance()`.
+   ✓ At least one role grants the first guard's permission, and no client entry imports `policy.ts`.
+
+4. **Factory.** Create `src/permdock/server.ts` (or the adapter's documented factory file) with `createPermDock` from `permdock/<framework>`. Copy the exact return names. -> [references/adapters.md](references/adapters.md)
+   ✓ The factory file compiles and exports the adapter's public members.
+5. **Guard.** Add one check on the path the user asked for: `assert` or `protect` / `getPermission` with a permission reference on the server, `<Protected permission={permissions.post.update}>` inside `PermDockProvider` in React.
+   ✓ That path cannot run without a `granted` decision, and the adapter handles a denial (Problem Details or fallback UI).
+6. **Check.** Run `permdock collect`, `permdock catalog`, `permdock usage` and `permdock doctor`, and add `permdock collect --check` to CI. For a Vite SPA, Expo or another framework without `'use client'`, set `doctor.clientEntries` to the client source globs so PD001 checks them. When client code lives outside `collect.srcPath`, list every source folder in `doctor.srcPath` instead of widening the catalog. Add a `describePolicy` suite from `permdock/testing` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). -> [references/policy-options.md](references/policy-options.md#cli-starting-points)
+   ✓ Collect and doctor findings are fixed, or the three files typecheck and one matrix test passes.
+
+## Next skills
+
+Install each with `npx skills add ScaleDockHQ/PermDock --skill <name>` when the app needs it:
+
+- `permdock-agents`: AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A and WebMCP tool maps, actors and `delegation`.
+- `permdock-approvals`: `approval: { by }`, quorum, escalation, `staleOn`, approval stores and the resume flow.
+- `permdock-tenancy`: named scopes, memberships, ownership rules (`min`, `assigns`, `for`) and custom roles.
+- `permdock-data`: `where()` and `filter()` in ORM queries, generated RLS, relationship graphs, parity tests.
+- `permdock-credentials`: `subjectFromJwt`, API keys and service accounts, share links.
+- `permdock-audit`: review the result or a pull request.
+
+## Verify before done
+
+- [ ] No string permission keys in app code; every check passes a reference.
+- [ ] `policy.ts` is imported only from server code, and PD001 is clean.
+- [ ] The subject resolver reads only the server session or a verified token.
+- [ ] `permdock collect --check` runs in CI, and a `describePolicy` suite covers the new grants.
+
+## Reference index
+
+- [references/adapters.md](references/adapters.md): factory shapes for Next.js, HTTP frameworks, RPC frameworks, UI frameworks, AuthZEN, OpenAPI, OpenTelemetry, SCIM, Cloud, Better Auth, Clerk, Supabase, the remote PDP and collect-only frameworks.
+- [references/policy-options.md](references/policy-options.md): limits, disclosure, plans, validity windows, step-up, and CLI starting points (OpenAPI import, Arazzo, Cloud push).
+- The `permdock` skill: the mental model, `explain` for an unexpected denial, and the docs MCP.
+- Docs: [policies](https://permdock.com/docs/concepts/policies), [conditions](https://permdock.com/docs/concepts/conditions), [decisions](https://permdock.com/docs/concepts/decisions), [adapters](https://permdock.com/docs/adapters).