Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Tamper-Evident Hash Chain

Every evidence pack a project produces is linked to its predecessor by hash and signed with a project-scoped Ed25519 key Roboticks holds in AWS KMS. The chain lets an auditor — or future-you, mid-recall — prove that no historical pack has been rewritten after the fact.
The chain is per-project. Each project has its own root pack and its own KMS key; chains do not cross projects.

​
What is in the chain

Every pack’s evidence_pack.manifest.json carries a chain block: 
"chain": {
  "parent_pack_id": "epak_01HF4ZN3…",
  "parent_manifest_sha256": "7a02f1…",
  "self_manifest_sha256": "9d11ba…",
  "chain_index": 47
}
"signature": {
  "algorithm": "ed25519",
  "key_id": "arn:aws:kms:eu-west-1:…:key/abc-…",
  "value": "MEQCIB…"
}
  • parent_manifest_sha256 is the previous pack’s self_manifest_sha256. The root pack carries parent_pack_id: null and parent_manifest_sha256: null.
  • self_manifest_sha256 is the SHA-256 of this manifest with the signature.value field stripped (the signature cannot sign itself).
  • signature.value is Ed25519Sign(privKey, self_manifest_sha256).
A second pack mutated after the fact would have an self_manifest_sha256 that no longer matches the parent_manifest_sha256 carried by every successor. The mismatch is detectable without re-verifying signatures.

​
Primitives

LayerPrimitive
Manifest hashingSHA-256
SigningEd25519
Key storageAWS KMS, project-scoped
Public key distributionPublished at https://api.roboticks.io/api/v1/organizations/{org_slug}/projects/{project_slug}/evidence/public-key and embedded in every pack’s README.md
Ed25519 was chosen for compactness (32-byte public keys, 64-byte signatures) and for the absence of nonce-reuse failure modes that plagued ECDSA deployments. SHA-256 is the obvious choice for ecosystem compatibility (every auditor tool already handles it).

​
Verifying a single pack

rbtk evidence verify epak_01HF5ZN3T0AAQ8X6BB1A8M2P3W
# … or, offline
rbtk evidence verify ./evidence-pack-v1.4.0.zip
The CLI:
  1. Extracts the manifest, strips signature.value, computes the SHA-256.
  2. Confirms it matches self_manifest_sha256.
  3. Fetches the project’s public key (or uses the embedded copy with --offline).
  4. Verifies Ed25519Verify(pubKey, signature.value, self_manifest_sha256).
  5. Re-computes the SHA-256 of every artefact referenced in the manifest and compares to the declared hash.
A passing verification prints: 
✓ Pack epak_01HF5ZN3T0AAQ8X6BB1A8M2P3W verified
  Manifest SHA-256: 9d11ba…
  Signature:        valid (key arn:aws:kms:…)
  Artefacts:        37 / 37 hashes match
  Chain index:      47

​
Verifying the full chain

rbtk evidence verify-chain --project acme-robotics/firmware
The CLI walks the chain from the root pack to the latest, verifying each pack’s signature and each parent_manifest_sha256 link. Any failure stops the walk and prints the failing pack ID and reason. For a project with 200 historical packs, expect a verify-chain to complete in ~30 seconds — most of the time is fetching manifests; signature math is microseconds per pack. For long chains, parallelise the per-pack verification: 
rbtk evidence verify-chain --project acme-robotics/firmware --parallel 8

​
What an auditor can prove

A passing verify-chain proves:
  1. Authenticity — every pack was signed by the project’s KMS key, meaning the Roboticks platform produced it.
  2. Integrity — no artefact referenced in any pack has been altered since signing.
  3. Order — packs are linked in their original generation order; no historical pack was retroactively inserted or removed.
  4. Non-repudiation — the project owner cannot later disavow having signed a pack (the KMS key is logged and rotated audibly).
It does not prove:
  • The underlying tests were correct.
  • The requirements pinned were the right ones.
  • The auditor’s interpretation of the standard was correct.
The hash chain is an integrity primitive. The substance of the evidence is the substance of your engineering. See the Disclaimer.

​
Key rotation

Project KMS keys rotate annually as a matter of policy. Rotation does not invalidate historical signatures — old signatures continue to verify against the historical public key, which is retained in the chain manifest (signature.key_id records the exact key used at signing time). Rotation is transparent to verification: the CLI fetches whichever historical public key the key_id resolves to.

​
What if a pack is missing

A pack can become unreachable — accidentally deleted in S3, evicted by an aggressive retention policy, lost in a region outage. The chain itself is unbroken (the successor still references the missing pack’s hash), but the missing pack cannot be re-verified. rbtk evidence verify-chain flags missing packs as MISSING and continues. The chain remains usable for every pack that is present; the missing one is documented in the verification report as an unrecoverable gap. The recommended remediation is to regenerate the pack from the same release (Releases are pinned commit sets; regenerated packs hash differently, but you can demonstrate the regeneration matches the original by re-running the same tests).

​
Compliance value

Many functional-safety regimes (IEC 61508, IEC 62061, EN ISO 13849, EU MR 2023/1230 technical-file rules) require evidence retention with integrity guarantees. The chain is what lets you tell a regulator, decades later, that the evidence in front of them is the evidence you produced at the time — not a post-hoc reconstruction.
Roboticks is audit-readiness tooling, not a certified toolchain. We assemble the evidence your notified body, certification body, or QA process ingests. We do not replace tool qualification (DO-178C, ISO 26262-8 TCL) and we do not issue conformity assessments. Verify the regulatory interpretations on this page against the standard text and your accredited assessor.