Available from seven days before expiry and, deliberately, at any point
after it up to deletion, so the same button rescues a lapsed instance.
Renewal is manual because it is the entire reclaim signal: an instance
nobody renews is one nobody is using, which is what makes reaping safe.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Provisions the control-plane instance and its owner, records the
admin_instances row, issues and injects a Free licence, and emails the
customer where it is and when it expires.
Licence issuance and email cannot fail the request. The instance exists
and the customer can sign in; rolling back something they can already see
would be worse than shipping it unlicensed for staff to fix.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Admin's second and final write path into the control plane. It creates
instances and users and nothing else; inject still owns exactly three
licence fields and is untouched.
The owner's password hash is copied from the HQ account, not shared. The
two diverge on the next password change, which is accepted: propagating a
hash across two databases is worse than two passwords that started equal.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ten tasks: cloudprov, instance creation, renewal, the notice sweep, the
reaper, the reconciler tie-in, the HQ and marketing UI, the sitesvc
cutover, and an end-to-end verification.
The reaper sweeps once at boot as inject's reconciler does, which is what
makes it observable at all — the ticker is hourly and deletion is
measured in days.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The old index was load-bearing because two lookups were unscoped. Both
are scoped now and the unscoped helper is gone, so the property that
matters is the absence of any unscoped lookup by email. Says so, and
documents auth_source hq.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
HQ sign-in names no instance, so a lookup of control-plane users by email
alone cannot be scoped — and users.email is no longer globally unique, so
it would return an arbitrary match. Every customer authenticates against
customer_users instead.
Legacy cloud customers get an HQ login from staff via the new
POST /api/staff/accounts/:id/users, alongside the manual instance attach
the spec README already describes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
users is unique on (instance_id, email) now, so an unscoped FindOne could
return an arbitrary one of several matching users. On the login path that
means signing someone into a tenant that is not theirs.
GetUserByEmail is deleted rather than left unused. Local sign-in resolves
its instance from the host, falling back to the single instance a
self-hosted deployment has, and refuses to guess otherwise. The OIDC
cross-instance guard goes: a scoped lookup cannot return another
instance's user, which is a stronger guarantee than the check it replaces.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nothing writes them yet. They land now so phases 2 and 3 do not require a
second rebuild of every service that consumes the shared module.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One address is one user within an instance, not globally, so an account's
people can be projected into every instance they are granted.
The replacement index is created before email_1 is dropped, so a failure
at any point leaves a working constraint. The drop is idempotent and
tolerates two services racing it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seven tasks: the index swap, the hq fields, the three scoped lookups,
removing admin's unscoped control-plane login, and an end-to-end
verification that two users sharing one address sign in to different
instances.
Also corrects the spec's phase list, which claimed phase 1 projects the
creator as owner. Projection needs instance creation, which is phase 2.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An account has people, and those people belong to several cloud
instances. That requires dropping the global unique index on users.email
for a compound (instance_id, email), scoping the two unscoped lookups
that made the global index load-bearing, and projecting HQ users into
instances as real control-plane users.
Self-hosted instances are never projected into; their users stay local.
Restructured into three phases: identity, creation and lifecycle,
membership.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Separates having an account from having an instance. Signup creates only
the HQ account; the customer then creates a Free cloud instance from the
portal, which provisions the control-plane instance, the admin_instances
row and a Free licence in one path.
Supersedes spec 5's signup-migration section.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Everything checkable without a browser, against scratch databases:
- All five Go modules and the adminsite production build compile clean.
- Scoping holds: own instance 200, another account's 404, nonexistent 404 --
indistinguishable, so no existence oracle -- and a customer session on the
staff API gets 401 where staff gets 200.
- max_relinks comes from the API (3), not a constant mirrored in TypeScript.
- The inline blob and the download endpoint return byte-identical content, so
the fallback is faithful rather than approximate.
- ADMIN_API_URL really is baked at build time: 9999 in the deliberately
broken image, 8083 in the good one.
- The served stylesheet carries site/'s tokens with matching values, plus
prefers-color-scheme and both data-theme overrides.
- With admin stopped the control plane still reports valid and mutations
still succeed -- instances never call admin.
- Admin touched only the three licence fields on instances; every other
control-plane collection is as the control plane left it.
Caught one stale-image bug doing this: the running admin predated the
customer blob change, so the licence response had no blob field at all.
Rebuilt and re-verified.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The previous commit missed this file: the repo tracks it as lowercase
claude.md, so staging CLAUDE.md matched nothing in the index.
admin/ was never documented here at all -- the backend plan's wiring task
covered compose and CI but not the file every session loads. So this adds
both services to the structure, admin's whole REST surface with its
404-never-403 rule, the three visual identities, and the coupling that
matters most: adminsite/ and site/ share one token set with nothing enforcing
the match, the same hazard shape as sitesvc's mirrored slug rules.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Publishes adminsite on 3004 -- 3000 is web, 3003 is the marketing site since
the port shuffle -- and adds the sixth CI image.
CLAUDE.md gains both new services. admin/ was never documented there at all:
the backend plan's wiring task covered compose and CI but not the file every
session actually loads. So this records admin's whole REST surface, its
404-not-403 rule, the three visual identities and, most importantly, that
adminsite/ and site/ share one token set with nothing enforcing the match --
the same hazard shape as sitesvc's mirrored slug rules.
Also notes that admin's REDIS_ADDR reaches admin only, because the base
compose hardcodes redis:6379 for server.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Licences and audit are both filterable client-side: the endpoints cap at 500
rows and staff are narrowing a list already in front of them.
Plans carry both guard rails spec 4 asks for. The confirmation names each
field that changes and states how many licences are already issued and
unaffected -- existing licences snapshotted their plan at issue time, and
saying so is what stops a well-meaning edit being followed by a panicked
reissue. Deployment is displayed and never editable, because moving a tier
between cloud and self-hosted would break the cloud-only rule spec 1 leans
on; that is a code review, not a form field.
The two edit buttons are the concrete changes staff need on day one. A
general-purpose limits editor waits until somebody asks for it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Removes vitest, React Testing Library, the config, the setup file and all
eleven test files, plus the test scripts and dev dependencies. Done at the
user's direction; it matches the rest of the repo, which has no automated
tests in any language.
All eleven were observed passing before removal, and their assertions are
kept in the plan as acceptance criteria to check by hand rather than deleted
outright -- they are the clearest statement of what each component has to do.
Consequence worth stating: Task 16's manual pass is now the only verification
that exists for spec 4. Four behaviours it must cover carefully, because each
is easy to break invisibly: 404-not-403 scoping, the expired card naming what
still works, relink disabling at zero, and the blob fallback when a download
fails.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The screen that answers "why did this stop working on the 14th". Read top to
bottom it is one instance's whole history: what was issued, why, by whom, and
what replaced it.
Superseded entries stay visible and overprinted rather than disappearing,
because licences are append-only and hiding them would destroy the only
record that answers the question. Each links to its successor.
Injection state is shown live for cloud instances and omitted for
self-hosted, where the customer holds the blob and there is nothing for us to
have written. Staff relinks carry no cap, with the reason stated inline: the
customer cap exists to put a human in the loop, and this is that human.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Search covers name, email, Paddle customer ID and instance UUID. The UUID
case is the one that matters: a support email often contains a UUID and
nothing else, and the empty state says so rather than just reporting nothing
found.
Account detail gathers everything about one customer on one screen --
instances, subscriptions, people, audit -- and says plainly when an account
has no people because it is a cloud account whose owner signs in with
control-plane credentials.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four counts, each one work somebody has to do today: failed injections,
licences expiring inside 14 days, past-due subscriptions, and purchases
unlinked for more than 48 hours. No totals and no revenue -- nothing that
cannot be acted on. Every row links straight to the thing that needs doing.
An empty queue says "nothing to do here" rather than rendering a bare zero,
so a quiet dashboard reads as quiet rather than broken.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The link screen carries the whole burden of the five-minute bar: it names
where to find the instance ID, validates the format before asking the server
so a typo is instant rather than a round trip, surfaces the backend's own
message when a UUID is already linked, and on success lands the customer
directly on the download rather than back on a list.
Billing is deliberately thin and says plainly that billing changes go
through support, rather than linking to a Paddle portal that does not exist
until spec 5.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The blob is shown inline as well as offered as a file, because a licence is
signed public data bound to one instance -- useless anywhere else -- and a
blocked download must never leave a paying customer stuck. Admin now returns
it to its owner for the same reason.
Relink shows the remaining allowance from the backend's max_relinks rather
than a hardcoded 3, and at zero it disables and says to contact support
instead of failing at the API.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
State reads three ways on every card -- a stripe, a shaped-and-labelled
pill, and the copy -- so it survives a colourblind reader and a glance at
arm's length. Colour alone would fail on the one screen where getting it
wrong costs money.
The expired card leads with what still works, because that is the first
thing a worried customer wants to know and the backend really does keep
servers, monitors and agent keys running. The awaiting-link card is
deliberately loud: a customer who has paid and not linked has paid for
nothing yet.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Route-group layouts do the guarding. A customer session on /staff/* is
redirected to its own home rather than shown a refusal -- there is nothing to
tell them about. This is UX only: admin enforces the same boundary with
RequireStaff/RequireCustomer and answers 404 rather than 403 for another
account's data, which is the layer that actually matters.
Signup carries the honeypot the backend expects and reports "check your
email" rather than claiming an account exists, matching a backend that
creates nothing until the link is opened.
Buttons match site/'s .btn--solid and .btn--line, neutral border included.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The repo's first frontend test setup: Vitest, React Testing Library, jsdom.
Scoped to the flows that lose money or leak data when broken, per spec 4.
lib/api.ts collapses every failure into three the UI can act on:
NotConnected (unreachable, or no URL baked in), ApiError 401 (redirect), and
ApiError with the backend's own message, which is customer-facing and shown
verbatim rather than replaced with something vaguer.
The not-connected panel names the variable, the value baked in, and both
reasons it fails -- unreachable from the browser, or missing from admin's
ADMIN_ORIGIN. Proven by test before it existed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A fifth Next.js app, built like web/ and site/: App Router, React 18,
Tailwind 3, TanStack Query, standalone output.
app/globals.css carries site/app/globals.css's token blocks copied verbatim
rather than retyped, so the two cannot drift by transcription. Tailwind holds
var() references only -- no component or config entry may contain a hex
value. The semantic three are aliased: site/'s --up/--pend/--down become
valid/warn/expired, so each app names the colours for what it shows.
Unlike web/, there is no rewrite proxy: the browser calls admin directly, so
NEXT_PUBLIC_ADMIN_API_URL must be browser-reachable and listed in admin's
ADMIN_ORIGIN.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Closes the rest of what spec 4's screens need. Account search now also
matches a Paddle customer ID and resolves an instance UUID to its owning
account -- a support email often contains a UUID and nothing else, and the
old search returned nothing for it.
GET /api/staff/instances/:id is the "why did this stop working" screen's
data: the instance, its account, its whole licence history newest first, and
whether the control plane currently holds the blob we think it holds.
Injection state is reported only for cloud, because for self-hosted the
customer holds the blob and there is nothing for us to have written.
Account detail gains subscriptions, customer users and its own audit trail.
No secret leaves: the password hash and both verify-token fields are json:"-".
The control-plane write surface is unchanged -- still exactly one UpdateOne
of three licence fields in inject.go, with reads everywhere else.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds GET /auth/me so the admin site's route guards can know who is signed
in, POST /auth/signup for self-hosted customers, and max_relinks on the
account payload so the UI never hardcodes a rule the backend enforces.
Signup follows sitesvc's proven shape: honeypot answered as success, a
generic 201 when the address already exists, and nothing usable until the
emailed link is opened.
Also fixes a lockout found while verifying it. When the verification email
failed, the account was rolled back but the customer_users row survived --
an orphan that can never be signed in to and that holds the unique index on
email, so every later signup with that address got a cheerful 201 and the
customer was locked out of their own address with no visible error.
CreateCustomerUser now undoes its own insert.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Replaces the petrol-and-serif direction with site/app/globals.css's token
set copied verbatim: brand navy accent, the same neutrals, the same clamp
type scale, 1200px rail, 4px radii, and site/'s heading treatment of the
sans at weight 800 rather than a serif display face.
The semantic three are aliased rather than renamed -- globals.css carries
site/'s --up/--pend/--down, and Tailwind exposes them as valid/warn/expired
so each app names them for what it actually shows. Same colours either way.
Tailwind now holds var() references only, so no component or config can
carry a hex value and drift. Buttons match site/'s .btn--solid and
.btn--line, including the neutral border on the secondary variant.
Records the caveat this creates: site/'s dark accent (#5b9be8) sits nearer
web/'s indigo than the light navy does, so the "which app am I in" cue rests
on the light ground and dark must not become the default.
Drops the guilloche ornament -- site/ carries nothing like it. The ledger
stays, because it is information design rather than decoration.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sixteen tasks: two that close gaps in admin's API, thirteen frontend, one
verification pass.
Auditing spec 4's screens against what spec 3 actually shipped turned up
eight things the UI needs and the backend does not expose -- including no
GET /auth/me at all, which no route guard can work without, and no signup
endpoint for the self-hosted flow the spec's app/signup/ implies. Those are
tasks 1 and 2 rather than frontend improvisation.
Records the approved design direction as fixed constraints: light ground
because web/ is dark-locked and telling the two apart is what stops a
Reissue landing in the wrong tab, petrol accent because green, amber and red
are spoken for by licence state and indigo belongs to web/, and the licence
ledger as the one screen that earns ornament.
Serves vantage-hq.hostxtra.co.uk on 3004 -- 3002 is the marketing site now,
and the host stays outside *.vantage.hostxtra.co.uk because that namespace
is per-tenant instance subdomains.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds REDIS_USERNAME and REDIS_PASSWORD. Both are optional, so an
unauthenticated instance still works unchanged. Redis 6+ ACL auth takes
both; a legacy requirepass instance takes the password with an empty
username, which is what go-redis needs to send single-argument AUTH.
Admin now defaults to the external Redis at 10.10.10.2:6379 rather than the
compose-local one, and no longer declares depends_on: redis -- it is not
starting that container any more. The base stack keeps its own Redis for
`server`, which still has no auth support.
Also fixes SMTP_PASSWORD in the admin block: it read `$SMTP_PASSWORD:-}`
rather than `${SMTP_PASSWORD:-}`, which appended a literal `:-}` to the
password and would have failed SMTP auth at the first verification email.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The 1.26.4 floor meant a base toolchain of 1.26.2 could not load the
workspace at all: the terminal worked only because GOTOOLCHAIN=auto
silently swapped in a downloaded 1.26.4, and gopls -- which does not get
that switch -- failed every packages.Load with
go: go.work requires go >= 1.26.4 (running go 1.26.2)
Nothing needed the patch-level floor. agent/go.mod already declared plain
go 1.26, so this makes the workspace uniform rather than introducing a new
convention, and CI is unaffected because golang:1.26 is already newer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ticks all 66 plan steps and records spec 3 as shipped.
Also corrects a stale line that still claimed existing cloud tenants are
grandfathered by migration 0005. That migration was reverted before plan 2
shipped; those instances are read-only until licensed by hand, and the same
file already said so one table above.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
StartReconciler only fired on its 15-minute ticker, so nothing reconciled
until a full interval had passed and restarting admin repaired nothing.
Injection failures are most likely around a deploy or a crash, which is
exactly when the backstop was asleep -- a paying customer could sit
read-only for 15 minutes with the repair already computable. A restart is
now also a supported way to force reconciliation.
Found by the plan's own Step 8, which assumed this behaviour: verified by
tampering with a control-plane blob, confirming the instance went invalid,
and watching the boot pass restore it (checked 1, repaired 1).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds admin to docker-compose.site.yml and a fourth Go image to the build
workflow, both following the conventions the other services already use.
LICENSE_SIGNING_KEY now appears in exactly one service in exactly one
compose file. It must never be added to server, and the self-hosted
docker-compose.yml still does not mention admin at all.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Completes the service -- this is the first commit where the whole thing
compiles and serves.
staffCreateInstance adopts a cloud instance that already exists in the
control plane, taking its name and slug from there and refusing when no
such instance exists: an admin row pointing at nothing would issue licences
nobody can use. Adopt then issue is how the existing read-only cloud
instances get licensed.
staffRelink has no attempt cap. The customer-facing limit exists to put a
human in front of the fourth attempt, and this is that human.
Editing a plan changes what a tier grants from now on only; existing
licences snapshotted theirs at issue time.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every customer handler that names an instance resolves it through
ownedInstance, which returns 404 rather than 403 for another account's
instance -- a 403 confirms the instance exists, which is an existence
oracle over customer data.
The unique index on admin_instances.instance_id, not the pre-check, is what
actually prevents two accounts owning one instance. Relink issues a
replacement covering the REMAINING term, so it cannot be used to extend a
subscription, and the old licence is not revoked because offline
verification has no revocation -- its instance binding is what stops it.
The route table lands with the staff handlers in the next commit so every
commit builds.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Mirrors the pattern sitesvc already proves: 32 random bytes, only the
SHA-256 hash stored, a 24-hour expiry, and the token cleared on use -- so a
leaked database yields no working links.
Unverified login returns a distinct "verify your email address first" rather
than the generic error. The address is already known to be theirs, so there
is nothing to disclose and that is the only useful thing to say.
Licence blobs are emailed inline. A blob is signed public data, not a
secret: it is useless on any instance other than the one it names.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Cloud customers sign in with the control-plane credentials they already
hold, so there is no second password to manage. Two accepted consequences,
documented at the handler: their control-plane password now also unlocks
billing, and only role owner may sign in -- admin and member are refused
because billing is an owner concern.
A self-hosted customer_users row wins over a control-plane user with the
same address, so the precedence is chosen rather than emergent.
Adds the reads of control users this needs; the write surface is still one
UpdateOne on instances.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One Redis session store and one cookie for all three identities. Staff
login returns the same error for every failure mode and spends a bcrypt
comparison against a dummy hash when no user exists, so neither the message
nor the timing confirms which addresses have accounts.
Staff users are created only by adminctl. There is no signup endpoint: a
licensing authority that can be joined over the internet is not one.
Pins gin and go-redis to the versions server/ already uses rather than the
latest tidy would pick.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Injection is a single UpdateOne of three licence fields, so it is
idempotent and safe to re-run. The control plane caches licence state for
60 seconds, so an injected licence takes effect within a minute with no
restart.
Deliver never fails its caller. The reconciler, not the issuance path, is
what actually guarantees a cloud instance ends up holding the licence admin
says it holds -- injection at issue time is best-effort and this is the
backstop.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Issue is the only place that signs. It records the licence, supersedes its
predecessor and updates the instance -- but deliberately does not deliver.
The ordering matters: a licence recorded but not delivered is recoverable,
because the customer can download it. A licence delivered but not recorded
is a support mystery with no paper trail.
Free stays cloud-only through one comparison of plan against instance
deployment, not a flag. Renewals reset relink_count because the cap is per
term.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds admin's own documents, its unique indexes and the plan seed from
shared/license.
Licences are append-only -- a renewal writes a new row and supersedes the
old one -- because the history is the support tool. Plans are seeded with
$setOnInsert only, so a redeploy never stamps over staff edits to limits,
features or Paddle IDs.
admin_instances.instance_id unique is a correctness property, not an
optimisation: without it two customers could both claim one self-hosted
UUID and both be issued licences for it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the admin module: env config with fail-fast validation, two MongoDB
connections (its own vantage_admin database plus a narrow path into the
control plane), the boot sequence and the image.
Config refuses to start without a signing key, and both Mongo URIs must
name their database inline -- admin talks to two databases, so a bare
MONGO_DB would be ambiguous about which.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Existing cloud instances get licensed by hand through the admin UI instead of
an automated backfill. That needs POST /api/staff/instances, which nothing else
provided — without it there is no way to attach an existing cloud instance to
an account.
mrhid6andClaude Opus 5
mrhid6