Development

Development

This page summarizes local development and package conventions for Certificate Gadgets.

Project Shape

Key files:

• src/core.ts: UI-independent CertGadgetsCore API for certificate parsing, tree models, DER/PEM/HEX/Base64 utilities, ASN.1 helpers, and network validation plan collection.
• src/validation.ts: network-assisted certificate validation planning, OCSP request creation, response assessment, and validation artifact helpers.
• src/app.ts: browser application shell, certificate tree UI, Validation pane, API Log, embedded PkiStudioJS viewer integration, host callbacks, and initCertificateGadgets export.
• src/main.ts: default app entry for index.html.
• src/viewer.ts: standalone PkiStudioJS viewer entry for viewer.html.
• src/styles.css: application and viewer-host styling.
• vite.config.ts: Vite build configuration, version injection, app entries, package entry outputs, and the local development fetch proxy.

Local Checks

Run these before handing normal code changes back:

npm run check
npm run build

For package or release-related changes, also run:

npm run pack:dry-run

Local Development Server

npm run dev -- --port 5173 --strictPort

Then open:

http://localhost:5173/

In VS Code, the Start certgadgets server task starts the same server.

The development server includes a localhost-only fetch proxy for explicit network validation requests that would otherwise be blocked by browser CORS rules.

Wiki Preview in Codespaces

The repository devcontainer can prepare Gollum and clone the GitHub Wiki repository into:

/workspaces/certgadgets.wiki

Start the local Wiki preview with the VS Code task:

Start certgadgets wiki

Gollum listens on port 4567.

Package Entry Points

The npm package is @pkistudio/certgadgets.

Exports:

• @pkistudio/certgadgets: dist/core.js.
• @pkistudio/certgadgets/core: dist/core.js.
• @pkistudio/certgadgets/validation: dist/validation.js.
• @pkistudio/certgadgets/app: dist/app.js.
• @pkistudio/certgadgets/styles.css: dist/styles.css.

Version Metadata

When bumping versions, keep version metadata synchronized across:

• package.json.
• package-lock.json.
• README.md.

The package version is used for __CERTGADGETS_VERSION__, the app About display, CertGadgetsCore.version, and CertGadgetsValidation.version.

GitHub Pages Network Validation

GitHub Pages serves Certificate Gadgets as a static HTTPS site. Browser security rules block many certificate validation URLs directly because certificates often publish AIA, OCSP, and CRL resources over http://, and many responders do not allow the Pages origin with CORS.

For static deployments, provide an HTTPS fetch proxy and pass its URL to the Vite build through VITE_CERTGADGETS_FETCH_PROXY_URL.

When this variable is set, the Pages build can fetch certificate validation resources through the configured proxy after direct browser fetch fails. Local development without the variable continues to use the Vite dev proxy on localhost.

Release Notes

Release work normally follows a PR path: branch, focused commit, push, PR, CI, merge, annotated tag, GitHub Release, npm publication, and verification.

Verify published package state with:

npm view @pkistudio/certgadgets@<version> version dist-tags dist.tarball --json

Certificate parsing and validation should continue to use PKIjs and asn1js structured APIs. Browser-shipped code should not gain Node-only runtime dependencies.