Accounts, sites and membership behind WorkOS sign-in

[lemarier]

The first cloud slice: accounts, sites and membership, which do not wait for the KM43 key work (origin89hq/km43#128, #129). Design and decisions: origin89hq/internal-research#1.

Scope

• Tokens. Verify WorkOS access tokens (JWT) against the WorkOS JWKS. Store our own user_id, and keep the provider's issuer and subject as an alias, never a bare sub.
• Model. Users, sites (named by the owner), controllers by device_id with an ownership generation, and memberships (owner, admin). History and access belong to a generation, never to a device_id alone.
• Linking. Link a controller the phone is already enrolled with to a site. The request carries device_id, epoch and a display name; it never carries the printed secret or a client key. Membership grants no controller access; the controller stays the authority.
• Account deletion, required in-app by App Store guideline 5.1.1(v). The server deletes the WorkOS user with the secret API key and removes memberships. It does not touch controller enrolments.
• API contract. A versioned contract package that the apps pin, following the Buddy pattern.

Out of scope

Invites, the readings store and MQTT, which wait for km43#129.

Repository setup still open

• Tooling and a Checks workflow land with the first code. When they do, add its job as a required status check.
• main has no branch protection or ruleset yet: GitHub refuses both on a private repository in a free organization. Either make the repository public, as the other service repos are, or upgrade the organization, then apply the buddy/website protection: PR required, linear history, conversation resolution, admins included.

Acceptance

Tests for token verification (valid, expired, wrong issuer or audience, unknown key), linking (success, duplicate, another owner's generation), and deletion; the contract published and consumed by origin89hq/apps.

[lemarier]

Follow-up for this slice: receive Sign in with Apple server-to-server notifications (consent revoked, Apple account deleted, email forwarding changed) at an HTTPS endpoint of this service. Verify their signed JWT and disable or delete the matching user. Then set that URL on the com.origin89.apps.ios App ID's Sign in with Apple configuration; it is left empty until the route exists.

[lemarier]

Sign-in methods are Apple, Google, passkeys and Magic Auth. With Magic Auth, whoever controls someone's email can sign in as them. So require a fresh sign-in (a recent auth_time) for invites, account deletion and linking a controller. Choose the production AuthKit domain before release, because passkeys are bound to it.

[lemarier]

Where the WorkOS credentials live, with separate staging and production WorkOS environments:

• Client IDs (public): plain per-environment configuration in this repo's deploy variables, as Buddy does. The app keeps them in a checked-in xcconfig: Debug uses staging, Release uses production.
• API keys: a Cloudflare Worker secret per Worker (wrangler secret put WORKOS_API_KEY) for staging and production, and .dev.vars (gitignored) for local development. Never stored in the app, never in GitHub Actions. A webhook secret, if added, is handled the same way.
• Apple .p8 and the Google client secret: only in WorkOS.
• Shared vault: the API keys and the .p8 are kept in a team vault as the source for restoring and rotating them.
• GitHub: holds only the org secret CLOUDFLARE_API_TOKEN and variables (account ID, Worker names, client IDs). Deployment environments need the repository to be public or the org to be upgraded, the same blocker as branch protection.

[lemarier]

WorkOS client IDs (public, ship in the app):

• staging: client_01M3C9M944Y53VA9PJRCW8T5S6
• production: client_01M3CC0Q23FPHK50YW1WXCNZ3S

The production application needs the same redirect com.origin89.apps.ios://auth/callback and its own Apple and Google provider credentials. Google there must use our own Web application client, not demo credentials.

The cloud accepts tokens from the client ID of its own environment only: staging Workers accept the staging ID, production Workers the production ID.