Developer Community Referral Controls: Consent-Based Attribution, Anti-Fraud Evidence, and Appealable Rewards

A Referral URL may look like nothing more than ?ref=alice, but it actually serves three different purposes: helping new members find the community, determining which touchpoint a registration is associated with, and deciding whether the inviter receives a reward. If the system binds all three to a persistent cookie and device fingerprint, users who decline marketing measurement may be unable to register, legitimate colleagues behind the same corporate NAT may be treated as a coordinated group, and link replays may issue duplicate rewards. AI Application Data Privacy provides the general principles; this article applies purpose limitation to every referral decision.

Reward settlement must also remain separate from growth attribution. This system emits at most an instruction declaring reward eligibility under a particular offer; it does not directly modify balances, expiration dates, or refunds. The Prepaid Credits Ledger handles idempotent posting and compensation. This prevents an anti-fraud rule rollback from silently rewriting financial history, while also preventing the ledger from deciding who is a suspicious member.

Three Contracts Keep Tokens from Becoming Identities

Operations first publishes an immutable community.referralOffer.v1, fixing the offer ID, terms digest, eligible audience, per-inviter cap, qualifying action, maturity window, reward type, prohibited relationships, and appeal deadline. Rule changes create a new version. A click binds to the version in effect at that time; stricter new terms cannot be applied after the action has been completed.

schema: community.referralOffer.v1
offerId: oss-sdk-july
version: 3
qualifyingAction: first-sandbox-api-success
maturity: 14d
inviterCap: 20
termsDigest: sha256:9d1...

The sharing service issues a short-lived referralToken containing no account data in plaintext. Its contents are limited to a random token ID, offer version, issuer key generation, expiration time, and allowed destination origin, and it is signed by the server. A click produces referral.touch.v1; the same public token can bring in multiple distinct members. When an invited account first accepts a qualifying touch, a CAS operation on (offerVersion, inviteeAccountRef) locks the inviter and token. Subsequent tokens leave only an audit trail and cannot take over attribution. Registration and the qualifying action each have an idempotent event ID. During key rotation, read-only keys capable of verifying old generations are retained until the longest maturity window ends. If a key leaks, a revocation generation blocks tokens that have not yet been accepted.

Consent state is recorded separately through consentSnapshotId, purpose, policy revision, capturedAt, expiry, and withdrawal generation. Marketing attribution requires an affirmative choice for the applicable purpose. Declining still allows registration and use of the public community. Global Privacy Control cannot be interpreted as affirmative consent. Sale or sharing purposes to which it applies must be handled according to site policy, with a processing receipt retained. Withdrawal stops subsequent user-level associations and deletes mappings that can be deleted, but it does not fabricate a security audit record claiming that something “never happened.”

WebAuthn can prove that the same account currently holds a registered credential; Passkeys in Practice explains the authentication flow. It cannot prove that only one person or organization exists in the real world, so it cannot serve as the sole proof against Sybil attacks. Privacy Pass can carry a type of authorization token without exposing a linkable identity, but it likewise does not mean that “this person has never registered before.” The system must state explicitly what each signal can prove; unknown cases enter INSUFFICIENT_EVIDENCE.

Base Decisions on Evidence References, Not Universal Profiles

When the maturity window is reached, referral.decision.v1 references the offer, locked touch, invitation relationship, server-side qualifying action, and ruleset digest. It outputs ELIGIBLE, QUARANTINED, REJECTED, or REVERSED together with a stable reason code. The separate marketing-attribution branch additionally references the consent snapshot. Declining marketing measurement does not revoke reward eligibility already earned under the program terms. Eligibility and reward instructions are unique by (offerVersion, inviteeAccountRef, qualifyingActionId). When an instruction is created, a CAS operation reserves capacity against the inviter cap in the same serializable transaction, so only one concurrent contender can claim the final slot. The detector uses a minimal set of signals, including account-level velocity, signed-token replay, explicit self-referral, cyclic relationships, and authorized matches involving the same payment instrument. IP addresses and shared devices can only increase uncertainty; they cannot independently justify rejection. Raw network identifiers are retained briefly, while the analytics layer receives only daily capped risk features. API Rate-Limiting Strategies handle request surges, but anti-fraud decisions still require a complete evidence chain.

High-risk candidates have their rewards quarantined first; their core accounts are not automatically banned. Human reviewers see the rule version, evidence summary, and a counterfactual explanation such as “Would the conclusion change if the shared-IP signal were removed?” They do not see unrelated private activity. Members can appeal within the specified period. Review produces a new decision generation and compensation instruction rather than overwriting the original rejection. Every state change is published as an event; consumers following Event-Driven Architecture must deduplicate by decision ID and reject stale generations.

The attack suite covers an inviter creating a new account for themselves, A inviting B and then B inviting A, concurrent redemption of the same token, the same invitee concurrently submitting multiple tokens from multiple inviters, multiple candidates racing for the last slot under an inviter cap, an intercepted link with a rewritten origin, changing the inviter after registration, repeated reports of one qualifying action, disposable email addresses, automated scripts distributed at a low rate, corporate colleagues sharing a NAT, family members sharing a device, a client clock running two days fast, a qualifying event arriving after the watermark, a race between offer expiration and key rotation, and consent withdrawal after a click. Real shared-network samples must also be injected to prove that the system does not harm legitimate teams merely to block synthetic attacks.

Launch gates require the following: tests detect signature tampering, expiration, incorrect origins, and deterministic self-referrals at a rate of 100%; when the same invitee uses any number of tokens to replay the same qualifying action, at most one eligibility instruction is produced; when one hundred concurrent candidates race for the final cap slot, exactly one reservation succeeds; user-level marketing attributions without valid consent are 0; automatic approvals when rule inputs are missing are 0; the false-quarantine rate among manually labeled legitimate samples is below 0.5%; 99% of decisions complete within 10 minutes after the maturity watermark; withdrawal propagation p99 does not exceed 24 hours; and eligibility instructions reconcile item by item with the totals received by the reward ledger. Accuracy must include the denominator of reviewed samples. A synthetic-attack pass rate cannot be presented as production recall.

The new rules first run in shadow mode for four weeks without affecting rewards, comparing only the old and new decisions and appeal outcomes. Quarantine, rather than automatic rejection, is then enabled for 5% of new offers. If false quarantines exceed the threshold, the missing-evidence rate rises above 1%, withdrawal propagation times out, or reconciliation fails, switch the activeRuleset alias back to the old digest, stop issuing new tokens, and continue processing in-flight candidates under the terms in effect when their tokens were issued. Rollback uses new compensating decisions to restore rewards that were wrongly denied while retaining the old evidence for audit. Failed cases cannot be deleted merely to make the rules appear more accurate.