diff --git a/docs/api.md b/docs/api.md index f49e494..3cc62bc 100644 --- a/docs/api.md +++ b/docs/api.md @@ -136,6 +136,7 @@ The table is generated from an isolated server's route registration. Product-sco | GET | `/v1/products/:productId/installations/:installationId/support/:id` | | POST | `/v1/products/:productId/installations/:installationId/support/:id/messages` | | GET | `/v1/products/:productId/keys` | +| GET | `/v1/products/:productId/integration-profile` | | POST | `/v1/products/:productId/refresh` | | POST | `/v1/products/:productId/register` | | POST | `/v1/products/:productId/usage/consume` | @@ -149,6 +150,7 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include | Code | | --- | | `account_mismatch` | +| `active_key_unavailable` | | `activation_limit_reached` | | `admin_disabled` | | `admin_unauthorized` | @@ -229,6 +231,7 @@ Domain errors use error/message/retryable/serverTime; rate limiting may include | `price_required` | | `product_archived` | | `product_exists` | +| `public_origin_unavailable` | | `quota_exhausted` | | `rate_limited` | | `reason_required` | diff --git a/docs/client-openapi.json b/docs/client-openapi.json index a5b5d5b..7c3b39d 100644 --- a/docs/client-openapi.json +++ b/docs/client-openapi.json @@ -220,6 +220,90 @@ } } }, + "/v1/products/{productId}/integration-profile": { + "get": { + "operationId": "getIntegrationProfile", + "summary": "get Integration Profile", + "description": "Public integration settings for one product. Pin the public key through a trusted channel before using it to verify tokens; this response alone does not establish trust.", + "security": [], + "parameters": [ + { + "name": "productId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "productId": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "issuer": { + "type": "string", + "const": "default" + }, + "serverUrl": { + "type": "string", + "format": "uri" + }, + "activeKey": { + "type": "object", + "properties": { + "kid": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "publicKeyPem": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "pattern": "^([0-9a-f]{2}:){7}[0-9a-f]{2}$" + }, + "retiredAt": { + "type": "null" + }, + "pending": { + "const": false + } + }, + "required": ["kid", "publicKeyPem", "fingerprint", "retiredAt", "pending"], + "additionalProperties": false + } + }, + "required": ["productId", "issuer", "serverUrl", "activeKey"], + "additionalProperties": false + } + } + } + }, + "default": { + "description": "Failure; inspect error and retryable. Never treat an error as a grant.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, "/v1/products/{productId}/register": { "post": { "operationId": "registerInstallation", diff --git a/docs/configuration.md b/docs/configuration.md index a05434d..bfacac9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -17,6 +17,7 @@ The CLI, server and admin seeding use the same selection rules. System settings | `LICENSE_AUTH_SECRET` | Better Auth cryptographic secret for the web console. Missing disables console authentication. | | `LICENSE_ADMIN_TOKEN` | Optional privileged bearer credential for automation and the admin CLI. Missing disables that access method. Keep it out of customer apps. | | `LICENSE_SERVER_URL` | Public server origin, used for console authentication and as the CLI destination. Overrides Render's `RENDER_EXTERNAL_URL` when supplied. A valid explicit URL or Render fallback is required for the production console. | + | `RENDER_EXTERNAL_URL` | Render-provided public URL. Used automatically for console authentication when `LICENSE_SERVER_URL` is unset or empty. Configure `LICENSE_SERVER_URL` to use a custom domain. | | `BETTER_AUTH_URL` | Better Auth's generic environment convention. Keyforge passes its own explicit base URL from `LICENSE_SERVER_URL`; configure that canonical setting. | | `LICENSE_SIGNING_KEY` / `LICENSE_SIGNING_KEY_FILE` | Ed25519 private signing material. Exactly one source must be configured. Startup fails without a valid key. | @@ -24,6 +25,8 @@ The CLI, server and admin seeding use the same selection rules. System settings | `LICENSE_DATA_KEYRING` / `_FILE` | AES-256-GCM ring for product keys and generated per-product private keys. Required for issuance, additional products and encrypted key recovery. | | `LICENSE_BACKUP_KEYRING` / `_FILE` | Separate archive encryption ring. Required for archive jobs and their restore/verification, not raw SQLite downloads. | +Dependent apps can read `GET /v1/products/:productId/integration-profile` without credentials to obtain the product ID, signed-token issuer, configured public server URL, and the single active public signing key (including its colon-separated fingerprint). The response contains no private key or customer data. The endpoint returns an error if the product, public URL, or a unique active key is unavailable. Operators can copy the same JSON from **Products → Signing keys → Copy integration settings**. The existing `/v1/products/:productId/keys` endpoint remains available for key lists during rotation. + Use `vp run secrets:init` to generate independent data and backup ring files. A ring has `{"active":"id","keys":{"id":"<64 hexadecimal characters>"}}`. Keep old keys while records or retained archives still reference them. Changing the active ring ID affects new encryption; it does not re-encrypt existing records. Store rings outside backups and source control, with a separate recovery copy. Generate signing material with `vp run license keygen`; it follows `LICENSE_SIGNING_KEY_FILE` and prints the public half. Generate each console/admin secret separately with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`, then save it privately in the appropriate environment setting. This command prints a real secret in the terminal. Do not reuse the signing key, data ring or backup ring as a console secret. `secrets:init` creates the two ring files; it does not populate `LICENSE_AUTH_SECRET` or `LICENSE_ADMIN_TOKEN`. The scaffolder can generate all of these independently for a new deployment. diff --git a/packages/create-keyforge-client/src/index.mjs b/packages/create-keyforge-client/src/index.mjs index 2a963b6..0f34245 100644 --- a/packages/create-keyforge-client/src/index.mjs +++ b/packages/create-keyforge-client/src/index.mjs @@ -121,6 +121,7 @@ export async function main(argv = process.argv.slice(2), io = process.stdout) { 2, ) + "\n", ); + await writeFile(resolve(directory, "pnpm-workspace.yaml"), "allowBuilds:\n esbuild: true\n"); await cp(fileURLToPath(new URL("../template/", import.meta.url)), directory, { recursive: true }); await writeFile( resolve(directory, ".gitignore"), diff --git a/scripts/generate-client-openapi.ts b/scripts/generate-client-openapi.ts index 35c240c..ae482de 100644 --- a/scripts/generate-client-openapi.ts +++ b/scripts/generate-client-openapi.ts @@ -305,6 +305,27 @@ operation( 200, "", ); +operation( + "get", + product + "/integration-profile", + "getIntegrationProfile", + "Public integration settings for one product. Pin the public key through a trusted channel before using it to verify tokens; this response alone does not establish trust.", + object({ + productId: id, + issuer: string({ const: "default" }), + serverUrl: string({ format: "uri" }), + activeKey: object({ + kid: id, + publicKeyPem: string(), + fingerprint: string({ pattern: "^([0-9a-f]{2}:){7}[0-9a-f]{2}$" }), + retiredAt: { type: "null" }, + pending: { const: false }, + }), + }), + undefined, + 200, + "", +); operation( "post", product + "/register", diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjs index 6ab9bfd..4f155c6 100644 --- a/scripts/package-smoke.mjs +++ b/scripts/package-smoke.mjs @@ -182,7 +182,19 @@ try { env, ); assert.ok(!result.stdout.includes("ENOENT"), result.stdout); - assert.match(result.stdout, new RegExp("Scaffolded " + directory + "(?:\\s|$)"), result.stdout); + assert.match( + result.stdout, + new RegExp( + "(?:Scaffolded\\s+" + + directory + + "|license service scaffolded in\\s+" + + directory + + "|(?:client\\s+)?starter created in" + + ")(?:\\s|$)", + "i", + ), + result.stdout, + ); const project = join(workspace, directory); const pkg = JSON.parse(await readFile(join(project, "package.json"), "utf8")); assert.equal(pkg.name, directory); @@ -190,10 +202,13 @@ try { assert.ok(!(await readdir(project)).includes("packages")); const policy = JSON.parse(await readFile(join(project, "keyforge.config.json"), "utf8")); assert.ok(policy.licenses); + // Install the scaffold's own UI dependencies before testing its docs module. + await run("vp", ["install", "--no-frozen-lockfile"], project, env); // Upstream-only guides/workflows are pruned; the generated docs must still work. await run("vp", ["exec", "tsx", "--test", "test/docs-reader.test.ts"], project, env); } else { assert.ok(pkg.dependencies["@zdevzone/keyforge-client"]); + await run("vp", ["install", "--no-frozen-lockfile"], project, env); await run("vp", ["run", "typecheck"], project, env); await cp(join(project, ".env.example"), join(project, ".env.local")); const demo = await run("vp", ["run", "demo"], project, env); diff --git a/src/app.ts b/src/app.ts index 96c41cb..aef506f 100644 --- a/src/app.ts +++ b/src/app.ts @@ -39,6 +39,7 @@ export interface BuildLicenseAppOptions { /** Vercel serves assets through its filesystem router; retain SPA fallback. */ serveStaticAssets?: boolean; kid?: string; + publicOrigin?: string; keyring?: KeyRing; backups?: BackupOptions; onRoute?: (method: string, url: string) => void; @@ -213,6 +214,7 @@ export async function buildLicenseApp(options: BuildLicenseAppOptions): Promise< config, privateKey: options.privateKey, kid, + publicOrigin: options.publicOrigin, keyring: options.keyring, auth: options.auth, now, diff --git a/src/platform.ts b/src/platform.ts index e003928..b0ed8b8 100644 --- a/src/platform.ts +++ b/src/platform.ts @@ -26,7 +26,7 @@ import { registerImportLicensing, type ImportAccount, } from "./import-licensing.js"; -import { describeSigningKey, verifyLicenseToken } from "./keypair.js"; +import { describeSigningKey, fingerprintPublicKey, verifyLicenseToken } from "./keypair.js"; import { registerLicenseDelivery, type LicenseRequest, @@ -52,7 +52,7 @@ import { import { buildReport, reportQuerySchema, type ReportBinding, type ReportUsage } from "./reports.js"; import { generateSigningKeyPair } from "./sign.js"; import { normalizeSupportRequest, supportRequestBodySchema } from "./support.js"; -import { productTokenSchema } from "./token-contract.js"; +import { productTokenSchema, TOKEN_ISSUER } from "./token-contract.js"; export const WORKSPACE = "workspace:default"; const scope = (id: string) => "product:" + id; @@ -223,6 +223,7 @@ export interface PlatformOptions { config: AppConfig; privateKey: string; kid: string; + publicOrigin?: string; keyring?: KeyRing; auth?: AuthInstance; now: () => Date; @@ -357,7 +358,7 @@ export class Platform { return this.sign(product, { v: 1, kind: "license", - iss: "default", + iss: TOKEN_ISSUER, productId: product.id, kid: product.keys.find((k) => k.retiredAt === null && !k.pending)!.kid, licenseId: license.id, @@ -660,6 +661,40 @@ export async function registerPlatform(app: FastifyInstance, options: PlatformOp serverTime: platform.time(), })), ); + app.get( + device + "/integration-profile", + wrap(async (req) => { + const product = await platform.product(req.params.productId); + const active = product.keys.filter((key) => key.retiredAt === null && !key.pending); + if (active.length !== 1) + throw new DomainError( + "active_key_unavailable", + active.length === 0 + ? "No active signing key is available for this product." + : "Multiple active signing keys are configured for this product.", + 503, + ); + if (!options.publicOrigin) + throw new DomainError( + "public_origin_unavailable", + "Configure LICENSE_SERVER_URL to export integration settings.", + 503, + ); + const key = active[0]; + return { + productId: product.id, + issuer: TOKEN_ISSUER, + serverUrl: options.publicOrigin, + activeKey: { + kid: key.kid, + publicKeyPem: key.publicKeyPem, + fingerprint: fingerprintPublicKey(key.publicKeyPem), + retiredAt: null, + pending: false, + }, + }; + }), + ); app.post( ap + "/keys/:kid/activate", wrap( @@ -1556,7 +1591,7 @@ export async function registerPlatform(app: FastifyInstance, options: PlatformOp token: platform.sign(product, { v: 1, kind: "trial", - iss: "default", + iss: TOKEN_ISSUER, productId: pid, kid: product.keys.find((k) => !k.retiredAt && !k.pending)!.kid, installationId: input.installationId, diff --git a/src/server.ts b/src/server.ts index 0f74230..d5c72c7 100644 --- a/src/server.ts +++ b/src/server.ts @@ -118,6 +118,7 @@ export async function createLicenseServer(serverless = false) { privateKey, signingKey, kid, + publicOrigin: env.LICENSE_SERVER_URL?.replace(/\/$/, ""), adminToken: env.LICENSE_ADMIN_TOKEN, database, config, diff --git a/src/token-contract.ts b/src/token-contract.ts index 0e40fe5..5be000f 100644 --- a/src/token-contract.ts +++ b/src/token-contract.ts @@ -4,8 +4,9 @@ import { entitlementsSchema } from "./config.js"; const id = z.string().min(1).max(200); const date = z.string().datetime({ offset: true }); +export const TOKEN_ISSUER = "default"; const common = { - iss: z.literal("default"), + iss: z.literal(TOKEN_ISSUER), productId: id, kid: id, installationId: id, diff --git a/test/app.test.ts b/test/app.test.ts index dfbf188..839a166 100644 --- a/test/app.test.ts +++ b/test/app.test.ts @@ -9,7 +9,8 @@ import { buildLicenseApp } from "../src/app.js"; import { BackupService } from "../src/backups.js"; import { configSchema } from "../src/config.js"; import { LicenseDatabase } from "../src/db.js"; -import { verifyLicenseToken } from "../src/keypair.js"; +import { fingerprintPublicKey, verifyLicenseToken } from "../src/keypair.js"; +import { Records } from "../src/platform-store.js"; import { Platform } from "../src/platform.js"; import { generateSigningKeyPair } from "../src/sign.js"; const pair = generateSigningKeyPair(); @@ -115,6 +116,7 @@ test("fresh contract removes legacy routes and preserves signed revocation", asy assert.equal(verified.valid, true); const payload = verified.payload as any; assert.equal(payload.v, 1); + assert.equal(payload.iss, "default"); assert.equal(payload.productId, "default"); assert.equal(payload.entitlements.imports, 100); assert.equal("allowance" in payload, false); @@ -247,6 +249,78 @@ test("product isolation and staged rotation", async (t) => { assert.equal(verifyLicenseToken(after, key.publicKeyPem).valid, true); assert.equal(verifyLicenseToken(after, pair.publicKey).valid, false); }); +test("public integration profile selects the active key across rotation", async (t) => { + const h = await harness(t, { app: { publicOrigin: "https://license.example.test" } }); + const url = "/v1/products/default/integration-profile"; + const get = () => h.app.inject({ method: "GET", url }); + let response = await get(); + assert.equal(response.statusCode, 200, response.body); + const original = response.json(); + assert.deepEqual(original, { + productId: "default", + issuer: "default", + serverUrl: "https://license.example.test", + activeKey: { + kid: original.activeKey.kid, + publicKeyPem: pair.publicKey, + fingerprint: fingerprintPublicKey(pair.publicKey), + retiredAt: null, + pending: false, + }, + }); + assert.equal(response.headers["cache-control"], "no-store"); + assert.equal(JSON.stringify(original).includes(pair.privateKey), false); + const prior = (await h.admin("GET", "/catalog")).json().product; + response = await h.admin("POST", "/keys/stage", { revision: prior.revision }); + assert.equal(response.statusCode, 200, response.body); + const staged = response.json().product; + const pending = staged.keys.find((key: any) => key.pending); + assert.deepEqual((await get()).json(), original); + response = await h.admin("POST", "/keys/" + pending.kid + "/activate", { + revision: staged.revision, + confirm: true, + }); + assert.equal(response.statusCode, 200, response.body); + const rotated = (await get()).json(); + assert.equal(rotated.activeKey.kid, pending.kid); + assert.equal(rotated.activeKey.publicKeyPem, pending.publicKeyPem); + assert.equal(rotated.activeKey.fingerprint, fingerprintPublicKey(pending.publicKeyPem)); + assert.equal(rotated.activeKey.pending, false); + assert.equal(rotated.activeKey.retiredAt, null); + assert.equal( + (await h.app.inject({ method: "GET", url: "/v1/products/default/keys" })).statusCode, + 200, + ); + assert.equal( + (await h.app.inject({ method: "GET", url: "/v1/products/absent/integration-profile" })) + .statusCode, + 404, + ); +}); + +test("integration profile reports missing and ambiguous active keys without changing them", async (t) => { + const h = await harness(t, { app: { publicOrigin: "https://license.example.test" } }); + const records = new Records(h.db.db); + const product = await records.get("workspace:default", "product", "default"); + const url = "/v1/products/default/integration-profile"; + const get = () => h.app.inject({ method: "GET", url }); + await records.put("workspace:default", "product", { ...product, keys: [] }); + let response = await get(); + assert.equal(response.statusCode, 503); + assert.equal(response.json().error, "active_key_unavailable"); + assert.deepEqual((await records.get("workspace:default", "product", "default"))?.keys, []); + await records.put("workspace:default", "product", { + ...product, + keys: [product.keys[0], { ...product.keys[0], kid: "second" }], + }); + response = await get(); + assert.equal(response.statusCode, 503); + assert.match(response.json().message, /Multiple active/); + const noOrigin = await harness(t); + response = await noOrigin.app.inject({ method: "GET", url }); + assert.equal(response.statusCode, 503); + assert.equal(response.json().error, "public_origin_unavailable"); +}); test("encrypted key storage never leaks through listings and authenticated reveal is audited", async (t) => { const h = await harness(t), l = await h.issue(); diff --git a/test/client-sdk.test.ts b/test/client-sdk.test.ts index 2377d66..5b7eaa6 100644 --- a/test/client-sdk.test.ts +++ b/test/client-sdk.test.ts @@ -98,6 +98,7 @@ async function fixture(t: any) { database, privateKey: pair.privateKey, kid: "sdk-key", + publicOrigin: "https://license.example.test", adminToken: "sdk-test-admin", keyring: { active: "test", keys: { test: randomBytes(32).toString("hex") } }, config: configSchema.parse({ limits: { enabled: false } }), @@ -1180,6 +1181,7 @@ test("OpenAPI request links and backend metering contracts are exercised without await call("GET", "/healthz"); await call("GET", "/v1/meta"); await call("GET", "/v1/products/default/keys"); + await call("GET", "/v1/products/default/integration-profile"); const catalog = await call<{ products: { plans: { id: string }[] }[] }>( "GET", "/v1/license-request-catalog", diff --git a/ui/src/api.ts b/ui/src/api.ts index f3107e2..84971e3 100644 --- a/ui/src/api.ts +++ b/ui/src/api.ts @@ -28,6 +28,18 @@ export interface License { export interface Meta { name: string; } +export interface IntegrationProfile { + productId: string; + issuer: string; + serverUrl: string; + activeKey: { + kid: string; + publicKeyPem: string; + fingerprint: string; + retiredAt: null; + pending: false; + }; +} /** Public deployment identity (product name for the login page and titles). */ export function fetchMeta(): Promise { diff --git a/ui/src/pages/Products.tsx b/ui/src/pages/Products.tsx index 65fd23e..abd92b2 100644 --- a/ui/src/pages/Products.tsx +++ b/ui/src/pages/Products.tsx @@ -6,6 +6,7 @@ import { Badge } from "@/components/ui/badge"; import { Input } from "@/components/ui/input"; import { fetchAdminConfig, request } from "../api"; +import type { IntegrationProfile } from "../api"; import { Button, Card, Modal, TextField, Spinner, ErrorNote } from "../components"; import { ActionButton } from "../components/ActionButton"; import { Choice } from "../components/Choice"; @@ -319,6 +320,21 @@ function ProductEditor({ Distribute a staged public key to dependent apps before activating it. Retain old trusted keys while grants remain in use.

+ {product.keys.map((k) => (