@jiaozi-protocol/sdk

TypeScript SDK for JIAOZI — register, attest, resolve and verify AI-agent credentials. The underlying protocol is open: specs and reference implementations live in the jiaozi-protocol GitHub org.

npm install @jiaozi-protocol/sdk

import { Gdid } from "@jiaozi-protocol/sdk";

const gdid = new Gdid({
  baseUrl: "https://www.jiaozi.io",       // or https://www.jiaozi.tech (China)
  apiKey: process.env.JIAOZI_API_KEY,
});

await gdid.register({ name: "MyAgent", ownerPubkey: "zOwner..." });
await gdid.attest(summary);          // local health-check report
await gdid.resolve("JIAOZI-2026-000001");
await gdid.verify("did:web:...");    // authenticity check

Core surface: register / verify / resolve / attest.

Credential → permission: requireTrust

Certified agents get more permissions. Gate your tools on the visiting agent's live jiaozi.status.v1 credential — signature, freshness (short TTL), revocation/suspension, trust level and the agent's self-declared attest.v1 behaviorBoundary are all checked locally, no network call needed.

Trust ladder (same medals as the portal): Bronze = software < Silver = cloud_attest < Gold = tee / tpm.

import { requireTrust, presentationFromHeaders } from "@jiaozi-protocol/sdk";

// Framework-agnostic pure function
const writeGate = requireTrust({
  minLevel: "cloud_attest",          // Silver or above
  behaviors: ["write"],              // must sit inside the declared boundary
  verify: { trustedKeys: ["z..."], expectedIssuer: "https://www.jiaozi.io" },
});

const decision = writeGate(presentationFromHeaders(req.headers));
// → { allowed: true, trustLevel, certId, payload }
// → { allowed: false, reasonCode, reason, trustLevel }

Deny codes (each with a bilingual human-readable reason): no_credential · expired · insufficient_level · behavior_out_of_boundary, refined by revoked / suspended / invalid_credential for fail-closed paths.

Three verification policies (policy option): "online" (default — embedded key + short-TTL freshness check), "pinned" (verify against locally pinned issuerKeys, no did.json resolution, freshness still enforced) and "offline" (pinned keys, freshness check skipped — the allow is explicitly marked freshness: "unverified", never a silent downgrade). pinned and offline fail closed at build time without issuerKeys. A fetchStatusCredential helper fetches a live credential from the default or a custom status source.

Express-style one-liner (answers 401/403 with the readable reason itself):

import { requireTrustExpress } from "@jiaozi-protocol/sdk";

app.post("/api/write",
  requireTrustExpress({ minLevel: "cloud_attest", behaviors: ["write"] }),
  (req, res) => res.json({ ok: true, caller: req.jiaoziTrust }));

Credentials travel in the x-jiaozi-status header (raw or base64url JSON), the optional boundary declaration in x-jiaozi-boundary. A runnable three-tier MCP-style demo lives in examples/mcp-trust-demo.

Verifying revocation freshness (no account needed)

Any relying party can verify a credential's live status offline:

import { verifyStatusCredential } from "@jiaozi-protocol/gdid-core/status";

const cred = await (await fetch("https://www.jiaozi.io/api/status/JIAOZI-2026-000001")).json();
const result = verifyStatusCredential(cred); // Ed25519 + TTL + serial checks

The status credential format is an open spec: jiaozi.status.v1.

Python

The Python SDK lives in packages/gdid-sdk-py (jiaozi-gdid on PyPI):

from jiaozi_gdid import Gdid

gdid = Gdid(base_url="https://www.jiaozi.io", api_key="...")
gdid.resolve("JIAOZI-2026-000001")

License

MIT