Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ Instructions for AI coding agents working in this repository.
- `src/platform-store.ts`: scoped records, serialized writes and encryption
- `src/backups.ts`: encrypted jobs, schedules, downloads and verification
- `src/postgres-archive.ts`: bounded portable application-data archives for serverless hosts
- `src/token-contract.ts`: license v4 and trial v2 schemas
- `src/token-contract.ts`: legacy v4/v2, opt-in import-license v5/trial v3, and separate recovery v1 schemas
- `src/import-licensing.ts`: opt-in cumulative allocations, atomic renewal sales, account ownership and approved recovery
- `src/db.ts`: dual-engine historical ledger repository and migrations
- `src/sign.ts`: Ed25519 signing and token helpers
- `src/auth.ts`: Better Auth setup for the console (admin plugin, role backfill)
Expand Down Expand Up @@ -72,6 +73,7 @@ Instructions for AI coding agents working in this repository.
- Do not change token signing format without coordinating client verification changes.
- Preserve fail-closed behavior when signing key is missing.
- Token payload changes require a version bump (`v`) and a compat story.
- Import licensing is explicit per-product opt-in. Never silently adopt a legacy license, infer zero from missing local usage, refill on payment/refresh, or accept a recovery artifact as a license. Server mutations and licensing events share the existing transaction; SDK import mutations require host-supplied atomic CAS and a shared media transaction. Preserve unknown lifetime history as unknown after recovery.
- Run `vp run typecheck` and `vp run test` after code changes before proposing completion.
- Config schema changes must keep `packages/create-keyforge` generating valid
output; `test/create-keyforge.test.ts` is what catches it.
Expand Down
24 changes: 24 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ The table is generated from an isolated server's route registration. Product-sco
| GET | `/admin/products/:productId/finance/report` |
| POST | `/admin/products/:productId/finance/sales` |
| POST | `/admin/products/:productId/finance/sales/:saleId/entries` |
| PUT | `/admin/products/:productId/import-policy` |
| GET | `/admin/products/:productId/installations` |
| POST | `/admin/products/:productId/keys/:kid/activate` |
| POST | `/admin/products/:productId/keys/stage` |
Expand All @@ -86,7 +87,11 @@ The table is generated from an isolated server's route registration. Product-sco
| GET | `/admin/products/:productId/licenses/:id/activations` |
| POST | `/admin/products/:productId/licenses/:id/deactivate` |
| GET | `/admin/products/:productId/licenses/:id/delivery` |
| GET | `/admin/products/:productId/licenses/:id/import-account` |
| POST | `/admin/products/:productId/licenses/:id/import-account` |
| POST | `/admin/products/:productId/licenses/:id/key` |
| POST | `/admin/products/:productId/licenses/:id/renew` |
| POST | `/admin/products/:productId/licenses/:id/replace-key` |
| POST | `/admin/products/:productId/licenses/:id/revoke` |
| GET | `/admin/products/:productId/machines` |
| POST | `/admin/products/:productId/machines/:id/clear` |
Expand All @@ -97,6 +102,9 @@ The table is generated from an isolated server's route registration. Product-sco
| PUT | `/admin/products/:productId/notifications/preferences` |
| POST | `/admin/products/:productId/notifications/read` |
| PUT | `/admin/products/:productId/plans/:id` |
| GET | `/admin/products/:productId/recovery-requests` |
| POST | `/admin/products/:productId/recovery-requests/:id/approve` |
| POST | `/admin/products/:productId/recovery-requests/:id/reject` |
| GET | `/admin/products/:productId/reports` |
| GET | `/admin/products/:productId/support` |
| GET | `/admin/products/:productId/support/:id` |
Expand All @@ -122,6 +130,8 @@ The table is generated from an isolated server's route registration. Product-sco
| GET | `/v1/products/:productId/installations/:installationId/notifications` |
| PUT | `/v1/products/:productId/installations/:installationId/notifications/preferences` |
| POST | `/v1/products/:productId/installations/:installationId/notifications/read` |
| POST | `/v1/products/:productId/installations/:installationId/recovery-requests` |
| POST | `/v1/products/:productId/installations/:installationId/recovery-requests/:id/claim` |
| GET | `/v1/products/:productId/installations/:installationId/support` |
| POST | `/v1/products/:productId/installations/:installationId/support` |
| GET | `/v1/products/:productId/installations/:installationId/support/:id` |
Expand All @@ -139,6 +149,7 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include

| Code |
| --- |
| `account_mismatch` |
| `activation_limit_reached` |
| `admin_disabled` |
| `admin_unauthorized` |
Expand Down Expand Up @@ -183,12 +194,16 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include
| `future_date` |
| `historical_overpayment` |
| `idempotency_conflict` |
| `import_account_missing` |
| `import_account_required` |
| `import_migration_required` |
| `initial_sale_exists` |
| `installation_unauthorized` |
| `insufficient_role` |
| `internal_error` |
| `invalid_assignee` |
| `invalid_date` |
| `invalid_import_allowance` |
| `invalid_license_request` |
| `invalid_message` |
| `invalid_origin` |
Expand All @@ -213,14 +228,20 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include
| `original_key_unavailable` |
| `overpayment` |
| `paid_license_required` |
| `policy_locked` |
| `price_required` |
| `product_archived` |
| `product_exists` |
| `quota_exhausted` |
| `rate_limited` |
| `reason_required` |
| `reauthentication_required` |
| `recovery_rate_limited` |
| `recovery_required` |
| `recovery_stale` |
| `recovery_unavailable` |
| `registry_disabled` |
| `renewal_unavailable` |
| `request_closed` |
| `request_not_found` |
| `request_pending` |
Expand All @@ -232,6 +253,7 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include
| `revision_required` |
| `service_unauthorized` |
| `signing_unavailable` |
| `single_installation_required` |
| `storage_credentials_required` |
| `storage_not_saved` |
| `support_rate_limited` |
Expand All @@ -244,10 +266,12 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include
| `unknown_meter_or_license` |
| `unknown_plan` |
| `unknown_product` |
| `unknown_recovery` |
| `unknown_sale` |
| `unknown_staged_key` |
| `unknown_support_request` |
| `usage_unauthorized` |
| `use_license_renewal` |
| `verification_unconfigured` |

## Console reports
Expand Down
15 changes: 15 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,18 @@ Restore current archives using `vp run backup:restore --file <archive> --job <UU
## Plan-based issuance

`vp run license issue --plan standard --to "Customer" --request-id UUID` copies saved plan terms and creates an unpaid ETB sale atomically. Configure the plan price first. Reuse the UUID when retrying. Overrides such as `--expires`, `--activations`, `--entitlements` and `--allowance` are rejected; edit the plan instead. Add `--installation ID` for authenticated dependent-app delivery, or share the returned key manually. Add `--paid --method "Bank transfer" --reference BANK_ID` to record full payment on today's UTC date. Existing records and signing/validation are unchanged. See [License requests and sales](license-sales.md).

## Import-account operators

See [import licensing and recovery](import-licensing.md) before opting a product in. These are explicit admin operations on the selected server; use `--product` and `--env-file` deliberately. No live product is changed by updating this source checkout.

- `vp run license imports-enable --entitlement imports --revision N`: enable future v5 issuance/v3 trials after updated clients are deployed.
- `vp run license imports-account LICENSE_ID`: inspect cumulative granted units and transactional licensing events; no customer usage is uploaded.
- `vp run license imports-adopt LICENSE_ID --granted N --revision N --reason TEXT --request-id UUID`: explicitly migrate a single-installation historical license without a new financial record. Client history must migrate separately.
- `vp run license renew LICENSE_ID --plan PLAN --mode renewal --request-id UUID`: add the selected plan allowance once and extend time. `--mode top_up` adds units only; `--mode extension` extends time only. Optional `--paid --method TEXT --reference TEXT` records today's full ETB receipt. Retrying the exact UUID/body never creates another sale or allocation.
- `vp run license replace-key LICENSE_ID --reason TEXT --request-id UUID`: replace the key on the same account/license without refilling allowance or creating a sale.
- `vp run license recovery-list`: list recovery requests for independent customer verification.
- `vp run license recovery-approve REQUEST_ID --revision N --mode restore --reason TEXT --request-id UUID`: approve a committed verified-backup restoration for 24 hours. `--mode lost_history` conservatively consumes previously granted allowance and keeps lifetime history unknown. Customer must claim from the authenticated target installation. It does not automatically grant new units.
- `vp run license recovery-reject REQUEST_ID --revision N --reason TEXT --request-id UUID`: reject a pending or approved recovery after independent review; repeated identical requests are safe.

These use the current product-scoped admin API. Existing manual sales creation is rejected for import-account licenses; purchases must use the atomic renewal endpoint. Marking an existing transaction paid remains a financial-only action. Deployed v4 products and existing sessions/records remain unchanged until explicit opt-in/migration.
Loading
Loading