Devices, password-hash import, external billing, an operator console, and operator permissions

[libworky]

This branch carries the work from running Rekey as the licensing and entitlement layer for a desktop product. The earlier revision of this PR covered devices, password-hash import and a bring-your-own billing provider. This revision adds the operator surface those features needed, plus a permission model that the operator surface turned out to require. Each part is its own commit series and stands alone. If only some of it is interesting to you, tell me which and I will split the rest out.

1. Devices, password-hash import, external billing provider

Unchanged from the earlier revision. Devices are a table with a status of ACTIVE, RELEASED or BLOCKED, optionally bound to sessions through a dev claim, with the cap sold as an entitlement (max_devices). Password hashes can be imported so users of an older system sign in without a reset. The external billing provider accepts subscription events from a billing system Rekey does not talk to, signed with a shared secret, with a documented contract for the event feed.

2. An operator console for support work

Before this, an operator looking at an end-user could read a lockout counter and a device list and act on neither. Every remedy needed a developer with an API client.

The end-user page is now a set of routed tabs: overview, subscriptions, devices, credits, security, data. Seven routes back it: unlock, resend verification, send a password reset (with a reason that lands in the audit trail, since an unrequested reset mail looks the same to the recipient as an attacker who reached the panel), list and revoke sessions, and release every device. Operators can also grant and cancel subscriptions from the panel, which used to be super-admin only.

Two role floors moved while doing this. Erasing an end-user and the plain cascade delete are both workspace-owner only now. The cascade delete was gated on write alone, so a member with an application grant could delete a person while the erase form correctly refused them.

Three API bugs came out of this. Device security events were written with an application id but no workspace id, and the read path filtered on workspace id, so the entire device audit trail was recorded and shown nowhere. The fix is on the read side: deriving the workspace during the write put a database read on the audit path and reordered webhook deliveries. Open-ended subscription grants were cancelled immediately rather than at period end, because with no period there is nothing to schedule against.

3. Email control

There was no way to stop an application sending email: not globally, not per event, not for one address. A product whose own backend already sends transactional mail delivered two of everything.

Three gates now sit in dispatch(), in order: a per-application master switch (a column, because the credentials save rewrites the config JSON wholesale and a flag stored there would be dropped), a per-event switch, and a suppression list keyed on lowercased address. Each suppression writes a log row with status: suppressed and the reason, so the delivery view can answer why a mail did not go.

One rule here is load-bearing. A suppressed send returns error, not no_transport. no_transport is the documented contract that hands the raw reset or magic-link token back to the caller so a self-hosted deployment without email can deliver it. Reporting a suppression that way would have turned "we switched email off" into "the API now returns live reset tokens".

Disabling an email the live auth config depends on (password reset while password sign-in is on, verification while verification is required) is refused rather than warned about, and the same check runs when the auth config is changed, from both the REST route and the MCP tool, so the coupling holds in both directions.

The email page is split into settings, templates, delivery and suppressions.

4. Subscription import

The event feed covers everything from the moment a billing system connects. It cannot cover what was sold before, which on migration day is the whole book of business.

An import is a run, not a call. Starting one reads the provider and records, per row, what would happen and why: matched by email, created as an unlinked user, skipped because no plan maps, skipped because the user already has a live subscription, or invalid. Nothing is written until the operator applies the preview behind a typed confirmation. An import never overwrites live entitlement and never matches an erased user.

The external provider gains a read side: one paginated endpoint the customer hosts, with a documented contract (docs/external-billing-pull.md). The request signature is deliberately not the webhook signature. The webhook helper signs the body, and a GET has no body, so reusing it would sign a constant per second. This direction signs the method and path. The fetch gets the same hardening as an outbound webhook delivery: resolved-address checks, pinned connections, refused redirects, capped body reads.

5. Operator permissions

A workspace had one lever for a member: which applications they could touch, and one of three roles on each. Every grant conferred read on everything. A support agent given an application to work in saw its revenue and every payment, and the only alternative was refusing them the application.

Rekey already had scopes on personal access tokens and MCP tokens. This attaches one registry of scopes to the membership itself: seven domains (end-users, billing, auth-config, developer, organizations, activity, overview) at read or write, with write implying read. The three grant roles become presets over the same vocabulary, and the effective set for a request is the intersection of the grant preset and the membership's scopes, so neither can widen the other. Tokens intersect with their holder's scopes at request time.

Every operator route declares what it needs on its route config, and a test reads the live route table and fails the build if any route is unclassified. The decision that used to exist in three diverging copies (two REST helpers and an MCP one) is one function over a plain context. The scope check runs after the existing existence and grant checks, so an application the caller cannot see still answers 404 and only one they can see answers 403 with the missing scope named.

Grants, roles, invitations, lifecycle, impersonation and erasure are floors that no scope can unlock. A team:write scope on a member would let them grant themselves everything and rewrite their own scopes, so it does not exist.

/me and the application read return the caller's resolved scopes, and the panel renders navigation from them instead of inferring an operator's role from a redacted field, which it did. The team page gets a scope editor. MCP tools consult the same registry, with role as the ceiling: an owner or admin passes the gate before the row is read, and promoting a member clears their stored scopes. The security event each tool call records names the scope that admitted it, and the request log carries the same per request, since under scopes "who did it" no longer implies "what they were allowed to do".

Nothing changes for an existing deployment until an admin restricts somebody. The two new membership columns carry constant defaults and the migration rewrites no rows. One deliberate change for existing APP_BILLING holders: provider credentials and refunds were plain write before, so the billing role could do neither. Under the preset it can.

6. A per-workspace switch for the operator MCP server

Two kill switches existed already, one for the whole deployment and one per application for the end-user MCP server. Neither let a workspace owner say that no agent may act as any of their operators. A workspace flag does that now. Off refuses every access token presented for the workspace at auth time and grants no new consent. It does not gate refresh: an agent holding a refresh token keeps rotating it while the workspace is off, and what it mints is refused like any other token, so nothing is revoked and turning the flag back on restores every agent without a re-consent. The flag is read through the membership row auth already fetches, so it costs no extra query per call, and flipping it is a security event.

Token lifetimes as deployment settings

The end-user and operator access tokens were fixed at 15 minutes and both refresh tokens at 30 days. Four settings replace the constants, with the old values as defaults and ceilings of a day, half a day and a year: a desktop application that opens once a month wants a longer refresh window, and an operator on a shift wants an access token that outlasts it. Refresh tokens are sliding, so the window only has to cover the longest gap between uses.

A longer access token needed a way to end a session early, since password change, sign-out everywhere, session revoke and device release only revoked refresh tokens. Both user models carry a "sessions invalid before" instant that every one of those paths stamps; the session middlewares and the SDK's user read refuse an access token issued before it on its next use, with the code SDKs already refresh on, so sessions that were not ended renew silently and only the ended one lands on sign-in. The panel and portal set their session cookies from the expiries the auth responses already carried instead of constants of their own.

Panel navigation

The end-user page had reached three stacked tab strips and two back links before showing anything about the user. Nested pages now get at most two tab strips; a third level becomes a segmented control inside the record's own header, and a breadcrumb replaces the back links. Three panel bugs were fixed along the way: nested tab strips never set aria-current, nested headings rendered at the same size as the page heading, and two comments cited a design document that did not exist.

Panel parity

A route-by-route comparison of the operator API against the panel found four things the API could do that the panel could not show or do. Both event logs rendered the event type and actor only, so what an event actually said (which tool an agent called and under which scope, whether a switch went on or off, which plan a grant named and why) was written and shown nowhere; a whitelisted set of metadata keys now renders as chips. The request log's read schema never declared the admitting scope, so the serializer dropped it before any client saw it; it is declared and shown. Adjusting a subscription's entitlement overrides and ending every live impersonation of an end-user existed only as routes; both have a panel surface now, and the billing view returns a subscription's current overrides so the dialog can show what it is changing.

Security events by the person they are about

The end-user page asks one question of the audit log: what happened to this person. The log stored the answer in two places. A person's own events name them as the actor; anything done to them by an operator or the system names them in metadata.endUserId, with somebody else as the actor. Nothing could filter on "either", so the panel read the application's latest 200 events three times, once per actor type, and matched both fields in memory. That was 600 rows fetched to render twenty on every view, and it missed a quiet user's history on a busy application entirely.

recordSecurityEvent now derives a subject_end_user_id at the one place events are written, so no emit site changed, and GET /tenant/security-events accepts ?endUserId= as an indexed equality. The migration backfills existing rows with the same rule. The explicit subject wins over the actor when both are present; in recorded data they never disagreed. A JSON expression index was the alternative and was rejected because Prisma cannot express one, so it would have lived only in migration SQL and read as drift on every later migrate.

The GDPR export had the same hole: it filtered on the end-user as actor, so a subject-access request omitted everything operators and the system did to the person. It now reads by subject. The acting operator's id is still not exported, since it is staff data rather than the subject's.

Log retention and an optional archive

security_events, email_logs and webhook_deliveries only ever grew. LOG_RETENTION_DAYS (default 30) prunes them on the existing ten-minute prune timer in bounded batches.

The rules are narrower than "delete old rows". Deliveries are pruned only when SUCCEEDED or FAILED and age by updated_at, because a pending delivery is live retry state and a failed one an operator redelivered yesterday is not stale just because it was created last month; the delete re-applies the predicate so a redeliver that lands mid-sweep wins. usage_records is deliberately out of scope: it looks like a log but is a billing ledger whose idempotency keys are what make a replayed usage event a no-op.

With LOG_ARCHIVE_S3_* set, each batch is written to any S3-compatible store (R2 or S3) as gzipped NDJSON under Hive-style date partitions before it is deleted, and a failed upload leaves the batch in place for the next sweep. The settings are all or nothing and a partial set refuses to boot, because a bucket configured without keys must not quietly mean pruning without archiving. Object keys are a digest of the batch's ids, so a retried upload overwrites its own object, and uploads carry Content-MD5 so they work against Object Lock buckets. Signing uses aws4fetch rather than the AWS SDK, since one PUT is the whole surface. docs/data-erasure.md now records that the audit trail is retained but bounded, and that erasure does not reach an archive copy.

Panel freshness and speed

Mutations landed and the page did not change. Server actions end in redirect('/...?done=1'), and the Router Cache is keyed by segment path rather than search params, so the redirect resolved to the entry the operator already had: the flash rendered, the data did not move. Five of 45 action files called revalidatePath; the end-user surface called it nowhere. api() now invalidates the tree after every non-GET, which covers every mutation including ones not written yet.

Getting the cache settings right took two wrong turns, which the panel README now records so nobody repeats them. staleTimes.dynamic: 0, which is also Next's default, does not mean fresh. The router still issues every viewport and hover prefetch and discards the result, so a client navigation is slower than opening the same URL in a new tab; one tab click measured three to four full server renders about a second apart. static: 0 additionally re-fetched the shared layout on every click. The settings are now { dynamic: 30, static: 180 }; neither window can show an operator a stale write, because the write invalidates.

Smaller fixes

The self-host compose file was missing the four token-lifetime settings from its environment allowlist, so setting them in a hosting dashboard did nothing and the compose-env CI check was failing on main. .env.bak* is now ignored.

Testing

The full API suite ran on the tip of this branch: 1907 of 1908 cases passed across 182 files. The one failure was a setup step in end-user-destructive-role-floors.test.ts, where a workspace sign-up returned 500 after 7.7 seconds late in a 32-minute run. The same file passes 7 of 7 on its own against the same tree, so it looks load-related rather than caused by these changes, but the server-side error was not captured.

Coverage from the earlier revision includes route classification completeness, cross-tenant isolation probes for every new route group, the scope gate over REST and MCP, the email token-withholding rule, and the import decision table. This revision adds log retention and archive (10 cases), the subject filter (6), and a subject-access export test that now asserts operator actions on the person are included and the operator's id is not. The two new migrations were generated from the schema diff and apply cleanly on a migrated database.

[Evy04]

Thank you for this, it was a large and careful piece of work. This repository is generated from our private monorepo on each release, so pull requests here can't be merged directly; instead the whole change was ported there as one commit authored to you. Everything landed: devices and fingerprints, password-hash import (argon2id and bcrypt, rehashed on first sign-in), the external billing provider, the operator console, and operator permissions. A few things changed on the way in: imported and external trials now go through the one-trial-per-buyer ledger, log retention defaults to unset instead of 30 and 90 days so upgrades never prune history, and erasure no longer releases another user's activation on a shared fingerprint. It shipped in 2.2.0-rc.1. Closing this now that it is in the release.