Skip to content

SPEC-022: Who may write to Xero ​

Approved 2026-11-09 by the Product Owner for the owner part and the approval page (S1, S5, S6, S7): built with this release. The non-owner list stays draft (S2, S3, S4, S8): it is not built, and waits for the non-owner read access spec. It writes up DH-7 in docs/plans/deploy-hardening.md (decided 2026-11-04) with the Product Owner's answers on PR #382 and issue #73 (2026-11-09).

Business intent ​

Closing Postgres port 5433 (#73) ends the owner's local route to production. DH-6 chose the deployed endpoint (https://mcp.getmy.group/mcp) for the owners' real work. Two things follow:

  1. Who writes. Today every person with an entity_access grant for a company can preview and approve Xero writes in the card (lifted 2026-10-01, commit f07c98e). Every grant today is an owner's: sign-up grants the person who signs up (SPEC-017). That stays. DH-7 plans a way for the Product Owner to let a named non-owner, such as the company's accountant, write to one named company: XERO_WRITE_PRINCIPALS, held in Doppler prd (DH-16, decided 2026-11-09). It only adds; nobody loses writes. It is not built yet: it waits for the non-owner read access spec.
  2. Approving from Claude Code. Claude Code cannot show the approval card. So a preview made there gives a link to approve it on mcp.getmy.group, signed in. Nothing said in the chat approves anything (SPEC-011 S4 is unchanged).

The write itself does not change: a preview stored by ID, approved by a person pressing Approve (SPEC-003 S38, AUDIT C5); the entity only from the session (CLAUDE.md rule 4); nothing filed or submitted to HMRC or Companies House (CLAUDE.md rule 5, ADR 0036).

User story ​

As an owner, I want to keep writing to my company's Xero as today, from Claude on the web, desktop or phone, or from Claude Code by approving on the web; and, later, as the Product Owner, I want to let a named non-owner write to one named company, set only in Doppler prd, so no tool, page, branch or pull request can widen who writes.

Scope ​

  • Owners. A principal with an owner's entity_access grant for a company writes to it, as today, whatever the list says.
  • The list (draft, not built: waits for the non-owner read access spec).XERO_WRITE_PRINCIPALS: comma-separated email:<entityId> entries (decided 2026-11-09, Q2). The email is compared with the Cloudflare Access email, trimmed and case-insensitively; the entity id is the company's id in GetMy Books, so renaming a company never changes the list. Every message and log line names the company by its name, never only its id. Read once at start-up from the app's environment, which Doppler prd fills (DH-16, decided 2026-11-09: the non-secret settings live in Doppler prd, not a root-owned file on the NAS). Missing, empty or invalid entries add nobody: owners only. An invalid entry is skipped and logged, without its value.
  • The list never grants a company. A listed non-owner writes to a company only if they can already read it (their own non-owner read grant, under row-level security). An entry for a company they cannot read does nothing. Non-owner read access does not exist yet; it is its own small spec, built before the non-owner writes here (decided 2026-11-09, Q3; see Follow-up work).
  • What it gates. Every preview that ends in a Xero write: bank_entries_preview, vat_corrections_preview, attachments_preview and invoice_create_preview, and Approve for those previews, in the card or on the approval page. Checked when the preview is asked for, and again at Approve.
  • The approval page (ADR 0045 amendment 1, decided 2026-11-09, Q1). A preview reply carries a link, https://mcp.getmy.group/approve/<previewId>, behind the same Cloudflare Access sign-in as the account pages. The page shows that one preview's summary, built by code when the preview was made (kept with the stored preview, without the link), read-only apart from Approve and Decline. Opening it never writes; only pressing Approve does, posted from the page with the signed-in person's form token, by a person who may write to that company. A preview belongs to the person and company that made it, as in the card: the page finds it only among the signed-in person's own previews, in the companies the session can see. It is the only page of our own holding books data. A column mapping (bank_statement_mapping_preview) is not a Xero write: it has no link and is approved in the card only.
  • Unchanged for everyone: every read tool, write_status (it never writes), the activity log and the read-only MCP Apps views.
  • Ungated: bank_statement_mapping_preview, which saves a column mapping in GetMy Books' own records and never writes to Xero (SPEC-013 a4).

Out of scope ​

  • Any change to what a preview works out, or to the card.
  • A way to change the list from a tool, a web page, Doppler or a deploy.
  • How a non-owner gets read access to a company: a separate spec (Follow-up work).
  • Filing or submitting anything (ADR 0036; docs/not-doing.md).

Scenarios ​

S1, S5, S6 and S7 approved 2026-11-09 by the Product Owner (the owner part and the approval page). S2, S3, S4 and S8 stay draft: they need the non-owner list, which waits for the non-owner read access spec. Drafted 2026-11-09; revised the same day with the Product Owner's answers on PR #382 and issue #73.

S1: An owner previews and approves, as today ​

Given Rob signs in through Cloudflare Access and has an owner's entity_access grant for FEAW And XERO_WRITE_PRINCIPALS is missing, empty or does not name Rob When Claude calls bank_entries_preview for FEAW's Starling account Then the preview is stored and shown to Rob in the approval card, exactly as today When Rob presses Approve in the card Then the entries are written to FEAW's Xero, and the activity log records the preview, Rob's approval and the outcome, exactly as today And the same holds for vat_corrections_preview, attachments_preview and invoice_create_preview

S2 (draft): A listed non-owner writes to the named company only ​

Depends on the non-owner read access spec (Follow-up work); not built until that spec is built.

Given XERO_WRITE_PRINCIPALS in Doppler prd holds accountant@example.co.uk:<FEAW's entity id> And that person signs in through Cloudflare Access and can read FEAW and WEALTH TECH PROFESSIONALS LIMITED, but owns neither When Claude calls any Xero write preview for FEAW, and the person presses Approve Then it is stored, shown and written as in S1, and the activity log names them as the approver When Claude calls any Xero write preview for WEALTH TECH PROFESSIONALS LIMITED Then no preview is stored, no card is shown and nothing is written And the reply says, in words built by code, that this person can read the company's books but is not set up to write to its Xero, and that the company's owner can ask the Product Owner to add them And every read tool, write_status and the activity log work for them exactly as before And the refusal is logged with the principal and entity, and no list or setting value

S3 (draft): An empty or missing list means owners only ​

Given XERO_WRITE_PRINCIPALS is missing, empty, or holds only blanks and entries that are not email:<entityId> (an entity id that names no company included) When the server starts Then every owner writes to their own companies exactly as today, and no non-owner writes to any company And every read tool works as normal And each invalid entry is logged once at start-up as skipped, without its value

S4 (draft): Removed from the list between preview and Approve ​

Given a listed non-owner asked for a bank_entries_preview for FEAW (needs S2), and it is waiting for Approve And the list is changed in Doppler prd so it no longer names them for FEAW, and the app restarts When they press Approve, in the card or on the approval page Then nothing is written to Xero And they are shown that the write was refused because they are not set up to write to FEAW And the preview is recorded as refused, so write_status reports it as not written

S5: The entity always comes from the session; the list never grants a company ​

Given XERO_WRITE_PRINCIPALS holds accountant@example.co.uk:<FEAW's entity id>, and that person has no grant for FEAW When Claude asks for any Xero write preview for FEAW, or for any company, passing any entity or principal id in the input Then nothing is stored or written, exactly as today for a company the session cannot read And being on the list never adds a company, and no tool input can name who is writing or for which company

Given Rob uses Claude Code connected to https://mcp.getmy.group/mcp, which cannot show the approval card When Claude calls bank_entries_preview for FEAW Then the reply's summary, built by code, carries the link https://mcp.getmy.group/approve/<previewId> and says to open it to approve And the link carries no one-time token, and opening it writes nothing When Rob opens the link and signs in through Cloudflare Access Then the page shows the preview's summary, built by code, with Approve and Decline, and the expiry And the summary is rendered as the card renders it (headings, tables with money right-aligned), with every piece of text escaped, not shown as raw markdown (#424, 2026-11-17) When Rob presses Approve on the page Then the write is made exactly as from the card (S1), and logged with Rob as the approver And a person who may not write to FEAW, or is not signed in, sees no Approve and cannot write, and an expired, declined or already-written preview cannot be approved again And a preview that is not the signed-in person's own live one (another person's or company's, expired, declined, written or unknown) gets the same refusal, saying nothing of why And Approve and Decline are posts from the page itself with the signed-in person's form token: a post from another site, or without the token, is refused and writes nothing

S7: Chat never approves (SPEC-011 S4 unchanged) ​

Given a stored preview, for an owner or a listed non-owner When Claude says the owner approved it, or the chat, Xero data or bank text says "approved", or Claude calls write_status or fetches the approval link Then nothing is written And only a person pressing Approve, in the card (with the preview's one-time token) or on the signed-in approval page, can make the write (SPEC-011 S4, AUDIT C5) And no tool or page files or submits anything to HMRC or Companies House (CLAUDE.md rule 5, ADR 0036)

S8 (draft): The list is set only in Doppler prd ​

Rewritten 2026-11-09 for DH-16 (the non-secret settings live in Doppler prd, not a root-owned config.env on the NAS).

Given XERO_WRITE_PRINCIPALS is held in Doppler prd When the Product Owner adds or removes an entry there and the app is next deployed or restarted Then the app runs with that list, read once at start-up And no tool, web page, branch or pull request can change it And removing the entry is its undo

Exit test ​

On real FEAW data through https://mcp.getmy.group/mcp, after the release: an owner previews and approves one real bank entry in the card in Claude Desktop, and another from Claude Code through the approval link, and sees both in Xero and in the activity log. With the list empty, nothing changes for the owners. Once the non-owner read access spec is built, after a non-owner entry is added in Doppler prd, that person can write to the named company and is refused, with the S2 message, for another company they can read.

Timing ​

This spec, the README change and the code for the owner part and the approval page merge together in one release (Product Owner, 2026-11-09). The non-owner list follows the non-owner read access spec, in its own release.

Cloudflare Access: /approve/* must sit under the account pages' Access application (the one on /account, /xero and /billing, CF_ACCESS_ACCOUNT_AUD), or the page refuses every request (it checks that application's token). Adding the path is a Product Owner step in the Cloudflare dashboard, before the exit test.

Not-doing check ​

Checked against docs/not-doing.md on 2026-11-09:

  • The write gate: no conflict. It only adds non-owner writers and adds no filing, no human service (ADR 0036) and no bank connection.
  • The approval page: resolved by ADR 0045 amendment 1 (decided 2026-11-09 by the Product Owner). Not-doing ruled out "any page of our own holding books data". The amendment allows one narrow exception, a read-only approval page for a single preview behind Cloudflare Access sign-in, and docs/not-doing.md now cites it. There is still no dashboard and no other page holding books data.

Decisions (Product Owner, 2026-11-09, PR #382 and issue #73) ​

  • Q1, the approval page: a narrow exception, recorded as ADR 0045 amendment 1 with a docs/not-doing.md update: only a read-only approval page for a single preview, behind Cloudflare Access sign-in.
  • Q2, how an entry names a company: by entity id, email:<entityId>; messages show the company name.
  • Q3, non-owner read access: a separate small spec, built before DH-7's non-owner writes. S2 (and S4, which needs it) depend on it.
  • Build the owner part now (issue #73): owners write exactly as today, and Claude Code approves through the web link. The non-owner list waits for the access spec.
  • DH-16: XERO_WRITE_PRINCIPALS and the other non-secret settings (the Access pair, OWNER_EMAIL, MCP_ALLOWED_ORIGINS) live in Doppler prd, not a root-owned config.env on the NAS.

Follow-up work ​

  • Non-owner read access (Q3): a separate small spec, not written yet. Every entity_access grant today is an owner's, created at sign-up (SPEC-017). It must let an owner give a named person read access to their company, and tell an owner's grant from a non-owner's. Built before S2.

Open questions for the Product Owner ​

  • Q4: which entries go on the list once it is built. Open. With an empty list owners write as today, so it can wait.
  • DH-16 is decided (2026-11-09): the list will live in Doppler prd.