Publish a SACD document so shares grant document access

[zer0stars]

The problem

A share writes permission bits on chain and points at a SACD document through the contract's source field. We passed "".

Permission bits govern telemetry. They say nothing about documents — dimo-app-backend gates a grantee's glovebox on a cloudevent agreement inside that document (hasDocumentAgreement), and a doc-only share is valid with permissions == 0. So a wallet we shared a vehicle with saw the vehicle on their phone and none of its documents.

Owners were never affected: resolveDocAccess short-circuits on ownership first.

The fix is that the agreements now exist at all. Everything below about signing is what makes the same document also work for a direct EventFilters consumer.

What changed

The share builds the document, signs it as the grantor, uploads it, and records ipfs://<cid>.

Shape follows the SDK's generatePermissionsSACDTemplate: a permission agreement naming each granted privilege, plus four cloudevent agreements over dimo.document.vehicle.*, dimo.document.driver.*, dimo.raw.vehicle.*, dimo.raw.driver.* — matching fleet-pairing's buildDocumentAgreements.

Three details that are silent when wrong:

• asset is the DID, not the NFT contract. The on-chain call takes the contract; the document takes did:erc721:137:0xbA57…:<tokenId>. Mismatch grants documents on paper and none in practice.
• The permission vocabularies differ — RawData here, GetRawData in the document. defaultPermissionList() feeds both the packed mask and the document, with a test that they can't drift.
• specversion is lower case, per the SACD spec and cloudevent.RawEvent's struct tag. The SDK emits specVersion, which deserializes to empty. Nothing reads it today; matching the spec removes a trap.

Signing

token-exchange-api checks ValidateSignature(record.Data, record.Signature, data.Grantor.Address) — payload is the data object alone, hashed with accounts.TextHash, verified against the grantor by EOA recovery then ERC-1271. The SACD spec agrees: "the cryptographic signature … created by signing the JSON data".

The grantor is the owner's kernel account and the owner never signs, so the signature comes from go-zerodev's SmartAccountPrivateKeySigner — the tenant's registered signer, wrapped in the kernel's EIP-712 domain and tagged with the validator identifier, which the kernel accepts via ERC-1271. SignMessage is deliberately not used: it applies a bare Keccak256 with no EIP-191 prefix.

Why this differs from the SDK, and why that isn't a contradiction

@dimo-network/transactions signs JSON.stringify(template) — the whole document — which cannot validate against record.Data.

It does not follow that SDK-based sharing is broken, and an earlier draft of this PR wrongly said so. The mobile glovebox never reaches that check: dimo-app-backend evaluates a grantee's document authority itself in resolveDocAccess, reading the cloudevent agreements and never looking at signature; the bytes then come back through the backend's own dev-license JWT, whose token exchange sends privileges and no EventFilters, so token-exchange takes its bitmask fallback.

The signature only decides a request carrying EventFilters. Signing data satisfies that path and the mobile one — a superset of the SDK's output, not a disagreement with it.

Risk

Bounded in both directions.

• Publishing is best-effort. Any failure — no URL, signing error, endpoint down — logs a warning and falls back to the empty source. The floor is today's behaviour.
• SACD_UPLOAD_URL is unset by default. Nothing changes until it is configured.
• Telemetry can't regress. ValidateAccess falls back to the on-chain bitmask whenever the source doc is unusable, for any request without EventFilters.

Revocations and the tenant self-grant pass "" deliberately: a revocation grants nothing to describe, and the self-grant has no grantee-facing document.

Testing

gofmt, go vet, golangci-lint (0 issues) and the full suite pass. New tests cover the document shape — including one running hasDocumentAgreement's exact three-condition check — and one pinning the EIP-191 hash the signature must cover.

Not yet exercised against a live share. Before enabling SACD_UPLOAD_URL, do one share on a throwaway vehicle and confirm both halves: the grantee sees documents, and telemetry still resolves.

🤖 Generated with Claude Code

https://claude.ai/code/session_011C3pLCzJDFMNVAX6waiJs6