Adgar Permissions — Current-State Reliability Assessment

1. Executive summary

Adgar wants a clean split between who can create/draft billing work, who can approve, process and send it, and who can change configuration — with configuration reserved to Zapfloor. The unit of implementation is the capability (e.g. "process an invoice", "send to accounting", "create a customer"); the three roles are just bundles of those capabilities.

On the backend, the capabilities are not separated. Almost every billing endpoint authorizes on the user's account type (operator), not on the permissions assigned to their role. Because every billing user is an operator, the backend cannot currently tell a drafter apart from an approver. Concretely:

• Editing a draft, processing it (locking it), sending it to the customer, and pushing it to Exact Online all pass through the same gate — so a user allowed to edit drafts can also do all three by a direct API call. They are only hidden in the UI.
• "Send" cannot be granted without also granting draft editing, because both ride the single update:invoice path.
• The role / permission / role-assignment endpoints do not restrict the change to a Zapfloor administrator. The most serious finding is that the role-assignment policy does not block a user from changing role assignments — so the "configuration is Zapfloor-only" boundary is not enforced, and a restricted user is not prevented from lifting their own restrictions if they reach the endpoint.
• The one control that holds today: withholding update:customer / delete:customer from a role really does block customer edits and deletes at the API. Customer creation, however, is not enforced.

For the Adgar conversation: the timeline in Sylvia's email assumed "if no additional development is needed, this can be completed by end of June." Additional development is needed. The permission names are mostly present and the UI is mostly wired, but making them reliable means adding real permission checks to the hq-api billing, subscription, accounting and role-management policies — a backend program of work, not a settings change.

2. The concept that decides everything

3. How permissions actually work here

A request travels through three layers. Today, the meaningful decision happens in the policy method at the bottom — and for billing that method ignores the permission catalogue.

The enforcement plumbing itself is sound: when a record is saved or destroyed, the service layer runs check_policy!, which calls can_create? / can_update? / can_destroy? and raises if they return false. resource_service.rb:159, 255–260 The issue is what those methods look at. The working pattern already exists elsewhere (e.g. customers, visitors: user.role_permissions.pluck(:name).include?("update:customer")) — it simply has not been applied to the billing surfaces in scope.

4. Requested capabilities — current status

One row per requested capability. "Who needs it" is the Adgar role the capability belongs to — shown as an attribute, not the organising structure. Hover the dotted capability text to see the source requirement.

5. The invoice lifecycle gap (the core defect)

Adgar's central ask is "drafters draft; approvers process & send." That maps to four transitions in an invoice's life. The platform intended a permission for each (the names exist), but only the first is even partly wired, and we found none of the others enforced. The whole chain currently rides one gate — update:invoice / can_update? — so it cannot be split.

6. Monthly invoice generation (the bill run)

The meeting describes creating Q3 invoices for several clients with a July 1st invoice date — that is OC-2's monthly invoice generator. It is relevant to Adgar because generating drafts is a Creator action and "no ad-hoc billing, contracts only" is a Creator/Approver constraint.

• The generator entry (generateMonthlyInvoices/Entry.vue) is embedded directly on the invoices, draft and overdue list pages (invoices/index.vue:190, draft/index.vue:51, overdue/index.vue:87) and is reachable by anyone who can open those lists — i.e. it is gated only by list:invoice, with no create:invoice check on the entry itself.
• It posts to /bill_runs (and /bill_runs/preview) in monthlyInvoiceGenerationStore.ts; we did not find a named permission enforced on that backend endpoint, so — like the rest of billing — generation is gated by user type, not by an assignable capability.
• Implication. "Creators generate drafts, Approvers do not generate" is not separable today, and the "contracts-only / no ad-hoc" rule is a stricter source restriction on creation that no single permission expresses. Both need a backend decision (see §9).

7. Top reliability risks (most critical first)

8. What works today vs what needs development

9. Backend development scope (implementation handoff)

Ordered by risk. Each item is "make the policy method check the named permission" using the pattern already proven on customers (user.role_permissions.pluck(:name).include?(…)), plus, where noted, a new permission or a transition-aware guard. Every item needs an hq-api request-spec that calls the endpoint directly with a restricted token — that is the only proof of reliability.

1. Config lockdown (security-critical, first). Replace the open role-assignment / role-permission / role policies with Administrator-only checks so restricted users cannot lift their own restrictions.
2. Invoice processing. Detect the is_draft: true → false transition and require process_invoice:invoice, separate from the plain draft-edit path (which should reject the transition for users without it).
3. Invoice / credit-note send. Enforce send_invoice:invoice on the email-send, Peppol and reminder paths; stop sending as system_user where it masks the actor.
4. Accounting export. Declare a new permission (e.g. send_to_accounting:invoice) and enforce it on send_to_exact / send_to_yuki and the accounting-config writes.
5. Draft create / edit / delete & bill run. Make InvoicePolicy check create:invoice / update:invoice / delete:invoice; gate the /bill_runs endpoint; decide credit notes (reuse create:invoice vs. add create:credit_note); decide the "contracts-only / no ad-hoc" source restriction.
6. Customer create. Mirror the working update/delete checks in can_create? (and on create_from_lead / merge / the operator-client add-customer route).
7. Subscriptions. Enforce create/update/delete:subscription and the indexation permissions; add a distinct permission if end/reactivate must be split from edit.
8. Contracts & billing entities. Enforce their permission groups; retire or gate the legacy v2 billing-entity controller and its config writes.
9. Front-end. Re-point OC-2's process/send buttons at the new permissions; add OC-2 unit tests for visible/hidden controls once the backend is in place.

10. Frontend & rollout notes

11. The three roles (reference)

For context only — the implementation unit is the capability above. These are the bundles Adgar defined.

12. How this was assessed

Every claim was traced to source in the checkouts listed in the header. The method was deliberately conservative: a capability was only marked "reliable" when the enforcing line could be cited; the default assumption was "not enforced until shown otherwise".

• Backend: read each relevant Pundit policy and the controller/service that calls it; for every permission name, grepped app/, config/ and lib/ to check whether it is ever read, not merely declared.
• Front-ends: located each gated control and the permission string it uses, and whether routes (not just buttons) are guarded.
• Cross-checked the crux questions with a second independent investigation pass over the same code.

Limitations: this is a static read of the code at the stated commits; it was not validated by issuing live API calls with restricted tokens. The development scope in §9 includes the request-spec tests that would provide that runtime proof. Line numbers will drift as the repos change.

13. Requirements & sources

Verbatim requirement text the capabilities above are traced to.

From Sylvia's email (the requirements)

Creator"Can create and edit draft invoices and/or credit notes. Can create and edit subscriptions. Cannot create or edit customers (read-only). Cannot process or send invoices (read-only). Cannot change configuration specifically billing entities, security roles and permissions. Can consult all data and reporting."

Approver"Can create and edit customers. Can process and send invoices and/or credit notes. Processing an invoice means converting it from a draft to a non editable invoice, then sending it to accounting and to the customer (via Peppol and/or e-mail). Cannot create or edit draft invoices. Cannot create or edit subscriptions. Cannot change configuration… Can consult all data and reporting."

Administrator"(Zapfloor only) Can change configuration for roles and permissions & billing entities upon request from 2 directors."

Scope"Out of scope — Data security: no additional restrictions based on data types will be available (e.g., a user only has access to a subset of customers)."

From the Adgar meeting notes

• "Created Q3 invoices for multiple clients using billing system." / "Selected July 1st as invoice date for Q3 billing cycle." → bill run (§6).
• "Draft invoices require manual review before processing." / "Cannot edit invoices once processed." → process must be a separate, enforced capability.
• "Cement Closed: 5th floor subscription ended June 30." / "Deleted draft invoice for terminated space." / "Ended subscription with custom end date." → subscription end + draft delete.
• "No ad-hoc billing — only contract-based recurring invoices." → source restriction on invoice creation.
• "System integration with Exact Online for accounting." → send-to-accounting capability.
• "Adgar billing entity requires restricted access." / "Administrative settings (bank details, addresses) limited to authorized users." → billing-entity config = Admin.
• "Configuration changes required for role-based permissions." → role/permission config = Admin.

14. Evidence appendix — key file references

15. Original source text

Full text supplied with the assessment, attached here for traceability.

Hi Dirk,

As promised, here is an overview of the requirements and the next steps.

Here are the requirements:
3 user types are defined in the Zapfloor platform:
Creator (Christel & Eddie)
Approver (Dirk)
Administrator (Zapfloor administrator)

Creator (Christel & Eddie)
Can create and edit draft invoices and/or credit notes
Can create and edit subscriptions
Cannot create or edit customers (read-only)
Cannot process or send invoices (read-only)
Cannot change configuration specifically billing entities, security roles and permissions
Can consult all data and reporting

Approver (Dirk)
Can create and edit customers
Can process and send invoices and/or credit notes. Processing an invoice means converting it from a draft to a non editable invoice, then sending it to accounting and to the customer (via Peppol and/or e-mail)
Cannot create or edit draft invoices
Cannot create or edit subscriptions
Cannot change configuration specifically billing entities, security roles and permissions
Can consult all data and reporting

Administrator (Zapfloor only)
Can change configuration for roles and permissions & billing entities upon request from 2 directors

Out of scope:
Data security : no additional restrictions based on data types will be available. (e.g., a user only has access to a subset of customers,...)

Next steps:
Investigation of the available settings: Many permission settings are already available. I will check if these cover the listed requirements and get back to you by the end of June.
Provide timing of implementation: If no additional development is needed, implementing these permissions can be completed by the end of June, allowing you to work in Zapfloor as needed from July on. If additional development is needed, I will inform you of a new timeline.
Extra: Establish a procedure within the Zapfloor CS team to allow changes in implementation. (changing roles, users, billing entities etc.) - to be discussed internally.

Feel free to add or correct anything. I will follow up after the investigation is finished.

KR
Sylvia

Adgar meeting

Quarterly Invoice Generation Process
Created Q3 invoices for multiple clients using billing system
Selected July 1st as invoice date for Q3 billing cycle
Draft invoices require manual review before processing
Check subscription amounts and adjustments
Verify PO numbers and rental details
Download drafts for signature collection

Client-Specific Invoice Updates
Sibelco: Standard rental invoice, no indexation required
Claudio: Processing rental charges
Cement Closed: 5th floor subscription ended June 30
Deleted draft invoice for terminated space
Ended subscription with custom end date
All invoices left in draft status for final review

Segregation of Duties Implementation
New approval workflow needed for invoice processing
Christel and Eddie: Create and modify draft invoices
Sylvia: Final approval and processing authority
Cannot edit invoices once processed
Must approve before sending to accounting/clients
System integration with Exact Online for accounting
Configuration changes required for role-based permissions

Billing Entity Security Controls
Adgar billing entity requires restricted access
Administrative settings (bank details, addresses) limited to authorized users
Client creation and contract management remains with Sylvia
No ad-hoc billing - only contract-based recurring invoices
Intercompany relationship with Brain requires separate consideration

Next Steps
Amogh: Research and configure role-based permissions system
Amogh: Send confirmation email with implementation timeline
Sylvia: Review draft invoices and make final adjustments
Team: Test new approval workflow once configured