Embedding

Embedding

The browser application is exported from @pkistudio/certgadgets/app as initCertificateGadgets.

import { initCertificateGadgets } from '@pkistudio/certgadgets/app';
import '@pkistudio/certgadgets/styles.css';

const app = initCertificateGadgets({
  mount: '#app',
  theme: 'dark',
  host: {
    confirmNetworkAccess: async ({ reason, url }) => {
      return window.confirm(`Allow network access for ${reason}?\n\n${url}`);
    },
    fetchNetworkResource: async ({ url, method, requestBytes, requestMediaType, acceptMediaType }) => {
      const response = await fetch(url, {
        method: method ?? (requestBytes ? 'POST' : 'GET'),
        headers: {
          ...(requestMediaType ? { 'Content-Type': requestMediaType } : {}),
          ...(acceptMediaType ? { Accept: acceptMediaType } : {})
        },
        body: requestBytes
      });
      const bytes = new Uint8Array(await response.arrayBuffer());
      return {
        status: response.status,
        byteLength: bytes.byteLength,
        bytes,
        mediaType: response.headers.get('Content-Type') ?? undefined
      };
    }
  }
});

app.loadCertificateBytes(new Uint8Array(await file.arrayBuffer()), file.name);

Mount Target

mount can be a selector or host element. The application fills the available browser viewport and manages its own certificate tree, detail pane, validation pane, splitters, ASN.1 viewer, and API log layout.

Initial Certificate

Pass an initial certificate when the host already has certificate bytes:

initCertificateGadgets({
  mount: '#app',
  certificate: {
    bytes,
    sourceName: 'server.cer'
  }
});

Hosts can also call loadCertificateBytes(bytes, sourceName) on the returned app instance.

Theme

The app follows browser or operating system light/dark preference by default.

Use theme: 'light' or theme: 'dark' to force a theme. The same effective theme is forwarded to viewer-only windows opened from the application.

The standalone app also supports query parameters:

?theme=light
?theme=dark

Host Callbacks

Host callbacks keep environment-specific behavior outside the package.

The Certificate Gadgets host contract currently includes:

• confirmNetworkAccess: ask the host to approve each explicit network validation request.
• fetchNetworkResource: let the host perform HTTP requests, proxy requests, or bridge to a native/Webview networking layer.

VS Code-specific file access, dialogs, network policy, and Webview lifecycle should stay in the host application, not inside @pkistudio/certgadgets.

App Instance

The returned app instance exposes:

• certificates: current loaded certificate documents.
• selectedNode: current selected certificate tree node.
• loadCertificateBytes(bytes, sourceName?): load or replace the current certificate.
• close(): clear the loaded certificate and validation results.

PkiStudioJS Integration

Certificate Gadgets imports PkiStudioJS from the published @pkistudio/pkistudiojs package:

• @pkistudio/pkistudiojs/oid-resolver.
• @pkistudio/pkistudiojs/viewer.

The embedded viewer is read-only for certificate investigation. Certificate Gadgets owns certificate loading, validation actions, and selected-item routing.