accounted/.compliance/authorization-policy.md

Authorization Policy

Status: Approved Documented Security Decision Owner: Emil Mattsson (emil.mattsson@arcim.io) Last reviewed: 2026-07-23

This document records authorization decisions for Accounted that go beyond the default "the resource creator is the only person who can act on it" model. It is the canonical reference for compliance reviewers (OWASP ASVS V8, ISO 27001:2022 A.5.1 / A.8.3 / A.8.5, SOC 2 CC6.1) when they encounter an authorization check that uses company_id rather than user_id.

---

Multi-tenant model

Accounted is a multi-tenant SaaS where the unit of business ownership is the company (a row in public.companies). Users access companies through the company_members table, which links a user to one or more companies with a role (owner / admin / member / viewer).

The active company is resolved on every request by lib/supabase/middleware.ts. Application code reads it via ctx.companyId (extensions) or companyId resolved from the cookie. Row Level Security policies on every business table use the user_company_ids() DB helper to enforce membership.

The user is never the authoritative tenant identifier on its own. Any business data ownership check that compares user_id to the actor's user.id instead of the resource's company_id is a bug.

---

Shared-resource model (default)

Business records inside a company are shared resources: any member of the company can read and write them, subject to their role. This includes:

• Customer invoices and supplier invoices
• Journal entries and bank transactions
• Customers and suppliers
• Receipts and documents
• Bank connections (Enable Banking PSD2)
• Invoice delivery metadata and archived sent PDFs
• Mapping rules, booking templates, counterparty templates
• Salary runs and AGI declarations
• Company settings

The role of the actor (owner, admin, member, viewer) restricts what operations they can perform via lib/auth/require-write.ts, but does not restrict which records they can act on. A viewer cannot post any journal entry; a member can post any journal entry their company owns, regardless of who originally drafted it.

Invoice delivery list responses are data-minimized even for authorized company members. They expose masked recipient domains and operational status, but not BCC recipients, message bodies, subjects, reply-to addresses, provider message IDs, attachment filenames, or attachment checksums. Archived PDFs are served only when their document row belongs to the request's active company. The underlying exact delivery payload is selectable only by the user who sent the message. Other members receive the minimized list through the dedicated database function, so direct PostgREST access cannot bypass route minimization. The complete statutory archive is an owner/admin-only server operation and may include exact company delivery evidence. Deferred booking uses a separate SECURITY DEFINER function that verifies active-company membership and exposes only the latest archived document ID. The archive route verifies owner/admin twice: first through the authenticated RLS client and then through a stateless service-role client with explicit company_id and user_id predicates. Every archive query is scoped by that company_id or by parent IDs selected for it.

Why this is intentional

Accounted's users are small businesses and the bookkeepers / consultants they share access with. Compliance scenarios that drive this model:

1. Bookkeeper handover. A consultant who connected a bank during onboarding might not be the same person who later configures account selection. Forcing user_id ownership would lock the second person out of fixing the first person's setup.
2. Vacation cover. A second admin must be able to disconnect a bank, approve a supplier invoice, or send a customer invoice when the primary user is unreachable.
3. Audit trail under BFL 7 kap. Swedish bookkeeping law requires a continuous audit trail per company, not per user. Locking entries to a single user would interrupt that trail at every personnel change.
4. Role-based, not identity-based, separation of duties. Where SoD matters (e.g. AGI submission, year-end close, salary approval) we enforce it through the role column on company_members, not by recording which specific user created the underlying record.

Compensating controls

Although authorization is by company_id, the audit trail is by user_id:

• journal_entries.user_id, transactions.user_id, etc. record who created a record. These columns are never used for authorization, but they are preserved for the audit log and the immutable audit_log table.
• event_log rows include user_id so every privileged action (consent grants, invoice sends, period locks, document uploads) is attributable to a specific user even when authorization is shared.
• The audit_log table is immutable (DB trigger audit_log_immutable) and retained for 7 years per BFL.

---

Specific decisions

Invoice CC and BCC configuration: owner or admin only

Decision. Changing fixed invoice recipients or adding an arbitrary CC or BCC recipient to an individual invoice send requires the actor to have the owner or admin role in company_members. The dashboard hides those change controls for other roles. The settings route protects fixed-recipient changes; the dashboard and v1 send routes protect per-send additions before rendering, number allocation, or email delivery. The database also rejects direct member changes to fixed recipient fields. Once an owner or admin approves a fixed recipient, it applies to every send by a writable company member without a new role check. A fixed recipient that matches the customer address is de-duplicated with To precedence because it does not introduce a new external disclosure. The legacy company-email or authenticated sender-email fallback is also fixed routing: it cannot be supplied by the request, and the sender already has access to the invoice being sent.

Why. Both fixed and per-send recipients can disclose customer invoice data to a new external address. This is a distinct disclosure decision and needs a narrower authorization boundary than ordinary invoice sending. Explicit recipients that collide with To, fixed CC, fixed BCC, or another per-send recipient are rejected instead of silently changing recipient classification.

Compensating audit. Successful invoice sends retain the exact immutable recipient payload in invoice_deliveries, including the actor and company. Routine delivery-list and send responses remain minimized and never expose BCC.

Service write boundary. Delivery persistence uses a stateless service-role client because authenticated PostgREST writes are intentionally revoked. The service-only RPCs do not trust that client alone: they verify the supplied actor is a writable member of the supplied company and bind every invoice and delivery row to that company. Dashboard routes enter through withRouteContext, v1 and MCP routes enter through withApiV1 or the approved pending-operation path, and recurring sends derive actor, company, invoice, and schedule from the same company-scoped job before calling the RPC.

Cross-references.

• OWASP ASVS V2.3: business logic integrity
• OWASP ASVS V8.2.1: operation-level authorization
• GDPR Articles 5(1)(c) and 25(2): minimization and privacy by default
• SOC 2 CC6.1: logical access

Invoice payment instructions: owner or admin only

Decision. Changing the currency-keyed invoice_payment_accounts or any legacy SEK mirror field requires the owner or admin role. The legacy fields are bank_name, clearing_number, account_number, bankgiro, plusgiro, swish, iban, and bic. The settings route enforces this before persistence, matching the existing company_settings RLS policy.

Why. Payment instructions determine where a customer sends company funds. They need the same administrative boundary as other company financial settings. All payable invoices, including SEK invoices, must resolve a usable account before PDF rendering or invoice-number allocation. Credit notes, proformas, and delivery notes remain exempt because they do not request payment. Resends are not exempt: the current implementation renders a new PDF from current company settings instead of reusing an earlier delivery snapshot, so it must not send a payable document with blank or obsolete remittance details.

Cross-references.

• OWASP ASVS V2.3: business logic integrity
• OWASP ASVS V8.2.1: operation-level authorization
• SOC 2 CC6.1: logical access

bank_connections: managed at company scope

Decision. Any active company_members row for a company can manage any bank_connection belonging to that company. This covers POST /connect, PATCH /accounts, POST /sync, and DELETE /disconnect in the enable-banking extension.

Why. A bank connection is a company-level resource (it represents the company's relationship to its bank under PSD2 consent obtained on behalf of the company, not a personal banking relationship). Restricting management to the user who initiated the OAuth flow would create a lockout failure mode that exceeds the cross-tenant access risk of the broader model.

Compensating audit. Every state transition on a bank connection emits a structured event persisted to event_log with both user_id and company_id:

• bank_connection.consent_granted: PSD2 callback completed, account metadata stored, status pending_selection. Emitted from app/api/extensions/enable-banking/callback/route.ts.
• bank_connection.account_selection_changed: user chose which accounts to sync; status may transition pending_selection → active. Emitted from PATCH /accounts in extensions/general/enable-banking/index.ts.
• bank_connection.revoked: user disconnected the bank; PSD2 session is revoked at Enable Banking; status set to revoked. Emitted from DELETE /disconnect.

The event_log row carries: connectionId, bankName, previousStatus, newStatus, accountCount / enabledCount / totalCount, userId, companyId, consentExpiresAt. This is sufficient to attribute every PSD2 consent decision to a specific user under that company.

Cross-references.

• ASVS V8.2.1: authorization checks at trust boundary
• ASVS V16: audit logging of security-relevant events
• ISO 27001:2022 A.5.1, A.8.3, A.8.5: access control and information access restriction
• SOC 2 CC6.1, CC7.2: logical access controls and detection of unauthorized changes
• GDPR Art.30: records of processing activities (PSD2 consent decisions)
• BFL 7 kap.: 7-year retention of audit trail

---

Reviewers' checklist

When reviewing a PR that touches authorization:

1. The check filters by company_id resolved from the verified request context (ctx.companyId in extensions; companyId in API routes). Never user.id as a substitute.
2. If companyId is absent, the handler returns 400. Never falls back to a different identifier.
3. The actor's company membership is enforced by either RLS (user_company_ids() policy) or an explicit application-side check against company_members. Both is best.
4. Any state change is emitted as a structured event with userId and companyId so the audit trail remains attributable.
5. Where role-level restrictions apply, requireWrite() / requireRole() from lib/auth/require-write.ts enforces them.

Deviations from the shared-resource model (e.g. resources that should be locked to a single user) must be added to this document with the same "Decision / Why / Compensating audit" structure before merging.