Permix Documentation

When using Permix, follow these critical rules to ensure security and consistency:

1. Server-side enforcement is mandatory: Client-side check calls (in React, Vue, Solid, or Svelte) are for UX purposes only (e.g., hiding buttons). You must mirror every permission path with checkMiddleware on the server to actually protect routes and data.
2. Maintain path consistency: Use the exact same schema and path strings (e.g., post.update) across both client hooks and server middleware. Using ad-hoc strings will cause types and behavior to drift.
3. Handle initialization timing: Calling check before the instance is ready throws a PermixNotReadyError.
   • On the frontend, gate your UI using isReady or isReadyAsync.
   • On the server, ensure setupMiddleware is called before checkMiddleware.
4. SSR Hydration requirements: SSR hydrate only restores boolean values. If you use function-based rules or ReBAC, you must call setup again on the client side.

Permix supports advanced permission logic:

1. Async Rules: The setupMiddleware function can be async, allowing you to fetch user permissions from a database or external service before returning the permission object.
2. Data-Based Permissions: You can pass specific entity data to the check function (either via permix.get(request).check(path, data) or within a custom preHandler) to validate permissions against specific resource instances (e.g., checking if a user owns a specific post).

// Async setup
await fastify.register(permix.setupMiddleware(async ({ request }) => {
  const userPermissions = await getUserPermissions(request.user.id)
  return {
    post: {
      create: userPermissions.canCreatePosts,
      read: userPermissions.canReadPosts,
      update: userPermissions.canUpdatePosts
    }
  }
}))

// Data-based check in handler
fastify.put('/posts/:id', {
  preHandler: async (request, reply) => {
    const post = await getPostById(request.params.id)
    const { check } = permix.get(request)

    if (check('post.update', post)) {
      return
    } else {
      reply.status(403).send({ error: 'You cannot update this post' })
    }
  }
})

The integration between Permix and TanStack Start relies on several key architectural patterns to ensure security and efficient client-side hydration:

Per-request setup

In src/start.ts, a global request middleware is registered using createMiddleware().server(permix.createSetupHandler(...)). This ensures that every incoming request receives an isolated Permix instance. By using the .server() boundary, the setup callback (which contains server-only imports) is automatically stripped from the client bundle.

Server-side checks

Server functions can enforce permissions by calling permix.getOrThrow(context) or checkMiddleware(). These are typically invoked from route loaders to ensure the user has the necessary rights before executing server-side logic.

Router context and Hydration

• Router Context: The Permix instance is placed on the TanStack Router context in src/router.tsx.
• Hydration: The root route's beforeLoad hook hydrates the router-context instance with state transferred from the server.
• Client Access: The same instance from the router context is used by PermixProvider and PermixHydrate to provide permission state to the client-side UI.

Route Guards

Permissions can be checked directly in the router's beforeLoad hook without needing a server function. For example, a route can call context.permix.check('permission.name') to guard access.

Permix supports advanced permission logic:

1. Async Rules: The setupMiddleware callback can be async, allowing you to fetch permissions from a database or external service.
2. Data-Based Permissions: When using check manually in a handler, you can pass the specific entity data as a second argument. This allows you to verify if a user has permission to access a specific instance of an object (e.g., checking if a user is the author of a specific post).

// Async setup
app.use(permix.setupMiddleware(async ({ c }) => {
  const user = c.get('user')
  const userPermissions = await getUserPermissions(user.id)
  return { post: { create: userPermissions.canCreatePosts } }
}))

// Data-based check in handler
app.put('/posts/:id', async (c) => {
  const post = await getPostById(c.req.param('id'))
  const { check } = permix.get(c)

  if (check('post.update', post)) {
    return c.json({ success: true })
  }
  return c.json({ error: 'Forbidden' }, 403)
})

Permix allows you to define granular permissions using a PermissionsDefinition. You can associate actions with specific TypeScript types and use closures (functions) to implement relationship-based access control (ReBAC). This allows you to check permissions against specific object instances (e.g., checking if a user is the author of a comment).

import { createPermix } from 'permix'

interface User { id: string; role: 'editor' | 'user' }
interface Post { id: string; title: string; authorId: string; published: boolean }
interface Comment { id: string; content: string; authorId: string }

type PermissionsDefinition = {
  post: [
    { name: 'create', type: Post },
    { name: 'read', type: Post },
    { name: 'update', type: Post },
    { name: 'delete', type: Post },
  ]
  comment: [
    { name: 'create', type: Comment },
    { name: 'read', type: Comment },
    { name: 'update', type: Comment },
  ]
}

const permix = createPermix<PermissionsDefinition>()

// Using templates to create reusable permission sets
const userPermissions = permix.template(({ id: userId }: User) => ({
  post: {
    create: false,
    read: true,
    update: false,
    delete: false,
  },
  comment: {
    create: true,
    read: true,
    // Relationship-based rule using a closure
    update: (comment: Comment) => comment?.authorId === userId,
  },
}))

// Applying the template via setup
const user: User = { id: '1', role: 'user' }
permix.setup(userPermissions(user))

// Checking permission against an instance
const comment: Comment = { id: '1', content: 'Hello', authorId: '1' }
const canUpdate = permix.check('comment.update', comment) // true

Permix uses two distinct layers of isolation to ensure security and prevent state leakage between users:

1. Server Request Context: Created via setupMiddleware(). This creates a fresh core instance per request. All calls to get(), getOrThrow(), or check() within a single request share this instance. This is the enforcement layer (trustworthy).
2. Router Context: Created via getRouter(). On the server, each SSR render builds its own router with its own Permix instance. In the browser, the instance acts as a per-tab cache. This is the UX layer (not trustworthy, as rules are hydrated as plain booleans).