@spec default_identity_dir() :: String.t() | nil

Returns ~/.conduit/ as the canonical identity directory.

@spec dg_ca_url() :: String.t()

Returns the canonical URL for the DataGrout CA certificate.

@spec dg_substrate_endpoint() :: String.t()

Returns the default endpoint for Substrate identity registration.

@spec fetch_ca_cert(String.t() | nil) :: {:ok, String.t()} | {:error, term()}

Fetch the DG CA certificate from ca.datagrout.ai.

Returns {:ok, pem_string} on success.

@spec generate_keypair() :: {:ok, {binary(), binary()}}

Generate an ECDSA P-256 keypair.

Returns {:ok, {private_key_pem, public_key_pem}} where both are PEM-encoded binaries. The private key never leaves the client.

@spec refresh_ca_cert(String.t(), String.t() | nil) ::
  {:ok, String.t()} | {:error, term()}

Refresh the local CA cert from the DG CA endpoint.

Fetches the CA cert and writes it to ca.pem in the given directory.

@spec register_identity(
  binary(),
  keyword()
) ::
  {:ok, DatagroutConduit.Registration.RegistrationResponse.t()}
  | {:error, term()}

Register identity with the DataGrout CA.

Sends the public key to the registration endpoint, authenticated with a bearer token. Returns {:ok, %RegistrationResponse{}} on success.

Options

• :auth_token - Bearer token for authentication (required)
• :name - Human-readable label (default: "conduit-client")
• :endpoint - Registration endpoint URL (default: dg_substrate_endpoint())

@spec rotate_identity(binary(), DatagroutConduit.Identity.t(), keyword()) ::
  {:ok, DatagroutConduit.Registration.RegistrationResponse.t()}
  | {:error, term()}

Rotate identity using existing mTLS cert.

Authenticates with the existing identity's client certificate instead of a bearer token. Generates a fresh registration with the new public key.

Options

• :name - Human-readable label (default: "conduit-client")
• :endpoint - Registration endpoint URL (default: dg_substrate_endpoint())

@spec save_identity(binary(), binary(), binary() | nil, String.t()) ::
  {:ok, %{cert: String.t(), key: String.t(), ca: String.t() | nil}}
  | {:error, term()}

Save identity files to a directory.

Writes cert.pem, key.pem, and ca.pem to dir. Sets file permissions to 0o600 on the key file. Creates dir if it does not exist.

Returns {:ok, %{cert: path, key: path, ca: path}}.