◆ KOVO
Star
Menu

API Reference

View as Markdown

@kovojs/verify

Generated from 1 public subpath — 11 exports, 11 documented. Do not edit by hand.

@kovojs/verify#

Task: Runtime-independent certificate verification API for exact packed Kovo artifacts and independently reviewed policy.

Source: packages/verify/src/index.ts

Values#

KOVO_CERTIFICATE_CAPABILITY_DOMAIN#

The nine raw authority kinds certified by kovo.certificate/v1 (SPEC §6.6).

Signature

ts
const KOVO_CERTIFICATE_CAPABILITY_DOMAIN = [
  'crypto-acquisition',
  'database-driver',
  'digest',
  'dynamic-loader',
  'filesystem',
  'network',
  'process',
  'vm',
  'worker',
] as const;

verifyCertificate#

Verify a certificate without importing Kovo's analyzer or runtime.

Parameter Type Description
certificateInput unknown Parsed, untrusted kovo.certificate/v1 input.
policyBytes Uint8Array Exact independently authenticated kovo.certificate-policy/v1 bytes.
artifacts KovoCertificateArtifactSource Finite source of exact packed runtime-module bytes.
(returns) Promise<KovoCertificateVerificationResult> The complete ordered findings and certificate statistics.

Signature

ts
async function verifyCertificate(
  certificateInput: unknown,
  policyBytes: Uint8Array,
  artifacts: KovoCertificateArtifactSource,
): Promise<KovoCertificateVerificationResult>;

verifyCertificateDirectory#

Verify against regular non-symlink files below an artifact root such as an unpacked node_modules directory. Only package dist trees named by the separately supplied policy are enumerated; executable siblings and package entrypoint retargeting fail closed.

Parameter Type Description
certificateInput unknown Parsed, untrusted kovo.certificate/v1 input.
policyBytes Uint8Array Exact independently authenticated kovo.certificate-policy/v1 bytes.
artifactRoot string Root containing the exact unpacked @kovojs/* package tree.
(returns) Promise<KovoCertificateVerificationResult> The complete ordered findings and certificate statistics.

Copyable example

ts
import { readFile } from 'node:fs/promises';
import { verifyCertificateDirectory } from '@kovojs/verify';

const certificate = JSON.parse(await readFile('./certificate.json', 'utf8'));
const policy = new Uint8Array(await readFile('./reviewer-policy.json'));
const result = await verifyCertificateDirectory(certificate, policy, './packages');

Signature

ts
async function verifyCertificateDirectory(
  certificateInput: unknown,
  policyBytes: Uint8Array,
  artifactRoot: string,
): Promise<KovoCertificateVerificationResult>;

formatCertificateVerification#

Render the byte-stable kovo-verify/v1 human report.

Parameter Type Description
result KovoCertificateVerificationResult Result returned by either certificate verifier.
(returns) string A newline-terminated report with the same ordered findings as the JSON CLI format.

Signature

ts
function formatCertificateVerification(result: KovoCertificateVerificationResult): string;

Supporting types#

KovoCertificateCapabilityKind#

A raw authority kind in a Kovo artifact certificate.

Signature

ts
type KovoCertificateCapabilityKind = (typeof KOVO_CERTIFICATE_CAPABILITY_DOMAIN)[number];

KovoCertificateRootKind#

An untrusted-data root kind in a Kovo artifact certificate.

Signature

ts
type KovoCertificateRootKind =
  | 'agent-tool-callback'
  | 'application'
  | 'durable-task'
  | 'endpoint'
  | 'layout'
  | 'mutation'
  | 'query'
  | 'route'
  | 'scheduled-task'
  | 'serialized-browser-handler'
  | 'webhook';

KovoCertificateV1#

Frozen independently-checkable artifact certificate (SPEC §6.6).

Signature

ts
interface KovoCertificateV1 {
  artifacts: readonly string[];
  cap: Readonly<Record<string, readonly KovoCertificateCapabilityKind[]>>;
  domain: typeof KOVO_CERTIFICATE_CAPABILITY_DOMAIN;
  doors: readonly {
    escapeId: KovoCertificateCapabilityKind;
    module: string;
    site: string;
  }[];
  edges: readonly (readonly [string, string])[];
  opaque: readonly { module: string; reason: string }[];
  policySha512: string;
  roots: readonly { module: string; rootKind: KovoCertificateRootKind }[];
  schema: 'kovo.certificate/v1';
}

KovoCertificatePolicyV1#

Independently supplied reviewer policy that owns certificate scope and authority posture.

Signature

ts
interface KovoCertificatePolicyV1 {
  artifacts: readonly { path: string; sha512: string }[];
  doors: KovoCertificateV1['doors'];
  opaque: KovoCertificateV1['opaque'];
  packages: readonly {
    manifest: Readonly<Record<string, unknown>>;
    name: string;
  }[];
  roots: KovoCertificateV1['roots'];
  schema: 'kovo.certificate-policy/v1';
}

KovoCertificateFinding#

One independently-derived checker failure.

Signature

ts
interface KovoCertificateFinding {
  code: string;
  message: string;
  obligation: 'closure' | 'coverage' | 'schema' | 'stability';
}

KovoCertificateArtifactSource#

Source of exact published artifact bytes supplied to the standalone checker.

Signature

ts
interface KovoCertificateArtifactSource {
  listArtifactPaths(): readonly string[];
  readArtifact(path: string): Uint8Array | undefined;
}

KovoCertificateVerificationResult#

Result of checking all three linear certificate obligations.

Signature

ts
interface KovoCertificateVerificationResult {
  findings: readonly KovoCertificateFinding[];
  ok: boolean;
  stats: {
    artifacts: number;
    capabilities: number;
    doors: number;
    edges: number;
    opaque: number;
    roots: number;
  };
}