IF Commons GitHub

physical/bundle

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-evidence-capture-seal FR-001, 0004-evidence-capture-seal FR-002, 0004-evidence-capture-seal FR-003, 0004-evidence-capture-seal FR-004, 0004-evidence-capture-seal FR-005, 0004-evidence-capture-seal FR-006

Sealing the journal and exporting a bundle (commons evidence-capture 0004-evidence-capture-seal): a seal is a person's signature, made with their SSH key, over the head of the journal at an instant, kept on the branch with an entry of the journal; a bundle is the journal up to an instant, the states it names by their digests, the evidence documents, a manifest and the signature over it, in the folder grc verifies offline. The collector never signs: both are made by a person, on demand, with a key whose passphrase only ssh-keygen sees.

import { sealPayload } from "./bundle.ts";
sealPayload({ fleet: "fcr", branch: "evidence", seq: 3, head: "ab".repeat(32), at: "2026-12-01T10:00:00Z" }).includes("opsfolio-seal/1"); // true

Source: commons/evidence-capture/src/physical/bundle.ts

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

physical.sealPayloadfunctionno test imports it
function sealPayload(s: { readonly fleet: string; readonly branch: string; readonly seq: number; readonly head: string; readonly at: string; }): string

The payload a seal signs: the fleet, the branch and the position and digest of the head of the journal, and when.

physical.SEAL_PAYLOAD_TYPEconstno test imports it
const SEAL_PAYLOAD_TYPE: "application/vnd.opsfolio.seal+json"

The payload type of a seal.

physical.TrustedSignertypeno test imports it
type TrustedSigner = { readonly name: string; readonly role: string; readonly key: string };

A signer a seal or a bundle is verified with: its name, its role and its public key line.

physical.sealPathconstno test imports it
const sealPath: (seq: number) => string

The path of a seal on the branch, by the position of the head it covers.

physical.sealJournalfunctionno test imports it
function sealJournal(store: GitRefStore, o: { readonly fleet: string; readonly key: SignKey; readonly now: string; }): Promise<Result<{ readonly seq: number; readonly head: string; readonly commit: string | undefined; }, string>>

Seals the journal: signs its head with the key and keeps the envelope and an entry seal on the branch, in one commit made at the instant.

physical.SealStatustypeno test imports it
type SealStatus = { readonly seals: readonly { readonly seq: number; readonly ok: boolean; readonly detail: string }[]; readonly lastSealedSeq: number | undefined; readonly unsealed: number };

What the seals of a journal say: each seal that verifies, each that does not and why, and how many entries came after the last good seal.

physical.sealStatusfunctionno test imports it
function sealStatus(store: GitRefStore, trusted: readonly TrustedSigner[]): Promise<Result<SealStatus, string>>

Verifies the seals of the branch with the signers trusted: the signature, and that the head it signed is the entry of the journal at that position.

physical.ExportOptionstypeno test imports it
type ExportOptions = { readonly fleet: string; readonly out: string; readonly until: string; readonly now: string; readonly key?: SignKey; readonly signers: readonly TrustedSigner[] };

What an export is given.

physical.Exportedtypeno test imports it
type Exported = { readonly dir: string; readonly items: number; readonly entries: number; readonly head: string; readonly signed: boolean };

What an export made.

physical.exportBundlefunctionno test imports it
function exportBundle(store: GitRefStore, o: ExportOptions): Promise<Result<Exported, string>>

Exports the journal up to an instant as a bundle in a folder that does not exist yet: the entries of the journal in order (the chain from the first, so that it verifies on its own), the states the entries name as items by their digests, the evidence documents, the manifest, the signers it was made with, and, where a key is given, the signature of the manifest by that key.

physical.bundlePolicyfunctionno test imports it
function bundlePolicy(roles: readonly string[], retention?: string): Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}

The policy a bundle is verified with: signers of the roles given may attest, with a key in a file, and evidence is kept as long as the verifier says.

physical.Verifiedtypeno test imports it
type Verified = { readonly report: BundleReport; readonly ok: boolean; readonly trustedOwn: boolean };

What verifying a bundle came to: the report of grc, whether it has no finding, and whose keys were trusted.

physical.verifyBundleDirfunctionno test imports it
function verifyBundleDir(dir: string, signers: readonly TrustedSigner[] | undefined, at: string): Promise<Result<Verified, string>>

Verifies a bundle in a folder offline: every item against the manifest, the chain of the journal against the head the manifest names, and the signature of the manifest with the signers given (or, where none are given, the bundle's own signers.json, which is said: a bundle can vouch only for what it holds). Nothing is written and no network is used.

sealPayloadfunctionno test imports it
function sealPayload(s: { readonly fleet: string; readonly branch: string; readonly seq: number; readonly head: string; readonly at: string; }): string

The payload a seal signs: the fleet, the branch and the position and digest of the head of the journal, and when.

SEAL_PAYLOAD_TYPEconstno test imports it
const SEAL_PAYLOAD_TYPE: "application/vnd.opsfolio.seal+json"

The payload type of a seal.

TrustedSignertype
type TrustedSigner = { readonly name: string; readonly role: string; readonly key: string };

A signer a seal or a bundle is verified with: its name, its role and its public key line.

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

sealPathconstno test imports it
const sealPath: (seq: number) => string

The path of a seal on the branch, by the position of the head it covers.

sealJournalfunction
function sealJournal(store: GitRefStore, o: { readonly fleet: string; readonly key: SignKey; readonly now: string; }): Promise<Result<{ readonly seq: number; readonly head: string; readonly commit: string | undefined; }, string>>

Seals the journal: signs its head with the key and keeps the envelope and an entry seal on the branch, in one commit made at the instant.

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

SealStatustypeno test imports it
type SealStatus = { readonly seals: readonly { readonly seq: number; readonly ok: boolean; readonly detail: string }[]; readonly lastSealedSeq: number | undefined; readonly unsealed: number };

What the seals of a journal say: each seal that verifies, each that does not and why, and how many entries came after the last good seal.

sealStatusfunction
function sealStatus(store: GitRefStore, trusted: readonly TrustedSigner[]): Promise<Result<SealStatus, string>>

Verifies the seals of the branch with the signers trusted: the signature, and that the head it signed is the entry of the journal at that position.

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

ExportOptionstypeno test imports it
type ExportOptions = { readonly fleet: string; readonly out: string; readonly until: string; readonly now: string; readonly key?: SignKey; readonly signers: readonly TrustedSigner[] };

What an export is given.

Exportedtypeno test imports it
type Exported = { readonly dir: string; readonly items: number; readonly entries: number; readonly head: string; readonly signed: boolean };

What an export made.

exportBundlefunction
function exportBundle(store: GitRefStore, o: ExportOptions): Promise<Result<Exported, string>>

Exports the journal up to an instant as a bundle in a folder that does not exist yet: the entries of the journal in order (the chain from the first, so that it verifies on its own), the states the entries name as items by their digests, the evidence documents, the manifest, the signers it was made with, and, where a key is given, the signature of the manifest by that key.

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

bundlePolicyfunctionno test imports it
function bundlePolicy(roles: readonly string[], retention?: string): Document & { readonly counts: readonly ObjectOf<{ kinds: Decoder<readonly string[]>; maxAge: Decoder<string>; }, { producers: Decoder<readonly string[]>; }>[]; readonly retention: string; readonly attesters: readonly string[]; readonly custody: "file" | "hardware" | "managed" | "none"; } & {}

The policy a bundle is verified with: signers of the roles given may attest, with a key in a file, and evidence is kept as long as the verifier says.

Verifiedtypeno test imports it
type Verified = { readonly report: BundleReport; readonly ok: boolean; readonly trustedOwn: boolean };

What verifying a bundle came to: the report of grc, whether it has no finding, and whose keys were trusted.

verifyBundleDirfunction
function verifyBundleDir(dir: string, signers: readonly TrustedSigner[] | undefined, at: string): Promise<Result<Verified, string>>

Verifies a bundle in a folder offline: every item against the manifest, the chain of the journal against the head the manifest names, and the signature of the manifest with the signers given (or, where none are given, the bundle's own signers.json, which is said: a bundle can vouch only for what it holds). Nothing is written and no network is used.

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

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