Validation API

Validation API

The Validation API is exposed by CertGadgetsValidation from @pkistudio/certgadgets/validation. It is UI-independent and helps hosts run explicit network-assisted validation flows.

import { CertGadgetsCore } from '@pkistudio/certgadgets';
import { CertGadgetsValidation, type NetworkFetchResult } from '@pkistudio/certgadgets/validation';

const certificate = CertGadgetsCore.createCertificateFromBytes(bytes, 'site.cer');
const [plan] = CertGadgetsCore.collectNetworkValidationPlans(certificate);

const fetchNetworkResource = async (request: typeof plan): Promise<NetworkFetchResult> => {
  const response = await fetch(request.url, {
    method: request.method ?? (request.requestBytes ? 'POST' : 'GET'),
    headers: {
      ...(request.requestMediaType ? { 'Content-Type': request.requestMediaType } : {}),
      ...(request.acceptMediaType ? { Accept: request.acceptMediaType } : {})
    },
    body: request.requestBytes
  });

  return {
    status: response.status,
    bytes: new Uint8Array(await response.arrayBuffer()),
    mediaType: response.headers.get('Content-Type') ?? undefined
  };
};

if (plan) {
  const preparedPlan = await CertGadgetsValidation.prepareNetworkValidationPlan(plan, {
    document: certificate,
    fetchNetworkResource
  });
  const result = await fetchNetworkResource(preparedPlan);
  const assessment = await CertGadgetsValidation.assessValidationContent(preparedPlan, result);

  console.log(assessment.status, assessment.transcript);
}

Validation Plans

Use createNetworkValidationPlan(node, resource?) or createNetworkValidationPlans(node) when a host is working directly with tree nodes.

Use CertGadgetsCore.collectNetworkValidationPlans(document) when a host wants unique plans for the entire certificate document.

Plans include operation, reason, URL, optional HTTP method, media types, request bytes, and certificate bytes needed for OCSP assessment.

Target Labels and Descriptions

Use getValidationTargetLabel(plan) to classify a request as a user-facing target such as:

• OCSP.
• AIA CA Issuers.
• CDP.
• AIA.

Use getNetworkValidationDescription(plan) to show a concise explanation before asking a user to allow network access.

OCSP Preparation

Use prepareNetworkValidationPlan(plan, options) before sending an OCSP request.

For OCSP plans, preparation fetches the issuer certificate from AIA CA Issuers, parses the target and issuer certificates, and generates an application/ocsp-request body.

The host must provide fetchNetworkResource when issuer certificate bytes are not already available. The API records transcript lines through addTranscriptLine when the host provides that callback.

Response Assessment

Use assessValidationContent(plan, result) after a network response is available.

The assessment returns:

• status: OK, NG, or ....
• summary: optional concise content summary.
• transcript: detailed follow-up lines for the validation result.

Use assessOcspResponse(plan, bytes) directly when a host only needs OCSP response interpretation.

Validation Artifacts

Use createValidationArtifacts(plan, result) to collect sent and received byte artifacts for display or viewer routing.

Artifacts are classified as:

• certificate.
• asn1.
• raw.

Use detectValidationDataArtifactKind(bytes, mediaType), isValidationArtifactCertificate(artifact), and isCertificateBytes(bytes, mediaType) when a host needs to decide whether to open bytes in Certificate Gadgets, an ASN.1 viewer, or a raw-byte path.

Network Boundaries

The Validation API does not silently fetch network resources. Host applications own user confirmation, HTTP transport, proxying, persistence, and UI display.

Browser hosts often need a proxy because many certificate AIA, OCSP, and CRL endpoints use http:// or omit CORS headers.