From d425549a63747046a055a684fdc70471936cea00 Mon Sep 17 00:00:00 2001 From: nitanshukintsugi Date: Tue, 22 Sep 2026 13:38:22 +0530 Subject: [PATCH 1/2] update readme to with auto hmac generation --- README.md | 62 +++++++++++++++++++++++++++++++--------- docker/README.md | 11 +++---- docs/killbill-docs-pr.md | 2 +- 3 files changed, 55 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 4117c7e..9c9f1d0 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,14 @@ Authentication on every call: | `X-Killbill-ApiKey` | Kill Bill tenant API key (must match your Kintsugi Kill Bill connection) | | `X-Killbill-Kintsugi-Signature` | HMAC-SHA256 hex digest of the **raw JSON body** | -The HMAC secret must match on both the Kill Bill plugin config and your Kintsugi Kill Bill connection. +The HMAC secret is stored on both the Kill Bill plugin config (`hmacSecret`) and the Kintsugi connection. In the product flow Kintsugi generates it and uploads plugin config when you **Enable Tax Collection** — you do not paste a secret by hand. ## Prerequisites - JDK 11+ - Maven 3.9+ (build from source) or a release JAR - Kill Bill **0.24.x** with invoice plugin support -- A Kintsugi account with Kill Bill connected and the tax engine enabled +- A Kintsugi account with Kill Bill connected and tax collection enabled ### Kill Bill compatibility @@ -65,7 +65,26 @@ See [Kill Bill plugin installation](https://docs.killbill.io/latest/plugin_insta ## Tenant configuration -### 1. Enable the invoice plugin +### Recommended: provision from Kintsugi + +After the plugin JAR is installed and running on Kill Bill: + +1. In Kintsugi, **Connect Kill Bill** (base URL, tenant API key/secret, admin username/password). +2. Click **Enable Tax Collection** on the connection. + +Kintsugi then: + +- Generates an HMAC secret for the connection (if one is not already set) +- Uploads `kintsugiUrl` + `hmacSecret` via `uploadPluginConfig/killbill-kintsugi` +- Enables `killbill-kintsugi` as the tenant invoice plugin (`uploadPerTenantConfig`) + +You do not need to create or paste an HMAC secret manually. + +### Manual / local fallback + +Use these curls only for local docker tooling, debugging, or environments where Kintsugi cannot reach Kill Bill to provision. + +#### 1. Enable the invoice plugin Kill Bill 0.24+ expects JSON for per-tenant config: @@ -79,7 +98,7 @@ curl -u ':' \ 'https:///1.0/kb/tenants/uploadPerTenantConfig' ``` -### 2. Upload plugin config +#### 2. Upload plugin config ```bash curl -u ':' \ @@ -92,24 +111,32 @@ hmacSecret: ' \ 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' ``` + YAML POJO form is also supported — see `KintsugiConfigurationHandler` in this repo. | Config key | Required | Description | |------------|----------|-------------| | `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` | -| `hmacSecret` | Yes | Shared secret; must match the HMAC secret on your Kintsugi Kill Bill connection | +| `hmacSecret` | Yes | Shared secret for request signatures; provisioned by Kintsugi on enable-tax (manual upload only for local/fallback) | | `killbillUrl` | No | Kill Bill base URL for optional Aviate billing-account lookup (default `http://127.0.0.1:8080`) | | `aviateIdToken` | No | Aviate JWT ([Aviate auth](https://docs.killbill.io/latest/aviate-authentication)). When set, the plugin reads [billing accounts](https://docs.killbill.io/latest/aviate-billing-account) before falling back to custom fields. Omit for non-Aviate deployments. | `kintsugiUrl` must be reachable from the Kill Bill JVM (network/firewall/DNS). -## Kintsugi setup +To **inspect** the stored tenant plugin config (not the healthcheck): -In your Kintsugi account: +```bash +curl -u ':' \ + -H 'X-Killbill-ApiKey: ' \ + -H 'X-Killbill-ApiSecret: ' \ + 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' +``` -1. Connect Kill Bill (base URL, tenant API key/secret, admin credentials). -2. Set the connection HMAC secret to the same value as plugin `hmacSecret`. -3. Enable the tax engine on the connection. +## Kintsugi setup + +1. Install this plugin on Kill Bill (see above). +2. In Kintsugi: **Connect Kill Bill** with base URL, tenant API key/secret, and admin credentials. +3. **Enable Tax Collection** on the connection — Kintsugi provisions HMAC + plugin config. See [Kintsugi documentation](https://trykintsugi.com/docs) for the full setup guide. @@ -128,7 +155,13 @@ curl -u ':' \ 'https:///plugins/killbill-kintsugi/healthcheck' ``` -Returns healthy when the plugin is loaded and tenant config is present. +Healthy response (plugin loaded and tenant config present): + +```json +{"message":"Kintsugi plugin configured"} +``` + +The healthcheck does **not** return `kintsugiUrl` or `hmacSecret`. To read those values, use `GET .../uploadPluginConfig/killbill-kintsugi` (see above). ## Local development @@ -145,11 +178,12 @@ See [docker/README.md](docker/README.md) for step-by-step scripts, configuration | Symptom | Likely cause | |---------|----------------| -| No `TAX` lines on invoice | Tax engine not enabled in Kintsugi, or ship-to address has no tax obligation | -| `401` / `403` from Kintsugi | HMAC mismatch — verify the same secret on plugin config and Kintsugi connection | -| `Kintsugi plugin not configured` in logs | Missing `uploadPluginConfig/killbill-kintsugi` for the tenant | +| No `TAX` lines on invoice | Tax collection not enabled in Kintsugi, or ship-to address has no tax obligation | +| `401` / `403` from Kintsugi | HMAC mismatch — re-run **Enable Tax Collection** (re-uploads matching secret), or align manual `hmacSecret` with the connection | +| `Kintsugi plugin not configured` in logs | Missing `uploadPluginConfig/killbill-kintsugi` for the tenant (enable tax from Kintsugi, or upload manually) | | Connection timeout | Kill Bill cannot reach `kintsugiUrl` (DNS, firewall, or Docker networking) | | Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant | +| Expected config keys in healthcheck body | Wrong endpoint — healthcheck only returns `{"message":"..."}`; use `GET .../uploadPluginConfig/killbill-kintsugi` | ## Behavior notes diff --git a/docker/README.md b/docker/README.md index c0b5bbc..5338eb9 100644 --- a/docker/README.md +++ b/docker/README.md @@ -14,7 +14,9 @@ against a local Kill Bill stack. No dependency on the Kintsugi platform repo. ```bash cp docker/.env.example docker/.env -# Edit KINTSUGI_HMAC_SECRET (must match Kintsugi Kill Bill connection) +# Edit KINTSUGI_HMAC_SECRET for this local stack (setup-tenant.sh uploads it) +# For a real Kintsugi connection, Enable Tax Collection provisions HMAC instead — +# only set this env when using the manual docker scripts below. # Edit KILLBILL_API_KEY / KILLBILL_API_SECRET for your tenant docker compose -f docker/docker-compose.yml up -d @@ -58,14 +60,13 @@ Kintsugi provisions a **test org** for Kill Bill maintainers. You do not put `or |----------|-------------| | `KILLBILL_API_KEY` / `KILLBILL_API_SECRET` | Kill Bill tenant credentials (create in Kaui). **Must equal** the Kintsugi Kill Bill connection `external_id`. | | `KINTSUGI_URL` | Kintsugi API base URL reachable **from the Kill Bill container** | -| `KINTSUGI_HMAC_SECRET` | HMAC secret from the Kintsugi Kill Bill connection (not an API key) | +| `KINTSUGI_HMAC_SECRET` | Secret uploaded by `setup-tenant.sh` as plugin `hmacSecret`. Product path: Kintsugi **Enable Tax Collection** generates this; for docker smoke, put the same value on the test connection (or let enable-tax overwrite Kill Bill and skip re-running setup with a different secret). | | `SMOKE_TAX_STATE` | US state for smoke ship-to (default `TX`; needs tax registration in the test org) | **Test org checklist (Kintsugi side):** -1. Kill Bill connection created with tax engine enabled -2. Connection HMAC secret → `KINTSUGI_HMAC_SECRET` -3. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui) +1. Kill Bill connection created with tax collection enabled (provisions HMAC + plugin config), **or** connection + matching `KINTSUGI_HMAC_SECRET` for manual docker setup +2. Connection tenant API key → `KILLBILL_API_KEY` (and matching Kill Bill tenant in Kaui) For a Kintsugi API running on the host machine: diff --git a/docs/killbill-docs-pr.md b/docs/killbill-docs-pr.md index 068b6e3..23e00cc 100644 --- a/docs/killbill-docs-pr.md +++ b/docs/killbill-docs-pr.md @@ -18,6 +18,6 @@ Per-tenant configuration: org.killbill.invoice.plugin=killbill-kintsugi ``` -Upload plugin config via `uploadPluginConfig/killbill-kintsugi` with `kintsugiUrl` and `hmacSecret`. See the plugin README for setup and verification steps. +Upload plugin config via `uploadPluginConfig/killbill-kintsugi` with `kintsugiUrl` and `hmacSecret`. Prefer provisioning from Kintsugi (**Enable Tax Collection**), which generates the HMAC and uploads config; manual curl is for local/fallback. See the plugin README for setup and verification steps. Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` From a1f6a4fc7ac8dbd17833b499b6e3ee718eff2d19 Mon Sep 17 00:00:00 2001 From: nitanshukintsugi Date: Thu, 24 Sep 2026 11:21:29 +0530 Subject: [PATCH 2/2] docs: drop manual uploadPluginConfig setup steps Address review: tenant config is provisioned only via Enable Tax Collection; keep GET inspect and docker toolkit for maintainers. Co-authored-by: Cursor --- README.md | 64 ++++++---------------------------------- docs/killbill-docs-pr.md | 10 ++----- 2 files changed, 11 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 9c9f1d0..1399232 100644 --- a/README.md +++ b/README.md @@ -65,59 +65,19 @@ See [Kill Bill plugin installation](https://docs.killbill.io/latest/plugin_insta ## Tenant configuration -### Recommended: provision from Kintsugi - -After the plugin JAR is installed and running on Kill Bill: +After the plugin JAR is installed and running on Kill Bill, configure the tenant from Kintsugi (no manual `uploadPluginConfig` / `uploadPerTenantConfig` curls): 1. In Kintsugi, **Connect Kill Bill** (base URL, tenant API key/secret, admin username/password). 2. Click **Enable Tax Collection** on the connection. -Kintsugi then: - -- Generates an HMAC secret for the connection (if one is not already set) -- Uploads `kintsugiUrl` + `hmacSecret` via `uploadPluginConfig/killbill-kintsugi` -- Enables `killbill-kintsugi` as the tenant invoice plugin (`uploadPerTenantConfig`) - -You do not need to create or paste an HMAC secret manually. - -### Manual / local fallback - -Use these curls only for local docker tooling, debugging, or environments where Kintsugi cannot reach Kill Bill to provision. - -#### 1. Enable the invoice plugin - -Kill Bill 0.24+ expects JSON for per-tenant config: - -```bash -curl -u ':' \ - -H 'X-Killbill-ApiKey: ' \ - -H 'X-Killbill-ApiSecret: ' \ - -H 'Content-Type: text/plain' \ - -H 'X-Killbill-CreatedBy: setup' \ - -d '{"org.killbill.invoice.plugin":"killbill-kintsugi"}' \ - 'https:///1.0/kb/tenants/uploadPerTenantConfig' -``` - -#### 2. Upload plugin config - -```bash -curl -u ':' \ - -H 'X-Killbill-ApiKey: ' \ - -H 'X-Killbill-ApiSecret: ' \ - -H 'Content-Type: text/plain' \ - -H 'X-Killbill-CreatedBy: setup' \ - -d 'kintsugiUrl: https://api.trykintsugi.com -hmacSecret: ' \ - 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' -``` - +Kintsugi then generates an HMAC secret (if needed), uploads plugin config (`kintsugiUrl` + `hmacSecret`), and enables `killbill-kintsugi` as the tenant invoice plugin. You do not paste secrets by hand. -YAML POJO form is also supported — see `KintsugiConfigurationHandler` in this repo. +For local docker / maintainer smoke tests that talk to Kill Bill without the product UI, see [docker/README.md](docker/README.md). | Config key | Required | Description | |------------|----------|-------------| -| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` | -| `hmacSecret` | Yes | Shared secret for request signatures; provisioned by Kintsugi on enable-tax (manual upload only for local/fallback) | +| `kintsugiUrl` | Yes | Kintsugi API base URL (no trailing slash), e.g. `https://api.trykintsugi.com` — set by Enable Tax | +| `hmacSecret` | Yes | Shared secret for request signatures — generated and uploaded by Enable Tax | | `killbillUrl` | No | Kill Bill base URL for optional Aviate billing-account lookup (default `http://127.0.0.1:8080`) | | `aviateIdToken` | No | Aviate JWT ([Aviate auth](https://docs.killbill.io/latest/aviate-authentication)). When set, the plugin reads [billing accounts](https://docs.killbill.io/latest/aviate-billing-account) before falling back to custom fields. Omit for non-Aviate deployments. | @@ -132,12 +92,6 @@ curl -u ':' \ 'https:///1.0/kb/tenants/uploadPluginConfig/killbill-kintsugi' ``` -## Kintsugi setup - -1. Install this plugin on Kill Bill (see above). -2. In Kintsugi: **Connect Kill Bill** with base URL, tenant API key/secret, and admin credentials. -3. **Enable Tax Collection** on the connection — Kintsugi provisions HMAC + plugin config. - See [Kintsugi documentation](https://trykintsugi.com/docs) for the full setup guide. ## Verify @@ -179,11 +133,11 @@ See [docker/README.md](docker/README.md) for step-by-step scripts, configuration | Symptom | Likely cause | |---------|----------------| | No `TAX` lines on invoice | Tax collection not enabled in Kintsugi, or ship-to address has no tax obligation | -| `401` / `403` from Kintsugi | HMAC mismatch — re-run **Enable Tax Collection** (re-uploads matching secret), or align manual `hmacSecret` with the connection | -| `Kintsugi plugin not configured` in logs | Missing `uploadPluginConfig/killbill-kintsugi` for the tenant (enable tax from Kintsugi, or upload manually) | +| `401` / `403` from Kintsugi | HMAC mismatch — re-run **Enable Tax Collection** (re-uploads matching secret) | +| `Kintsugi plugin not configured` in logs | Tenant plugin config missing — re-run **Enable Tax Collection** | | Connection timeout | Kill Bill cannot reach `kintsugiUrl` (DNS, firewall, or Docker networking) | -| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant | -| Expected config keys in healthcheck body | Wrong endpoint — healthcheck only returns `{"message":"..."}`; use `GET .../uploadPluginConfig/killbill-kintsugi` | +| Healthcheck unhealthy | Plugin config missing `kintsugiUrl` or `hmacSecret` for the tenant — re-run **Enable Tax Collection** | +| Expected config keys in healthcheck body | Wrong endpoint — healthcheck only returns `{"message":"..."}`; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect | ## Behavior notes diff --git a/docs/killbill-docs-pr.md b/docs/killbill-docs-pr.md index 23e00cc..2f0d677 100644 --- a/docs/killbill-docs-pr.md +++ b/docs/killbill-docs-pr.md @@ -12,12 +12,6 @@ Install: kpm install_java_plugin kintsugi --from-source-file=target/kintsugi-plugin-0.1.0.jar ``` -Per-tenant configuration: +Per-tenant configuration is provisioned from Kintsugi: connect Kill Bill, then **Enable Tax Collection** (sets the invoice plugin and uploads `kintsugiUrl` / `hmacSecret`). See the plugin README for setup and verification steps. -```properties -org.killbill.invoice.plugin=killbill-kintsugi -``` - -Upload plugin config via `uploadPluginConfig/killbill-kintsugi` with `kintsugiUrl` and `hmacSecret`. Prefer provisioning from Kintsugi (**Enable Tax Collection**), which generates the HMAC and uploads config; manual curl is for local/fallback. See the plugin README for setup and verification steps. - -Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` +Healthcheck: `GET /plugins/killbill-kintsugi/healthcheck` → `{"message":"Kintsugi plugin configured"}` (does not return config keys; use `GET .../uploadPluginConfig/killbill-kintsugi` to inspect).