Appearance
0038: Self-service onboarding
Context
GetMy Books is to be sold to UK owner-directors on Xero, used from Claude. Today every new owner needs the operator: a seeded principal, the Xero connect script run on a laptop, and a script per bank account. That is a service done for the customer, and the launch decisions of 2026-10-09 keep GetMy Books outside AML supervision as a self-service software tool: the owner does every step, Get My Books staff never prepare or review anyone's books, and support is for the software only. "Multi-user sign-up" was on the not-doing list; this ADR reverses it (the docs track edits docs/not-doing.md).
Decision
Keep the auth model. Cloudflare Access verifies who someone is; the app verifies the Access token on every request (ADR 0012, rule C4) and takes the email only from it. Data access stays principal rows plus row-level security by
entity_access(ADR 0003).Access admits any email by one-time PIN, Microsoft or Google. The app, not the Access allowlist, now decides what a signed-in person can do. ADR 0020's named allowlist and Entra-only rule are amended as below; its 8-hour session stays. Amended 2026-10-15 (Product Owner, at Rob Duncan's request: the emailed PIN alone looked unofficial). The "Self-service Sign-up" policy admits any of three login methods: Cloudflare's one-time PIN; Google (a Google Cloud OAuth client in the getmy.group organisation); and Microsoft (the multi-tenant app "GetMy Books sign-in" in the getmy.group tenant, through Cloudflare's generic OIDC on Microsoft's
commonendpoint, so any work, school or personal Microsoft account). Microsoft returns theemailclaim only for a domain the tenant has verified (unverified email claims are removed for multi-tenant apps), so another tenant cannot claim an address it does not own. Customers start atgetmy.group/signin, whose buttons each go to an Access path onmcp.getmy.group/signin/<provider>that allows that one method and redirects to it, so Cloudflare's chooser (monochrome icons, branding shared with FEAW's portal) is not shown; the app then sends them to/start(since ADR 0041: to the account home,/, which sends anyone without an account on to/start). The single sign-in carries across the Access applications on the team domain. The app still takes only the email from the signed token (decision 1).Signed in but unknown reaches
/startonly. Routes under/start,/xero/and/account/accept a verified email with no principal row;/mcpstill refuses it, and now also refuses a principal with no company.POST /startcreates the principal.Xero connects from the web with the same scopes as the script and one shared code path (
src/xero/connect.ts). The organisation is the one chosen on Xero's consent screen (Xero's auth event id), never the first listed. The redirect URI isXERO_WEB_REDIRECT_URI.A new company is created by a narrow database function (
create_entity_for_principal, migration 0017): theentitypolicy needs anentity_accessrow before the entity is visible, and the grant needs the entity first, so the app role cannot do both under RLS. The function creates exactly one company and one grant, for the principal in the transaction's context, and nothing else.Leaving is self-service (
/account/delete). Credentials and the owner's VAT memory go at once; the accounting record stays for its retention period (SPEC-017 lists both). Whether another person shares a company is read byentity_has_other_members(migration 0017), since RLS shows a person only their own grants.Amended 2026-10-09 (launch integration): deleting the account first cancels the Stripe subscription of each company only that person uses (refusing, and deleting nothing, if Stripe cannot), then deletes that company completely through
delete_company_for_principal(migration 0018). Amended 2026-10-12 (issue #255): its activity log is deleted too, with no copy kept (migration 0019)./account/exportgives the person their own account data as JSON.Forms use a token tied to the signed-in email (HMAC under a key derived from
XERO_TOKEN_ENCRYPTION_KEY, so no new secret), plus Sec-Fetch-Site and the SameSite Access cookie.Terms acceptance (ADR 0036 rule 5).
/startneeds a tick-box accepting the Terms of service and Privacy notice, at the version insrc/platform/terms.ts(printed at the top of both documents). The app records principal, version and time interms_acceptance(row-level security by principal). A principal that has not accepted the current version is sent back to/startto accept it, and/mcpand billing refuse it; export and delete still work.
Owner actions (Cloudflare and Xero)
On the Access application GetMy Books MCP (mcp.getmy.group, team feaw), applied by the Product Owner:
| Setting | Value |
|---|---|
| Login methods | add One-time PIN; keep "GetMy (getmy.group)" Entra |
| New policy, first in order | Name "Self-service sign-up"; Decision Allow; Include Everyone; Require login method One-time PIN; Exclude none |
| Existing policy "Named people, Entra with MFA" | keep, unchanged, for the operators |
| Application session | 8h (unchanged) |
| Instant Auth | off, so the login page offers both methods |
| Paths covered | the whole hostname: /, /mcp, /start, /xero/*, /account/*, /billing/* (/health stays bypassed as today; /admin has its own application, ADR 0041) |
Managed OAuth for /mcp | unchanged (ADR 0012) |
In the Xero developer portal, on the GetMy Books app, add the redirect URI https://mcp.getmy.group/xero/callback, and set XERO_WEB_REDIRECT_URI=https://mcp.getmy.group/xero/callback in Doppler prd. The app's Xero tier must allow as many connected organisations as customers (ADR 0024).
Consequences
- One-time PIN is a single factor: anyone who controls the email inbox can sign in as that person. An owner's books are then reachable by whoever holds their mailbox, as with Xero's own email sign-in. MFA stays required for the operators' Entra policy.
- Anyone can create a principal row. It holds only an email and grants nothing until that person connects their own Xero.
- The kept records name a deleted person's email while they are kept (ADR 0026's proposed retention). The scheduled deletes ADR 0026 lists are built (issue #295, migration 0034, ADR 0026 amendment of 2026-11-03), and since PR #360 (Decided 2026-11-04 by the Product Owner (chat)) the person delete (no grant, named by no kept record, nothing newer than 90 days) runs on the server's sweep, after the delete of former customers' companies.
- Support stays for the software only: the pages and the tool descriptions never offer anyone to look at the customer's books.