<!--
NON-NORMATIVE DOCUMENT

This file is historical/legacy/audit material and may contain aspirational language.
The canonical, current claims & limits are in: docs/CLAIMS_AND_LIMITS.md
-->

# Vaultfire Belief Identity Linker

The Trust Sync phase introduces a persistent anchor between a partner user and
an onchain wallet. Anchors are encrypted before being written to storage so
partners can maintain a verifiable link without exposing belief data in plain
text.

## Real-time Resolver

Partners can resolve wallet trust metadata without cloning repository JSON snapshots by querying the identity resolver microservice described in `docs/production-readiness.md`. The resolver mirrors the encrypted anchor store and surfaces belief scores via `GET /resolve/:walletId`. When a wallet has no live data the service responds with the default fallback payload so partner systems can degrade gracefully while waiting for first contact.

## API Overview

`POST /link-identity`
: Upserts the anchor for a `wallet` + `partnerUserId` pair. Payload
  requirements:

  ```json
  {
    "wallet": "0x1234...",
    "partnerUserId": "partner-42",
    "beliefScore": 0.82,
    "metadata": {
      "intents": ["loyalty"],
      "ethicsFlags": ["consent:verified"]
    }
  }
  ```

  Responses include both the decrypted anchor and the latest Signal Compass
  snapshot so a caller immediately sees the effect of the update.

`GET /link-identity`
: Fetches the decrypted anchor. Both `wallet` and `partnerUserId` query
  parameters are required.

All identity routes require an authenticated partner or admin access token and
pass through the ethics guard middleware. Belief scores must be between `0` and
`1`. Scores below the configured breach threshold automatically fire the
`onBeliefBreach` webhook event.

## Storage Backends

The default store is in-memory for local development. Production deployments
should choose Postgres or MongoDB by updating `vaultfirerc.json` or the
`VAULTFIRE_IDENTITY_PROVIDER` environment variable. Anchors are encrypted with
AES-256-GCM using the key supplied via `VAULTFIRE_ENCRYPTION_KEY`.

| Provider  | Configuration Notes |
|-----------|--------------------|
| `postgres` | Set `trustSync.identityStore.postgres.connection` to a valid `pg` connection configuration. The table `belief_identity_anchors` is created if missing. |
| `mongo`    | Provide a connection URI and optional database/collection overrides in `trustSync.identityStore.mongo`. Indexes for anchor and wallet hashes are maintained. |

## Breach Detection

Set `trustSync.identityStore.breachThreshold` to customise the score that
should trigger `onBeliefBreach`. The default is `0.35`. Breaches are recorded in
all telemetry channels and propagated to any registered partner hooks.

## Remote verification

Partners can opt into remote verification by configuring
`trustSync.verification.remote`. When present the Trust Sync API forwards anchor
payloads to the remote verifier and includes the verdict in the response. A
rejected verdict returns HTTP `409` so client SDKs can surface actionable
messages.

### `trustSync.verify()`

`trustSync.verify()` enforces timestamp validation and replay protection before
dispatching the payload. Anchors must include an ISO timestamp within ±2
minutes of the verifier's clock or they are immediately rejected. The verifier
computes a deterministic replay key from the anchor fingerprint and partner
context. Any subsequent call within the configured replay window returns
`{ status: "rejected", reason: "replay_detected" }` and records telemetry for
investigation. When the remote endpoint is unavailable the verifier now returns
`{ status: 'pending' | 'deferred', checksum }` where `checksum` is a SHA-256
digest of the payload. Partners can use that checksum to confirm the fallback
entry matches the original request before re-processing it offline.

```json
{
  "trustSync": {
    "verification": {
      "remote": {
        "endpoint": "https://partner.example.com/verify-anchor",
        "apiKey": "partner-service-token"
      }
    }
  }
}
```

The verifier receives `{ anchor, context }` and should respond with
`{ accepted: true }` or `{ accepted: false, reason: "explain" }`. Any network
failures are logged as deferred telemetry so operators can re-run the
verification later.
