feat(dir): add ownership claim referrer, search, and CLI (v1) by vivekkrishna · Pull Request #1478 · agntcy/dir

vivekkrishna · 2026-05-09T12:27:00Z

Summary

Implements SPIFFE-based record ownership using the existing `api/sign/v1/Signature` referrer type — as requested in the review: "make it part of the standard Signature field instead of adding new claims object."

Ownership claims are now pushed as `SignatureReferrerType` referrers with `content_type = "agntcy.dir.ownership.v1"` and `annotations["owner_id"] = `. No new proto message is needed.

Design

Field	Value
Referrer type	`agntcy.dir.sign.v1.Signature` (existing)
`content_type`	`agntcy.dir.ownership.v1`
`annotations["owner_id"]`	SPIFFE ID of the claiming principal
`signed_at`	RFC3339 timestamp
`signature`	Base64 ECDSA/RSA sig over SHA-256(owner_id + ":" + signed_at)
`certificate`	Base64 DER-encoded SPIFFE SVID X.509 certificate

Unsigned claims (no `--key`/`--cert`) are accepted in dev environments; the reconciler logs a warning and indexes them without verification.

Changes

API

`api/core/v1/referrer_types.go`: `OwnershipContentType = "agntcy.dir.ownership.v1"` constant
`api/ownership/v1/sign.go`: `NewClaim`, `SignClaim`, `VerifyClaim`, `IsSigned`, `IsOwnershipClaim`, `GetOwnerID` — all operating on `*signv1.Signature`
Removed: `proto/agntcy/dir/ownership/v1/claim.proto` + generated files (no new proto needed)

Search

`proto/agntcy/dir/search/v1/record_query.proto`: `RECORD_QUERY_TYPE_OWNER = 20`
`server/types/search.go`: `Owners []string` filter + `WithOwners()`
`server/database/gorm/record.go`: owner JOIN filter
`server/database/utils/utils.go`: `RECORD_QUERY_TYPE_OWNER` → `WithOwners()`

Database

`server/database/gorm/owners.go`: `Owner` model (`record_cid`, `owner_id`, `claimed_at`)
`server/database/gorm/migration.go`: `Owner{}` in `AutoMigrate` list
`server/types/database.go`: `OwnershipDatabaseAPI` interface (`AddOwner`, `RemoveOwners`)

Ingestor

`server/ingest/ingest.go`: eagerly indexes ownership claims on push so search is immediate without waiting for the reconciler

Reconciler

`reconciler/tasks/ownership/task.go`: walks `SignatureReferrerType` referrers, filters by `IsOwnershipClaim`, verifies SPIFFE signatures, syncs `owners` table
`reconciler/config/config.go`: `Ownership` config field
`reconciler/service/service.go`: ownership task registration

CLI

`cli/cmd/ownership/ownership.go`: `dirctl ownership claim [--key --cert ]`

Test plan

All unit tests pass (`go test ./...` in api, server, reconciler, cli modules)
Lint clean (golangci-lint)
7 ownership search e2e tests pass (exact match, wildcards, combined filter, negative cases)
7 ownership signing e2e tests pass (signed claim indexed, identity mismatch rejected, idempotent re-push)

Generated with Claude Code

codecov · 2026-05-09T12:44:51Z

Codecov Report

❌ Patch coverage is 55.10836% with 145 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
api/ownership/v1/sign.go	49.6%	48 Missing and 22 partials ⚠️
reconciler/tasks/ownership/task.go	47.3%	33 Missing and 6 partials ⚠️
cli/cmd/ownership/ownership.go	77.1%	4 Missing and 4 partials ⚠️
server/database/gorm/record.go	61.9%	7 Missing and 1 partial ⚠️
reconciler/service/service.go	44.4%	2 Missing and 3 partials ⚠️
server/database/gorm/record_exclude.go	0.0%	4 Missing and 1 partial ⚠️
server/ingest/ingest.go	64.3%	2 Missing and 3 partials ⚠️
server/types/search.go	50.0%	3 Missing ⚠️
reconciler/tasks/ownership/config.go	50.0%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

vivekkrishna · 2026-05-20T20:39:07Z

@ramizpolic Any comments on this?

ramizpolic · 2026-05-20T21:00:14Z

Hey @vivekkrishna, thanks for the PR. It looks good from my end, the only issue is that we are working on simplifying the interfaces and API surface in this PR #1500, and I am not sure which order to take (merge that PR, adjust this, or something else). I think that work will be done soon (end of next week). Can we hold this PR open until then and do a rebase together to merge this PR?

Alternatively, I think you don't even need any code changes for your functionality since you can already push whichever referrer you want and it should work out of box. Code snippet below

dir/server/store/oci/referrers.go

Lines 62 to 75 in 0c58515

    
           // Route based on referrer type 
        
           switch referrer.GetType() { 
        
           case corev1.SignatureReferrerType: 
        
           	// TODO: validate signature 
        
           	return s.pushReferrer(ctx, recordCID, referrer) 
        
           case corev1.PublicKeyReferrerType: 
        
           	// TODO: validate public key 
        
           	return s.pushReferrer(ctx, recordCID, referrer) 
        
           default: 
        
           	// Store as generic OCI referrer 
        
           	return s.pushReferrer(ctx, recordCID, referrer) 
        
           }

The only issue would be that the CLI is not available, but this can be handled through a separate CLI for your needs built with DIR Go SDK. Lets sync tomorrow/when it works for you on Slack and we can decide next steps together.

vivekkrishna · 2026-05-20T21:09:20Z

Sure @ramizpolic , I will sync up over slack.

vivekkrishna · 2026-05-23T19:00:05Z

Hi @ramizpolic . After analysis, merging as-is makes sense for these reasons.

The generic PushReferrer path (referrers.go:72-74) just stores a blob in OCI with no DB indexing — no owners table, no --owner search, and no foundation for manager subtree search. #1478's owners table + eager indexing + reconciler is exactly what makes ownership searchable and is the prerequisite for manager search (#1468).

On the #1500 question: planning to land #1478 on v1 PushReferrer as-is, then rebuild ownership onto the v2 ObjectStore + ObjectReferrer path once #1500 merges — does that sequencing work? Only immediate blocker is Target() added to StoreAPI in #1500 will break #1478's compile, so I'll add that method to the v1 OCI store when rebasing. Happy to hold if you'd rather do it right in v2 from the start — just didn't want to block manager search on #1500's timeline.

ramizpolic · 2026-05-25T22:28:17Z

+	var ownershipClaim *ownershipv1.Claim
+
+	if request.GetType() == corev1.OwnershipClaimReferrerType {
+		claim := &ownershipv1.Claim{}
+		if err := claim.UnmarshalReferrer(&corev1.RecordReferrer{Data: request.GetData()}); err != nil {
+			errMsg := fmt.Sprintf("failed to decode ownership claim: %v", err)
+


this ownership claim is currently unverifiable since the following things can happen:

user has write access to the OCI store (either directly or via sync)

user writes an ownership claim to a non-owned resource through OCI referrers (either directly or through its own OCI that gets synced to a targeted node)

target node indexes ownership through the reconciler

the resource is reported as owned by someone who actually doesnt own it

this behavior enables targeted attacks across the network since the data has 2 access points:

unsafe route through OCI that doesnt get verified in the reconciler

secure route through the controller that does get verified

my concern here is that the ownership claims are not verifiable. we already support verifiable claims through a public key and keyless OIDC signing (dirctl sign) via COSIGN which gets verified and indexed into the database. I am not sure if we currently have a mechanism to search over this data, but it is present and may only need query params to be exposed on the client-side. perhaps @paralta can assist on this question

i think a secure/verifiable way to enable this functionality is to add support for SPIFFE-based signing. this would provide all the things you need, and i would happily merge it. it would also be a super important feature for us, not just for local use-case, but across the (insecure) network.

could you please adjust the implementation according to the notes above and we can merge it right away

Thanks for the input @ramizpolic , addressed with new commit.

Addresses ramizpolic's security comment on PR agntcy#1478. Without signing, any caller with OCI write access could forge ownership claims; the reconciler would index them blindly. Changes: - proto: add signature (bytes) and certificate (bytes) fields to Claim - api/ownership/v1/sign.go: SignClaim, VerifyClaim, IsSigned; supports ECDSA (P256/P384/P521) and RSA; canonical payload SHA-256(owner_id:claimed_at) - cli: --key / --cert flags on ownership claim; identity mismatch caught client-side before any network call - reconciler: TrustedCACertFile config; verifyClaim() gate before db.AddOwner(); unsigned claims accepted with warning in dev mode (no SPIFFE configured) - server/controller: indexOwnershipClaim() helper verifies signed claims before eager db.AddOwner() so tampered claims are rejected at push time - tests: GenerateSpiffeTestCert helper (pure crypto/x509, no SPIRE needed); 14_ownership_signing_test.go (happy path, identity mismatch, idempotent re-push); 5 unit tests covering round-trip, tamper detection, and unsigned-claim rejection

Addresses ramizpolic's security comment on PR agntcy#1478. Without signing, any caller with OCI write access could forge ownership claims; the reconciler would index them blindly. Changes: - proto: add signature (bytes) and certificate (bytes) fields to Claim - api/ownership/v1/sign.go: SignClaim, VerifyClaim, IsSigned; supports ECDSA (P256/P384/P521) and RSA; canonical payload SHA-256(owner_id:claimed_at) - cli: --key / --cert flags on ownership claim; identity mismatch caught client-side before any network call - reconciler: TrustedCACertFile config; verifyClaim() gate before db.AddOwner(); unsigned claims accepted with warning in dev mode (no SPIFFE configured) - server/controller: indexOwnershipClaim() helper verifies signed claims before eager db.AddOwner() so tampered claims are rejected at push time - tests: GenerateSpiffeTestCert helper (pure crypto/x509, no SPIRE needed); 14_ownership_signing_test.go (happy path, identity mismatch, idempotent re-push); 5 unit tests covering round-trip, tamper detection, and unsigned-claim rejection Signed-off-by: Vivek Krishna Choppa <vivekkrishnachoppa@gmail.com>

vivekkrishna · 2026-05-28T21:41:26Z

should we add this 1.5 milestone?

Addresses ramizpolic's security comment on PR agntcy#1478. Without signing, any caller with OCI write access could forge ownership claims; the reconciler would index them blindly. Changes: - proto: add signature (bytes) and certificate (bytes) fields to Claim - api/ownership/v1/sign.go: SignClaim, VerifyClaim, IsSigned; supports ECDSA (P256/P384/P521) and RSA; canonical payload SHA-256(owner_id:claimed_at) - cli: --key / --cert flags on ownership claim; identity mismatch caught client-side before any network call - reconciler: TrustedCACertFile config; verifyClaim() gate before db.AddOwner(); unsigned claims accepted with warning in dev mode (no SPIFFE configured) - server/controller: indexOwnershipClaim() helper verifies signed claims before eager db.AddOwner() so tampered claims are rejected at push time - tests: GenerateSpiffeTestCert helper (pure crypto/x509, no SPIRE needed); 14_ownership_signing_test.go (happy path, identity mismatch, idempotent re-push); 5 unit tests covering round-trip, tamper detection, and unsigned-claim rejection Signed-off-by: Vivek Krishna Choppa <vivekkrishnachoppa@gmail.com>

ramizpolic · 2026-06-15T08:45:50Z

Hi @vivekkrishna, we will include this feature in v1.6, but we will need to make it part of the standard Signature field instead of adding new claims object. Are you okay if we cherry pick commits from this PR and continue working on it?

vivekkrishna · 2026-06-15T13:05:54Z

Hi @ramizpolic , that works for me. Can you let me know the planned timeline for v1.6 release? Also see if you can add me or tag me in new PR for review or modify this same PR?. Also can you confirm search filter by --owner is still preserved after the signature approach, that is crucial for overall epic?

Addresses ramizpolic's security comment on PR agntcy#1478. Without signing, any caller with OCI write access could forge ownership claims; the reconciler would index them blindly. Changes: - proto: add signature (bytes) and certificate (bytes) fields to Claim - api/ownership/v1/sign.go: SignClaim, VerifyClaim, IsSigned; supports ECDSA (P256/P384/P521) and RSA; canonical payload SHA-256(owner_id:claimed_at) - cli: --key / --cert flags on ownership claim; identity mismatch caught client-side before any network call - reconciler: TrustedCACertFile config; verifyClaim() gate before db.AddOwner(); unsigned claims accepted with warning in dev mode (no SPIFFE configured) - server/controller: indexOwnershipClaim() helper verifies signed claims before eager db.AddOwner() so tampered claims are rejected at push time - tests: GenerateSpiffeTestCert helper (pure crypto/x509, no SPIRE needed); 14_ownership_signing_test.go (happy path, identity mismatch, idempotent re-push); 5 unit tests covering round-trip, tamper detection, and unsigned-claim rejection Signed-off-by: Vivek Krishna Choppa <vivekkrishnachoppa@gmail.com>

vivekkrishna · 2026-07-27T03:43:09Z

@ramizpolic Can you check if these updates look good to approve based on recent comments with signature?

…rrer Implements ownership claims as part of the standard api/sign/v1/Signature referrer (content_type = "agntcy.dir.ownership.v1") rather than a bespoke proto type, following reviewer feedback from ramizpolic. Changes: - Add api/ownership/v1/sign.go: NewClaim, SignClaim, VerifyClaim, IsOwnershipClaim, GetOwnerID helpers operating on *signv1.Signature; SPIFFE/X.509 SVID signing with ECDSA/RSA support; canonical payload SHA-256(owner_id + ":" + signed_at) - Add ownership reconciler task (reconciler/tasks/ownership/): walks SignatureReferrerType referrers, filters by content_type, verifies SPIFFE cert chain and signature, indexes owners into DB - Add server/database/gorm/owners.go: Owner model (record_cid, owner_id, claimed_at) with AddOwner/RemoveOwners; migrate via AutoMigrate - Add OwnershipDatabaseAPI to server/types/database.go and DatabaseAPI composite - Add owner search filter (RECORD_QUERY_TYPE_OWNER = 20, WithOwners/WithoutOwners) wired through proto, pb.go, DB utils, and search types, including --exclude-owner to match the repo's include/exclude filter invariant - Add server/ingest/ingest.go: eager ownership index on Signature referrer push so search reflects new owner immediately without waiting for reconciler - Add CLI subcommand: dirctl ownership claim [--key/--cert] <record-cid> <owner-id> - Add e2e tests: 13_ownership_search_test.go (unsigned claims, wildcard owner search), 14_ownership_signing_test.go (signed SPIFFE claims, reconciler re-index, identity mismatch rejection) - Bump buf.lock for protovalidate to resolve a stale dependency lock that failed CI's "task gen" clean-tree check Signed-off-by: Vivek Krishna Choppa <vivekkrishnachoppa@gmail.com>

vivekkrishna requested a review from a team as a code owner May 9, 2026 12:27

github-actions Bot added the size/M Denotes a PR that changes 200-999 lines label May 9, 2026

vivekkrishna force-pushed the feat/ownership-v1 branch from 9cca9e0 to 21fdd72 Compare May 9, 2026 12:33

vivekkrishna force-pushed the feat/ownership-v1 branch from 21fdd72 to 330f7ad Compare May 11, 2026 20:55

vivekkrishna mentioned this pull request May 12, 2026

[Epic] Manager-scoped agent discovery via org hierarchy resolver #1468

Open

vivekkrishna force-pushed the feat/ownership-v1 branch 3 times, most recently from 516e1e8 to f01858e Compare May 14, 2026 04:29

ramizpolic self-requested a review May 20, 2026 21:00

ramizpolic assigned vivekkrishna May 20, 2026

ramizpolic added this to Discovery May 20, 2026

github-project-automation Bot moved this to Backlog in Discovery May 20, 2026

ramizpolic moved this from Backlog to In Progress in Discovery May 20, 2026

ramizpolic added area/dir/server area/cli labels May 20, 2026

ramizpolic reviewed May 25, 2026

View reviewed changes

vivekkrishna force-pushed the feat/ownership-v1 branch from f01858e to 6f92157 Compare May 26, 2026 00:42

github-actions Bot added size/L Denotes a PR that changes 1000-1999 lines and removed size/M Denotes a PR that changes 200-999 lines labels May 26, 2026

vivekkrishna force-pushed the feat/ownership-v1 branch from fca09a8 to e03f587 Compare May 26, 2026 02:14

vivekkrishna force-pushed the feat/ownership-v1 branch from e03f587 to a1d7ba7 Compare May 27, 2026 19:38

ramizpolic added this to the [WIP] DIR v1.5 milestone May 29, 2026

ramizpolic linked an issue May 29, 2026 that may be closed by this pull request

[Feature] Support SPIFFE-based record identifiers #1559

Open

vivekkrishna force-pushed the feat/ownership-v1 branch from a1d7ba7 to 67cc5b8 Compare May 30, 2026 20:03

ramizpolic modified the milestones: DIR v1.5, v1.6 Jun 15, 2026

ramizpolic added the triage/needs-information Indicates an issue or PR needs more information in order to work on it. label Jun 15, 2026

ramizpolic removed this from the DIR v1.6 milestone Jul 15, 2026

ramizpolic closed this Jul 15, 2026

github-project-automation Bot moved this from In Progress to Done in Discovery Jul 15, 2026

ramizpolic reopened this Jul 15, 2026

vivekkrishna force-pushed the feat/ownership-v1 branch from 67cc5b8 to 47fdcff Compare July 26, 2026 21:37

vivekkrishna force-pushed the feat/ownership-v1 branch 2 times, most recently from 75cd280 to caa182a Compare July 27, 2026 04:39

vivekkrishna force-pushed the feat/ownership-v1 branch from 3eed9f0 to dca5214 Compare August 15, 2026 19:46

vivekkrishna force-pushed the feat/ownership-v1 branch from fbf9b7b to 2b8aacb Compare August 28, 2026 06:05

vivekkrishna force-pushed the feat/ownership-v1 branch from 2b8aacb to f21d694 Compare August 29, 2026 00:17

Merge branch 'main' into feat/ownership-v1

a7a7344

Navigation Menu

Uh oh!

feat(dir): add ownership claim referrer, search, and CLI (v1) - #1478

feat(dir): add ownership claim referrer, search, and CLI (v1)#1478
vivekkrishna wants to merge 2 commits into
agntcy:mainfrom
vivekkrishna:feat/ownership-v1

vivekkrishna commented May 9, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 9, 2026 •

edited

Loading

Uh oh!

vivekkrishna commented May 20, 2026

Uh oh!

ramizpolic commented May 20, 2026 •

edited

Loading

Uh oh!

vivekkrishna commented May 20, 2026

Uh oh!

vivekkrishna commented May 23, 2026 •

edited

Loading

Uh oh!

ramizpolic May 25, 2026 •

edited

Loading

Uh oh!

vivekkrishna May 26, 2026

Uh oh!

vivekkrishna commented May 28, 2026

Uh oh!

ramizpolic commented Jun 15, 2026 •

edited

Loading

Uh oh!

vivekkrishna commented Jun 15, 2026

Uh oh!

vivekkrishna commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

vivekkrishna commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Design

Changes

Test plan

Uh oh!

codecov Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vivekkrishna commented May 20, 2026

Uh oh!

ramizpolic commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vivekkrishna commented May 20, 2026

Uh oh!

vivekkrishna commented May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramizpolic May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vivekkrishna May 26, 2026

Choose a reason for hiding this comment

Uh oh!

vivekkrishna commented May 28, 2026

Uh oh!

ramizpolic commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vivekkrishna commented Jun 15, 2026

Uh oh!

vivekkrishna commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vivekkrishna commented May 9, 2026 •

edited

Loading

codecov Bot commented May 9, 2026 •

edited

Loading

ramizpolic commented May 20, 2026 •

edited

Loading

vivekkrishna commented May 23, 2026 •

edited

Loading

ramizpolic May 25, 2026 •

edited

Loading

ramizpolic commented Jun 15, 2026 •

edited

Loading