fix(auditor): composite-owner upgrades and undecodable owners in input attribution

An upgrade issued back to a composite owner emits one output row per
member under a shared output index. Members resolving to one enrollment
ID attribute the upgrade input to it, now covered by tests; members
spanning enrollment IDs fail the audit naming both IDs — a record keeps
a single sender per action, and leaving the input unattributed would
credit the members without debiting anyone. Refs #2242.

The identity layer signals an owner it cannot decode — an unknown
identity type, a missing deserializer, undecodable audit info — by
returning an error. Treat such an owner as unresolved instead of
failing the audit: a transfer input stays unattributed, an upgrade
input still takes the issued enrollment ID.

Also correct the documented audit-info preference order: the locally
stored audit info wins wherever it exists, since Request.AuditRecord
fills it in before the gap filling runs.

Signed-off-by: Evan <evanyan@sign.global>

Author: EvanYan1024

docs/services/auditor.md

@@ -59,11 +59,11 @@ An audit record pairs every input and output with an enrollment ID. Inputs do no
 Each such input is resolved from its own spent token:
 
 1. The spent token is read from the vault, yielding its owner, type, and quantity.
-2. The owner is resolved to an enrollment ID and revocation handle through `WalletManager.GetEIDAndRH`, preferring the audit info carried by the record over the locally stored one — a counterparty's audit info is not necessarily present locally.
+2. The owner is resolved to an enrollment ID and revocation handle through `WalletManager.GetEIDAndRH`, using the audit info attached to the input: the locally stored audit info of the spent token's owner where present, the one carried by the request metadata otherwise — a counterparty's audit info is not necessarily present locally. An owner the identity layer cannot decode counts as resolving to nothing.
 
-Across the built-in drivers, a **token upgrade** is the action whose metadata describes no sender for its inputs, and whose pre-upgrade owner often resolves to nothing: that identity predates the current driver and the request carries no audit info for it. Since an upgrade re-issues the spent tokens to the same party under a fresh identity, such an input takes the enrollment ID of the outputs issued by **its own action**, when every one of them resolves to the same party. The revocation handle comes from the same output, and is dropped when the outputs carry more than one. Without this the upgraded amount would be credited to the owner without ever being debited, doubling the holding.
+Across the built-in drivers, a **token upgrade** is the action whose metadata describes no sender for its inputs, and whose pre-upgrade owner often resolves to nothing: that identity predates the current driver and the request carries no audit info for it. Since an upgrade re-issues the spent tokens to the same party under a fresh identity, such an input takes the enrollment ID of the outputs issued by **its own action**, when every one of them resolves to the same party. The revocation handle comes from the same output, and is dropped when the outputs carry more than one. Without this the upgraded amount would be credited to the owner without ever being debited, doubling the holding. A composite owner issues one output row per member, all under one output index: members resolving to one enrollment ID attribute the input to it, while members spanning enrollment IDs fail the audit — a record keeps a single sender per action, and an unattributed input would credit the members without debiting anyone.
 
-An owner that maps to no single enrollment ID — a composite owner such as a multisig, or one whose audit info is not available to this auditor — leaves its input **unattributed**, with an empty enrollment ID. Amount aggregations skip empty enrollment IDs, so an unattributed input is counted for nobody. Guessing instead, for instance from the first output, would in a payment attribute the payer's spending to the recipient and silently corrupt both balances.
+An owner that maps to no single enrollment ID — a composite owner such as a multisig, or one whose audit info is not available to, or not decodable by, this auditor — leaves its input **unattributed**, with an empty enrollment ID. Amount aggregations skip empty enrollment IDs, so an unattributed input is counted for nobody. Guessing instead, for instance from the first output, would in a payment attribute the payer's spending to the recipient and silently corrupt both balances.
 
 An action whose inputs attribute to **more than one** enrollment ID — reachable when the tokens to spend are passed explicitly, since they are not constrained to a single wallet — fails the audit with an error naming the cause: a transaction record keeps a single sender per action, so the store cannot represent it. Representing multi-sender actions is tracked separately.
 

token/services/auditor/auditor.go

@@ -449,12 +449,15 @@ func rejectMultiOwnerActions(record *token.AuditRecord) error {
 // completeInputsWithEmptyEID fills in missing enrollment ID information for inputs in the audit record
 // by querying the token vault. This is necessary when inputs don't have enrollment IDs explicitly set.
 // Each input is attributed to the enrollment ID resolved from its own token
-// owner and the audit info carried by the record (falling back to the locally
-// stored audit info). An input the request describes no sender for is an upgrade
-// input, and falls back to the enrollment ID the request issues to. An owner that
-// maps to no single enrollment ID leaves its input unattributed rather than booked
-// under a guessed enrollment ID, so a record keeping such an input is not fully
-// attributed on return.
+// owner and the audit info the input carries — the locally stored audit info
+// of the owner where present, the one carried by the request otherwise (see
+// Request.AuditRecord). An owner the identity layer cannot decode counts as
+// resolving to nothing. An input the request describes no sender for is an
+// upgrade input, and falls back to the enrollment ID the request issues to;
+// an upgrade issued to a composite owner spanning enrollment IDs fails the
+// audit (see issuedToEIDAndRH). An owner that maps to no single enrollment ID
+// leaves its input unattributed rather than booked under a guessed enrollment
+// ID, so a record keeping such an input is not fully attributed on return.
 func (r *requestWrapper) completeInputsWithEmptyEID(ctx context.Context, record *token.AuditRecord) error {
 	filter := record.Inputs.ByEnrollmentID("")
 	if filter.Count() == 0 {
@@ -490,15 +493,22 @@ func (r *requestWrapper) completeInputsWithEmptyEID(ctx context.Context, record
 
 		eID, rID, err := wm.GetEIDAndRH(ctx, item.Owner, item.OwnerAuditInfo)
 		if err != nil {
-			return errors.WithMessagef(err, "failed resolving enrollment id for input [%v]", item.Id)
+			// the identity layer reports an owner it cannot decode — an unknown
+			// identity type, or audit info it cannot deserialize — as an error;
+			// such an owner is unresolvable here, not a failure of the audit
+			logger.DebugfContext(ctx, "owner of input [%v] does not resolve, treating it as unresolved: %v", item.Id, err)
+			eID, rID = "", ""
 		}
 		if eID == "" && upgraded {
 			// an upgrade re-issues the spent tokens to their owner under a fresh
 			// identity, so the outputs of the very same action carry the
 			// enrollment ID the input belongs to. The pre-upgrade identity
 			// itself often resolves to nothing here: it predates the current
 			// driver and the request metadata carries no audit info for it.
-			eID, rID = issuedToEIDAndRH(record.Outputs, item.ActionIndex)
+			eID, rID, err = issuedToEIDAndRH(record.Outputs, item.ActionIndex)
+			if err != nil {
+				return err
+			}
 		}
 		if eID == "" {
 			// the owner maps to no single enrollment ID — a composite owner,
@@ -520,28 +530,47 @@ func (r *requestWrapper) completeInputsWithEmptyEID(ctx context.Context, record
 // issuer but no owner. Every issued output of the action must resolve to the same
 // enrollment ID: one resolving to none cannot be shown to belong to the same party
 // as the others. The handle is kept only while it stays paired with that ID.
-func issuedToEIDAndRH(outputs *token.OutputStream, actionIndex int) (string, string) {
+//
+// A composite owner issues one output row per member, all under one output index.
+// Members resolving to distinct enrollment IDs leave no single enrollment ID to
+// book the input under, and an unattributed input would credit the members
+// without debiting anyone: such an action fails the audit instead.
+func issuedToEIDAndRH(outputs *token.OutputStream, actionIndex int) (string, string, error) {
 	issued := outputs.Filter(func(o *token.Output) bool {
 		return o.ActionIndex == actionIndex && len(o.Issuer) != 0 && len(o.Owner) != 0
 	}).Outputs()
 	if len(issued) == 0 {
-		return "", ""
+		return "", "", nil
+	}
+
+	eIDByIndex := map[uint64]string{}
+	for _, output := range issued {
+		if output.EnrollmentID == "" {
+			continue
+		}
+		if eID, ok := eIDByIndex[output.Index]; ok && eID != output.EnrollmentID {
+			return "", "", errors.Errorf(
+				"output [%d] of action [%d] is issued to a composite owner whose members span enrollment IDs ([%s] and [%s]): no single enrollment ID to attribute its input to",
+				output.Index, actionIndex, eID, output.EnrollmentID,
+			)
+		}
+		eIDByIndex[output.Index] = output.EnrollmentID
 	}
 
 	eID, rH := issued[0].EnrollmentID, issued[0].RevocationHandler
 	if eID == "" {
-		return "", ""
+		return "", "", nil
 	}
 	for _, output := range issued[1:] {
 		if output.EnrollmentID != eID {
-			return "", ""
+			return "", "", nil
 		}
 		if output.RevocationHandler != rH {
 			rH = ""
 		}
 	}
 
-	return eID, rH
+	return eID, rH, nil
 }
 
 // String returns a string representation of the wrapped token request.

token/services/auditor/auditor_internal_test.go

@@ -447,8 +447,8 @@ func TestCompleteInputsWithEmptyEID_TransferInputIgnoresIssuedEID(t *testing.T)
 	assert.Empty(t, record.Inputs.At(0).EnrollmentID)
 }
 
-// Issuing to more than one party leaves the upgrade input unattributed: there is
-// no single enrollment ID to charge it to.
+// Issuing to more than one party — two outputs, each with its own index — leaves
+// the upgrade input unattributed: there is no single enrollment ID to charge it to.
 func TestCompleteInputsWithEmptyEID_AmbiguousIssuedEIDStaysUnattributed(t *testing.T) {
 	tmsWithToken, ws := newInternalTestManagementServiceWithTokens(t, []*token2.Token{
 		{Type: "USD", Quantity: "100", Owner: []byte("pre-upgrade-owner")},
@@ -460,8 +460,8 @@ func TestCompleteInputsWithEmptyEID_AmbiguousIssuedEIDStaysUnattributed(t *testi
 	record := &token.AuditRecord{
 		Inputs: token.NewInputStream(nil, []*token.Input{{Id: &token2.ID{TxId: "123"}}}, 0),
 		Outputs: token.NewOutputStream([]*token.Output{
-			{Issuer: driver.Identity("issuer"), Owner: []byte("alice"), EnrollmentID: "alice"},
-			{Issuer: driver.Identity("issuer"), Owner: []byte("bob"), EnrollmentID: "bob"},
+			{Index: 0, Issuer: driver.Identity("issuer"), Owner: []byte("alice"), EnrollmentID: "alice"},
+			{Index: 1, Issuer: driver.Identity("issuer"), Owner: []byte("bob"), EnrollmentID: "bob"},
 		}, 0),
 	}
 	err := rw.completeInputsWithEmptyEID(context.Background(), record)
@@ -470,6 +470,57 @@ func TestCompleteInputsWithEmptyEID_AmbiguousIssuedEIDStaysUnattributed(t *testi
 	assert.Empty(t, record.Inputs.At(0).EnrollmentID)
 }
 
+// An upgrade issued back to a composite owner emits one output row per member,
+// all under one output index. Members resolving to one enrollment ID attribute
+// the input to it; their distinct revocation handles drop the handle.
+func TestCompleteInputsWithEmptyEID_CompositeUpgradeSharedEIDAttributed(t *testing.T) {
+	tmsWithToken, ws := newInternalTestManagementServiceWithTokens(t, []*token2.Token{
+		{Type: "USD", Quantity: "100", Owner: []byte("pre-upgrade-composite")},
+	})
+	ws.GetAuditInfoReturns(nil, nil)
+	rw := newRequestWrapper(
+		token.NewRequest(tmsWithToken, token.RequestAnchor("tx-composite-upgrade")), tmsWithToken,
+	)
+	record := &token.AuditRecord{
+		Inputs: token.NewInputStream(nil, []*token.Input{{Id: &token2.ID{TxId: "123"}}}, 0),
+		Outputs: token.NewOutputStream([]*token.Output{
+			{Index: 0, Issuer: driver.Identity("issuer"), Owner: []byte("member-0"), EnrollmentID: "alice", RevocationHandler: "rh-0"},
+			{Index: 0, Issuer: driver.Identity("issuer"), Owner: []byte("member-1"), EnrollmentID: "alice", RevocationHandler: "rh-1"},
+		}, 0),
+	}
+	err := rw.completeInputsWithEmptyEID(context.Background(), record)
+	require.NoError(t, err)
+
+	in := record.Inputs.At(0)
+	assert.Equal(t, "alice", in.EnrollmentID)
+	assert.Empty(t, in.RevocationHandler)
+}
+
+// Members spanning enrollment IDs leave no single enrollment ID to book the
+// input under, and leaving it unattributed would credit the members without
+// debiting anyone: the audit fails, naming the enrollment IDs.
+func TestCompleteInputsWithEmptyEID_CompositeUpgradeSpanningEIDsFailsAudit(t *testing.T) {
+	tmsWithToken, ws := newInternalTestManagementServiceWithTokens(t, []*token2.Token{
+		{Type: "USD", Quantity: "100", Owner: []byte("pre-upgrade-composite")},
+	})
+	ws.GetAuditInfoReturns(nil, nil)
+	rw := newRequestWrapper(
+		token.NewRequest(tmsWithToken, token.RequestAnchor("tx-composite-span")), tmsWithToken,
+	)
+	record := &token.AuditRecord{
+		Inputs: token.NewInputStream(nil, []*token.Input{{Id: &token2.ID{TxId: "123"}}}, 0),
+		Outputs: token.NewOutputStream([]*token.Output{
+			{Index: 0, Issuer: driver.Identity("issuer"), Owner: []byte("member-0"), EnrollmentID: "alice"},
+			{Index: 0, Issuer: driver.Identity("issuer"), Owner: []byte("member-1"), EnrollmentID: "bob"},
+		}, 0),
+	}
+	err := rw.completeInputsWithEmptyEID(context.Background(), record)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "composite owner")
+	assert.Contains(t, err.Error(), "alice")
+	assert.Contains(t, err.Error(), "bob")
+}
+
 // An output of the same action that resolves to no enrollment ID cannot be shown
 // to belong to the party the others name, so the action does not count as issuing
 // to exactly one party.
@@ -581,21 +632,65 @@ func TestCompleteInputsWithEmptyEID_NilVaultTokenErrors(t *testing.T) {
 	assert.Contains(t, err.Error(), "nil input at [0]th input")
 }
 
-func TestCompleteInputsWithEmptyEID_OwnerResolutionErrorPropagates(t *testing.T) {
+// The identity layer signals an owner it cannot decode by returning an error —
+// an unknown identity type, a missing deserializer, undecodable audit info.
+// Such an owner is unresolvable, not a failure: the input stays unattributed
+// instead of failing the whole audit.
+func TestCompleteInputsWithEmptyEID_OwnerResolutionErrorLeavesUnattributed(t *testing.T) {
 	tmsWithToken, ws := newInternalTestManagementServiceWithTokens(t, []*token2.Token{
 		{Type: "USD", Quantity: "100", Owner: []byte("owner1")},
 	})
-	ws.GetAuditInfoReturns(nil, errors.New("no audit info stored"))
+	ws.GetEIDAndRHReturns("", "", errors.New("no deserializer found for [legacy]"))
 	rw := newRequestWrapper(
 		token.NewRequest(tmsWithToken, token.RequestAnchor("tx-res-err")), tmsWithToken,
 	)
 	record := &token.AuditRecord{
-		Inputs:  token.NewInputStream(nil, []*token.Input{{Id: &token2.ID{TxId: "123"}}}, 0),
+		Inputs: token.NewInputStream(nil, []*token.Input{{
+			Id:             &token2.ID{TxId: "123"},
+			Owner:          []byte("owner1"),
+			OwnerAuditInfo: []byte("legacy-audit-info"),
+		}}, 0),
 		Outputs: token.NewOutputStream([]*token.Output{{EnrollmentID: "target"}}, 0),
 	}
 	err := rw.completeInputsWithEmptyEID(context.Background(), record)
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "failed resolving enrollment id")
+	require.NoError(t, err)
+
+	in := record.Inputs.At(0)
+	assert.Empty(t, in.EnrollmentID)
+	assert.Empty(t, in.RevocationHandler)
+	// the remaining fields are still filled in from the spent token
+	assert.Equal(t, token2.Type("USD"), in.Type)
+	assert.Equal(t, "100", in.Quantity.Decimal())
+}
+
+// A pre-upgrade owner from an older driver carries audit info the identity
+// layer cannot deserialize: GetEIDAndRH errors. The upgrade fallback still
+// runs, so the input takes the issued enrollment ID instead of the resolution
+// error blocking the upgrade forever.
+func TestCompleteInputsWithEmptyEID_UpgradeOwnerResolutionErrorTakesIssuedEID(t *testing.T) {
+	tmsWithToken, ws := newInternalTestManagementServiceWithTokens(t, []*token2.Token{
+		{Type: "USD", Quantity: "100", Owner: []byte("pre-upgrade-owner")},
+	})
+	ws.GetAuditInfoReturns([]byte("legacy-audit-info"), nil)
+	ws.GetEIDAndRHReturns("", "", errors.New("no deserializer found for [legacy]"))
+	rw := newRequestWrapper(
+		token.NewRequest(tmsWithToken, token.RequestAnchor("tx-upgrade-res-err")), tmsWithToken,
+	)
+	record := &token.AuditRecord{
+		Inputs: token.NewInputStream(nil, []*token.Input{{Id: &token2.ID{TxId: "123"}}}, 0),
+		Outputs: token.NewOutputStream([]*token.Output{{
+			Issuer:            driver.Identity("issuer"),
+			Owner:             []byte("post-upgrade-owner"),
+			EnrollmentID:      "alice",
+			RevocationHandler: "alice-rh",
+		}}, 0),
+	}
+	err := rw.completeInputsWithEmptyEID(context.Background(), record)
+	require.NoError(t, err)
+
+	in := record.Inputs.At(0)
+	assert.Equal(t, "alice", in.EnrollmentID)
+	assert.Equal(t, "alice-rh", in.RevocationHandler)
 }
 
 func TestRejectMultiOwnerActions(t *testing.T) {