Skip to content

Add VIEWER role, document access control, and validate signed filter values - #6

Merged
Max Musing (MaxMusing) merged 3 commits into
mainfrom
cursor/embed-security-clarity-ed21
Nov 6, 2026
Merged

Max Musing (MaxMusing) merged 3 commits into
mainfrom
cursor/embed-security-clarity-ed21

Conversation

@MaxMusing

Copy link
Copy Markdown
Member

Summary

This PR makes the SDK's types and docs match how Basedash actually enforces access. It also adds one validation step before shared-dashboard filter tokens are signed.

  • VIEWER role. BasedashRole is now "ADMIN" | "MEMBER" | "VIEWER". Basedash's SSO claim schema already accepts all three (z.enum(MemberRole)), but the SDK type only allowed two. The role descriptions come from Basedash's role options. VIEWER is view-only: it can open resources shared with it, but cannot create, edit, or chat.
  • groups docs. The "Reserved for future group synchronization" comment was wrong, so this PR replaces it with the live behavior:
    • The claim is applied on every login, and names match existing groups case-insensitively, ignoring surrounding spaces.
    • It adds memberships, and removes only the memberships it added earlier.
    • It never creates groups.
    • Group membership affects data-source, dashboard, and chat access, and row-level security policies receive group names.
    • Integrators should pass only group names their own server controls.
  • Existing Basedash accounts. The docs now note that role and groups are not applied when the email belongs to a verified Basedash account that is already an active member of the organization.
  • Hiding features is not access control. The README and CONTRACT.md now say plainly that the component you choose, the hide* options, hideSidebar, and initialPage are presentation only. A new "Access control" section points integrators to a signed VIEWER role and server-controlled groups for least privilege.
  • Signed filter values. These are documented as being rendered into chart SQL as raw text, never to be built from viewer-influenced input.
  • Validation before signing. createDashboardFilterToken now throws before signing if a value contains ', ", `, \, ;, --, or /*:
    • The value is first converted to text the same way Basedash does it (arrays joined with ,, numbers and booleans with String()).
    • This is the same free-text check Basedash applies to values a viewer supplies (isAllowedPublicVariableValue), and the only part of that check that doesn't depend on the variable's declared type.
    • The error message names the param but leaves out its value.

Behavior change

Integrators who currently sign values containing those sequences (for example, a company name with an apostrophe) will now get a TypeError instead of a token. The changeset is marked minor for that reason. The SDK is also stricter than Basedash in one case: a LIST dropdown option that itself contains one of these sequences is accepted from a viewer, but rejected by the SDK. CONTRACT.md documents this.

Scope

  • This PR does not change the Basedash backend. Signed filter values are still rendered into SQL without binding or escaping, and fixing that needs a Basedash change.
  • This PR does not remove or change public/shared dashboards, or how they behave without a filter token.
  • No changes to tokens, claims, endpoints, or embed URLs. The only runtime change is the new validation in createDashboardFilterToken.

Testing

  • pnpm check passes: typecheck, 49 tests, build, publint, and attw. The node10 resolution rows are ignored, as on main.
  • New tests in tests/server.test.ts:
    • A VIEWER token signs and verifies.
    • Each forbidden sequence, plus one inside an array item, is rejected, and a spy on SignJWT.prototype.sign confirms nothing is signed.
    • The rejected value doesn't appear in the error message.
    • Arrays are checked the way Basedash renders them (joined with ,).
    • Typical UUIDs, emails, ISO dates, labels, negative numbers, and booleans are still accepted.
  • Against the old src/server/index.ts, 9 of the new tests fail; with this change they pass.
  • The example apps (examples/nextjs, examples/vite) typecheck against the local SDK source. The Next.js token route was also run against the built package with a randomly generated throwaway secret that was never printed or stored.
Open in Web Open in Cursor 

Basedash accepts ADMIN, MEMBER, and VIEWER in the SSO role claim; the
type only allowed the first two. Document the live role and groups
claim behavior in the types.

createDashboardFilterToken now rejects values whose rendered text
contains ' " ` \ ; -- or /*, the free-text check Basedash applies to
viewer-supplied values but not to signed ones, before signing.

Co-authored-by: Max Musing <MaxMusing@users.noreply.github.com>
State that components, hide options, and the sidebar are presentation
only, document the live role and groups claim behavior, recommend
VIEWER and server-controlled groups for least privilege, and warn that
signed filter values are rendered into chart SQL as raw text.

Co-authored-by: Max Musing <MaxMusing@users.noreply.github.com>
Co-authored-by: Max Musing <MaxMusing@users.noreply.github.com>
@MaxMusing
Max Musing (MaxMusing) merged commit 4c854f3 into main Nov 6, 2026
1 check passed
@MaxMusing
Max Musing (MaxMusing) deleted the cursor/embed-security-clarity-ed21 branch November 6, 2026 18:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants