Skip to content

SPEC-017: Self-service onboarding ​

APPROVED 2026-10-09 with ADR 0038. It reverses the not-doing line "Multi-user sign-up". The capability model has no onboarding capability yet, so this spec traces to CAP-01.1 (Xero connection) until the docs track adds one.

AMENDED 2026-11-03 (issue #292, ADR 0042 points 2 and 4): S21. The account pages (/account/*, /xero/*, and SPEC-016's /billing) get their own Cloudflare Access application with an 8-hour session, while the Claude connector keeps 30 days. The app checks that application's AUD (CF_ACCESS_ACCOUNT_AUD) on those paths, as it does for /admin (ADR 0041). / and /start stay under the connector's application.

AMENDED 2026-11-04 (issue #295, QD-35, ADR 0026 amendment, PR #360; Decided 2026-11-04 by the Product Owner (chat)): S23 to S25. S23 and S24 are no longer held: the sweep runs them. A company stops being a customer when both its subscription has ended and its Xero connection is gone (removed, or not renewed within the 60 days a Xero refresh token lasts); retired_at is the later of the two dates, and a comped company never retires. The clock starts at deploy: no company is deleted until 90 days after the deploy that switches the company deletes on, whatever its history (retired_at is set no earlier than that moment).

AMENDED 2026-11-17 (issue #406, from the owner-session review in #420): S27 to S29. connection_check also says, for each company, what is still to set up (bank account, receipts address, company profile, VAT status), each with the tool that fixes it, so the owner no longer finds the gaps one refusal at a time. It stays read-only: it never adds a bank account, whatever Xero holds; bank_account_add saves GetMy Books' own setting only, never Xero.

Business intent ​

Today a new owner cannot start: the operator seeds a principal and an entity (scripts/db-seed-owner.ts), runs the Xero connect script on their laptop (scripts/xero-connect.ts) and adds each statement-file account (scripts/statement-account-add.ts). That is a human service, and GetMy Books must stay a self-service software tool (ADR 0038): the owner does every step, the software only offers it. This slice lets an owner-director sign in, connect their own Xero organisation, add a statement-file bank account from Claude, and remove their access and their company's Xero connection, with no operator involved.

User story ​

When I find GetMy Books, I want to sign in with my email, connect my company's Xero, and see how to add the connector to Claude, so that I can use it the same day without asking anyone. When I stop, I want to remove my access and my company's Xero connection myself.

Scope ​

  • Sign-in stays Cloudflare Access (ADR 0004, 0012). The Access policy admits any email through a one-time PIN (ADR 0038 lists the settings). The app still verifies the Access token on every request and takes the email only from it.
  • GET /start (server-rendered HTML, no script): an email with no principal sees what GetMy Books is (a software tool that finds what to check in Xero; the owner confirms and approves everything; no advice, no filing, no human review of their books) and a form to create an account. The form has a tick-box to accept the Terms of service and the Privacy notice, linked to their pages on the docs site, and carries the current terms version (TERMS_VERSION, src/platform/terms.ts, also printed at the top of both documents). An email with a principal sees its companies, a "Connect Xero" link, the next steps, a "Download my data" link and a "Delete my account" link.
  • POST /start needs the tick-box and the current terms version. It creates the principal for the email in the verified token and records the acceptance (terms_acceptance: principal id, terms version, accepted at; row-level security by the principal in context). Nothing in the form names the email. Doing it twice is harmless.
  • Terms acceptance gates use. A principal that has not accepted the current version (a new version means accepting again) sees the accept form on /start; /xero/* sends it to /start; /mcp and the billing pages refuse it (403, "finish setting up at /start"). Downloading and deleting the account still work without it.
  • GET /xero/connect starts Xero's OAuth with the scope list in src/xero/session.ts and the redirect URI XERO_WEB_REDIRECT_URI. The state is random and bound, through a signed, short-lived, HttpOnly cookie, to the signed-in email. Without XERO_WEB_REDIRECT_URI the connect page says connecting is not set up yet.
  • GET /xero/callback checks the state against the cookie and the signed-in email, exchanges the code, and picks the organisation the owner chose on Xero's consent screen (the one Xero lists with this sign-in's auth event). The organisation's base currency must be GBP (ADR 0025). It creates an entity named after the Xero organisation (its legal name, else its display name), grants the principal access to it, and saves the encrypted token through the existing token store. Connecting the same organisation again only replaces its token.
  • Next steps, shown after a connect and on /start (amended by SPEC-018: now the account home, /, shows them per company): set the company profile in Claude with company_profile_set (company number, VAT quarters, payroll, year end; SPEC-015), subscribe (a form posting to /billing/checkout, built by the billing track), add the connector in Claude with the server URL https://mcp.getmy.group/mcp, and add statement files in Claude (download CSV, OFX or QIF from the bank, attach it in Claude, and bank_account_add links the account to Xero). company_profile_set and bank_account_add work before the company is subscribed (SPEC-016).
  • /mcp still requires a principal, and now also at least one company (an entity_access row) and acceptance of the current terms. Anyone else is refused with 403 and pointed at /start.
  • bank_account_add (MCP tool, entity from the session): with no xeroBankAccount it lists the company's active Xero bank accounts and saves nothing; with one, it creates or renames the statement-file account linked to it. Saves GetMy Books' own setting only, never Xero.
  • GET/POST /account/delete: the confirm page, then removal.
    1. Subscriptions first (SPEC-016 S20 to S22). For each company where the person is the only member and its entity_subscription row has a Stripe subscription that is not already ended (canceled or incomplete_expired), the subscription is cancelled at Stripe through the billing module. If Stripe refuses or cannot be reached, nothing is deleted and the page says so and to try again. With billing not set up (no Stripe settings) deletion goes ahead only for companies with no Stripe subscription id; otherwise it is refused.
    2. Companies only this person uses are deleted completely: the Xero connection (its refresh token revoked at Xero, best effort), the profile, the subscription row, saved column mappings, bank accounts, write previews, the write log, VAT treatments, every access grant and the company row (delete_company_for_principal, migration 0018), and any statement lines held in memory for it (SPEC-003 S39).
    3. Shared companies lose only this person's grant.
    4. The person's terms acceptances and principal row are deleted, unless a record in a shared company still names them.
  • Nothing of the company is kept on delete (issue #255, Product Owner 2026-10-12): its activity log is deleted with everything else (migration 0019). Until then a pseudonymised copy went to retained_activity_log; 0019 deleted those rows, and the table stays empty until it is dropped. Everything above is deleted at once. The company's accounting records themselves stay in its Xero organisation, which GetMy Books never deletes.
  • GET /account/export returns the signed-in person's own account data as JSON (content-disposition: attachment): their email and when the account was made, their terms acceptances, and for each company their grant shows, its name, profile, subscription status (status, period end, comped; no Stripe ids), and bank account names. No Xero books data: that stays in Xero.
  • Security: every POST form carries a token tied to the signed-in email (HMAC under a key derived from XERO_TOKEN_ENCRYPTION_KEY) and is refused when the browser says it is cross-site. All output is escaped. No redirect target comes from input. Pages are no-store with a CSP that allows no script.

Out of scope ​

  • Billing (the billing track): this slice only links to /billing/checkout.
  • Inviting a second person to a company, or several people sharing one. Each sign-up gets its own entity per Xero organisation.
  • Any human help with a customer's books (ADR 0038).
  • HMRC and Companies House connections and any filing.
  • Rate limits (Cloudflare Access sits in front of every route).

Integration sketch ​

  • src/web/onboarding.ts: the routes and pages, mounted from app.ts. Its store and Xero calls are passed in, so it is tested without a database.
  • src/platform/accounts.ts: principal, company list, new company with its grant (create_entity_for_principal, migration 0017), and leaving (entity_has_other_members, migration 0017).
  • src/xero/connect.ts: one path for the script and the web: the tenant chosen on Xero's consent screen, the GBP check and the organisation name, and saving a connection for a principal. src/xero/oauth.ts gains token revocation.
  • src/mcp/bank-account-tools.ts: bank_account_add.
  • src/platform/terms.ts: TERMS_VERSION. src/platform/accounts.ts: sign-up with acceptance, export, and deletion (delete_company_for_principal, migration 0018).
  • src/billing/cancellation.ts: which subscription to cancel, or why deletion is refused (pure); src/xero/connect.ts deleteAccount sets each subscription to end at the period end through the injected Stripe calls before anything is deleted, and puts it back if the deletion is refused (SPEC-016 S20, S21, issue #326).

Scenarios ​

S1: A new email reaches /start, not a 403 ​

Given Cloudflare Access signed in new@example.com, who has no principal When they open /start Then they see the sign-up page with a form to create an account And /mcp still refuses them with 403

S2: Sign-up uses the email from the token only ​

Given new@example.com is signed in When they post /start with a valid form token and any other fields Then a principal is created for new@example.com, and they are sent to /start Amended by SPEC-018 S16 (2026-10-15): they are sent to the account home, /.

S3: A form without the right token is refused ​

When a POST to /start or /account/delete has no token, a token for another email, or Sec-Fetch-Site cross-site Then it is refused with 403 and nothing changes

S4: Connect Xero starts OAuth bound to the person ​

Given a signed-in person with a principal When they open /xero/connect Then they are sent to Xero's authorise URL with the session scopes, XERO_WEB_REDIRECT_URI and a random state And a signed HttpOnly, Secure, SameSite=Lax cookie binds that state to their email for 10 minutes

S5: The callback checks the state ​

When /xero/callback arrives with a state that does not match the cookie, an expired cookie, a cookie for another email, or no cookie Then it is refused with 400 and no code is exchanged

S6: A connect creates the company and saves its token ​

Given Xero lists two organisations and the token's auth event matches "Acme Ltd" only When the callback completes Then an entity "Acme Ltd" is created with access for the person, the token is saved encrypted for it, and the page shows the next steps Amended by SPEC-018 S16 (2026-10-15): the person is sent to the account home, /, which shows the company's card.

S7: Only GBP organisations connect ​

When the chosen organisation's base currency is not GBP Then nothing is saved and the page says why

S8: Reconnecting replaces the token only ​

Given the person already has the entity connected to that Xero organisation When they connect it again Then no new entity is created and the token is replaced

S9: /mcp needs a company ​

Given a principal with no entity_access row When they call /mcp Then it is refused with 403 and told to finish setting up at /start

Given the company's Xero has bank accounts "Business Current" and "Amex" When bank_account_add is called with no xeroBankAccount Then it lists both and saves nothing When it is called with xeroBankAccount "Amex" Then a statement-file account "Amex" linked to that Xero account is saved for that company only

S11: Deleting the account deletes the company completely ​

Given the person is the only member of "Acme Ltd", which has a Xero connection, a profile, a subscription row, a bank account with a column mapping, a write preview, a write log row, VAT treatments and activity log rows When they confirm on /account/delete Then every one of those rows, the access grant and the company row are deleted, the refresh token is revoked at Xero, and their terms acceptances and principal are deleted unless a record in a shared company names them And its activity log rows are deleted too, with no copy kept in retained_activity_log (issue #255)

S12: Deleting leaves shared companies alone ​

Given another person also has access to the company When one of them deletes their account Then only their grant is removed; the Xero connection stays

S13: Output is escaped and nothing redirects off-site from input ​

When an organisation name or an error contains HTML Then it is shown as text And every redirect goes to a fixed path or Xero's authorise URL

S14: Sign-up needs the terms accepted ​

Given new@example.com has no principal When they post /start without the acceptance tick-box, or with a terms version that is not the current one Then it is refused with 400 and no principal is created When they post it ticked with the current version Then the principal is created and terms_acceptance records their principal id, the version and the time

S15: A new terms version must be accepted again ​

Given a principal with a company accepted an older terms version When they open /start, /xero/connect or /mcp Then /start shows the accept form, /xero/connect sends them to /start, and /mcp gives Claude the setup notice (S20) And /account/export and /account/delete still work

S16: Deleting a company cancels its subscription first ​

Given the person is the only member of "Acme Ltd", whose subscription is active at Stripe When they confirm on /account/delete Then the Stripe subscription is cancelled through the billing module before anything is deleted (set to end at the period end, SPEC-016 S20, issue #326, 2026-11-03)

S17: Deletion is refused when the subscription cannot be cancelled ​

Given Stripe refuses or cannot be reached when cancelling Acme Ltd's subscription, or billing is not set up and Acme Ltd has a Stripe subscription id When they confirm on /account/delete Then nothing is deleted and the page says the subscription could not be cancelled and to try again later And with billing not set up and no Stripe subscription id, deletion goes ahead

S18: The owner downloads their account data ​

When a signed-in person opens /account/export Then they get JSON with their email, terms acceptances, and each company's name, profile, subscription status and bank account names And no Stripe ids, Xero tokens or Xero books data

S19: The next steps say to set the company profile ​

When a connect completes, or a person with a company opens /start Then the next steps say to set the company profile with company_profile_set (company number, VAT quarters, payroll, year end), which works before subscribing Amended by SPEC-018 S10, S16 (2026-10-15): both now land on the account home, /, whose company card says when the profile is not set and to ask Claude to set it up.

S20: Claude tells a person without access what to do ​

Given a person Cloudflare Access signed in who has no GetMy Books account, or has not accepted the current terms When Claude connects to /mcp Then the server lists only connection_check, which reads nothing and answers that they must sign in at /start to finish setting up or to accept the current terms, with the full link And its instructions tell Claude to say so before anything else And no tool that reads or writes books data is listed or callable

S21: The account pages take only their own Access application's token (issue #292, 2026-11-03) ​

Given CF_ACCESS_ACCOUNT_AUD is set to the AUD of the "GetMy Books account pages" Access application (8-hour session, ADR 0042) When a signed-in person opens /account/delete, /xero/connect or /billing/portal with a token for the connector's application (CF_ACCESS_AUD, 30 days) Then the reply is 401 and nothing runs And with a token for the account pages' application the page works as before And /, /start and /mcp still take the connector's token, and refuse the account pages' token And with CF_ACCESS_ACCOUNT_AUD not set, every page takes the connector's token, as before

S22: Old write records and activity log rows are deleted after six years (issue #295, 2026-11-03) ​

Given a company whose profile says its year ends on a given day and month, and another with no year end When the sweep runs Then a ledger_write or activity log row is deleted the day after the sixth anniversary of the end of the financial year it was written in, and kept until then And with no year end, the day after the seventh anniversary of the day it was written And nothing else of the company changes

S23: A company that stopped being a customer is deleted 90 days later (issue #295, 2026-11-03; amended 2026-11-04) ​

Given a company whose subscription has ended (not comped; no row, or a Stripe status other than active, trialing, past_due, unpaid, incomplete or paused), ended on the date its row last changed (or the day the company was created, with no row) And whose Xero connection is gone: no connection row (gone on the first sweep that saw it so), or a row whose token was last saved more than 60 days ago (gone 60 days after that save, when Xero's refresh token ran out: disconnected in Xero, or never reconnected) When the sweep runs Then entity.retired_at records the later of the two dates, and is cleared again if the company subscribes or reconnects And 90 days after retired_at the company and everything held for it are deleted, as account deletion does (S11) And a live customer, a company whose subscription ended but whose Xero connection is still live, a comped company, and a company retired less than 90 days ago, are untouched And no company is deleted until 90 days after the deploy that switched the company deletes on (recorded once by migration 0036, never moved by a later deploy), however long ago it left: retired_at is never set earlier than that moment, so a company that left before it counts as leaving then

S24: A person nothing names any more is deleted (issue #295, 2026-11-03; amended 2026-11-04) ​

Given a person with no access grant, named by no ledger_write, activity log, preview or column-mapping row, whose sign-up, terms acceptances and usage records are all more than 90 days old When the sweep runs Then the person and their terms acceptances are deleted And a person still named by one ledger_write row, a person with a grant, and a person who signed up in the last 90 days are kept

S25: The sweep logs counts only (issue #295, 2026-11-03; amended 2026-11-04) ​

When the sweep runs Then it runs the six-year deletes (S22), then the company delete (S23), then the person delete (S24) And when any of them removes anything, the server logs one line with how many write records, activity log rows, companies and people were deleted, and nothing else about them

S26: A smoke probe proves the MCP server answers, for one service token only (issue #81, Product Owner decision 2026-11-06) ​

Given CF_ACCESS_SMOKE_AUD is the AUD of the "GetMy Books smoke probe" Access application on /smoke/mcp (a Service Auth policy) and SMOKE_ACCESS_CLIENT_ID is its service token's client id When the post-deploy smoke test sends GET /smoke/mcp with that service token Then the app verifies the Access token as for every door (issuer, audience, signing keys) and that it names no email and its common_name is SMOKE_ACCESS_CLIENT_ID And it starts the MCP server in-process with no principal, lists its tools, and answers 200 with only {"status":"ok","tools":<count>}: no tool names or payloads, no company data, nothing written And a request with no token, a token that does not verify, a person's token (with an email), or another service token is refused (401 or 403) and nothing runs And with either setting not set the route answers 404 And /mcp is unchanged: a service token there is still refused as having no email (403)

S27: connection_check lists what each company still needs, each with its fix (issue #406, 2026-11-17) ​

Given receipts by email is set up on the server And a connected company with a profile but no VAT status in it, no bank account in GetMy Books and no receipts address When connection_check is called Then that company's row carries one list of gaps: its bank account, its receipts address and its VAT status, each with the step that fixes it (bank_account_add, receipts_address, company_profile_set) And a company with no profile has one gap for the profile (company_profile_set), which covers its VAT status And a company with a profile, a VAT status, a bank account and a receipts address has no gaps, and the reply says it is ready to go And with receipts by email not set up on the server, no receipts address gap is listed And nothing is saved in GetMy Books or in Xero

S28: A missing bank account lists the Xero bank accounts in the same reply (issue #406, 2026-11-17) ​

Given a connected company with no bank account in GetMy Books When connection_check is called and Xero has two active bank accounts, "Business Current" (code 090) and "Card" (code 091) Then the bank account gap lists both by name and code, and says to ask the owner which one their statements are for and then call bank_account_add with that xeroBankAccount And when Xero has exactly one, the fix names it: bank_account_add with xeroBankAccount "Business Current" saves it in one step And when Xero has none, the fix says to add the bank account in Xero first, then call bank_account_add And connection_check adds no bank account itself, however many Xero has

S29: No "It has: none" without a next step (issue #406, 2026-11-17) ​

Given a company with no bank account in GetMy Books When a bank tool is asked for the bank account "Business Current" Then the refusal says the company has no bank accounts set up and to add one with bank_account_add And when Xero has no active bank account and receipts are looked for against a named Xero account, or bank_account_add is given an account Xero does not have, the refusal says Xero has none and to add the bank account in Xero first, then call bank_account_add

Exit test ​

The Product Owner, with a fresh email that has no principal: signs in through Access with a one-time PIN, creates the account on /start, connects a GBP Xero demo company, sees it listed with the next steps, adds the connector in Claude and runs connection_check, company_profile_set and bank_account_add, downloads the account data from /account/export, then deletes the account and sees /mcp refuse that email.