Class: Clickwrap::Integrity::Anchor

Inherits:
Object
  • Object
show all
Defined in:
lib/clickwrap/integrity/anchor.rb

Overview

The adapter contract for publishing exact event-chain snapshots somewhere outside the primary database, plus a reference base implementation that publishes nowhere and says so. Configuration itself defaults to nil.

config.anchor_event_history_with = MyIndependentAnchor.new

WHY THIS SEAM EXISTS. A chain makes a rewrite of history detectable for as long as a checkpoint remains trustworthy, and the ordinary checkpoint lives in the same database as the events. Whoever can rewrite one can usually rewrite the other. Publishing an exact snapshot somewhere the application cannot quietly edit — an append-only object store with a retention lock, a separate account, a notary, a transparency log, a printout in a safe — narrows that gap.

WHAT AN ANCHOR CLAIMS. Exactly what the place it published to can support, and not one word more. Clickwrap records the reference and the receipt an adapter returns; it never upgrades either into a guarantee the anchoring service did not make. An anchor does not make evidence impossible to alter, does not establish identity, and does not supply time — a storage service writing "received at 14:02" is telling you when it received bytes, which is a different claim from a timestamp authority's, and different again from proof that something happened at 14:02.

WRITING ONE. Implement #publish(chain_snapshot) and #verify(publication, chain_snapshot), and report honestly from #capabilities. Subclassing this class is the easy path: Configuration#anchor_event_history_with= checks that the object responds to #anchor, and the base class provides that name as the entry point to your #publish. An adapter written from scratch must respond to #anchor as well.

Everything here is optional. Configuration defaults to nil; assigning an instance of this base class is an explicit unavailable/no-publication adapter for testing or capability reporting.

Defined Under Namespace

Classes: Publication, Verification

Instance Method Summary collapse

Instance Method Details

#anchor(chain_head) ⇒ Object

The name Configuration#anchor_event_history_with= checks for. Kept as a thin alias so the contract can read as publish/verify while the configuration keeps the verb it already documents.



94
 
# File 'lib/clickwrap/integrity/anchor.rb', line 94

def anchor(chain_head) = publish(chain_head)

#available? ⇒ Boolean

Returns:

  • (Boolean) 


123
 
# File 'lib/clickwrap/integrity/anchor.rb', line 123

def available? = false

#capabilities ⇒ Object

What this adapter actually supplies, in the words of the thing that supplies it. clickwrap:doctor and the receipt's integrity fragment read this rather than assuming a configured adapter means a stronger claim.



112
113
114
115
116
117
118
119
120
121
 
# File 'lib/clickwrap/integrity/anchor.rb', line 112

def capabilities
  {
    "name" => provider_name,
    "available" => available?,
    "publishes_outside_primary_database" => false,
    "independently_verifiable" => false,
    "supplies" => "Nothing. This is the default placeholder that reports the absence of an " \
                  "anchor for explicit adapter-contract tests. Configuration normally remains nil."
  }
end

#provider_name ⇒ Object 



125
 
# File 'lib/clickwrap/integrity/anchor.rb', line 125

def provider_name = "no_anchor"

#publish(_chain_head) ⇒ Object

Publishes this exact chain snapshot outside the primary database. Called after the events it covers have committed, never inside their transaction: an anchoring service cannot join a database transaction, and pretending otherwise is how a network timeout becomes a rolled-back capture.



82
83
84
85
86
87
88
89
 
# File 'lib/clickwrap/integrity/anchor.rb', line 82

def publish(_chain_head)
  Publication.new(
    anchored: false,
    provider_name: provider_name,
    detail: "This anchor adapter publishes nowhere, so this chain snapshot was not published outside " \
            "the primary database."
  )
end

#to_s ⇒ Object 



127
 
# File 'lib/clickwrap/integrity/anchor.rb', line 127

def to_s = "#{self.class.name} (#{provider_name})"

#verify(_publication, _chain_head) ⇒ Object

Re-reads what was published and compares it with the exact snapshot passed for this event. This is the half that does the work: publishing bytes nobody ever checks establishes nothing.



99
100
101
102
103
104
105
106
107
 
# File 'lib/clickwrap/integrity/anchor.rb', line 99

def verify(_publication, _chain_head)
  Verification.new(
    checked: false,
    verified: false,
    provider_name: provider_name,
    detail: "This anchor adapter publishes nowhere, so there is no outside publication to compare " \
            "with this chain snapshot."
  )
end