Skip to content

ADR 0019: First-Run Production Administrator Bootstrap

Decision

BooksPlus production first-run setup must include an explicit administrator bootstrap step.

In production mode, the bootstrap creates or resolves a real BooksPlus actor mapped to the current desktop operating-system identity. That actor may receive only the minimum initial production authority needed to continue setup and manage security. The authority must be represented through ordinary roles, permissions, role assignments, and protected-action names from the central protected-action registry.

The bootstrap must be visible in onboarding and must create durable security audit evidence. It is allowed only when no active production administrator or owner authority exists for the target company or setup context.

Developer Test Full Access remains development/test-only. It must not be used for production administrator bootstrap, production owner assignment, production permission readiness, or any hidden production grant.

Rationale

Production setup needs a real first authority before normal authorization can govern later security changes. Without a defined bootstrap rule, implementers may be tempted to reuse development/test full access, create hidden production grants, or treat setup acknowledgement as if it were security authority.

BooksPlus must preserve the desktop identity model: the current operating system account is the first trust boundary, and BooksPlus actor records map that identity into application authorization and audit evidence.

The bootstrap must establish only enough authority to proceed safely. It must not define the final production role model, create broad user-management workflows, or bypass policy-based authorization after setup begins.

Implications

The first bootstrap actor must be attributable and active. Disabled or retired actors must not be silently reused for production authority.

Bootstrap authority remains ordinary authorization data. Roles are permission bundles and must not bypass policy-based authorization. Later protected actions must still be authorized by named protected actions and, when security-relevant, must emit security audit events.

Bootstrap must not make permission setup complete by itself. Permission readiness remains backed by the existing setup acknowledgement evidence for permission review and protected-action visibility.

Once a company exists, company-scoped permissions and company-scoped audit events must use the company identity defined by the Company Identity and Context contract. Company creation and company selection may still begin without an existing company context as allowed by that contract.

If production security state already exists, bootstrap must be idempotent and reviewable. Expected existing actor, role, and assignment records may be reported as already present. Conflicting security state must stop the bootstrap and require review rather than being silently overwritten or repaired.

The accepted bootstrap decision requires a minimum bootstrap permission bundle, but it does not require the full production role matrix, full user-management workflow, support-access workflow, or final step-up confirmation policy to be settled before implementation begins.

Boundaries

This ADR does not define:

  • final production role templates or a final role-permission matrix;
  • broad user-management workflows;
  • support-access grant, use, or revoke workflows;
  • a web-style username and password system;
  • a policy engine or automatic policy-default enforcement;
  • hidden production grants based on runtime mode;
  • new accounting, posting, fiscal-period, chart, source-document, close, report, backup, adapter, import, or historical-conversion rules.

This ADR does not change development/test seeding. Development/test actors, BooksPlus Test Company, and Developer Test Full Access remain unavailable in production company data unless explicit development or test mode is active.

Guidance

For MVP:

  • show the production administrator bootstrap step clearly during first-run or onboarding;
  • identify the first production actor from the current desktop operating-system identity;
  • create or resolve only ordinary actor, role, permission, and role-assignment records;
  • use protected-action names from the central registry when defining bootstrap permissions;
  • record security audit events for actor creation or resolution, role creation or resolution when applicable, role assignment, and bootstrap completion;
  • distinguish bootstrap security authority from setup permission-review acknowledgement;
  • make repeated bootstrap attempts idempotent when the expected records already exist;
  • stop and require review when existing production security state conflicts with the bootstrap assumptions.

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 the existing permission-review acknowledgement;
  • view the security audit evidence needed to review the bootstrap.

The initial 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.

For MVP, desktop operating-system identity is sufficient for bootstrap when paired with an explicit visible confirmation and durable security audit events. The design must preserve a place to add step-up confirmation later for especially dangerous actions, including role or permission changes, backup restore, support-access grants, company-data export, period reopen, and security recovery.

Acceptance criteria

  • Production mode can establish first real setup and security authority without development/test seed data.
  • Production mode never creates, activates, assigns, or relies on Developer Test Full Access.
  • Bootstrap produces durable security audit evidence.
  • Onboarding can distinguish bootstrap authority from permission readiness acknowledgement.
  • Permission readiness remains incomplete until existing permission-review evidence is recorded.
  • Subsequent security changes remain protected and audited according to the security contracts.

Deferred decisions

  • Final production role templates and the final role-permission matrix remain deferred. They should be resolved in the roles and permissions contract or a later ADR. This ADR only requires the minimum bootstrap role described above.
  • Full user-management workflows after bootstrap remain deferred. Later work should cover actor creation, mapped operating-system identity management, disablement, retirement, role assignment, permission review, audit review, and recovery when no active administrator remains.
  • Support-access grant, use, and revoke workflows remain governed by the support-access ADR and contract. Bootstrap must not create hidden support access, permanent vendor access, or shared support credentials.
  • Step-up confirmation beyond the desktop operating-system identity is not required for MVP bootstrap. Later security-sensitive actions should support step-up confirmation where policy requires higher assurance.