diff --git a/CONFORMANCE.md b/CONFORMANCE.md index fd492ea..bee30ee 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -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. diff --git a/README.md b/README.md index a0358b1..691acf6 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/reference-discovery.md b/docs/reference-discovery.md new file mode 100644 index 0000000..1cd346f --- /dev/null +++ b/docs/reference-discovery.md @@ -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. diff --git a/internal/consumerapi/references.go b/internal/consumerapi/references.go new file mode 100644 index 0000000..e79e247 --- /dev/null +++ b/internal/consumerapi/references.go @@ -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), + } +} diff --git a/internal/consumerapi/references_helpers_test.go b/internal/consumerapi/references_helpers_test.go new file mode 100644 index 0000000..de49b9a --- /dev/null +++ b/internal/consumerapi/references_helpers_test.go @@ -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 +} diff --git a/internal/consumerapi/references_test.go b/internal/consumerapi/references_test.go new file mode 100644 index 0000000..98ef9d8 --- /dev/null +++ b/internal/consumerapi/references_test.go @@ -0,0 +1,95 @@ +package consumerapi + +import ( + "fmt" + "github.com/NTARI-RAND/Cloudy/internal/techtree" + "strings" + "testing" +) + +// Catches wrong direction/kind filters, skipped edges, repeated edges, and broken signed exports. +func TestReferenceDiscoveryPages(t *testing.T) { + f := referenceFixture(t) + for _, direction := range []string{"inbound", "outbound"} { + t.Run(direction, func(t *testing.T) { + want := f.incoming + if direction == "outbound" { + want = f.outgoing + } + got := collectEdges(t, f, direction) + if fmt.Sprint(got) != fmt.Sprint(want) { + t.Fatalf("edge set/order: %v, want %v", got, want) + } + }) + } + for i, kind := range []string{"cites", "builds_on", "reproduces", "refutes", "contests"} { + page := readEdges(t, f.h, claimsPath+f.claim+"/references?direction=inbound&kind="+kind) + if len(page.References) != 1 || page.References[0].ReferenceID != f.incoming[i] || page.NextCursor != "" { + t.Fatalf("kind %s filter incorrect", kind) + } + } +} + +func TestReferenceDiscoveryValidation(t *testing.T) { + f := referenceFixture(t) + base := claimsPath + f.claim + "/references" + for _, query := range []string{"", "?direction=both", "?direction=inbound&kind=unknown", "?direction=inbound&kind=", "?direction=inbound&cursor=-1", "?direction=inbound&cursor=abc", "?direction=inbound&cursor=1.5", "?direction=inbound&cursor=999999999999999999999999", "?direction=inbound&cursor=9999", "?direction=inbound&limit=0", "?direction=inbound&limit=101", "?direction=inbound&limit=no", "?direction=inbound&limit=", "?direction=inbound&direction=outbound"} { + rec, _ := do(t, f.h, "GET", base+query, nil) + if rec.Code != 400 { + t.Errorf("%s: got %d, want 400", query, rec.Code) + } + } + for _, tc := range []struct { + id string + status int + }{{"bad", 400}, {strings.Repeat("00", 32), 404}} { + rec, _ := do(t, f.h, "GET", claimsPath+tc.id+inboundPath, nil) + if rec.Code != tc.status { + t.Errorf("id %s: got %d, want %d", tc.id, rec.Code, tc.status) + } + } +} + +func TestReferenceDiscoveryEmptyAndAppend(t *testing.T) { + f := referenceFixture(t) + empty := readEdges(t, f.h, claimsPath+f.from+inboundPath) + if len(empty.References) != 0 || empty.NextCursor != "" { + t.Fatal("empty result incorrect") + } + base := claimsPath + f.claim + "/references?direction=inbound&limit=1" + first := readEdges(t, f.h, base) + added := postEdge(t, f.h, f.from, f.claim, techtree.RefCites) + want := append(append([]string{}, f.incoming[1:]...), added) + var got []string + cursor := first.NextCursor + for requests := 0; requests < 10; requests++ { + page := readEdges(t, f.h, base+"&cursor="+cursor) + for _, r := range page.References { + got = append(got, r.ReferenceID) + } + if page.NextCursor == "" { + break + } + cursor = page.NextCursor + } + if fmt.Sprint(got) != fmt.Sprint(want) { + t.Fatalf("append shifted cursor: got %v want %v", got, want) + } +} + +func TestReferenceDiscoveryBounds(t *testing.T) { + f := referenceFixture(t) + for i := 0; i < 100; i++ { + postEdge(t, f.h, f.from, f.claim, techtree.RefCites) + } + base := claimsPath + f.claim + inboundPath + for _, tc := range []struct { + query string + count int + }{{"", 50}, {"&limit=100", 100}} { + page := readEdges(t, f.h, base+tc.query) + if len(page.References) != tc.count || page.NextCursor == "" { + t.Fatalf("page bounds: got %d want %d", len(page.References), tc.count) + } + } +} diff --git a/internal/consumerapi/server.go b/internal/consumerapi/server.go index 8e2cc97..74f57a2 100644 --- a/internal/consumerapi/server.go +++ b/internal/consumerapi/server.go @@ -335,6 +335,7 @@ func (s *Server) Handler() http.Handler { mux.HandleFunc("GET /api/v1/claims/{id}", s.handleGetClaim) mux.HandleFunc("GET /api/v1/claims/{id}/export", s.handleExportClaim) mux.HandleFunc("POST /api/v1/references", s.handleAddReference) + mux.HandleFunc("GET /api/v1/claims/{id}/references", s.handleGetReferences) mux.HandleFunc("GET /api/v1/market/categories", s.handleCategories) mux.HandleFunc("POST /api/v1/market/listings", s.handleCreateListing) mux.HandleFunc("GET /api/v1/market/listings", s.handleBrowseListings) diff --git a/internal/techtree/references.go b/internal/techtree/references.go new file mode 100644 index 0000000..f5a7ab2 --- /dev/null +++ b/internal/techtree/references.go @@ -0,0 +1,44 @@ +package techtree + +import "errors" + +// ErrReferencePage reports an invalid append cursor, kind, or page size. +var ErrReferencePage = errors.New("techtree: invalid reference cursor, kind, or limit") + +// References returns matching accepted edges in append order, with defensive +// copies. Cursor is an absolute log position (claims occupy positions too). +// Next is the first unreturned match's position, or -1 when exhausted. Appends +// cannot shift positions; the caller serializes tree access as for Log. +func (t *Tree) References(id ClaimID, inbound bool, kind RefKind, cursor, limit int) (refs []Reference, next int, err error) { + if cursor < 0 || cursor > len(t.log) || limit < 1 || limit > 100 { + return nil, -1, ErrReferencePage + } + if kind != "" && !validRefKind(kind) { + return nil, -1, ErrReferencePage + } + if _, ok := t.claims[id]; !ok { + return nil, -1, ErrUnknownClaim + } + refs = make([]Reference, 0, limit) + for pos := cursor; pos < len(t.log); pos++ { + ref := t.log[pos].Reference + if !matchesReference(ref, id, inbound, kind) { + continue + } + if len(refs) == limit { + return refs, pos, nil + } + refs = append(refs, cloneRef(*ref)) + } + return refs, -1, nil +} + +func matchesReference(ref *Reference, id ClaimID, inbound bool, kind RefKind) bool { + if ref == nil || (kind != "" && ref.Kind != kind) { + return false + } + if inbound { + return ref.To == id + } + return ref.From == id +}