[Bccorb]

Closes #233

Permissions and organization roles on the client user, for showing and hiding UI. The client reads them from GET users/me and still never decodes a token. The server must still enforce, and the docs say so.

Public API

From @seamless-auth/client, re-exported by React, React Native, Angular, Vue and Svelte:

• hasPermission(user, required, { organization? }): any of required
• hasAllPermissions(user, required, { organization? }): all of required, and an empty list answers false
• hasRole(user, required): instance roles only, scoped matching through hasScopedRole
• hasOrganizationRole(user, required): active organization roles only, exact matching
• types PermissionCheckOptions and UserAuthorization

From @seamless-auth/react only: usePermissions() and UsePermissionsResult. It returns the same four checks without the user argument, plus loading, roles, permissions, organizationRoles, organizationPermissions and activeOrganizationId.

Decisions

• Separate hasOrganizationRole, not an option on hasRole. The two match differently (scoped and exact), and a forgotten option would be the failure ADR 0004 P2 rules out.
• { organization: true } counts only the active organization, the same option as requirePermission in feat(guards): add organization aware requirePermission guards seamless-auth-server#275. The default is the union of permissions and organizationPermissions (ADR P6).
• The standalone and hook hasRole is scoped, while useAuth().hasRole stays exact and answers undefined when signed out. Same name, different semantics for admin:read. I left the existing method alone and documented the difference.
• First runtime import from @seamless-auth/types. The client imports @seamless-auth/types/permission/matching, which has no Zod. It is external in the client build, and AGENTS.md now records the exception. Each Jest config maps and transforms that one file, because the package ships ESM under the import condition only. An adopter whose Jest runs our client through its own transform allowlist needs @seamless-auth/types in that allowlist too.

What was run

All on Node 24, in this branch:

• npm run lint: pass
• npm run typecheck: pass, all six packages
• npm run format:check: pass
• npm run check:types-current: pass, 0.38.0
• npm run build: pass, including check-react-dist and check-vue-dist
• npm test -- --coverage --runInBand: pass. Jest 59 suites, 896 tests. Vitest (Svelte) 3 files, 56 tests. permissions.ts and usePermissions.ts at 100 percent
• npm run check-npm-build: pass
• Zod check: the repo has no automated one. I bundled packages/client/dist/index.js and packages/react/dist/index.js with esbuild for the browser and read the metafile: no Zod input, and the only @seamless-auth/types input is permission/matching.js

What was not run

• Against a real API. API PR feat(organizations): carry organization roles and permissions in the access token seamless-auth-api#577 is open and not merged, so the tests use mocked /users/me responses shaped by MeUserSchema. An API without it answers false everywhere, by design
• The conformance workflow and the seamless-cli browser harness
• A native or Metro build of React Native (Jest and the rollup build only)

Left out

• usePermissions equivalents in React Native, Vue, Svelte and Angular. The issue names React, and those bindings get the helpers through their re-export lists. They also have no hasPermission method on their service or session class
• ../seamless-auth-docs is not updated
• An automated Zod-free bundle check

Noticed, not changed

• packages/client/src/scopedRoles.ts is a hand-kept copy of @seamless-auth/types/role/matching. Now that a Zod-free runtime subpath is in use, it could import rather than copy
• meHandler in seamless-auth-server/packages/core/src/handlers/me.ts returns only user and credentials, so organizations, activeOrganization and recovery do not reach the client through it. user passes through whole, so the new fields do