Skip to main content

Module licence

clawft_kernel

Module licence 

Source
Expand description

Seed licence proxy, member side (ADR-106 phase 1a).

Types, stores and policy for the mesh checkout of Cognitum cogs, as pure in-process code (no network, no transport):

Every signature is Ed25519, checked with verify_strict, over domain tag || "\n" || canonical JSON payload. The signer keys are the existing crate::workload_pkg::TrustAnchors operator keys; the grant key is the one the binding names.

Structs§

AdmissionPosture
What the node’s mesh admission looks like when a binding arrives.
Approval
An operator’s approval to run these binaries of one cog version.
ApprovalRow
One held approval.
ApprovalStore
Persisted operator hash approvals of one node.
BindingRecord
The operator-signed Seed to mesh binding.
ChainLicenceSink
Appends every LicenceEvent to the chain.
CheckoutGrant
The signed grant payload.
CheckoutGrantStore
Persisted binding and grant state of one node.
CheckoutRelay
The relay.
CheckoutWire
A request for a cog version, as sent to weft-licence and by members to the steward. Every string is a short token; version may be latest.
CtxAdmission
Licensed peers only (ADR-106 phase 1c): verified by admission and of class node. Leaves, legacy and unauthenticated peers get no floods and no sync, whether they are admitted or not.
FloorPreview
The floor now, after a reset, and the grants that would come back.
FloorState
Floor state for one grant key.
GrantArtifact
One checked-out binary.
GrantCursor
Where the grant page stopped: grants are ordered by (seq, cog, version).
GrantRow
One (cog, version) slot of the grant store.
GrantsPage
One page of GET /licence/v1/grants?since=<ctr>.
HttpLicenceTransport
LicenceTransport over HTTP.
LicenceExchange
Receives, applies, forwards and syncs the licence records of one node.
LicenceExchangeConfig
Timing knobs of the exchange.
LicenceExchangeParts
Everything [LicenceExchange::start] needs.
LicenceLinkConfig
Where weft-licence is and how the link is trusted.
LicenceRef
The licence the grant rests on: a hash of the reference, no account label.
LicenceRequest
One request in HTTP shape.
LicenceResponse
What weft-licence answered.
LocalMeshId
Shared, live handle to this node’s mesh id. A change (new nonce or pin) reaches every store holding a clone, which then report orphaned state.
MeshCheckoutPolicy
The checkout-aware redistribution policy.
MeshId
The identity of one mesh: sha256("weft-licence-v1/mesh-id\n" || genesis_pin || mesh_nonce).
NoExtraChecks
The member profile adds nothing.
NoFlood
Floods nothing.
NoopSink
Drops every event.
PeerSnapshot
The service’s peer view.
RecordingSink
Keeps every event (tests, and callers that drain into the chain).
RelayLimits
Limits on what members can cost the steward (ADR-106 section 6): a request budget per member, and a bound on checkouts running at once. Over-limit refusals are not chained, so they cannot grow the chain either.
RenewalConfig
Timing of the pull.
RenewalReport
What one pass did.
Renewer
The steward’s renewal pull.
ReplayGuard
Verifier-side replay memory: nonce to its signed timestamp (ms). Entries older than the window are evicted by timestamp; when the memory is full of live entries a new request is refused, never the whole set forgotten.
RequestAuth
The signature headers of one request.
RevivedGrant
A grant a reset would make valid again.
RunPermit
Evidence for the run, for provenance.
RunRequest
What is about to be installed or run.
ServiceLicenceLinks
The licence exchange’s mesh in service mode.
ServiceLinksCounters
Counters, all monotonic.
SharedTransport
A shared transport, so one link serves every per-call client.
SignedEnvelope
A signed payload as it travels: the exact signed JSON, key and signature (hex). One shape for every record kind; the domain tag keeps kinds apart.
SignedLicenceClient
LicenceClient that signs every request with the steward key.
StewardCheck
Inputs of the steward checks.
StewardLicenceClient
LicenceClient bound to the store’s binding in effect.
StoreRunGate
CognitumRunGate over this node’s stores.
TransportLimits
Timeouts and caps of one link.
VerifiedCheckoutGrant
A grant that passed every check and is valid right now. Only the store makes one; crate::mesh_artifact::ArtifactExchange::grant_checkout takes it.

Enums§

BindState
Whether a binding binds or unbinds.
CheckoutCaller
Who is asking.
CheckoutRefusal
Why a checkout was refused or failed. CheckoutRefusal::code is the stable code a requester sees.
ExchangeError
Why a record was not accepted.
LicenceClientError
Why a licence call failed.
LicenceError
Why a licence record or store operation was refused.
LicenceEvent
Something worth chaining. The daemon maps these to chain events; the stores only report them through a LicenceEventSink.
MeshIdConfigError
Why the configured pin or nonce gives no mesh id.
Outcome
What an accepted record did.
Receipt
What an accepted record did here.
RequestRefused
Why a verifier refused a request. All are refused before any work is done.
RunDenied
Why the gate refused.
RunRefusal
Why the gate refused.
RunVerdict
What the gate decided when it did not refuse.
Spend
Whose budget a record’s signature verify is charged to.
SyncMsg
A message on mesh.cog.sync.

Constants§

APPROVALS_FILE
File name inside the store directory.
APPROVAL_DOMAIN
Domain tag of operator hash approvals.
ARTIFACT_PATH
Path prefix of the artifact endpoint (BLAKE3 hex follows).
BINDING_DOMAIN
Domain tag of binding records.
BOUND_MARKER
The sticky “this node was Seed-bound” marker, beside the store file. It outlives a deleted or replaced store file, so the run gate fails closed instead of treating such a node as never bound.
CHECKOUT_PATH
Path of the checkout endpoint.
CLOCK_FLOOR_SECS
The COG-011 bridge’s clock floor (CLOCK_FLOOR_MS / 1000), unix seconds (2026-05-28 UTC). A clock below it is not set: nothing is signed or issued.
DEFAULT_MAX_ARTIFACT_BYTES
Default largest artifact accepted (the weft-licence default limit).
EVENT_KIND_CHECKOUT_GRANTED
Chain event: a grant was obtained and seeded.
EVENT_KIND_CHECKOUT_LAPSED
Chain event: the Seed withdrew a checkout (released, or no longer licensed).
EVENT_KIND_CHECKOUT_REFUSED
Chain event: a checkout request was refused or failed.
EVENT_KIND_CHECKOUT_RENEWED
Chain event: a renewed grant was installed and flooded.
FAR_FUTURE_CLAMP_SECS
The clock high-water mark grows at most this far past the newest accepted issued_at.
GATE_ACTION
Gate action asked for every checkout request.
GRANTS_FILE
File name inside the store directory.
GRANTS_PATH
Path of the renewal listing (?since=<seq>).
GRANT_DOMAIN
Domain tag of checkout grants.
GRANT_SKEW_SECS
A grant issued more than this far ahead of the local clock is deferred.
LICENCE_EVENT_PREFIX
Chain event kinds are this prefix plus LicenceEvent::name, for example licence.binding_conflict.
LICENCE_TOPICS
The licence control topics carried through the service.
MAX_APPROVALS
Most approvals held.
MAX_ARTIFACT_BYTES
Largest artifact size a grant may list: 1 GiB.
MAX_FLOORS
Most floor entries a store file may hold (one per grant key, in practice one).
MAX_GRANT_SLOTS
Most (cog, version) grant slots held.
MAX_GRANT_TTL_SECS
Longest grant lifetime (expires_at - issued_at): 7 days.
MAX_PAYLOAD_BYTES
Largest signed payload accepted, in bytes.
MAX_REPLY_SENDS
Reply sends in flight at once; past it a reply is dropped and counted (the peer’s next sync asks again).
MAX_REPLY_SENDS_PER_PEER
Reply sends in flight to one peer, inside MAX_REPLY_SENDS.
MAX_STORE_BYTES
Largest persisted store file read back, in bytes.
MAX_SYNC_RETRIES
Unanswered requests re-sent to one peer in a row before giving up until the next periodic or on-connect sync.
MAX_UNIX_TIME
Latest time accepted in any record or floor (2100-01-01), unix seconds.
MESH_ID_DOMAIN
Domain tag of the mesh id hash.
PEER_REFRESH
How often the daemon asks the service who is connected.
RENEW_PATH
Path of the renewal call (signs a new grant for every active checkout).
REQUEST_DOMAIN
Domain tag of steward requests.
REQUEST_WINDOW_MS
Default replay window, each side of the verifier’s clock.
SYNC_MAX_BYTES
Most payload bytes in one sync response.
SYNC_MAX_ENTRIES
Most entries in one sync response.

Traits§

BindingExtraCheck
Where the STEWARD profile (phase 1d) plugs in: the 600 s age window, the live GET /api/v1/identity match, the grant key fingerprint the operator confirmed. Runs after the member checks and before the record is stored.
CognitumRunGate
The gate a workload-host asks before it installs or starts a Cognitum-origin cog.
GrantFlood
Spreads a new grant to the mesh. Phase 1b replaces the implementation with the mesh.cog.grant flood and sync; the relay only calls this.
LicenceClient
What the checkout relay needs from weft-licence.
LicenceEventSink
Receives LicenceEvents. Called after the store’s lock is released, but a sink must still not call back into the store.
LicenceLinks
The mesh a super::LicenceExchange floods and syncs over.
LicenceTransport
One signed round trip to weft-licence.
PeerAdmission
Which peers may sync with this node and be sent its licence floods.
PeerDirectory
Who the machine mesh service says is connected.

Functions§

check_run
Decide req. approvals is None when this node has no approval store (no mesh): every Cognitum run is then refused for no_approval once the grant check passes.
install_grant
Register signed in store and, when accepted, make the bytes of every currently valid grant for the cog version shareable in exchange. This is the member side of a grant arriving (reply, flood or sync).
is_licence_topic
True when msg is on one of LICENCE_TOPICS.
key_id
"ed25519:" plus 16 hex chars of sha256(public key): the grant key id the operator compares at init time.
may_run
May req be installed or run? Needs a valid grant and a covering approval, and the binary’s ArtifactHash must not be revoked.
mesh_id_from_config
Derive the local mesh id. Ok(None) while either value is absent: the licence path then stays inert (the policy equals ManifestPolicy). A malformed value is an error, never a silent None, so the caller can say why checkout stays off.
sha256_hex
sha256 of bytes, lower-case hex.
sign_approval
Sign approval as the operator. The sha256 list is sorted and de-duplicated first so there is one canonical spelling.
sign_binding
Sign record as the operator.
sign_grant
Sign grant with the grant key. grant_key_id, the artifact order and grant_id are filled in so the result is canonical.
sign_request
Sign a request with the steward key. nonce must satisfy valid_nonce.
sign_unbind
Sign the unbind of prev: same Seed and mesh, state: unbound, seq one higher. Everything else, bound_at included, is copied from prev, so two operators unbinding the same record at once produce byte-identical records (Ed25519 is deterministic) instead of an equal-seq conflict. Any node holding an operator key can do this and LicenceExchange::issue_binding it.
signing_string
The bytes the steward key signs.
system_clock
The wall clock.
system_clock_ms
The wall clock in milliseconds.
valid_nonce
A nonce the server accepts: 16 to 64 ASCII alphanumerics.
verify_approval
Verify signed: pinned operator key, strict signature, canonical payload, well-formed fields, and mesh_id equal to local (A2).
verify_approval_signature
Signature and shape only, with no mesh check (store load, and the CLI’s check of an orphaned approval before it re-signs it for the new mesh).
verify_binding_member
The MEMBER verification profile: pinned operator signature, strict signature check, canonical payload, mesh_id equal to local. Members have no Seed link, so there is no age check and no identity match. The stateful rules (seq above the stored one, equal-seq conflicts) are the store’s (super::CheckoutGrantStore::accept_binding).
verify_grant
Verify signed under the bound grant_pubkey and require it is for local. The key comparison is the cheap first check.
verify_request
Verify req against the bound steward. Cheap checks first; the signature last; only a request whose signature verified is charged a nonce.

Type Aliases§

Clock
Source of unix seconds. Injected so tests control the clock.
ClockMs
Source of unix milliseconds. Injected so tests control the clock.
PostureFn
The node’s admission state, read each time a binding arrives.
SignedApproval
A signed Approval.
SignedBinding
A signed BindingRecord.
SignedGrant
A signed CheckoutGrant.