TypeScript SDK for DeFarm — verifiable agri traceability with client-side sealing: sensitive fields are encrypted on your side so that only the recipients you address can ever read them. The DeFarm server stores the sealed envelope and is structurally blind — it holds no private key, so it cannot read, not merely does not.
Don't trust DeFarm — audit this SDK. The crypto client is open source (MIT) precisely so that an agency, a partner, or an auditor can audit every cryptographic operation on a key. The pure crypto lives in
src/core/, free of network and I/O, and is held byte-for-byte to the Rust reference implementation by cross-language conformance vectors.
HMAC(HKDF(DK), plaintext), not a raw hash — so low-entropy values
(a price, a CPF) cannot be brute-forced from public anchors.API reference: defarm-repo.github.io/defarm-sdk-ts — generated from the code's TSDoc on every merge (no drift by construction).
npm install @defarm/sdk
Node 18+. Pure-JS crypto (hpke-js + noble) — no native modules.
import { DefarmClient } from "@defarm/sdk";
const defarm = new DefarmClient({
gateway: testGateway, // ask DeFarm for your test-environment host; one base URL repoints everything
network: "testnet", // production anchoring is explicit opt-in
});
await defarm.login(email, password);
// 1. Keys: generated locally on first use, public halves registered with a signed binding.
const identity = await defarm.ensureKeys();
// 2. Ingest (partner API key required; preview = dry-run, writes nothing).
const client2 = new DefarmClient({ gateway, auth: { apiKey } });
const { dfids } = await client2.ingest([{ value_chain: "DEFARM", country: "BR", year: 2026, sisbov, breed: "Nelore" }]);
// 3. Seal a field — only the addressed recipient (and you) can ever read it.
const sealed = await defarm.seal({
dfid,
fieldPath: "preco_venda",
value: "R$ 8.500,00",
circuitId,
to: [buyerRecipient], // resolved from the directory; binding re-verified before sealing
});
// 4. The recipient opens locally with their own private key.
const opened = await buyer.open({ dfid, fieldPath: "preco_venda" });
console.log(opened.value, opened.authorshipVerified);
// 5. Anyone verifies the DFID publicly — no account, no trust in DeFarm.
const report = await defarm.verify(dfid);
Safe defaults, enforced by the SDK (the integrator exposes at most three choices per sensitive field — seal? for whom? via link? — everything else is default/directory/domain):
0.2.x is the first line with client-side sealing (the 0.1.x line was a thin HTTP client,
pre-sealing). The cross-language conformance vectors are green in CI and regenerated weekly
from the server's Rust implementation. Features
blocked on backend work are declared and throw NotImplementedError with the issue reference —
they are never faked: grant() (re-wrap), grantLink() (capability token), revoke().
| Path | What |
|---|---|
src/core/ |
Pure crypto — the auditable surface. No network, no I/O. |
src/client.ts |
The five operations: ensureKeys, ingest, seal, open, verify. |
src/keystore.ts |
Where private keys live (file / memory / bring-your-own HSM). |
test/vectors/ |
Cross-language conformance vectors generated by the Rust oracle. |
The trust story of this SDK is that you do not have to take DeFarm's word for anything — each claim has an artifact you can check yourself:
| Claim | What to audit |
|---|---|
| "DeFarm cannot read sealed fields" | src/core/ — every cryptographic operation on a key, pure and network-free. Standard crypto only: HPKE (RFC 9180), HKDF/HMAC, Ed25519, JCS (RFC 8785). |
| "The client matches the server byte-for-byte" | test/vectors/ — conformance vectors generated by the server's own Rust implementation, replayed on every CI run; the suite fails closed if they are missing. |
| "Commitments don't leak low-entropy values" | The hiddenCommitment reference page — rationale generated from the implementing code, not from marketing. |
| "Records are real without trusting DeFarm" | defarm-verify — an independent verifier (public-chain anchor, IPFS, recomputed hashes) that runs on your machine. |
| "Keys and credentials never leave your side" | Where the proof actually lives: src/keystore.ts (private-key custody) and src/client.ts (every request body the SDK assembles — read it and confirm no private KEY material ever goes in — the only credential in any request body is your own password, on /auth/login). The MCP server and CLI additionally refuse credentials anywhere but server-side configuration — enforced by tests. |
Everything is MIT-licensed. If your audit finds something, open an issue — adversarial review is how every release of this SDK was built.
The independent verifier — anchors via Horizon, snapshots via IPFS, hashes recomputed from
scratch — is defarm-repo/defarm-verify (MIT).