TLS & Certificates

The agent serves wss:// with a self-signed certificate generated from a key it creates once and keeps. Nothing is installed into any trust store by default.

Native devices: pin the key

Phones, readers and other native clients should not install a certificate authority. They verify the agent by pinning its public key, reported as serverInfo.publicKeyPin at registration and handed out at pairing. The pin survives certificate reissues, which happen whenever the host's addresses change.

See Setting up an iOS or Android device for the pairing flow and the trust-evaluation code, including the two ways it commonly goes wrong.

Browsers: provide a certificate, or install a CA

A browser cannot pin, so it needs a certificate it already trusts:

1. Provide one: point -cert / -key at a certificate for a name you control that resolves to the agent. Nothing is installed, and the browser trusts it because a public CA issued it.
2. -install-ca: creates a local certificate authority and installs it in the system trust store. A CA there can sign for any name, not just this agent, so prefer option 1 where you can arrange it.

With -install-ca, the bootstrap server on port 9472 serves the root certificate for installation, PIN-gated.

Browsers also need their origin allowed. See Browser origins. A trusted certificate and an allowed origin are separate requirements, and a failure of either looks the same from the page.

Error Codes

Errors arrive as a response with success: false, a human-readable error string, and a structured payload:

{
  "id": "req_1",
  "type": "error",
  "success": false,
  "error": "data too large: 900 bytes exceeds tag NDEF capacity of 504 bytes",
  "payload": {
    "code": "CAPACITY_EXCEEDED",
    "retryable": false,
    "op": "WriteData",
    "tagUID": "04:A1:B2:C3"
  }
}

code has always been present and its strings are stable. retryable, op, and tagUID are additive: a client reading only code is unaffected.

retryable answers whether repeating the identical request could plausibly succeed. Combined with code it gives three distinct outcomes:

Protocol errors

Raised by the bridge itself, before reaching a tag.

NFC errors

Something happened at the tag. These mirror the agent's internal error codes.