Skip to content

Contract: Roles and permissions

Status

Draft.

Purpose

This contract defines how BooksPlus roles and permissions should behave.

Contract

Roles are permission bundles. Permissions authorize protected actions. Roles must not bypass policy-based authorization.

Authorization must evaluate the actor, company, and protected action together when an action affects company data, company configuration, accounting records, auditability, backups, or sensitive information.

Company identity and company context are defined by the Company Identity and Context contract.

The minimum authorization context for a protected company-scoped action is:

  • actor identifier;
  • company identifier;
  • protected action name;
  • target type when applicable;
  • target identifier when applicable;
  • correlation identifier when part of a larger workflow.

Draft standard roles

BooksPlus may define initial roles such as:

  • Owner;
  • Accounting Admin;
  • Accountant;
  • Bookkeeper;
  • Reviewer;
  • Read-only;
  • Sysadmin;
  • Support;
  • Developer Test Full Access.

These names are draft and may be revised as implementation clarifies the security model.

Developer Test Full Access is a development/test-only bundle. It must be generated from the protected action registry and must not exist in production company data unless an explicit development or test mode is active.

Rules

  • A role may grant multiple permissions.
  • A permission should map to a protected action or protected capability.
  • Business logic should check policies or permissions, not role names alone.
  • Accounting administration and technical sysadmin authority should be separable.
  • Support permissions should be narrow and time-limited.
  • Company-scoped permissions must be checked against the company for the request.
  • Broad test roles must still use ordinary permission checks and audit behavior.
  • New protected actions must be intentionally included in or excluded from broad test bundles.

Acceptance criteria

  • A user can have more than one role.
  • A protected action can be tested against a named permission or policy.
  • Removing a permission prevents the protected action even if the user still has other roles.
  • A sysadmin role does not automatically grant accounting posting authority unless explicitly configured.
  • A narrow actor without the required company-scoped permission is denied.
  • The developer test permission bundle covers every registered protected action in development/test mode.