IF Commons GitHub

logical/ledger

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-grc-evidence FR-004, 0006-grc-evidence FR-009

The ledger and the manifest of evidence (0006-grc-evidence): an append-only, hash-chained list of what was kept, and the manifest of a bundle that lists its items by digest and the head of the ledger. Pure apart from hashing, which is the same on every runtime.

import { appendEntry, verifyLedger } from "./ledger.ts";
const e1 = await appendEntry(undefined, { at: "2026-01-01T00:00:00Z", type: "observation", subject: "host-1", evidence: "ab".repeat(32) });
(await verifyLedger([e1])).kind; // "ok"

Source: commons/grc/src/logical/ledger.ts

5 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.GENESISconstno test imports it
const GENESIS: string

The previous of the first entry.

logical.appendEntryfunctionno test imports it
function appendEntry(previous: (Document & { readonly seq: number; readonly previous: string; readonly type: string; rea… (503 characters)
function appendEntry(previous: (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}) | undefined, item: { readonly at: string; readonly type: string; readonly subject: string; readonly evidence: string; }): Promise<Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}>

The entry after previous (none for the first): its sequence number, the digest of the one before, and its own digest.

logical.LedgerFaulttypeno test imports it
type LedgerFault = { readonly seq: number; readonly reason: string };

The first entry that was changed, removed, inserted or reordered.

logical.verifyLedgerfunctionno test imports it
function verifyLedger(entries: readonly (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {})[], head?: string | undefined): Promise<Result<void, LedgerFault>>

Verifies the chain; with head (the digest a signature covers) it also finds entries cut off the end.

logical.makeManifestfunctionno test imports it
function makeManifest(items: readonly { readonly digest: string; readonly size: number; readonly mediaType: string; }[], ledgerHead: string, at: string): Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}

The manifest of a bundle: the items in the byte order of their digests, and the head of the ledger.

logical.ManifestFaultstypeno test imports it
type ManifestFaults = { readonly missing: readonly string[]; readonly extra: readonly string[]; readonly different: readonly string[] };

What a set of items has that its manifest does not say.

logical.verifyManifestfunctionno test imports it
function verifyManifest(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}, present: readonly { readonly digest: string; readonly size: number; }[]): ManifestFaults

Each item the manifest lists that is missing, each present that it does not list, and each whose size differs.

logical.manifestBytesfunctionno test imports it
function manifestBytes(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}): Uint8Array<ArrayBufferLike>

The canonical bytes a manifest is signed over.

GENESISconst
const GENESIS: string

The previous of the first entry.

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

appendEntryfunction
function appendEntry(previous: (Document & { readonly seq: number; readonly previous: string; readonly type: string; rea… (503 characters)
function appendEntry(previous: (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}) | undefined, item: { readonly at: string; readonly type: string; readonly subject: string; readonly evidence: string; }): Promise<Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {}>

The entry after previous (none for the first): its sequence number, the digest of the one before, and its own digest.

Imported by 54 tests of the run (54 passed, 0 failed): the library's results

LedgerFaulttypeno test imports it
type LedgerFault = { readonly seq: number; readonly reason: string };

The first entry that was changed, removed, inserted or reordered.

verifyLedgerfunction
function verifyLedger(entries: readonly (Document & { readonly seq: number; readonly previous: string; readonly type: string; readonly subject: string; readonly evidence: string; readonly digest: string; } & {})[], head?: string | undefined): Promise<Result<void, LedgerFault>>

Verifies the chain; with head (the digest a signature covers) it also finds entries cut off the end.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

makeManifestfunction
function makeManifest(items: readonly { readonly digest: string; readonly size: number; readonly mediaType: string; }[], ledgerHead: string, at: string): Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}

The manifest of a bundle: the items in the byte order of their digests, and the head of the ledger.

Imported by 21 tests of the run (21 passed, 0 failed): the library's results

ManifestFaultstypeno test imports it
type ManifestFaults = { readonly missing: readonly string[]; readonly extra: readonly string[]; readonly different: readonly string[] };

What a set of items has that its manifest does not say.

verifyManifestfunction
function verifyManifest(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}, present: readonly { readonly digest: string; readonly size: number; }[]): ManifestFaults

Each item the manifest lists that is missing, each present that it does not list, and each whose size differs.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

manifestBytesfunctionno test imports it
function manifestBytes(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}): Uint8Array<ArrayBufferLike>

The canonical bytes a manifest is signed over.

Titles, headings, exports, tables, columns and requirements. Esc closes.