Permission

The @talosjs/permission component is a fine-grained access control layer built on CASL. You describe what is allowed as a set of abilities, each one a pair of an action (read, update, delete, …) and a subject (User, Article, all, …), then ask whether the current user can or cannot perform an action. Permissions are written as classes that extend the abstract Permission base, registered with the container, and attached to routes so authorization runs before your handler.

The authorization model

Authorization here is ability-based rather than flag-based: you grant concrete action + subject pairs instead of scattering boolean role checks across your code. setUserPermissions(context) derives abilities from the request context, so a single permission class adapts to admins, owners, and guests. Because can() and cannot() take an optional field, you can allow reading name while forbidding password on the same subject. For consistency, EPermissionAction ships more than 60 actions and EPermissionSubject ships common subjects, both with literal types you can extend per domain. Register a permission class with a decorator and you can resolve it from the container or wire it to a route.

How it works

A permission is a class extending Permission. You implement three methods, then build() compiles the rules into a CASL ability you query with can/cannot.

Method	Purpose
`allow()`	Declare baseline abilities with `this.ability.can(...)` / `this.ability.cannot(...)`. Returns `this`.
`setUserPermissions(context)`	Add abilities derived from the request context (the user, their roles, ownership). Returns `this`.
`check(context)`	Custom gate run before the route handler; return `false` to deny outright.
`build()`	Compile declared rules into the ability. Must run before `can`/`cannot`. Returns `this`.
`can(action, subject, field?)`	Whether the action is allowed on the subject (optionally a field).
`cannot(action, subject, field?)`	Whether the action is forbidden on the subject (optionally a field).

The lifecycle is a fluent chain: declare context-driven rules, declare baseline rules, build, then query.

const permission = new ArticlePermission();

permission
  .setUserPermissions(context) // abilities from the current user
  .allow() // baseline abilities
  .build(); // compile before checking

if (permission.can(EPermissionAction.EDIT, "Article")) {
  // proceed
}

can and cannot throw a PermissionException (NOT_BUILT) if called before build(). The MANAGE action and the all subject act as wildcards, so this.ability.can("manage", "all") grants everything.

Decorator and usage

`@decorator.permission()`

Registers a permission class with the container. It accepts an optional scope (defaults to singleton).

import type { ContextType } from "@talosjs/controller";
import { decorator, EPermissionAction, Permission } from "@talosjs/permission";

@decorator.permission()
export class ArticlePermission extends Permission {
  public allow(): this {
    this.ability.can(EPermissionAction.READ, "Article");
    this.ability.can(EPermissionAction.VIEW, "Article");
    return this;
  }

  public setUserPermissions(context: ContextType): this {
    const { user } = context;
    if (!user) return this;

    // Authenticated users can create and edit articles
    this.ability.can(EPermissionAction.CREATE, "Article");
    this.ability.can(EPermissionAction.EDIT, "Article");

    // Admins manage everything
    if (user.roles.includes("ROLE_ADMIN")) {
      this.ability.can(EPermissionAction.MANAGE, "all");
    }

    return this;
  }

  public check(context: ContextType): boolean {
    return true;
  }
}

Attach the class to a route and authorization runs automatically before the handler:

import type { ContextType, IController } from "@talosjs/controller";
import { Route } from "@talosjs/routing";
import { ArticlePermission } from "@/permissions/ArticlePermission";

@Route.http({
  name: "api.articles.update",
  path: "/api/articles/:id",
  method: "PUT",
  permission: ArticlePermission,
})
class ArticleUpdateController implements IController {
  public async index(context: ContextType) {
    // Reached only when the permission allows it
  }
}

You can also evaluate a permission manually, which is useful for ownership checks the route-level gate can’t know about:

const permission = new ArticlePermission();

permission
  .setUserPermissions(context)
  .allow()
  .build();

if (permission.cannot(EPermissionAction.DELETE, "Article")) {
  return context.response.exception("Not authorized", { status: 403 });
}

Restrict to specific fields by passing a field name:

permission.can(EPermissionAction.READ, "User", "name"); // true
permission.can(EPermissionAction.READ, "User", "password"); // false

Exceptions

The component throws PermissionException when an ability is queried before the permission has been built. It carries a machine-readable key, a human-readable message, and a data object.

Key	When
`NOT_BUILT`	`can()` or `cannot()` is called before `build()`.

import { PermissionException } from "@talosjs/permission";

try {
  permission.can(EPermissionAction.READ, "Article");
} catch (error) {
  if (error instanceof PermissionException) {
    logger.error(`Permission error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Getting permissions right

Compile the ability once after declaring rules, and always do it before checking; querying before build() throws PermissionException (NOT_BUILT). Keep the chain consistent by running setUserPermissions() first, then allow(), with build() last, so context-driven rules are in place when you compile. Reach for EPermissionAction and EPermissionSubject over raw strings to keep checks consistent. The manage / all wildcard grants every action on every subject, so scope it to trusted roles only. Keep ownership logic inside the permission: pass owner data through the context and decide in setUserPermissions() rather than in the controller. Use check() for coarse gates such as method, IP, or headers, and let can/cannot handle the fine-grained decisions. When you throw a PermissionException, keep its key constant and put the variable detail in data.

CLI command

Scaffold a permission class and its test file with the generator. It writes the class under modules/<module>/src/permissions/<Name>Permission.ts and installs @talosjs/permission if it is missing.

# Interactive: prompts for the name
talos permission:create

# Provide the name
talos permission:create --name=EditArticle

# Target a module and overwrite
talos permission:create --name=EditArticle --module=blog --override

Option	Description	Default
`--name`	Permission class name. The `Permission` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class is a ready-to-fill stub with the three methods and inline examples:

import type { ContextType } from "@talosjs/controller";
import { decorator, Permission } from "@talosjs/permission";

@decorator.permission()
export class EditArticlePermission extends Permission {
  public allow(): this {
    // Example: Add permissions using this.ability.can()
    // this.ability.can("read", "YourEntity");
    // this.ability.can(["read", "update"], "YourEntity", { userId: user.id });

    return this;
  }

  public setUserPermissions(context: ContextType): this {
    // Example: Grant full access to admins
    // const { user } = context;
    //
    // if (!user) {
    //   return this;
    // }
    //
    // const { roles } = user;
    // if (roles.includes("ROLE_ADMIN")) {
    //   this.ability.can("manage", "all");
    //   return this;
    // }

    return this;
  }

  public check(context: ContextType): boolean {
    // Example: Restrict access based on request method
    // const { method } = context;
    // if (method === "DELETE") {
    //   return false;
    // }

    return true;
  }
}

See permission:create for the full command reference.

Use with Claude and Codex

The generator ships a matching permission:create skill. It runs the scaffold, then guides your AI agent through completing the permission: implementing allow() with ability rules and setUserPermissions() with role-based logic. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a permission that controls who can edit articles.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a permission that controls who can edit articles.

For example, the prompt above maps to permission:create --name=EditArticle, then implements allow() and setUserPermissions() so only the right users can edit articles.

Getting Started

AI

Framework

Command Line

The authorization model

How it works

Decorator and usage

`@decorator.permission()`

Exceptions

Getting permissions right

CLI command

Use with Claude and Codex

​The authorization model

​How it works

​Decorator and usage

​@decorator.permission()

​Exceptions

​Getting permissions right

​CLI command

​Use with Claude and Codex

The authorization model

How it works

Decorator and usage

`@decorator.permission()`

Exceptions

Getting permissions right

CLI command

Use with Claude and Codex