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