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
3 changes: 3 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand All @@ -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` |
Expand Down Expand Up @@ -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` |
Expand Down
84 changes: 84 additions & 0 deletions docs/client-openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
3 changes: 3 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,16 @@ 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. |
| `LICENSE_PUBLIC_KEY` | A dependent app convention for its trusted public verification key; Keyforge does not read this variable. Public keys are shared; private keys stay on the server. |
| `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.
Expand Down
1 change: 1 addition & 0 deletions packages/create-keyforge-client/src/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand Down
21 changes: 21 additions & 0 deletions scripts/generate-client-openapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
17 changes: 16 additions & 1 deletion scripts/package-smoke.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -182,18 +182,33 @@ 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);
if (name === "keyforge") {
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);
Expand Down
2 changes: 2 additions & 0 deletions src/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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,
Expand Down
43 changes: 39 additions & 4 deletions src/platform.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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;
Expand Down Expand Up @@ -223,6 +223,7 @@ export interface PlatformOptions {
config: AppConfig;
privateKey: string;
kid: string;
publicOrigin?: string;
keyring?: KeyRing;
auth?: AuthInstance;
now: () => Date;
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
3 changes: 2 additions & 1 deletion src/token-contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading