Skip to main content

Actor Resolver

The actor resolver defines who is attempting the action at runtime.

It is one of the most important integration points in the JavaScript SDK because it connects Actra to your application’s identity model.

The resolver is configured through the real runtime API:

runtime.setActorResolver((ctx) => ({
  role: ctx.user.role,
}))

Core Mental Model​

Actor = who is attempting the action

Typical actor identities include:

  • authenticated users
  • service accounts
  • internal automation
  • workflow systems
  • background workers
  • AI agents
  • admin tools

Policies then reference these fields using:

subject:
  domain: actor
  field: role

Basic Resolver​

The most common resolver maps authenticated user identity.

runtime.setActorResolver((ctx) => ({
  user_id: ctx.user.id,
  role: ctx.user.role,
  tenant: ctx.user.tenant,
}))

This is ideal for:

  • RBAC
  • tenant isolation
  • department routing
  • approval routing

AI Agent Identity​

One of Actra’s strongest modern use cases.

runtime.setActorResolver((agentCtx) => ({
  agent: agentCtx.name,
  role: "tool_runner",
}))

This is ideal for:

  • tool gating
  • autonomous workflows
  • MCP tool execution
  • multi-agent governance
  • LLM safety boundaries

Express / Fastify Request Resolver​

A common Node.js production pattern.

runtime.setActorResolver((req) => ({
  user_id: req.user.id,
  role: req.user.role,
  tenant: req.user.tenant,
}))

This makes Actra integrate naturally with request-scoped auth middleware.

Service-to-Service Identity​

For internal platform systems.

runtime.setActorResolver((ctx) => ({
  service: ctx.serviceName,
  role: "internal_service",
}))

Excellent for:

  • microservices
  • internal APIs
  • deployment systems
  • CI bots
  • platform automation

Queue / Worker Identity​

Useful for job processors and background systems.

runtime.setActorResolver((job) => ({
  worker: job.queueName,
  role: "worker",
}))

Best for:

  • BullMQ
  • RabbitMQ consumers
  • Kafka processors
  • cron jobs
  • ETL workflows

Resolver Failure Behavior​

If the resolver throws an exception, runtime evaluation fails safely.

The runtime throws:

ActraError

with a wrapped message:

Resolver failed: ...

This ensures broken identity extraction never silently bypasses policy.

Missing Resolver Behavior​

If no actor resolver is configured:

runtime.setActorResolver(...)

then the runtime uses an empty actor object.

{}

This is safe but typically not sufficient for production authorization.

Best Practices​

Keep actor identity-focused​

Use actor only for:

  • identity
  • role
  • tenant
  • department
  • trust level
  • agent name

Avoid business state fields here.

Use stable field names​

Good:

role

Avoid unstable fields:

latestRoleVersion

Do not duplicate snapshot state​

Use:

  • actor → who
  • snapshot → current system state

This keeps policies auditable.

Production Mental Model​

Request / Worker / Agent
 -> Resolve identity
 -> Build actor object
 -> Runtime evaluation

This is how Actra connects to real-world identity systems