---
title: "@kovojs/verify"
description: Runtime-independent certificate verification API for exact packed Kovo artifacts and independently reviewed policy.
order: 10
---

# @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`](https://github.com/kovojs/kovo/blob/main/packages/verify/src/index.ts)

### Values

#### `KOVO_CERTIFICATE_CAPABILITY_DOMAIN` {#kovocertificatecapabilitydomain}

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` {#verifycertificate}

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

| Parameter | Type | Description |
| --- | --- | --- |
| `certificateInput` | <code>unknown</code> | Parsed, untrusted `kovo.certificate/v1` input. |
| `policyBytes` | <code>Uint8Array</code> | Exact independently authenticated `kovo.certificate-policy/v1` bytes. |
| `artifacts` | <code><a href="#kovocertificateartifactsource">KovoCertificateArtifactSource</a></code> | Finite source of exact packed runtime-module bytes. |
| *(returns)* | <code>Promise&lt;<a href="#kovocertificateverificationresult">KovoCertificateVerificationResult</a>&gt;</code> | The complete ordered findings and certificate statistics. |

**Signature**

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

#### `verifyCertificateDirectory` {#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` | <code>unknown</code> | Parsed, untrusted `kovo.certificate/v1` input. |
| `policyBytes` | <code>Uint8Array</code> | Exact independently authenticated `kovo.certificate-policy/v1` bytes. |
| `artifactRoot` | <code>string</code> | Root containing the exact unpacked `@kovojs/*` package tree. |
| *(returns)* | <code>Promise&lt;<a href="#kovocertificateverificationresult">KovoCertificateVerificationResult</a>&gt;</code> | 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` {#formatcertificateverification}

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

| Parameter | Type | Description |
| --- | --- | --- |
| `result` | <code><a href="#kovocertificateverificationresult">KovoCertificateVerificationResult</a></code> | Result returned by either certificate verifier. |
| *(returns)* | <code>string</code> | A newline-terminated report with the same ordered findings as the JSON CLI format. |

**Signature**

```ts
function formatCertificateVerification(result: KovoCertificateVerificationResult): string;
```

### Supporting types

#### `KovoCertificateCapabilityKind` {#kovocertificatecapabilitykind}

A raw authority kind in a Kovo artifact certificate.

**Signature**

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

#### `KovoCertificateRootKind` {#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` {#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` {#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` {#kovocertificatefinding}

One independently-derived checker failure.

**Signature**

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

#### `KovoCertificateArtifactSource` {#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` {#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;
  };
}
```