Debugging Permissions

Copy markdown

# Debugging Permissions Given that permissions are defined in their own file and internally applied to queries, it might be hard to figure out if or why a permission check is failing. ## Read Permissions You can use the `analyze-query` utility with the `--apply-permissions` flag to see the complete query Zero runs, including read permissions. ```bash npx analyze-query --schema-path='./shared/schema.ts' --query='issue.related("comments")' --apply-permissions --auth-data='{"userId":"user-123"}' ``` If the result looks right, the problem may be that Zero is not receiving the `AuthData` that you think it is. You can retrieve a query hash from websocket or server logs, then ask Zero for the details on that specific query. Run this command with the same environment you run `zero-cache` with. It will use your `upstream` or `cvr` configuration to look up the query hash in the cvr database. ```bash npx analyze-query --schema-path='./shared/schema.ts' --hash='3rhuw19xt9vry' --apply-permissions --auth-data='{"userId":"user-123"}' ``` > The printed query can be different than the source ZQL string, because it is rebuilt from the query AST. But it should be logically equivalent to the query you wrote. ## Write Permissions Look for a `WARN` level log in the output from `zero-cache` like this: ``` Permission check failed for {"op":"update","tableName":"message",...}, action update, phase preMutation, authData: {...}, rowPolicies: [...], cellPolicies: [] ``` Zero prints the row, auth data, and permission policies that was applied to any failed writes. > The ZQL query is printed in AST format. See [Query ASTs](https://zero.rocicorp.dev/docs/debug/query-asts) to convert it to a more readable format.

Or, for AI assistants

ALWAYS readllms.txtfor curated documentation pages and examples.

Given that permissions are defined in their own file and internally applied to queries, it might be hard to figure out if or why a permission check is failing.

Read Permissions

You can use the analyze-query utility with the --apply-permissions flag to see the complete query Zero runs, including read permissions.

Copynpx analyze-query
  --schema-path='./shared/schema.ts'
  --query='issue.related("comments")'
  --apply-permissions
  --auth-data='{"userId":"user-123"}'

If the result looks right, the problem may be that Zero is not receiving the AuthData that you think it is. You can retrieve a query hash from websocket or server logs, then ask Zero for the details on that specific query.

Run this command with the same environment you run zero-cache with. It will use your upstream or cvr configuration to look up the query hash in the cvr database.

Copynpx analyze-query
  --schema-path='./shared/schema.ts'
  --hash='3rhuw19xt9vry'
  --apply-permissions
  --auth-data='{"userId":"user-123"}'

Write Permissions

Look for a WARN level log in the output from zero-cache like this:

CopyPermission check failed for {"op":"update","tableName":"message",...}, action update, phase preMutation, authData: {...}, rowPolicies: [...], cellPolicies: []

Zero prints the row, auth data, and permission policies that was applied to any failed writes.