# zidane/dist-feed

Import: `import { … } from 'zidane/dist-feed'`. Source: [src/dist/manifest.ts](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts).

## Functions

### `checkDistArtifact`

Function.

Throws a [`DistVerificationError`](https://zidane.si/docs/reference/dist-feed.md#DistVerificationError) unless `data` has the artifact's size and SHA-256.

```ts
function checkDistArtifact(
  data: Uint8Array,
  artifact: Pick<DistArtifact, 'name' | 'sha256' | 'size'>,
): void
```

**Parameters**

- `data` (`Uint8Array`): The downloaded file.
- `artifact` (`Pick<DistArtifact, 'name' | 'sha256' | 'size'>`): Its entry in a verified manifest.

Source: [src/dist/manifest.ts:290](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L290)

### `compareVersions`

Function.

Semver order of two versions (`-1`, `0`, `1`): a release is newer than its
prereleases, numeric prerelease parts compare as numbers. Unparseable
versions compare equal (never "newer").

```ts
function compareVersions(a: string, b: string): -1 | 0 | 1
```

**Parameters**

- `a` (`string`): A version (a leading `v` is ignored).
- `b` (`string`): Another one.

**Returns** `-1 | 0 | 1`

Source: [src/dist/manifest.ts:311](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L311)

### `distBaseUrl`

Function.

The feed's base URL: `ZIDANE_DIST_URL` when set, else [`DIST_BASE_URL`](https://zidane.si/docs/reference/dist-feed.md#DIST_BASE_URL); no trailing slash.

```ts
function distBaseUrl(env?: Record<string, string | undefined>): string
```

**Parameters**

- `env?` (`Record<string, string | undefined>`, default `process.env`): Environment to read (default `process.env`).

**Returns** `string`

Source: [src/dist/manifest.ts:100](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L100)

### `distManifestUrl`

Function.

The manifest URL: the newest release's, or `version`'s (while the feed still keeps it).

```ts
function distManifestUrl(baseUrl: string, version?: string): string
```

**Parameters**

- `baseUrl` (`string`): The feed's base URL.
- `version?` (`string`): A release to pin (with or without `v`); omitted: `latest.json`.

**Returns** `string`

Source: [src/dist/manifest.ts:119](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L119)

### `distPublicKey`

Function.

The public key clients trust: `ZIDANE_DIST_PUBLIC_KEY` when set, else [`DIST_PUBLIC_KEY`](https://zidane.si/docs/reference/dist-feed.md#DIST_PUBLIC_KEY).

```ts
function distPublicKey(env?: Record<string, string | undefined>): string
```

**Parameters**

- `env?` (`Record<string, string | undefined>`, default `process.env`): Environment to read (default `process.env`).

**Returns** `string`

Source: [src/dist/manifest.ts:109](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L109)

### `distTarget`

Function.

The feed's names for this host's OS and CPU, or `null` when the feed has no build for it.

```ts
function distTarget(
  platform?: string,
  arch?: string,
): { arch: DistArch; os: DistOs } | null
```

**Parameters**

- `platform?` (`string`, default `process.platform`): A `process.platform` value (default: this host's).
- `arch?` (`string`, default `process.arch`): A `process.arch` value (default: this host's).

**Returns** `{ arch: DistArch; os: DistOs } | null`

Source: [src/dist/manifest.ts:130](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L130)

### `fetchDistManifest`

Function.

Downloads and verifies a manifest: the newest release's, or `version`'s.
A pinned version must be the one the manifest names.

```ts
function fetchDistManifest(
  options?: { baseUrl?: string; fetch?: (url: string, init?: RequestInit) => Promise<Response>; publicKey?: string; timeoutMs?: number; version?: string },
): Promise<DistManifest>
```

**Parameters**

- `options?` (`{ baseUrl?: string; fetch?: (url: string, init?: RequestInit) => Promise<Response>; publicKey?: string; timeoutMs?: number; version?: string }`, default `{}`): The release to pin, the feed, the key, the `fetch` and the timeout (all optional).

**Returns** `Promise<DistManifest>`

Source: [src/dist/manifest.ts:228](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L228)

### `findDistArtifact`

Function.

The artifact of `kind` for `os` / `arch` (default: this host), or `undefined`.

```ts
function findDistArtifact(
  manifest: DistManifest,
  kind: DistArtifactKind,
  target?: { arch: DistArch; os: DistOs } | null,
): DistArtifact | undefined
```

**Parameters**

- `manifest` (`DistManifest`): A verified manifest.
- `kind` (`DistArtifactKind`): What to install.
- `target?` (`{ arch: DistArch; os: DistOs } | null`): OS and CPU (default: this host's; `null` finds nothing).

**Returns** `DistArtifact | undefined`

Source: [src/dist/manifest.ts:271](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L271)

### `parseDistManifest`

Function.

Parses and validates a manifest's JSON (no signature check: see [`verifyDistManifest`](https://zidane.si/docs/reference/dist-feed.md#verifyDistManifest)).

```ts
function parseDistManifest(text: string): DistManifest
```

**Parameters**

- `text` (`string`): The manifest's JSON.

**Returns** `DistManifest`

Source: [src/dist/manifest.ts:165](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L165)

### `parseMinisignPublicKey`

Function.

Parses a public key file (`minisign.pub`) or its bare base64 line.

```ts
function parseMinisignPublicKey(text: string): MinisignPublicKey
```

**Parameters**

- `text` (`string`): The file's contents, or its base64 line.

**Returns** `MinisignPublicKey`

Source: [src/dist/minisign.ts:88](https://github.com/Tahul/zidane/blob/main/src/dist/minisign.ts#L88)

### `sha256Hex`

Function.

Lower-case hex SHA-256 of `data`.

```ts
function sha256Hex(data: Uint8Array): string
```

**Parameters**

- `data` (`Uint8Array`): Bytes to hash.

**Returns** `string`

Source: [src/dist/manifest.ts:280](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L280)

### `verifyDistManifest`

Function.

Checks `json` against its minisign signature file, then parses it. Throws a [`DistVerificationError`](https://zidane.si/docs/reference/dist-feed.md#DistVerificationError) when either fails.

```ts
function verifyDistManifest(
  json: string | Uint8Array<ArrayBufferLike>,
  signature: string,
  publicKey?: string,
): DistManifest
```

**Parameters**

- `json` (`string | Uint8Array<ArrayBufferLike>`): The manifest's bytes, exactly as served.
- `signature` (`string`): Its `.minisig` file.
- `publicKey?` (`string`): The trusted key (default [`distPublicKey`](https://zidane.si/docs/reference/dist-feed.md#distPublicKey)).

**Returns** `DistManifest`

Source: [src/dist/manifest.ts:211](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L211)

### `verifyMinisign`

Function.

Checks a minisign signature file against `message` and `publicKey` (a
`minisign.pub` file, its base64 line, or a parsed key): the key id, the
signature of the prehashed message, then the trusted comment's signature.
Returns the trusted comment; throws on any mismatch.

```ts
function verifyMinisign(
  message: Uint8Array,
  signatureFile: string,
  publicKey: string | MinisignPublicKey,
): { trustedComment: string }
```

**Parameters**

- `message` (`Uint8Array`): The signed file's bytes.
- `signatureFile` (`string`): The `.minisig` file's contents.
- `publicKey` (`string | MinisignPublicKey`): The trusted key.

**Returns** `{ trustedComment: string }`

Source: [src/dist/minisign.ts:118](https://github.com/Tahul/zidane/blob/main/src/dist/minisign.ts#L118)

## Classes

### `DistVerificationError`

Class.

A manifest or artifact that does not check out: a bad or missing signature,
a malformed manifest, another release than asked for, a wrong checksum or
size. Not a network failure: something served is not what was signed.

```ts
class DistVerificationError extends Error
```

**Constructor**

```ts
new DistVerificationError(message: string, options?: ErrorOptions)
```

Creates the error.

**Parameters**

- `message` (`string`): What did not check out.
- `options?` (`ErrorOptions`): Optional `cause`.

**Returns** `DistVerificationError`

**Properties**

- `name` (`string`, default `'DistVerificationError'`): Always `'DistVerificationError'`.

Source: [src/dist/manifest.ts:141](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L141)

## Constants

### `DIST_BASE_URL`

Constant.

Where the feed lives. `ZIDANE_DIST_URL` overrides it (a mirror, a test server).

```ts
const DIST_BASE_URL = 'https://zidane.si/dl'
```

Source: [src/dist/manifest.ts:22](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L22)

### `DIST_IMAGE_PATTERN`

Constant.

What `DistManifest.image` looks like: a repository pinned by digest.

```ts
const DIST_IMAGE_PATTERN: RegExp
```

Source: [src/dist/manifest.ts:93](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L93)

### `DIST_LATEST_FILE`

Constant.

The newest release's manifest, at the feed's root.

```ts
const DIST_LATEST_FILE = 'latest.json'
```

Source: [src/dist/manifest.ts:32](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L32)

### `DIST_PUBLIC_KEY`

Constant.

The minisign public key that signs the feed (`src/dist/minisign.pub`).
Check by hand: `minisign -Vm latest.json -P <this>`. `ZIDANE_DIST_PUBLIC_KEY`
overrides it (a test feed).

```ts
const DIST_PUBLIC_KEY = 'RWTeH2EIT+uzHQnG7U5bcHFzskL0m++wKuc3U5zEom2+tRn/8UukIDGk'
```

Source: [src/dist/manifest.ts:29](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L29)

### `DIST_RELEASE_FILE`

Constant.

A release's manifest, inside its `v<version>/` folder.

```ts
const DIST_RELEASE_FILE = 'manifest.json'
```

Source: [src/dist/manifest.ts:34](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L34)

## Interfaces

### `DistArtifact`

Interface.

One downloadable file of a release.

```ts
interface DistArtifact
```

**Properties**

- `arch` (`DistArch`): CPU architecture it runs on.
- `kind` (`DistArtifactKind`): What it is (a client looks for the kind it installs).
- `name` (`string`): File name inside the release folder.
- `os` (`DistOs`): Operating system it runs on.
- `sha256` (`string`): Lower-case hex SHA-256 of the file.
- `size` (`number`): Size in bytes.
- `url` (`string`): Absolute download URL.

Source: [src/dist/manifest.ts:49](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L49)

### `DistFile`

Interface.

A file of a release that runs nowhere (its notes).

```ts
interface DistFile
```

**Properties**

- `name` (`string`): File name inside the release folder.
- `sha256` (`string`): Lower-case hex SHA-256 of the file.
- `size` (`number`): Size in bytes.
- `url` (`string`): Absolute download URL.

Source: [src/dist/manifest.ts:67](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L67)

### `DistManifest`

Interface.

The signed manifest of one release.

```ts
interface DistManifest
```

**Properties**

- `artifacts` (`DistArtifact[]`): Every artifact of the release.
- `date` (`string`): When the release was published (ISO 8601).
- `image?` (`string`): The zidane-server image of this release, pinned by digest (`ghcr.io/<owner>/zidane-server@sha256:<hex>`), when the release pushed one.
- `notes?` (`DistFile`): The release notes (`NOTES.md`, Markdown: this release's and the one before), when the release wrote them.
- `version` (`string`): Release version, without a leading `v`.

Source: [src/dist/manifest.ts:79](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L79)

### `MinisignPublicKey`

Interface.

A minisign public key.

```ts
interface MinisignPublicKey
```

**Properties**

- `keyId` (`Uint8Array`): The 8-byte key id a signature names.
- `publicKey` (`Uint8Array`): The raw Ed25519 public key (32 bytes).

Source: [src/dist/minisign.ts:37](https://github.com/Tahul/zidane/blob/main/src/dist/minisign.ts#L37)

## Types

### `DistArch`

Type.

A CPU architecture the feed ships for.

```ts
type DistArch = 'arm64' | 'x64'
```

Source: [src/dist/manifest.ts:41](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L41)

### `DistArtifactKind`

Type.

What an artifact is: the TUI binary archive, the server binary archive, or
one of the desktop app's packages. Clients skip kinds they do not know.

```ts
type DistArtifactKind =
  | 'tui'
  | 'server'
  | 'desktop-dmg'
  | 'desktop-zip'
  | 'desktop-appimage'
  | 'desktop-deb'
```

Source: [src/dist/manifest.ts:46](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L46)

### `DistOs`

Type.

An operating system the feed ships for.

```ts
type DistOs = 'darwin' | 'linux'
```

Source: [src/dist/manifest.ts:39](https://github.com/Tahul/zidane/blob/main/src/dist/manifest.ts#L39)