Appearance
SPEC-008: Xero connection
Written after the build. The connection is built and in daily use. This spec describes what the code does today, so the capability has a spec to trace to; the scenarios are the behaviours the existing tests already pin.
Business intent
Xero is the ledger (Vision, horizon 1). Every check GetMy Books makes starts with a Xero read, so each company needs a connection that stays valid without anyone re-authorising it every half hour, that never leaks across companies, and that fails loudly when it breaks. Protects SM-3: no figure is traceable if the connection read the wrong company.
User story
When I connect FEAW or WealthTechPros to Xero once, I want every later check to use that company's own connection, refreshed automatically, so that I am never asked to sign in again, and a problem is raised before it is noticed.
Scope
- Connect once per company (
scripts/xero-connect.ts). The access and refresh tokens are stored encrypted (AES-256-GCM,src/platform/crypto.ts) inxero_connection, one row per entity, under row-level security (ADR 0003). Reconnecting updates that row. - Scopes requested in
src/xero/session.ts. Read-only: invoices, payments, contacts, settings, and the bank summary report. Write-capable: bank transactions (bank_entries_preview, ADR 0016), manual journals (vat_corrections_preview, ADR 0017) andfiles(the Files inbox and its links, ADR 0031), plusoffline_access. So the connection can write to Xero, and every write is previewed and approved first (AUDIT M4, C5). A scope change means each company reconnects once. Note, 2026-10-30 (ADR 0043):accounting.invoices(write) replacesaccounting.invoices.read, forinvoice_create_preview(SPEC-019); each company reconnects once for it. - A valid token on every call.
getValidAccessTokenreturns the stored token if it has not expired (with 30 seconds of slack), else refreshes it. Xero rotates the refresh token, so a refresh is saved only over the version that was read (optimistic concurrency): of two processes refreshing at once, exactly one is stored and the other uses the winner. - Which organisation. Xero lists every organisation the app is connected to, so the first is not safe. A company's organisation is the one whose name contains the company's name, ignoring case (
src/xero/tenant-choice.ts). An explicitTENANT_IDwins, but aTENANT_IDXero did not offer is refused with an error, not ignored. No match, or more than one, is refused, never guessed. - What the organisation says. Legal name (falling back to the display name), VAT scheme, base currency and lock dates (
src/xero/organisation.ts). A missing VAT scheme or currency is undefined, which the rules refuse; an organisation not in GBP is refused (ADR 0025). - Rate limits (
src/xero/http.ts, and the write path insrc/xero/bank-writes.ts). The daily limit (5,000 requests for an organisation) stops at once, with no retry, and says roughly when it resets. Any other 429 waits as long as Xero'sRetry-Aftersays, or a default delay (normally 5 seconds, 1 second for the open-documents read) when it says nothing, and retries at most 3 times. For reads, a limit that still has not cleared says which limit it was. Writes (the PUT path) retry the same way, but after 3 retries fail with the generic "Xero refused …: HTTP 429" and do not name the limit. That inconsistency is known and left as a follow-up. - Failures that may pass are tried again, a little (2026-11-02, #297). A read that Xero answers with a 5xx, does not answer within the time limit, or cannot reach Xero at all is tried again at most twice, after 1 second and then 3 seconds (S16). A write carries an
Idempotency-Key, so Xero applies it once however often it is sent: it is tried again the same way, but only when Xero could not be reached, did not answer, or answered 502, 503 or 504 (S17). A 4xx is never tried again. These retries are separate from the 429 retries above. - Failures are alerted. Three failed refreshes in a row for one entity log an alert and send a push, once; a success resets the count; each entity is counted separately. The counts live in the app's memory, so a restart starts them again. A refresh that fails because another process already rotated the token, and is then rescued by the stored winner, counts as neither a failure nor a success. The push goes out only when
ALERT_NTFY_TOPICis set. - A connection Xero no longer accepts is alerted once (2026-11-02, #297). When refreshing a company's connection says it must be reconnected (the grant expired, was revoked or the company was disconnected in Xero), an alert is logged and a push "Xero reconnect needed" is sent, once for that company until a refresh succeeds again (S18). The push names no company, person or figure; the log carries the entity id. A 401 on a call made with a token not yet due for refresh is not alerted itself: the next refresh, within the token's 30 minutes, says the same and alerts. Like the counts above, this lives in the app's memory, so a restart may alert once more.
Out of scope
- The number of Xero connections and Xero's tiers for other customers (ADR 0024), until anyone outside FEAW and WealthTechPros is onboarded.
- Ledgers other than Xero (
docs/not-doing.md).
Data model sketch
xero_connection (entity_id, encrypted access and refresh tokens, expiry, tenant id, token version), row-level security by entity.
Scenarios
S1: A token round-trips, encrypted
Given a connection saved for an entity When it is loaded Then the access token, refresh token, expiry and tenant match what was saved And the stored columns never contain the plaintext tokens
S2: Saving again replaces the stored connection
Given an entity that is already connected When it is saved again Then the later token is the one loaded And there is one connection per entity: the table's primary key is the entity (src/platform/schema.ts), which the test relies on and does not assert
S3: A valid token is used as it is
Given a stored token that has not expired When a token is needed Then it is returned with no refresh
S4: An expired token is refreshed and saved
Given a stored token that has expired When a token is needed Then Xero is asked for a new one and it is saved over the version read
S5: Two refreshes at once store one
Given two processes refreshing the same token When both try to save Then exactly one is stored and the other uses the stored winner
S6: Never connected is said plainly
Given an entity that was never connected When a token is needed Then the error says Xero is not connected for that entity
S7: Companies are isolated
Given a token stored for one entity When another entity's connection is asked for Then nothing is returned: the row-level policy is scoped by entity And a refreshed token cannot be saved for an entity the caller cannot see
S8: Repeated refresh failures alert once
Given three failed refreshes in a row for one entity When the third fails Then an alert is logged and a push is sent, once And a success resets the count, and each entity is counted on its own
S9: The organisation is never guessed
Given a company name and the organisations Xero lists When the match is none, or more than one Then it is refused with the organisations Xero offered And a TENANT_ID that Xero did not offer is refused too
S10: A missing scheme or currency is refused by the rules
Given an organisation with no VAT scheme or base currency set When its facts are read Then each is undefined, and the rules refuse to derive a return (that refusal is SPEC-001 S7; the currency refusal is S13)
S11: A rate limit is waited out or named
Given Xero answers 429 to a read (not the daily limit) When the retry-after is given Then the call waits as long as Xero says, and retries at most 3 times (four calls in all) And a limit that never clears names which limit it was
S12: The daily limit stops at once
Given Xero answers 429 with the daily limit problem When the call is made Then it is not retried, and the error says the organisation's daily limit is used up and roughly when it resets
S13: An organisation not in pounds is refused
Given an organisation whose base currency is not GBP When a check reads it Then it is refused before any figure is read (ADR 0025)
S14: A long Retry-After never holds a call for long (approved 2026-10-06 by the Product Owner, pre-sale review)
Given Xero answers 429 (not the daily limit) with a Retry-After longer than a minute When the call waits to retry Then each wait is at most 60 seconds, and after 3 retries it gives up naming which limit did not clear (S11)
S15: A write is rate limited the same as a read (approved 2026-10-06 by the Product Owner, pre-sale review)
Given Xero answers 429 to a write (spend or receive money, a transfer, a journal, or attaching a file) When the limit never clears, or it is the daily limit on any attempt Then the error is the one a read gives: which limit did not clear after 3 retries, or that the daily limit is used up and roughly when it resets And never "Xero refused …: HTTP 429"
A daily-limit 429 on any attempt, the last retry of a read or a write included, gives the daily-limit message with its reset time, never "did not clear" (review of PR #205).
S16: A read Xero fails or does not answer is tried again, a little (2026-11-02, #297)
Given Xero answers a read with a 5xx, does not answer within the time limit, or cannot be reached When the call is made Then it is tried again at most twice, after 1 second and then 3 seconds (tests shorten the waits) And the third failure is reported as it came And a 4xx is reported at once, never tried again
S17: A write is tried again only when it is safe (2026-11-02, #297)
Given a write (every write carries an Idempotency-Key, so Xero applies it once however often it is sent) When Xero cannot be reached, does not answer within the time limit, or answers 502, 503 or 504 Then it is sent again at most twice, after 1 second and then 3 seconds, with the same key And a 4xx, or a 500, is reported at once, never tried again
The Files upload (SPEC-021, receipts by email) is a write like any other: it carries an Idempotency-Key, so it is sent again the same way, with the same key and the same file, and a 4xx or a 500 is reported at once (2026-11-03, #340). Every request to Xero, the upload included, follows one retry policy.
S18: A connection Xero no longer accepts is alerted once (2026-11-02, #297)
Given Xero refuses a company's refresh because the connection must be reconnected When the refresh fails, and again on every later call for that company Then an alert is logged with the entity id and a push "Xero reconnect needed" is sent, once And the push names no company, person or figure And another company's reconnect is alerted on its own And once a refresh for that company succeeds (it was reconnected), a later reconnect is alerted again
Dependencies
XERO_TOKEN_ENCRYPTION_KEY,XERO_CLIENT_ID,XERO_CLIENT_SECRET(Doppler).XERO_REDIRECT_URIis optional and defaults to the local callback used by the connect script.- The alerting push (
docs/plans/alerting.md):ALERT_NTFY_TOPIC(Dopplerprd, optional; without it no push is sent).
Exit test
Each company reads through its own stored connection after an access token has expired, with no manual step. To be confirmed by the Product Owner.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Encrypted at rest | Stored tokens never appear in plaintext | S1 |
| V2 | One writer wins | A refresh saves only over the version read | S5 |
| V3 | Entity isolation | No principal can read another entity's connection | S7 |