From 9c3ddc01e7345b35552663bf308d5939efb79729 Mon Sep 17 00:00:00 2001 From: Keysat Date: Sat, 13 Jun 2026 06:40:06 -0500 Subject: [PATCH] Fix doc drift; document no-enforce-mode and universal publish Corrections surfaced by doc-auditor + start9-spec-checker: - testing.md: api suite 47 -> 54 - payments.md: FK enforcement confirmed at db/mod.rs:29 - startos-packaging.md: publish.sh now ships a universal s9pk - licensing-tiers.md: record enforce-mode retirement and Creator caps Refresh Current state for the StartOS submission-blocker work. --- AGENTS.md | 45 ++++++++++++++++++++++++-------- docs/guides/licensing-tiers.md | 11 ++++++++ docs/guides/payments.md | 8 +++--- docs/guides/startos-packaging.md | 13 +++++---- docs/guides/testing.md | 4 ++- 5 files changed, 61 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c93f44c..8ef420c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,8 +90,10 @@ Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-licensi ## Open TODOs -- Extend `publish.sh` to build + upload aarch64 (arm builds fine; only x86 ships - today), or narrow the manifest's arch claim. `riscv` target unverified. +- Verify the universal multi-arch publish end-to-end: `publish.sh` now runs + `make universal` (one `keysat.s9pk`, both arches) instead of x86-only; the first + real publish must confirm the registry index lists both arches. `riscv` target + unverified (not in the manifest, so `make universal` excludes it). - StartOS Community Registry submission criteria — Start9 hasn't published the checklist; reach out directly when ready. - Registry icon doesn't render in the StartOS marketplace (see `guides/startos-packaging.md`). @@ -105,15 +107,34 @@ Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-licensi - **Live**: server `immense-voyage.local` runs daemon `0.2.0:54` (migrations 0020–0022). Registry `registry.keysat.xyz` publishes `:54`; four SDKs published; - `keysat.xyz` + `docs.keysat.xyz` deployed. **Prod is still `:54` — this + `keysat.xyz` + `docs.keysat.xyz` deployed. **Prod is still `:54` — the prior session's two P1 fixes are committed to source but NOT yet built/installed/ published. Next release builds `:55`.** +- **This session (UNCOMMITTED across 4 repos; docs + StartOS packaging, no daemon + logic changed)** — doc-auditor + start9-spec-checker + 2 reviewer passes, all + approved/no blockers; `tsc` + `bash -n` clean. By repo: + - *root* (Gitea): `testing.md` api 47→54; `payments.md` FK confirmed + (`db/mod.rs:29`); `startos-packaging.md` + this block updated for universal + publish; `licensing-tiers.md` gained the "no enforce mode / Creator caps" note. + - *keysat-docs* (Gitea): `integrate.html` phantom `GET /v1/licenses/{id}/status` + → real `POST /v1/validate` w/ `key`. **Needs `deploy-sites.sh docs` to go live.** + - *keysat daemon* (GitHub+gitea): new `instructions.md` (Start9-required); + manifest `packageRepo` + `docsUrls[1]` dead-link fixes; `v0.2.0.ts` stale-header + removed; `activateLicense.ts`/`showCredentials.ts` enforce-mode drift cleaned + (enforce retired — `self_license.rs:15`). + - *go SDK* (Gitea): README v0.1→v0.2. + - *operator-local* `~/.keysat/publish.sh` (gitignored, NOT committed): x86-only → + `make universal` (one `keysat.s9pk`, both arches). **Pending a verification build.** + All 4 StartOS submission blockers now addressed. Left for operator decision: + `integrate.html` BTCPay-only prereq/refund copy (no Zaprite mention). Commit = + 4 per-repo commits (root, keysat-docs, go SDK are Gitea-only; daemon is + GitHub+gitea — also `git push gitea main`). - **`:52`/`:53` = multi-provider/merchant-profile model**: data model + backend resolution shipped and audited sound; resolution/CRUD query surface has tests. Both `:54` P0s (provider-injection test seam; Zaprite webhook-forgery re-confirm) remain fixed; live purchase + settle paths sound. -- **Done this session (source only, awaiting `:55`)** — the two open P1s: +- **Unshipped source work (awaiting `:55`)** — two P1s from the prior session: 1. **Settle-amount tripwire.** `get_invoice_status` now returns `ProviderInvoiceSnapshot { status, amount }`; `audit_settle_amount` (shared by webhook + reconcile issue paths) WARNs + writes an `invoice.amount_mismatch` @@ -150,19 +171,21 @@ Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-licensi errors return plain-text not JSON (breaks SDK `JSON.parse`); product `slug` has no validation (empty/300-char/meta chars stored); `GET /v1/admin/products` returns 405 though OpenAPI documents it; dep advisories (`sqlx`→≥0.8.1 - RUSTSEC-2024-0363, `rustls-webpki`→≥0.103.12); **4 StartOS submission blockers** — - missing `instructions.md`, dead `packageRepo` (`…/keysat-startos`→`…/keysat`) + - `docsUrls` (`/docs/`→`/licensing-service/docs/`) manifest links, aarch64 - declared-but-not-shipped; no CI + fmt/clippy/prettier unenforced. + RUSTSEC-2024-0363, `rustls-webpki`→≥0.103.12); **4 StartOS submission blockers** + (spec-checker-verified) all addressed and staged, pre-build — manifest + `packageRepo` (`…/keysat-startos`→`…/keysat`) and `docsUrls[1]` + (`docs/INTEGRATION.md`→`KEYSAT_INTEGRATION.md`, the real repo-root file) fixed; + `instructions.md` written (reviewer + doc-auditor signed off); aarch64 now shipped + via `publish.sh` `make universal` (one s9pk, both arches — pending a verification + build); no CI + fmt/clippy/prettier unenforced. - **Deferred (P3+ — bulk or later decision)**: `/v1/purchase` 400 vs `/v1/btcpay/webhook` 503 for the same no-provider cause; undocumented required `kind` on discount-codes; field-naming drift (`license_id`/`id`, machines `key` vs `license_key`, `redeem`/`purchase` `product` vs `validate` `product_slug`); migration self-heal `_sqlx_migrations` allowlist foot-gun; 2 KB unauth Zaprite - payload WARN-log; outbound-webhook SSRF (operator-only); stale - `versions/v0.2.0.ts:3-4` "NOT YET WIRED" comment; re-register the master Zaprite - webhook at the path-keyed URL; registry icon non-render (known platform limit); + payload WARN-log; outbound-webhook SSRF (operator-only); re-register the master + Zaprite webhook at the path-keyed URL; registry icon non-render (known platform limit); optional fmt/prettier standalone commit. - **Tests/build**: `cargo check` clean (1 intentional deprecation warning); full diff --git a/docs/guides/licensing-tiers.md b/docs/guides/licensing-tiers.md index 99e6ad7..35ec173 100644 --- a/docs/guides/licensing-tiers.md +++ b/docs/guides/licensing-tiers.md @@ -12,6 +12,17 @@ paths: The daemon licenses **itself** via its own licensing scheme — the operator runs a master Keysat that issues the license this instance validates. +## Always boots — no enforce mode + +Enforce mode was **retired**: there is no `KEYSAT_LICENSE_ENFORCE` build flag and +`check_at_boot` (`license_self.rs`) always returns `Ok`. A missing/invalid +self-license logs a warning and the daemon runs at the free **Creator** tier +(`Tier::Unlicensed`, surfaced as "Creator" in the admin UI) with Creator caps — +**5 products, 5 policies per product, 10 active discount codes**. Activating a +license lifts those caps and unlocks `recurring_billing` + `zaprite_payments`. +Treat any "marketplace build refuses to start without a license" wording in code +comments or copy as stale. + ## Live entitlements Tier gates must read **LIVE** entitlements from `licenses.entitlements` (refreshed diff --git a/docs/guides/payments.md b/docs/guides/payments.md index 990ce4e..70b9d74 100644 --- a/docs/guides/payments.md +++ b/docs/guides/payments.md @@ -111,9 +111,11 @@ response carries no parseable positive amount. Regression tests in `tests/api.rs `get_merchant_profile_for_product` bug; prefer a subquery or qualify columns. `tests/api.rs::merchant_profile_provider_resolution_queries_round_trip` exercises the resolution surface — keep it green when touching these queries. -- FK enforcement is **not** guaranteed at runtime: `PRAGMA foreign_keys = ON` in a - migration is connection-scoped. Confirm the pool sets it per-connection before - relying on cascade/constraint behavior (e.g. deleting a profile with products). +- FK enforcement is **ON**: the sqlx pool sets `.foreign_keys(true)` per + connection (`db/mod.rs:29`), so cascade/constraint behavior is safe to rely on + (e.g. deleting a profile with products). A bare `PRAGMA foreign_keys = ON` in a + migration would be connection-scoped and is not what guarantees this — the pool + option is. - Known: after a `:52`+ install the master Zaprite webhook still points at the legacy URL — works via back-compat, needs re-register for per-provider isolation. - `unlimited_merchant_profiles` entitlement gates profile count (Creator = 1, diff --git a/docs/guides/startos-packaging.md b/docs/guides/startos-packaging.md index fb29868..86dab66 100644 --- a/docs/guides/startos-packaging.md +++ b/docs/guides/startos-packaging.md @@ -38,7 +38,7 @@ silently no-ops an install whose version equals what's already installed. Run ## Release (operator-local scripts, in `~/.keysat/`, gitignored) ``` -~/.keysat/publish.sh # version-gate → make x86 → FileBrowser upload → registry register → GitHub mirror +~/.keysat/publish.sh # version-gate → make universal → FileBrowser upload → registry register → GitHub mirror ~/.keysat/deploy-sites.sh landing docs # push static sites; accepts: landing | docs | registry-landing ``` @@ -49,10 +49,13 @@ Credentials: `~/.keysat/filebrowser.env` (`chmod 600`); env `KEYSAT_FB_USER`, ## Arch & manifest -- Both `x86_64` and `aarch64` build cleanly (arm verified 2026-06-12). The - manifest declares `['x86_64', 'aarch64']` but `publish.sh` only uploads x86_64 — - **don't claim multi-arch as shipped** until publish handles both. (`riscv` target - exists, unverified.) +- Both `x86_64` and `aarch64` build cleanly (arm verified 2026-06-12). `publish.sh` + now builds a single universal `keysat.s9pk` via `make universal` (both arches in + one package — the registry holds one s9pk per version, so a per-arch split won't + work), matching the manifest's `['x86_64', 'aarch64']` claim. **Pending a + verification build**: the combined universal pack hasn't been run end-to-end yet; + confirm the registry index lists both arches on the first publish. (`riscv` target + exists, unverified; not in the manifest, so `make universal` excludes it.) - Manifest `license` is `LicenseRef-Keysat-1.0`, matching the package-root `LICENSE` SPDX id. diff --git a/docs/guides/testing.md b/docs/guides/testing.md index 7d0bfa4..70581a3 100644 --- a/docs/guides/testing.md +++ b/docs/guides/testing.md @@ -54,7 +54,9 @@ webhook settle-confirmation guard (see [payments](payments.md)). The 3 `:52`-era known-failing tests are **resolved**: the two `paid_purchase_*` greened via the seam, the dead `payment_provider_preference_round_trip` deleted. -api suite is now **47 pass / 0 fail**; all other suites green. +api suite is now **54 pass / 0 fail** (47 after the `:52` fixes, plus the +post-`:54` scoped-key role-boundary and settle-tripwire tests); all other +suites green. ## Cross-language wire-format tests