Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,7 @@ Pages avoid full-log/category/sales-history copies, but sparse filters can scan
the remaining catalogue. Existing unpaged reads remain unbounded; in-memory,
single-writer and witnessing limitations remain unchanged. See
`docs/marketplace-browse.md` for query syntax and compatibility limits.

### Signed reference discovery

`GET /api/v1/claims/{id}/references` exposes accepted structural edges in append order, with bounded pages and complete signed fields. Decimal-string nanoseconds preserve independent signature verification; no narrative is included and no relationship becomes a truth score. `TestReferenceDiscoveryPages`, `TestReferenceDiscoveryEmptyAndAppend`, `TestReferenceDiscoveryBounds`, and `TestReferenceDiscoveryValidation` bind filtering, cursor stability, signature/precision preservation, privacy, and invalid-input behavior. This additive read does not change the techtree's single-writer stand-in status.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,3 +165,5 @@ independent witnessing.
AGPL-3.0-or-later.

*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org*

Signed claim-reference discovery: see [reference discovery](docs/reference-discovery.md) for the public paginated API and offline verification fields.
18 changes: 18 additions & 0 deletions docs/reference-discovery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Inspecting signed claim references

`GET /api/v1/claims/{id}/references` is public and additive. Existing claim summaries and reference creation are unchanged.

Query parameters:

- `direction` is required: `inbound` matches the reference's `to`; `outbound` matches its `from`.
- `kind` optionally filters `builds_on`, `cites`, `contests`, `reproduces`, or `refutes`.
- `limit` defaults to 50 and must be an integer from 1 through 100.
- `cursor` is an unsigned decimal append-log position. Omit it or use an empty string to start at zero. Positions count claims as well as references. A cursor beyond the current log is invalid.

Recognized query parameters must not be repeated. Invalid IDs, directions, kinds, limits, or cursors return HTTP 400; a well-formed ID for an unknown claim returns 404. Unknown query parameters are ignored.

The response is `{"references": [...], "next_cursor": "..."}`. An empty result uses `[]`; `next_cursor` is empty when this traversal has no more matching edges. Otherwise, pass it unchanged with the same claim, direction, and kind. Results follow accepted append order, with no ranking. Newly appended edges cannot shift existing cursor positions and may appear in subsequent pages; this is a live traversal, not a frozen snapshot. After exhaustion, start a new traversal to discover later appends.

Each reference contains `reference_id`, `platform`, `asserter`, `kind`, `from`, `to`, `nonce`, `asserted_at_ns`, and `signature`. Binary fields use hexadecimal. `asserted_at_ns` is a **decimal string**, preserving exact signed nanoseconds in JavaScript and other clients whose JSON numbers are floating point. Reconstruct a `techtree.Reference` with those signed fields to call `Verify()` and compare `ID()` with `reference_id`.

No claim narrative or Locker contents are exported. A signature establishes authorship and unchanged bytes, not truth, privileged status, or witness independence. The techtree remains its documented single-writer stand-in. Pages allocate copies for at most `limit` references; discovery scans append history without cloning the complete log. Sparse matches can still require a linear scan.
121 changes: 121 additions & 0 deletions internal/consumerapi/references.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
package consumerapi

import (
"encoding/hex"
"errors"
"net/http"
"net/url"
"strconv"

"github.com/NTARI-RAND/Cloudy/internal/techtree"
)

// referenceExport contains structural fields only. Decimal-string nanoseconds
// preserve every signed timestamp bit in clients whose JSON numbers are doubles.
type referenceExport struct {
ReferenceID string `json:"reference_id"`
Platform string `json:"platform"`
Asserter string `json:"asserter"`
Kind string `json:"kind"`
From string `json:"from"`
To string `json:"to"`
Nonce string `json:"nonce"`
AssertedAtNs string `json:"asserted_at_ns"`
Signature string `json:"signature"`
}

type referenceQuery struct {
inbound bool
kind techtree.RefKind
cursor, limit int
}

func parseReferenceQuery(q url.Values) (referenceQuery, error) {
result := referenceQuery{limit: 50}
for _, name := range []string{"direction", "kind", "cursor", "limit"} {
if len(q[name]) > 1 {
return result, errors.New("reference query parameters must not be repeated")
}
}
switch q.Get("direction") {
case "inbound":
result.inbound = true
case "outbound":
default:
return result, errors.New("direction must be inbound or outbound")
}
result.kind = techtree.RefKind(q.Get("kind"))
if _, present := q["kind"]; present && result.kind == "" {
return result, errors.New("kind must name an existing reference kind")
}
var err error
result.cursor, err = parsePageNumber(q.Get("cursor"), 0)
if err != nil {
return result, err
}
if _, present := q["limit"]; present {
result.limit, err = parsePageNumber(q.Get("limit"), -1)
}
return result, err
}

func parsePageNumber(raw string, fallback int) (int, error) {
if raw == "" {
return fallback, nil
}
for _, c := range raw {
if c < '0' || c > '9' {
return 0, errors.New("cursor and limit must be unsigned decimal integers")
}
}
n, err := strconv.Atoi(raw)
if err != nil {
return 0, errors.New("cursor or limit exceeds integer range")
}
return n, nil
}

func (s *Server) handleGetReferences(w http.ResponseWriter, r *http.Request) {
raw, ok := decodeHex32(r.PathValue("id"))
if !ok {
writeErr(w, http.StatusBadRequest, "claim id must be 32-byte hex")
return
}
query, err := parseReferenceQuery(r.URL.Query())
if err != nil {
writeErr(w, http.StatusBadRequest, err.Error())
return
}
s.mu.Lock()
refs, next, err := s.tree.References(techtree.ClaimID(raw), query.inbound, query.kind, query.cursor, query.limit)
s.mu.Unlock()
if err != nil {
status := http.StatusBadRequest
if errors.Is(err, techtree.ErrUnknownClaim) {
status = http.StatusNotFound
}
writeErr(w, status, err.Error())
return
}
out := make([]referenceExport, 0, len(refs))
for _, ref := range refs {
out = append(out, exportReference(ref))
}
cursor := ""
if next >= 0 {
cursor = strconv.Itoa(next)
}
writeJSON(w, http.StatusOK, struct {
References []referenceExport `json:"references"`
NextCursor string `json:"next_cursor"`
}{out, cursor})
}

func exportReference(ref techtree.Reference) referenceExport {
id := ref.ID()
return referenceExport{
ReferenceID: hex.EncodeToString(id[:]), Platform: ref.Platform, Asserter: hx(ref.Asserter), Kind: string(ref.Kind),
From: hex.EncodeToString(ref.From[:]), To: hex.EncodeToString(ref.To[:]), Nonce: hex.EncodeToString(ref.Nonce[:]),
AssertedAtNs: strconv.FormatInt(ref.AssertedAt.UnixNano(), 10), Signature: hx(ref.Signature),
}
}
155 changes: 155 additions & 0 deletions internal/consumerapi/references_helpers_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
package consumerapi

import (
"encoding/hex"
"encoding/json"
"net/http"
"strconv"
"strings"
"testing"
"time"

"github.com/NTARI-RAND/Cloudy/internal/techtree"
)

const claimsPath = "/api/v1/claims/"
const inboundPath = "/references?direction=inbound"

type edgeWire struct {
ReferenceID string `json:"reference_id"`
Platform string `json:"platform"`
Asserter string `json:"asserter"`
Kind string `json:"kind"`
From string `json:"from"`
To string `json:"to"`
Nonce string `json:"nonce"`
AssertedAtNs string `json:"asserted_at_ns"`
Signature string `json:"signature"`
}

type edgeResponse struct {
References []edgeWire `json:"references"`
NextCursor string `json:"next_cursor"`
}

type edgeFixture struct {
h http.Handler
claim, from, to string
incoming, outgoing []string
}

func referenceFixture(t *testing.T) edgeFixture {
t.Helper()
h := newTestServer(t)
pub, priv := key(42)
registerMember(t, h, pub, priv)
ids := make([]string, 3)
for i := range ids {
ids[i] = anchorClaim(t, h, pub, priv, techtree.KindFact, "private inputs", "private method", "private result")
}
f := edgeFixture{h: h, claim: ids[0], from: ids[1], to: ids[2]}
for _, kind := range []techtree.RefKind{techtree.RefCites, techtree.RefBuildsOn, techtree.RefReproduces, techtree.RefRefutes, techtree.RefContests} {
f.incoming = append(f.incoming, postEdge(t, h, ids[1], ids[0], kind))
f.outgoing = append(f.outgoing, postEdge(t, h, ids[0], ids[2], kind))
postEdge(t, h, ids[1], ids[2], kind)
}
return f
}

func postEdge(t *testing.T, h http.Handler, from, to string, kind techtree.RefKind) string {
t.Helper()
pub, priv := key(42)
ref, err := techtree.NewReference(platform, pub, kind, decodeClaimID(t, from), decodeClaimID(t, to), time.Unix(1700000000, 123456789).UTC())
if err != nil {
t.Fatal(err)
}
if err = ref.Sign(priv); err != nil {
t.Fatal(err)
}
rec, out := do(t, h, "POST", "/api/v1/references", referenceDTO{Platform: ref.Platform, Asserter: hex.EncodeToString(ref.Asserter), Kind: string(kind), From: from, To: to, Nonce: hex.EncodeToString(ref.Nonce[:]), AssertedAtNs: ref.AssertedAt.UnixNano(), Signature: hex.EncodeToString(ref.Signature)})
if rec.Code != http.StatusCreated {
t.Fatalf("post edge: %d %s", rec.Code, rec.Body.String())
}
return out["reference_id"].(string)
}

func readEdges(t *testing.T, h http.Handler, path string) edgeResponse {
t.Helper()
rec, _ := do(t, h, "GET", path, nil)
if rec.Code != http.StatusOK {
t.Fatalf("get edges: %d %s", rec.Code, rec.Body.String())
}
var page edgeResponse
if err := json.Unmarshal(rec.Body.Bytes(), &page); err != nil {
t.Fatal(err)
}
if page.References == nil {
t.Fatal("references must be an array")
}
if strings.Contains(rec.Body.String(), "private inputs") || strings.Contains(rec.Body.String(), "narrative") {
t.Fatal("member-local narrative leaked")
}
for _, wire := range page.References {
verifyExportedEdge(t, wire)
}
return page
}

func verifyExportedEdge(t *testing.T, wire edgeWire) {
t.Helper()

// Decode independently from the production export; verification catches missing signed fields.
pub, err := hex.DecodeString(wire.Asserter)
if err != nil {
t.Fatal(err)
}
sig, err := hex.DecodeString(wire.Signature)
if err != nil {
t.Fatal(err)
}
nonce, err := hex.DecodeString(wire.Nonce)
if err != nil || len(nonce) != 32 {
t.Fatal("bad nonce")
}
ns, err := strconv.ParseInt(wire.AssertedAtNs, 10, 64)
if err != nil {
t.Fatal(err)
}
if ns != 1700000000123456789 {
t.Fatalf("timestamp lost precision: %s", wire.AssertedAtNs)
}
ref := techtree.Reference{Platform: wire.Platform, Asserter: pub, Kind: techtree.RefKind(wire.Kind), From: decodeClaimID(t, wire.From), To: decodeClaimID(t, wire.To), AssertedAt: time.Unix(0, ns), Signature: sig}
copy(ref.Nonce[:], nonce)
id := ref.ID()
if !ref.Verify() || hex.EncodeToString(id[:]) != wire.ReferenceID {
t.Fatal("exported reference cannot be verified")
}
ref.Kind = techtree.RefKind("tampered")
if ref.Verify() {
t.Fatal("tampered artifact verifies")
}
}

func collectEdges(t *testing.T, f edgeFixture, direction string) []string {
t.Helper()
base := claimsPath + f.claim + "/references?direction=" + direction + "&limit=2"
var got []string
cursor := ""
for requests := 0; requests < 5; requests++ {
page := readEdges(t, f.h, base+"&cursor="+cursor)
if len(page.References) > 2 {
t.Fatal("page exceeds limit")
}
for _, r := range page.References {
got = append(got, r.ReferenceID)
}
if page.NextCursor == "" {
break
}
if page.NextCursor == cursor {
t.Fatal("cursor did not advance")
}
cursor = page.NextCursor
}
return got
}
Loading