Appearance
SPEC-007: HMRC connection
Status: parked by ADR 0036. The HMRC connection was the first step towards filing (SPEC-002), which ADR 0036 rules out; it is not built while that ADR stands.
Source:
docs/plans/hmrc-connection.md(issue #85), awaiting the Product Owner's approval of QD-23, QD-25 and QD-26. This spec puts that plan in the standard form; where they differ, the plan was written first and this spec follows it. No code exists yet.
Business intent
GetMy Books cannot see HMRC. VAT return dates are calculated from each company's VAT quarters, so it cannot tell whether a return was filed or paid, or what HMRC holds. HMRC's Making Tax Digital for VAT API is the route. Connecting it lets SPEC-001 back-test each draft against the return HMRC holds (S1), and SPEC-004 use HMRC's own obligation dates, "filed" and "paid". Protects SM-1 (no late filings) and SM-3 (drafts match the filed return).
User story
When I connect FEAW to HMRC once, I want GetMy Books to know what HMRC holds for our VAT, so that deadlines are HMRC's own and every draft is checked against the filed return.
Scope
- Connect a company at
/hmrc/connect, behind Cloudflare Access and the per-person check. The person signs in at HMRC with the company's Government Gateway user ID for VAT and grantsread:vat(QD-26: whose ID).stateis single-use, bound to the session and the entity, and expires in 10 minutes; HMRC's code expires in 10 minutes too.- The entity comes from the session only (rule 4). The VAT registration number is the entity's own, checked against HMRC's customer information, never taken from input.
- Tokens are encrypted (
src/platform/crypto.ts) underHMRC_TOKEN_ENCRYPTION_KEY, inhmrc_connectionunder row-level security. Access tokens last 4 hours; refresh tokens stop after 18 months. - The connect page sends
WEB_APP_VIA_SERVERfraud prevention headers (ADR 0006).
- A daily sync at 06:00 Europe/London for each connected company, with
BATCH_PROCESS_DIRECTheaders. It reads obligations (4 years back), submitted returns for fulfilled periods, liabilities, payments, and penalties if enabled. Everything is integer pence at the boundary (ADR 0025), stored under row-level security withentity_id. - Failures: 401 refreshes once, then marks the connection broken and alerts; 429 honours
Retry-After; 5xx or a 30-second timeout keeps the last good cache and says how old it is. - Tools read the cache, never HMRC:
vat_obligations,vat_hmrc_account, and the existingvat_verify_returnanddeadlines_upcoming, which use the cache. No tool calls HMRC, submits or approves (rule 5).
Out of scope
- Filing (SPEC-002), except as the route to production credentials under QD-25 option 2.
- MTD for Income Tax (not limited companies); MTD for Corporation Tax (no HMRC date); PAYE (waits for QD-17 (b)).
- Agent access (the accountant's agent services account).
Data model sketch
hmrc_connection (encrypted tokens), vat_obligation, vat_return_filed, vat_liability, vat_payment: each with entity_id under row-level security.
Scenarios
S1: Connect a company
Given a signed-in person with access to FEAW When they complete /hmrc/connect with the sandbox test organisation Then an encrypted hmrc_connection row exists for FEAW only And neither the token nor the code appears in any log
S2: A forged callback is refused
Given a callback whose state is reused, expired, or from another session or entity When it arrives Then it is refused and nothing is stored
S3: Fraud prevention headers pass
Given the sync and the connect page When their headers go to the Test Fraud Prevention Headers API Then HMRC reports no errors, and any warnings are recorded and explained
S4: The sync fills the cache in pence
Given the sandbox's canned obligations and returns When the sync runs Then the cache holds them in integer pence, and a second run changes nothing
S5: Back-test against the filed return
Given the filed March to May 2026 return in the cache When vat_verify_return runs on FEAW's draft for that quarter Then each of the nine boxes matches (SPEC-001 S1)
S6: Expiry is flagged
Given a refresh token 18 months old When the sync runs Then the connection is marked "reconnect needed", an alert goes out, and the deadline radar shows it
S7: Companies are isolated
Given a session for WealthTechPros only When HMRC data is requested Then no FEAW HMRC data is returned
Dependencies
A Developer Hub account on an organisation address, with a sandbox application subscribed to VAT (MTD) and Test Fraud Prevention Headers (QD-23).
QD-25: the route to production credentials. HMRC's VAT (MTD) end-to-end guide sets minimum functionality for production: the fraud prevention headers, retrieving obligations, and submitting a VAT return. Approval also needs a live submission with the VAT number, after sandbox testing, and takes about 10 working days (contact SDSTeam@hmrc.gov.uk; two questionnaires). The guide was checked on 2026-09-30. It names no exception for read-only or in-house software, so read-only production access comes with filing, not before it. The options (the plan's recommendation first):
- Ask HMRC first. Email the SDS team: GetMy Books is in-house software for our own two companies and wants
read:vatonly. Ask whether production credentials can be issued without a submission, or what they need. The fraud prevention headerGov-Vendor-Product-Namealready allows for "internal use only" software. - Build filing (SPEC-002) and file one real return through GetMy Books as the live submission. The first chance after the June to August 2026 return (due 7 October, filed by the accountant) is September to November 2026, due 7 January 2027, and needs Rob and the accountant to agree that GetMy Books files that quarter.
- Stay in the sandbox until one of those lands.
Recommended: option 1 now, with 3 meanwhile; option 2 only if HMRC says no.
- Ask HMRC first. Email the SDS team: GetMy Books is in-house software for our own two companies and wants
QD-26: whose Government Gateway user ID authorises FEAW.
Detail carried over from the plan
These come from docs/plans/hmrc-connection.md and are normative here.
- Paperwork first (Stage 0). A Developer Hub account on an organisation address (
dev@getmy.groupor similar, not a personal one) with Rob and Fraser as team members; a sandbox application subscribed to VAT (MTD) and Test Fraud Prevention Headers; a sandbox test organisation from the Create Test User API; and the email to the SDS team. - Redirect URIs.
https://mcp.getmy.group/hmrc/callback(behind Access, the same login as/mcp), andhttp://localhost:3000/hmrc/callbackfor development only. - Batch headers describe the NAS, the originating device: a stored device UUID, local IPs and MACs, timezone, OS,
Gov-Vendor-Product-Name: GetMy Books, and the version (BATCH_PROCESS_DIRECT, ADR 0006). - Secrets. Production
HMRC_CLIENT_IDandHMRC_CLIENT_SECRETin Dopplerprdonly, the sandbox pair indev. Each company connects once in production. - Tool returns.
vat_obligations: open and recent periods with due date, received date and status.vat_hmrc_account: what HMRC says is owed and paid per period, with the cache's age. - The deadline radar shows "reconnect HMRC" 30 days before the 18 months end.
- Directors' own tax is post-MVP (CAP-02.6).
Exit test
The Product Owner connects FEAW in the sandbox, and S1 to S4, S6 and S7 pass. S5 needs FEAW's real filed March to May 2026 return in the cache, so it can only run against production credentials, which wait on QD-25. S6 cannot be reached by waiting 18 months, so it is exercised with a simulated expired refresh token.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Pence at the boundary | Every HMRC amount is stored as integer pence | S4 |
| V2 | Entity from the session | The entity comes only from the session, and state is bound to the session and entity | S1, S2 |
| V3 | VAT number never from input | The VAT number is the entity's own, checked against HMRC's customer information | Deferred: a scenario is added when the connect page is built |
| V4 | Cache only | No MCP tool calls HMRC | Deferred: a test of the HMRC client's callers is added when the sync is built |