@torquedev/ext-authorization

HookBus-based authorization middleware for Torque. Reads permissions: declarations from bundle manifests and intercepts interface:before-call and route:before hooks to enforce role and record-level access control before business logic runs.

Install

npm install github:michaeljabbour/torque-ext-authorization

Peer dependency: @torquedev/core >=0.1.0

Usage

import { AuthorizationService } from '@torquedev/ext-authorization';

const authService = new AuthorizationService({
  hookBus,
  coordinator,
  config: {
    defaultPolicy: 'deny',   // 'deny' (default) | 'allow'
    logDenials: true,
    logGrants: false,
  },
});

coordinator.registerService('authorization', authService);

Bundles declare permissions in manifest.yml:

permissions:
  createDeal:
    roles: [admin, sales_rep]
  archiveDeal:
    roles: [admin]
  updateDeal:
    roles: [admin, sales_rep]
    check: owner_or_admin
    record_from: dealId
    getter: getDeal

Enforcement flow

Each call passes through three stages:

1. Unauthenticated check -- if no currentUser is present, the call is rejected.
2. Role check -- currentUser.role must appear in the permission's roles array.
3. Record-level check -- an optional check function runs against the resolved record.

When no permission rule is declared for a method, the defaultPolicy config decides the outcome.

API

checkPermission(bundle, method, { currentUser, record, args })

Non-throwing permission check. Returns { value: true } or { value: false, message }.

registerCheck(name, fn)

Register a custom check function. Receives { currentUser, record, args, coordinator, bundle, method } and should throw AuthorizationError on failure. May be async.

hasPermission(bundle, method)

Returns true if a permission rule is declared for the given bundle method.

listPermissions()

Returns all declared permissions keyed by bundle.

bundlePermissions(bundle)

Returns the permissions object for a single bundle.

Built-in checks

| Check | Behaviour | |---|---| | owner_or_admin | Admin bypasses; others must own the record. | | team_visible | Record owner must be in the current user's team. Falls back to owner_or_admin. | | self_only | User can only act on their own records. | | created_by | Admin bypasses; others must have created the record. |

AuthorizationError

Thrown on access denial. Caught by the server and returned as HTTP 403.

import { AuthorizationError } from '@torquedev/ext-authorization';

err.status   // 403
err.code     // 'FORBIDDEN'
err.bundle   // e.g. 'pipeline'
err.method   // e.g. 'updateDeal'

Exports

import { AuthorizationService, AuthorizationError, builtinChecks } from '@torquedev/ext-authorization';

Testing

npm test

ESM-only. Requires Node.js with the built-in test runner.

License

MIT