ex_bitstring_status_list

ex_bitstring_status_list is a focused Elixir library for Bitstring Status List credentials and entry verification.

Quick links: Hex package | Hex docs | Supported features | Interop notes | Fixture policy

What Standard Is This?

Bitstring Status List is the W3C format for publishing revocation, suspension, or similar status information for many verifiable credentials at once. Instead of giving every credential its own status document, an issuer can publish one compressed list and let each credential point at an index inside it.

ex_bitstring_status_list implements that status-list boundary for Elixir.

Why You Might Use It

Use ex_bitstring_status_list when you need to:

• issue many credentials and track whether each one is active, revoked, or suspended
• build or read BitstringStatusListCredential documents
• keep revocation logic separate from generic VC validation
• avoid inventing a custom status format for your credential system

The package owns status-list-specific semantics:

• allocate stable entry indices
• encode and decode bitstring lists
• construct BitstringStatusListEntry values
• construct BitstringStatusListCredential credentials
• resolve entry status from a decoded list or full credential

Generic VC envelope validation belongs in ex_vc. DID and key resolution belong in ex_did.

Status

Current support:

• Recommendation-shaped bitstring construction with a 16KB privacy floor
• multibase base64url + GZIP encodedList encoding/decoding
• revocation, suspension, refresh, and message purposes
• entry generation, validation, and index parsing
• status resolution from a decoded list or a full BitstringStatusListCredential
• statusSize, statusMessages, statusReference, and ttl support
• contractual released fixture corpus for package-owned behavior and Recommendation examples

Deliberately out of scope:

• generic VC validation
• cryptographic proof verification
• DID resolution
• issuer workflow and protocol transport

Installation

def deps do
  [
    {:ex_bitstring_status_list, "~> 0.1.0"}
  ]
end

Usage

Build a list and allocate an entry:

{:ok, status_list, index} =
  ExBitstringStatusList.new_status_list(size: 1024)
  |> ExBitstringStatusList.allocate_index()

entry =
  ExBitstringStatusList.entry("https://issuer.example/status/revocation", index)

Revoke an index and resolve its status:

status_list =
  ExBitstringStatusList.new_status_list(size: 8)
  |> ExBitstringStatusList.revoke(3)

ExBitstringStatusList.status_at(status_list, 3)
# => :revoked

Build a message-oriented status list:

status_list =
  ExBitstringStatusList.new_status_list(
    purpose: "message",
    status_size: 2,
    status_messages: [
      %{"status" => "0x0", "message" => "pending_review"},
      %{"status" => "0x1", "message" => "accepted"},
      %{"status" => "0x2", "message" => "rejected"},
      %{"status" => "0x3", "message" => "undefined"}
    ],
    status_reference: "https://example.org/status-dictionary/"
  )

Serialize to a status list credential:

credential =
  ExBitstringStatusList.to_credential(status_list,
    id: "https://issuer.example/status/revocation",
    issuer: "did:web:issuer.example"
  )

Resolve status directly from the credential plus entry:

ExBitstringStatusList.status_from_credential(credential, entry)
# => :active | :revoked | integer

Resolve the Recommendation-shaped status result:

{:ok, result} = ExBitstringStatusList.resolve_status(credential, entry)

result.status
result.valid
result.message

Testing And Fixtures

The library is tested with:

• direct unit tests for Recommendation-shaped package behavior
• golden fixtures for deterministic credential examples
• released fixtures derived from W3C Recommendation examples and package-owned deterministic cases
• a release gate that verifies formatting, compile, tests, docs, and Hex package build

Normal mix test and normal library usage do not require Node, Rust, or network access. The committed released fixtures are the contract for currently supported package-owned behavior.

Run the local release gate with:

mix ex_bitstring_status_list.release.gate

Release Automation

The mirrored ex_bitstring_status_list repository is expected to carry:

• CI on push and pull request
• a manual publish workflow

The publish workflow should be triggered through workflow_dispatch after the version and changelog are ready. It publishes to Hex first and then creates the matching Git tag and GitHub release automatically. It expects a HEX_API_KEY repository secret in the standalone ex_bitstring_status_list repository.

Releasing From GitHub

Releases are cut from the public github.com/bawolf/ex_bitstring_status_list repository, not from the private monorepo checkout.

The shortest safe path is:

1. finish the change in libs/ex_bitstring_status_list
2. run scripts/release_preflight.sh
3. sync and verify the standalone repo with scripts/sync_standalone_repo.sh and scripts/verify_standalone_repo.sh
4. push the mirrored release commit to main in github.com/bawolf/ex_bitstring_status_list
5. in GitHub, go to Actions, choose Publish, and run it with the version from mix.exs

The GitHub workflow is responsible for:

• rerunning the release gate
• publishing to Hex
• creating the matching git tag
• creating the matching GitHub release

Maintainer Workflow

ex_bitstring_status_list is developed in the delegate monorepo. The public github.com/bawolf/ex_bitstring_status_list repository is the mirrored OSS surface for issues, discussions, releases, and Hex publishing.

The monorepo copy is authoritative for:

• code
• tests and fixtures
• docs
• GitHub workflows
• release tooling

Direct standalone-repo edits are temporary hotfixes only and must be backported to the monorepo immediately.

The intended workflow is:

1. make library changes in libs/ex_bitstring_status_list
2. run scripts/release_preflight.sh
3. sync the package into a clean checkout of github.com/bawolf/ex_bitstring_status_list
4. verify the mirrored required file set with scripts/verify_standalone_repo.sh
5. review and push from the standalone repo
6. trigger the publish workflow from the standalone repo

A helper to sync all public package repos from the monorepo lives at /Users/bryantwolf/workspace/delegate/scripts/sync_public_libs.sh.