Commit 8a4bcd1
authored
(Billing for self hosts) Tie enterprise key to server (twentyhq#22464)
# Enterprise key: bind to a server, free dev instances, self-serve
transfer, shorter license
## Summary
Enterprise keys were being reused across multiple instances (e.g. one
prod + one dev, or several environments), which broke seat accounting
and made licensing ambiguous. This PR ties each enterprise key to a
**single server**, while giving customers a legitimate, self-serve way
to run a **free development instance** and to **move their key** when
they replace a server.
## Product behavior
### 1. Enterprise key is bound to one server
- The first server to validate an enterprise key **claims** it
(claim-on-first-use). From then on, that key is bound to that one server
(until unbound - see 3.).
- Any other instance that presents the **same key from a different
server is hard-rejected**: it does not receive a license, so enterprise
features stay off there.
- Each instance has a stable server identifier. If one isn't set, the
instance generates and persists one automatically on first validation
(in keyValuePair table), so existing customers generally don't need to
do anything (unless they have disabled config variables in db then they
should add it to .env).
### 2. Free development instance
- Every enterprise subscription gets **one free, non-billable
development instance** in addition to its production instance.
- An instance registers as development by declaring its instance type as
`development` (done by default when validating the enterprise key, then
can be toggled from UI or by updating value in keyValuePair table).
- The free dev slot is only granted while there is an **active
production instance** on the same subscription (so it's a perk for
paying customers, not a way to run for free).
- Only **one** dev instance can be active at a time per subscription,
and it is **not counted as a billable seat**.
### 3. Self-serve unbind / rebind (transfer)
- Admins can **release** the binding from the enterprise settings, which
frees the key so it can be **claimed by a new server**.
- This is the intended path when **sunsetting an instance and standing
up a new one** (migration, re-hosting, disaster recovery): release on
the old/dead box, then the new box claims it on its next validation.
- To prevent abuse, releases are **rate-limited (10 per rolling 30
days)**; hitting the limit shows a clear message.
### 4. Automatic release of dead servers
- If a bound server stops checking in for **14 days**, its binding is
considered stale and is **auto-released**, so a replacement can claim
the key without any manual step. This covers the case where the old
server is already gone and can't release itself.
### 5. Shorter license validity (30 → 7 days)
- The license (validity token) now expires after **7 days** instead of
30. The daily background refresh keeps healthy instances licensed
transparently.
- This limits the value of copying a license from one instance to
another, since a copied license now stops working within a week.
### 6. License issuance is rate-limited
- Issuing a new license is capped at **twice per 24h, independently for
production and for development**. This tolerates the normal daily
refresh (including small drift between runs) while blocking bursts of
license minting for cloned instances.
- Hitting this limit never revokes an existing, still-valid license —
the current one keeps working until it expires; the manual "refresh"
button just reports that the daily limit was reached.
## What changes for existing self-hosted customers
**If you run a single production instance with one enterprise key:**
nothing to do. On the next validation your instance reports its server
identifier, claims the binding, and keeps working.
**If you reuse one key across several instances (e.g. prod + dev, or
multiple environments):** only the **first** instance to validate keeps
its license. The others will **lose enterprise features**. To migrate:
- Keep your production instance as-is (it claims the binding).
- For a secondary/testing box, mark it as a **development instance**
(set the instance type to `development`) to use the free dev slot — no
extra cost.
- If you genuinely need multiple production instances, you'll need
**separate subscriptions/keys** for each.
**If you're replacing a server (decommissioning + rebuilding):**
- **Release** the binding from enterprise settings on the old instance,
then start the new one — it will claim the key automatically.
- If the old server is already gone, just wait for the **14-day
auto-release**, or contact support.
**Legacy instances that can't persist a server identifier
automatically:** set the server identifier explicitly in your
environment configuration (the instance logs a message telling you to do
so).
**Offline instances:** because licenses now last 7 days, an instance
that can't reach our licensing endpoint for more than a week will lose
enterprise features until it can check in again.
> A migration email will be sent to affected customers separately.
## Technical implementation (brief)
- Binding state lives in the **subscription's billing metadata** (bound
server id + last-seen timestamps for prod and dev, release timestamps,
and license-issuance timestamps). No new database is introduced on the
licensing side; the billing provider's subscription metadata is the
source of truth.
<img width="976" height="413" alt="metadata_3"
src="https://github.com/user-attachments/assets/ccc64822-e177-4223-a65a-4a4602aedf0e"
/>
- On each validation, a pure **binding resolver** takes the reported
server id + instance type + current metadata and returns `allowed` (with
the metadata to persist and whether the seat is billable) or `rejected`.
It handles claim-on-first-use, staleness/auto-release, the
dev-requires-active-prod rule, and the single-dev-slot rule.
- **Rate limits** (release + license issuance) use a shared
sliding-window helper stored as pruned timestamp lists in the same
metadata, so the metadata self-cleans and never grows unbounded. License
issuance uses **separate windows per instance type**.
- The self-hosted instance **generates and persists a server
identifier** if none is configured, and sends it (plus instance type) as
instance metadata on validation.
- A rejected binding returns a specific error code; the instance
**revokes its stored license** on that code. A license-issuance
rate-limit instead **throws a typed exception that surfaces to the
manual refresh** while leaving the existing license untouched; the daily
refresh job swallows it.
- License lifetime is a configurable duration (defaulted from 30 to **7
days**), clamped to the subscription's cancellation date when sooner.1 parent ed2b2f8 commit 8a4bcd1
54 files changed
Lines changed: 2028 additions & 78 deletions
File tree
- packages
- twenty-client-sdk/src/metadata/generated
- twenty-front/src
- generated-metadata
- modules
- client-config
- hooks
- states
- types
- information-banner/components
- enterprise
- settings/enterprise/graphql/mutations
- pages/settings/enterprise
- twenty-server
- src/engine/core-modules
- client-config
- services
- enterprise
- cron/jobs
- services
- types
- twenty-config
- twenty-website
- src
- app/api/enterprise
- reissue
- release
- seats
- status
- validate
- platform/enterprise
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 2 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1961 | 1961 | | |
1962 | 1962 | | |
1963 | 1963 | | |
| 1964 | + | |
1964 | 1965 | | |
1965 | 1966 | | |
1966 | 1967 | | |
| |||
3301 | 3302 | | |
3302 | 3303 | | |
3303 | 3304 | | |
| 3305 | + | |
3304 | 3306 | | |
3305 | 3307 | | |
3306 | 3308 | | |
| |||
Lines changed: 4 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1598 | 1598 | | |
1599 | 1599 | | |
1600 | 1600 | | |
| 1601 | + | |
1601 | 1602 | | |
1602 | 1603 | | |
1603 | 1604 | | |
| |||
2833 | 2834 | | |
2834 | 2835 | | |
2835 | 2836 | | |
| 2837 | + | |
2836 | 2838 | | |
2837 | 2839 | | |
2838 | 2840 | | |
| |||
4713 | 4715 | | |
4714 | 4716 | | |
4715 | 4717 | | |
| 4718 | + | |
4716 | 4719 | | |
4717 | 4720 | | |
4718 | 4721 | | |
| |||
6078 | 6081 | | |
6079 | 6082 | | |
6080 | 6083 | | |
| 6084 | + | |
6081 | 6085 | | |
6082 | 6086 | | |
6083 | 6087 | | |
| |||
Lines changed: 6 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3821 | 3821 | | |
3822 | 3822 | | |
3823 | 3823 | | |
| 3824 | + | |
| 3825 | + | |
| 3826 | + | |
3824 | 3827 | | |
3825 | 3828 | | |
3826 | 3829 | | |
| |||
7146 | 7149 | | |
7147 | 7150 | | |
7148 | 7151 | | |
| 7152 | + | |
| 7153 | + | |
| 7154 | + | |
7149 | 7155 | | |
7150 | 7156 | | |
7151 | 7157 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
924 | 924 | | |
925 | 925 | | |
926 | 926 | | |
| 927 | + | |
927 | 928 | | |
928 | 929 | | |
929 | 930 | | |
| |||
2641 | 2642 | | |
2642 | 2643 | | |
2643 | 2644 | | |
| 2645 | + | |
2644 | 2646 | | |
2645 | 2647 | | |
2646 | 2648 | | |
| |||
8080 | 8082 | | |
8081 | 8083 | | |
8082 | 8084 | | |
| 8085 | + | |
| 8086 | + | |
| 8087 | + | |
| 8088 | + | |
| 8089 | + | |
8083 | 8090 | | |
8084 | 8091 | | |
8085 | 8092 | | |
| |||
9016 | 9023 | | |
9017 | 9024 | | |
9018 | 9025 | | |
| 9026 | + | |
9019 | 9027 | | |
9020 | 9028 | | |
9021 | 9029 | | |
| |||
Lines changed: 11 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
| 17 | + | |
17 | 18 | | |
18 | 19 | | |
19 | 20 | | |
| |||
34 | 35 | | |
35 | 36 | | |
36 | 37 | | |
| 38 | + | |
37 | 39 | | |
38 | 40 | | |
39 | 41 | | |
| |||
126 | 128 | | |
127 | 129 | | |
128 | 130 | | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
129 | 135 | | |
130 | 136 | | |
131 | 137 | | |
| |||
210 | 216 | | |
211 | 217 | | |
212 | 218 | | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
213 | 223 | | |
214 | 224 | | |
215 | 225 | | |
| |||
248 | 258 | | |
249 | 259 | | |
250 | 260 | | |
| 261 | + | |
251 | 262 | | |
252 | 263 | | |
253 | 264 | | |
| |||
Lines changed: 11 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
Lines changed: 2 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
| 12 | + | |
12 | 13 | | |
13 | 14 | | |
14 | 15 | | |
| |||
45 | 46 | | |
46 | 47 | | |
47 | 48 | | |
| 49 | + | |
48 | 50 | | |
Lines changed: 2 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
| 6 | + | |
6 | 7 | | |
7 | 8 | | |
8 | 9 | | |
| |||
63 | 64 | | |
64 | 65 | | |
65 | 66 | | |
| 67 | + | |
66 | 68 | | |
67 | 69 | | |
68 | 70 | | |
| |||
Lines changed: 25 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
Lines changed: 12 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
0 commit comments