ReBAC membership tuples for Convex: idempotent edges, paginated member/resource queries, and relation guards — auth-agnostic, sandboxed tables.
npm install @vllnt/convex-memberships@vllnt/convex-memberships stores who is related to what using memberRef, resourceRef, and relation. Your app defines the meaning of each reference and relationship, so one storage model can support several domains.
Add or remove relationship tuples, transition a relation, and paginate in either direction: members of a resource or resources of a member. Re-adding the same tuple is idempotent. Opaque kind and status fields let the host describe its own entities.
The host owns authentication and permission policy. Always specify the accepted relation in authorization checks: an any-relation check can also match an invited or suspended relationship. This is a flat relationship store; transitive group expansion belongs in the application.
Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).
The `@vllnt/convex-memberships` component stores `(memberRef, resourceRef, relation)` tuples so you can call `memberships.add(ctx, userId, orgId, 'admin')` to assign a role and `memberships.isMember(ctx, userId, orgId, 'admin')` to gate access. Your host mutation handles auth; the component only stores and queries the edge. This keeps authorization logic centralized without coupling it to a specific auth provider.
`@vllnt/convex-memberships` exposes `memberships.listMembers(ctx, resourceRef, paginationOpts, relation?)` which returns a paginated `Page<MemberEntry>` compatible with Convex's built-in pagination. You can optionally narrow results to a single relation such as `'admin'` or `'invited'`. The symmetric `memberships.members(ctx, memberRef, paginationOpts)` returns all resources a member belongs to.
`@vllnt/convex-memberships` provides `memberships.setRelation(ctx, memberRef, resourceRef, fromRelation, toRelation)` which atomically transitions an edge from one relation to another. The method returns `{ ok, reason? }` where `reason` is `NOT_FOUND` if the source edge does not exist or `EXISTS` if the destination already exists, preventing silent collisions.
`@vllnt/convex-memberships` implements flat ReBAC tuples as a sandboxed Convex component. Each tuple is `(memberRef, resourceRef, relation)` with an optional `memberKind` and `status`, all stored as opaque host strings the component never interprets. Transitive graph traversal is not yet supported and is planned for a future version.
`@vllnt/convex-memberships` is fully auth-agnostic. The host application resolves identity and decides who may create or read an edge; the component only receives and stores opaque string refs. This means it works with Clerk, Auth0, custom JWT auth, or any other system you use with Convex.
`add` in `@vllnt/convex-memberships` is idempotent on the full `(memberRef, resourceRef, relation)` tuple. If a matching edge already exists, the call returns the existing document id and patches `memberKind` and `status` if they differ. No duplicate edges are created.
Calling `memberships.isMember(ctx, memberRef, resourceRef)` without a `relation` argument returns `true` for any stored relation, including `'invited'`, `'suspended'`, or `'banned'`. For authorization gates, always pass an explicit `relation` or enumerate the relations your policy accepts to avoid granting access to non-active membership states.
No. `@vllnt/convex-memberships` currently stores flat edges only. A member of a group that is itself a member of an org will not be automatically resolved as a member of that org. Transitive expansion is planned for a future version.
Import hooks from `@vllnt/convex-memberships/react` and pass your host app's re-exported query reference as the first argument. For example, `useIsMember(api.memberships.isMember, { memberRef: userId, resourceRef: orgId, relation: 'admin' })` returns `boolean | undefined`, where `undefined` means the query is still loading. React is an optional peer dependency; backend-only consumers do not pull it in.