Contract: Roles and permissions

Status

Accepted.

Purpose

This contract defines how BooksPlus roles, permissions, and role assignments must 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.

Permissions must reference protected-action names from the central protected action registry unless a future accepted contract defines another stable protected capability model.

The Accounting Correction Contract defines separate permissions for correction staging, readiness, abandonment, reversal posting, and adjustment posting. Adding those actions to the registry or a development/test full-access bundle does not grant them to any production role.

The Close Run Contract separately defines evaluation, waiver, approval, abandonment, soft-close, hard-close, and reopen permissions. Permission to change fiscal-calendar configuration, post journal entries, or perform one Close action does not imply authority for another.

The Reporting Contract separately defines report.view and report_run.capture. Permission to review workflow state, Close evidence, Source Documents, or the audit log does not independently authorize formal report access or capture.

The Sales Tax Accounting and Remittance Contract separately defines return staging, readiness, filing approval, external-filing evidence, abandonment, remittance approval, external-payment evidence, remittance posting, remittance abandonment, and bank- match permissions. Sales Summary, routine posting, Finance, Close, Reporting, or Source Document permission does not imply any sales-tax control permission.

The Company Conversion Run Contract separately defines staging, mapping, reconciliation, approval, application, failure, abandonment, and supersession permissions. Import staging, chart maintenance, or routine posting permission does not imply authority to approve or apply a company conversion.

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.

Role template guidance

BooksPlus may define initial production role templates such as:

Owner;
Accounting Admin;
Accountant;
Bookkeeper;
Reviewer;
Read-only;
Sysadmin.

These names are template guidance only. Business logic must not authorize protected behavior from role names alone. Final production role templates and the final role-permission matrix remain deferred until accepted in this contract or a later ADR.

Accounting administration and technical sysadmin authority must remain separable. A sysadmin role does not automatically grant accounting posting, period close, backup restore, support-access grant, company-data export, or unrestricted accounting authority unless those protected actions are explicitly assigned.

Support access is governed by the support-access truth. This contract does not accept a production support role template, support-access grant workflow, or permanent vendor/support access.

Bootstrap role

First-run production administrator bootstrap is governed by ADR 0019.

Production bootstrap must create or resolve ordinary actor, role, permission, and role-assignment records. It must not rely on hidden grants or development / test permission bundles.

The initial bootstrap role must be named distinctly from final operating roles, such as Initial Production Administrator or Bootstrap Owner. Its permissions must be limited to the protected actions needed to:

create or resolve the first production actor;
create or resolve the minimum role, permission, and role-assignment records needed for bootstrap;
manage users, roles, and permissions enough to complete setup and hand off to ordinary production security administration;
view protected-action and permission-readiness state;
record or complete setup permission-review acknowledgement;
view the security audit evidence needed to review the bootstrap.

The bootstrap role must not automatically grant accounting posting, period close, backup restore, support-access grant, company-data export, or unrestricted accounting authority unless those protected actions are explicitly assigned by ordinary authorization data.

Development and test roles

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 must map to a protected action registry name unless a future accepted contract defines another stable protected capability model.
Role creation, role changes, permission changes, and role-assignment changes must emit durable security audit events when security-relevant.
Business logic must check policies or permissions, not role names alone.
Accounting administration and technical sysadmin authority must be separable.
Support permissions must 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.
Production correction preparation and posting permissions must be assigned explicitly; role names do not imply journal_entry.reverse or journal_entry.adjust.
Production Close permissions must be assigned explicitly; role names and generic financial-period maintenance do not imply close, waiver, approval, finalization, or reopen authority.
Production Reporting permissions must be assigned explicitly. A role name, accounting posting permission, or Close permission does not imply report.view or report_run.capture.
Production sales-tax control permissions must be assigned explicitly. Permission to prepare or approve a return does not imply permission to record external filing, approve or post a remittance, record external payment, or record a bank match.
Production company-conversion permissions must be assigned explicitly. Permission for one conversion transition does not imply another, and company_conversion_run.apply does not grant its downstream chart, Source Document, or posting permissions.

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.
Production bootstrap can create minimum ordinary role, permission, and role-assignment records without using Developer Test Full Access.
Role and permission changes create security audit evidence.
A support role or support-access grant is not created by this contract alone.
An actor cannot post a correction merely because the actor may post routine journal entries.
An actor cannot waive, approve, finalize, or reopen merely because the actor may evaluate Close readiness or maintain a fiscal calendar.
An actor cannot view or capture formal reports merely because the actor may post, review workflow support, or perform Close actions.
An actor cannot approve a sales-tax filing or remittance, record external completion, post a remittance, or record a bank match merely because the actor may stage Sales facts, post ordinary entries, use Finance, or perform Close actions.
An actor cannot approve or apply a company conversion merely because the actor may stage imports, maintain accounts, or post routine entries.

Deferred decisions

Final production role templates and the final role-permission matrix.
Full user-management workflows after first-run bootstrap.
Support-access grant, use, and revoke workflows.
A broader protected capability model beyond protected-action registry names.

../accounting-correction.contract.md
../close-run.contract.md
../reporting.contract.md
../sales-tax-accounting-and-remittance.contract.md
../company-conversion-run.contract.md