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
7 changes: 7 additions & 0 deletions docs/about-andhub.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# About AndHub

AndHub builds and maintains KeyForge.

KeyForge is MIT-licensed, self-hosted software for issuing and managing signed licenses across a company's products. Teams run it on their own infrastructure and keep control of their data, signing keys and deployment.

[View KeyForge on GitHub](https://github.com/zdevzone/keyforge).
58 changes: 29 additions & 29 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,46 @@
# KeyForge documentation

Deploy your own license server, issue licenses from priced plans, and connect your software to signed online and bounded offline authorization.
Self-hosted license management for software products.

**New to KeyForge? Start with the [beginner guide](getting-started.md).** It takes you from a source checkout to your first license activation and explains which secrets belong on the server and which configuration belongs in your app.
**New here?** Follow the [beginner guide](getting-started.md) to run the server and activate a license.

## Run a server

- [Setup and first license](getting-started.md): prerequisites, environment, generated secrets, first operator and verification.
- [Project CLI](../packages/create-keyforge/README.md): generate a deployment with your database, licensing model and host settings.
- [Configuration](configuration.md): environment variables, databases, deployment policy and defaults.
- [Deployment](deploy.md): Render, Docker, local/VPS, Fly.io, Railway, Koyeb and cPanel.
- [Backups and recovery](backups.md): encrypted archives, independent schedules, verification and restoration.
- [Database maintenance](database.md): SQLite/PostgreSQL selection, demo data and the admin-preserving reset.
- [Upgrade an existing installation](database.md#fresh-v1-baseline): backups, schema changes and older client compatibility.
- [Project CLI](../packages/create-keyforge/README.md) — generate a deployment.
- [Configuration](configuration.md) — environment variables and defaults.
- [Deployment](deploy.md) — Docker, VPS, Render, Fly.io, Railway, Koyeb, Vercel and cPanel.
- [Vercel deployment](vercel.md) — hosted setup and backups.
- [cPanel deployment](cpanel-guide.md) — prebuilt releases and Passenger.
- [Backups and recovery](backups.md) — create, verify and restore archives.
- [Database maintenance](database.md) — manage SQLite or PostgreSQL.

## Operate KeyForge

- [Licenses, requests and payments](license-sales.md): plans, automatic ETB sales, unpaid balances, payment recording and delivery.
- [CLI reference](cli.md): key generation, diagnostics, issuance, revocation, seat release and maintenance commands.
- [API reference](api.md): authentication, permissions, routes, request bodies and errors.
- [Package publishing](publishing.md): GitHub Actions releases and manual Bash/Windows PowerShell commands for the SDK and both CLIs.
- [Maintainer guide](maintaining.md): contributions, testing on Render, production promotion and rollback.
- [Licenses and payments](license-sales.md) — plans, issuance, balances and payment records.
- [CLI reference](cli.md) — issue, revoke and inspect licenses.
- [API reference](api.md) — routes, access rules and errors.
- [Package releases](publishing.md) — publish the SDK and command-line tools.
- [Maintainer guide](maintaining.md) — contribute, deploy and recover.

## Connect an application

- [Integration guide](dependent-app-integration.md): registration, activation, offline authorization, support and trusted metering.
- [Import licensing and recovery](import-licensing.md): additive paid allowances, permanent trial conversion, atomic local usage and staff-approved recovery.
- [TypeScript SDK](../packages/keyforge-client/README.md): secure storage, retries, signed-token verification and client methods.
- [Device recognition](device-identity.md): optional Windows, Linux and macOS signals, diagnostics and recovery.
- [Token verification](verify-token.md): the exact Ed25519 license/trial v1 contract for any language.
- [Client OpenAPI](client-openapi.json): download the language-independent client API contract.
- [Studio Proof contract review](studio-proof-contract.md): production verification, endpoint details, migration boundaries and outstanding product decisions.
- [AI integration context](dependent-app-ai-context.md): concise instructions for your app's coding assistant.
- [Integration guide](dependent-app-integration.md) — registration, activation and offline use.
- [Import licensing and recovery](import-licensing.md) — paid allowances and approved recovery.
- [TypeScript SDK](../packages/keyforge-client/README.md) — verify grants and call the API.
- [Device recognition](device-identity.md) — optional device signals and recovery.
- [Windows adapter](windows-device-identity.md) — Windows-specific identity details.
- [Studio Proof contract](studio-proof-contract.md) — the verified integration contract.
- [Token verification](verify-token.md) — the Ed25519 token contract.
- [Client OpenAPI](client-openapi.json) — download the API schema.
- [AI integration context](dependent-app-ai-context.md) — instructions for coding assistants.

## Understand the boundaries
## Reference

KeyForge is MIT-licensed, self-hosted software for one company managing multiple products. It does not currently provide multi-tenant vendor hosting, public operator sign-up, email delivery or a payment gateway. Sales and payments are manually recorded in ETB. New activation and trial authorization require internet; offline use only continues within a previously signed grant.
- [Architecture and limitations](integration-review.md) — current scope and boundaries.
- [Documentation maintenance](documentation-site.md) — update and publish these guides.

See [current limitations and architecture](integration-review.md) before making production or hosted-service commitments.
## Before you deploy

## About these guides
KeyForge is self-hosted for one company managing multiple products. It has no vendor-hosted multi-tenancy, public operator sign-up, email delivery or payment gateway. New activation requires internet; offline use continues only within a signed grant.

This site bundles an explicit selection of the repository's Markdown with each UI build. It does not fetch GitHub on each visit. Update the files, run the checks and rebuild/redeploy to update this site's content. GitHub remains the source and download location; the documentation shown here describes the code shipped with this deployment.

Maintain the reader and its public file allowlist using the [documentation maintenance guide](documentation-site.md).
Read [architecture and limitations](integration-review.md) before making production or hosted-service commitments.
4 changes: 2 additions & 2 deletions docs/ui-component-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Registry inspection: `.artifacts/communication-registry.json`; upstream sources

Inbox previews explicitly prefix internal messages with “Private note”. Notifications now retain personal product-scoped history, deletion tombstones. Operator preferences cover messages, assignments and expiration alerts at 30, 7 and 1 days; disabling them stops future captures without erasing history. Preferences live in Settings and persist on the server, while appearance is local to this browser. The page and dropdown refresh every 30 seconds while mounted; read actions and dependent-app preferences use authenticated APIs. Recording an initial or renewal sale does not change license access or expiry.

The final desktop/mobile browser pass covers Settings tabs, avatar workflow, persistent appearance, notification dropdown/table/bulk controls and confirmation, including dark appearance and overflow checks. Evidence is under `.artifacts/console-smoke/`; see `ui/.impeccable/surfaces/console-patterns.md` for the capture list. Both reduced-motion animation and transition duration use `0ms` in `ui/src/index.css`, verified by live computed colors after the dark contrast correction. No shipping raster was added. Shared SQLite setup and demo reset guidance is in `docs/database.md`.
The final desktop/mobile browser pass covers Settings tabs, avatar workflow, persistent appearance, notification dropdown/table/bulk controls and confirmation, including dark appearance and overflow checks. Evidence is under `.artifacts/console-smoke/`; the console design review notes contain the capture list. Both reduced-motion animation and transition duration use `0ms` in `ui/src/index.css`, verified by live computed colors after the dark contrast correction. No shipping raster was added. Shared SQLite setup and demo reset guidance is in `docs/database.md`.

## Plan issuance, preinstallation requests and payments (2026-10-15)

Expand All @@ -66,6 +66,6 @@ Sources: `ui/src/IssueLicense.tsx`, `ui/src/components/PaymentFields.tsx`, `ui/s

Finish disposition: **SHIP** for the sampled visible composition. All 11 `.artifacts/issuance-smoke/*.png` images were opened: the desktop public request entry, desktop/mobile private issued-key status, unpaid desktop issuance, paid desktop/mobile issuance including its lower payment controls, desktop Mark as paid, desktop financial report and desktop/mobile Account. `request-mobile.png` is the private status/retrieval view, not the public entry form. The focused browser workflow supplied by the implementation pass covered public request/private retrieval, unpaid and paid issuance, later payment, Settings and responsive Account. Detector output in `.artifacts/issuance-smoke/detector.json` is `[]`.

The extension reuses the incumbent panel, dialog, field, checkbox, selector and table language. No new typography, palette, token system or shipping raster was introduced, so `ui/DESIGN.md` and `ui/.impeccable/design.json` remain unchanged. This capture set contains no new dark appearance evidence; prior dark-system documentation remains the reference. The visual disposition does not independently guarantee backend atomicity, authorization, idempotency or financial correctness.
The extension reuses the incumbent panel, dialog, field, checkbox, selector and table language. No new typography, palette, token system or shipping raster was introduced, so `ui/DESIGN.md` and the component preview sidecar remain unchanged. This capture set contains no new dark appearance evidence; prior dark-system documentation remains the reference. The visual disposition does not independently guarantee backend atomicity, authorization, idempotency or financial correctness.

Separate implementation verification reports 115 tests passed and 7 optional tests skipped; issuance smoke, console smoke, typechecks and `build:all` passed. A local server refresh retained all record counts, including 3 users and 5 sessions, with database integrity OK and zero foreign-key errors. `vp run check` remains blocked by six pre-existing formatting files; no new lint warnings were reported. These are implementation-pass results, not additional claims derived from the screenshot review.
4 changes: 2 additions & 2 deletions docs/ui-redesign.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,13 @@ Environment validation resolves `LICENSE_SERVER_URL` first, then `RENDER_EXTERNA

## Validation and design handoff

The token-bearing [visual system](../ui/DESIGN.md) and schemaVersion 2 [component preview sidecar](../ui/.impeccable/design.json) now describe the shipped Polaris palette, typography, square geometry, responsive layout and shared adapters. [The console surface brief](../ui/.impeccable/surfaces/console-patterns.md) retains the operational contracts and records the replacement visual authority.
The token-bearing [visual system](../ui/DESIGN.md) and schemaVersion 2 component preview sidecar describe the shipped Polaris palette, typography, square geometry, responsive layout and shared adapters. The console design review notes retain the operational contracts and record the visual authority.

Validation passed: `vp run check`, `vp run test` (117 passed, seven optional skips), `vp run build:all`, and the console and issuance browser suites. The three warnings in inactive sources were corrected by tracking the upload error callback dependency and using native semantic elements for typing status and reaction controls. The required searchable-recipient and empty-ID manual-option paths passed. The finish reviewer accepted all twelve required fresh desktop/mobile light/dark captures with a **SHIP** disposition and no material fixes. Credential scanning found zero matches in changed files and built assets.

The design detector ran once before documentation was refreshed and reported nine advisory type sizes outside the old Inter ramp. DESIGN now records the actual Polaris annotation, title and metric sizes, including 10/11/15/24/26/28/30px; no detector rerun is implied. Visual review establishes sampled composition and interaction evidence, not an independent proof of backend financial correctness or authorization.

The later [public welcome and device extension](../ui/.impeccable/surfaces/welcome.md) preserves this console system. Its fresh finish reviewer returned **SHIP** with all twelve required public/device captures valid and no material fixes. The extension's detector report (`.artifacts/windows-welcome-detect.json`) has no primary findings and five advisory findings for intentional public-only brand/display/section sizes; those roles are now scoped in DESIGN and the sidecar without changing console typography. The two shipped welcome rasters are light/dark captures of the real Plans composition with synthetic demo data. The welcome brief records their provenance, routing and product contracts, plus the exact review evidence paths. Earlier validation counts above remain historical rather than a claim about this extension's test run.
The later public welcome and device extension preserves this console system. Its fresh finish reviewer returned **SHIP** with all twelve required public/device captures valid and no material fixes. The extension's detector report (`.artifacts/windows-welcome-detect.json`) has no primary findings and five advisory findings for intentional public-only brand/display/section sizes; those roles are now scoped in DESIGN and the sidecar without changing console typography. The two shipped welcome rasters are light/dark captures of the real Plans composition with synthetic demo data. Design review notes record their provenance, routing and product contracts, plus the exact review evidence paths. Earlier validation counts above remain historical rather than a claim about this extension's test run.

## Source references

Expand Down
2 changes: 2 additions & 0 deletions packages/create-keyforge/src/template.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ const PRUNE = [
"test/import-licensing.test.ts",
// A dated review of upstream's deployment is not a new deployer's configuration.
"docs/studio-proof-contract.md",
// Upstream's About page describes AndHub; generated projects use their own identity.
"docs/about-andhub.md",
"test/scaffold-prompts.test.ts",
"scripts/package-smoke.mjs",
"scripts/release-packages.mjs",
Expand Down
27 changes: 18 additions & 9 deletions scripts/docs-smoke.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ try {
});
assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth));
assert.equal(await page.locator("html").getAttribute("data-theme"), theme);
if (width <= 639) {
await page.getByRole("button", { name: "Toggle documentation navigation" }).click();
await page.locator('[data-mobile="true"] a[aria-current="page"]').waitFor();
}
const contrast = await page.evaluate(() => {
const canvas = document.createElement("canvas"),
context = canvas.getContext("2d");
Expand All @@ -115,17 +119,20 @@ try {
});
return rgb[0] * 0.2126 + rgb[1] * 0.7152 + rgb[2] * 0.0722;
};
const style = getComputedStyle(
document.querySelector('.docs-navigation a[aria-current="page"]'),
);
const selector =
innerWidth <= 639
? '[data-mobile="true"] a[aria-current="page"]'
: '.docs-guide-sidebar a[aria-current="page"]';
const style = getComputedStyle(document.querySelector(selector));
const a = luminance(style.color),
b = luminance(style.backgroundColor);
return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
});
assert.ok(contrast >= 4.5, theme + " selected navigation contrast: " + contrast);
if (width <= 639) await page.keyboard.press("Escape");
await page.screenshot({ path: join(captures, name + ".png"), fullPage: true });
}
await page.getByRole("button", { name: "Open documentation navigation" }).click();
await page.getByRole("button", { name: "Toggle documentation navigation" }).click();
await page.screenshot({ path: join(captures, "mobile-navigation.png") });
await page.keyboard.press("Escape");
await page.setViewportSize({ width: 1440, height: 1000 });
Expand All @@ -142,14 +149,16 @@ try {
await page.getByRole("heading", { name: "Generate secrets", exact: true }).waitFor();
await page.screenshot({ path: join(captures, "beginner-secrets-" + name + ".png") });
}
await page.setViewportSize({ width: 1440, height: 1000 });
await page.goto(origin + "/docs");
await page.getByRole("button", { name: "Open documentation navigation" }).click();
await page.getByRole("dialog").getByRole("link", { name: "Beginner guide", exact: true }).click();
await page
.locator(".docs-guide-sidebar")
.getByRole("link", { name: "Beginner guide", exact: true })
.click();
await page.getByRole("heading", { name: "Beginner guide", exact: true }).waitFor();
assert.equal(await page.getByRole("dialog").count(), 0);
await page.getByRole("button", { name: "On this page", exact: true }).click();
await page.setViewportSize({ width: 390, height: 844 });
await page
.getByRole("navigation", { name: "On this page", exact: true })
.locator(".docs-mobile-toc")
.getByRole("link", { name: "Understand the keys and credentials" })
.click();
await page.waitForURL(/#understand-the-keys-and-credentials$/);
Expand Down
Loading
Loading