Harbor & content-addressed images

What you’ll get here

how Smart Engines ties running code to exact image digests, publishes a threshold-signed manifest of its own images, protects node software, and keeps its private image registry’s credential split across the validators.

Everything in the other pages assumes the validator, host, and gateway are running the right code. But a container image is usually addressed by a tag (“latest”) that anyone with a push token can silently repoint. A digest is the cryptographic fingerprint of the exact bytes, and it can’t be repointed. Smart Engines publishes the digests of its own images in a manifest the validators sign together, and runs a private registry per cluster, Harbor, for customers’ app images.

🧠 For Normies

A “tag” like latest is a sticky note that anyone can move to point at different code. A “digest” is a fingerprint of the exact bytes — it can’t be faked or moved. This page is about how the platform records the fingerprints of approved code, and how it runs a private app store (Harbor) whose master credential no single party holds.

---

Two problems this solves

Mutable tags

Anyone with a registry write token can repoint a tag at a different image — a compromised CI pipeline could silently roll out a backdoor.

Admin sprawl

If a registry’s master credential sits whole in one place, whoever reaches that place controls the registry.

Smart Engines answers both: the platform-image manifest is a threshold-signed catalog of (imageName → sha256digest) pairs that anyone can check, and the credential that manages Harbor is split into shares held by the validators.

---

Content addressing and the signed manifest

%%{init: {'flowchart':{'htmlLabels':true,'curve':'basis'}}}%%
flowchart TD
    Pub["Validators<br/>threshold-sign (imageName → digest)"] --> Repl["Every validator<br/>re-verifies before storing"]
    Repl --> Pubq["Public discovery API<br/>anyone can fetch and check"]
    Repl --> Adm["Admission check<br/>built, not yet enabled"]

The manifest

The validators sign each entry with their shared threshold key (BLS) over the canonical JSON of { imageName, version, sha256digest, mirrors }. The digest is what counts; mirrors only say where to find the bytes, and bytes pulled from any mirror must hash to the digest.

Every validator re-verifies

Before storing a manifest, each validator checks the signature, and checks that the signing key is the validators’ group key on record. A publisher without enough shares can’t produce a valid signature, and one that brings its own key is rejected.

Anyone can check

The signed manifests are public. With the SDK, client.discovery.platformImages.list() lists them, listEnvelopes() returns each one with its signature and public key so you can verify it yourself, and verify() checks a digest against the manifest. The underlying endpoints are under GET /api/v3/discovery/platform-images.

Admission check

A check that rejects any platform pod whose image doesn’t carry the signed digest is built, not yet enabled. Built, not yet enabled

Customer app pods are pinned by digest when they are deployed. The platform’s own pods are deployed by version tag today, with the signed manifest as the public record of which digest each version should be.

🧠 For Normies

The fingerprint of approved code is signed by the validators together, and every validator re-checks that signature before trusting it. Anyone can download the list and check an image against it. Making the cluster refuse any platform image that isn’t on the list is built and switches on later.

---

Protected node images

Smart Engines node software ships as protected images:

• One encrypted file per service. Each service is bundled into a single file, obfuscated, and encrypted with AES-256-GCM.
• A key in two halves. The decryption key is split in two. One half ships inside the image; the other half comes only with a node’s signed, per-node licence. Without a valid licence the code cannot be decrypted and will not run.
• Checked at runtime. When the node starts, the loader checks the code’s integrity and resists debugging.

---

Harbor — the per-cluster registry & quorum-gated rotation

Harbor is the private container registry on each cluster where customers’ smart-app images are stored, with a separate project per app. A dedicated registry service creates the per-app projects and the credentials that push and pull them.

Rotating credentials by quorum

The credential that registry service uses to manage Harbor’s robot accounts is never stored whole. It is split into Shamir shares, and each validator holds one share, encrypted at rest. To use or rotate it, the registry service has to ask the validators for their shares, and a threshold of them must release theirs. Each validator releases only to the registry service’s own pinned, signed identity, never to a key named in the request. After a rotation, the new secret is split again and dealt back to the validators.

%%{init: {'sequence':{'showSequenceNumbers':false}}}%%
sequenceDiagram
    autonumber
    participant Prov as Registry service
    participant V as Validators
    participant Harbor as Harbor
    Prov->>V: signed request for shares
    V->>V: each checks the pinned identity
    V-->>Prov: a threshold of shares
    Prov->>Prov: rebuild the credential
    Prov->>Harbor: rotate: mint a fresh credential
    Prov->>V: deal new shares to every validator

🧠 For Normies

The registry’s master credential is cut into pieces, and each validator keeps one. Using or changing it needs enough validators to hand over their pieces, and they only hand them to the one service that’s allowed to ask.

---

Platform images vs tenant images

Image	Stored in	Run with
smart-validator, smart-host, smart-gateway	platform registry	version tag; digest published in the threshold-signed manifest
Customer smart-app images	per-cluster Harbor, one project per app	pinned by digest

The platform’s own code and the customers’ code travel different paths, but the trust anchor is the same idea throughout: fingerprinted bytes.

---

Recap

• The authoritative (imageName → digest) mapping for platform images is a threshold-signed manifest, re-verified by every validator and publicly checkable through the SDK’s client.discovery.platformImages.
• Customer app pods are pinned by digest. Platform pods are deployed by version tag, and an admission check that enforces the signed digest is built, not yet enabled.
• Node software ships as protected images that run only with a valid per-node licence.
• Harbor is the per-cluster registry for customer app images. The credential that manages it is split into Shamir shares held by the validators, and a threshold of them must release their shares to use or rotate it.

---

Next steps

Genesis & lifecycleWhere the signing keys come from.

Smart ValidatorThe validators that sign the manifest.

Run a nodeProtected images and how node runners will join.

GlossaryNew term?