FFI Bindings for Integrity Core

.github/workflows/ci-check.yml

@@ -47,6 +47,9 @@ jobs:
       - name: build
         run: nix develop . -c just build
 
+      - name: build-ffi-feature
+        run: nix develop . -c cargo check --locked --features ffi
+
       - name: build-wasm
         run: nix develop . -c just build-wasm
 

.github/workflows/release-native-ffi.yml

@@ -0,0 +1,195 @@
+name: Release Native FFI Artifacts
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and package release artifacts without publishing a GitHub release"
+        required: true
+        default: true
+        type: boolean
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build (${{ matrix.label }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            label: linux x86_64
+            asset_suffix: linux-x86_64
+            lib_path: target/release/libintegrity.so
+            lib_name: libintegrity.so
+            import_lib_candidates: ""
+          - os: macos-13
+            label: macos 13 x86_64
+            asset_suffix: macos-13-x86_64
+            lib_path: target/release/libintegrity.dylib
+            lib_name: libintegrity.dylib
+            import_lib_candidates: ""
+          - os: macos-14
+            label: macos 14 aarch64
+            asset_suffix: macos-14-aarch64
+            lib_path: target/release/libintegrity.dylib
+            lib_name: libintegrity.dylib
+            import_lib_candidates: ""
+          - os: macos-15-intel
+            label: macos 15 x86_64
+            asset_suffix: macos-15-x86_64
+            lib_path: target/release/libintegrity.dylib
+            lib_name: libintegrity.dylib
+            import_lib_candidates: ""
+          - os: macos-15
+            label: macos 15 aarch64
+            asset_suffix: macos-15-aarch64
+            lib_path: target/release/libintegrity.dylib
+            lib_name: libintegrity.dylib
+            import_lib_candidates: ""
+          - os: windows-2022
+            label: windows x86_64
+            asset_suffix: windows-x86_64
+            lib_path: target/release/integrity.dll
+            lib_name: integrity.dll
+            import_lib_candidates: "target/release/integrity.lib target/release/integrity.dll.lib target/release/libintegrity.dll.a"
+
+    steps:
+      - name: Install Nix
+        uses: eqtylab-actions/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Cachix
+        uses: eqtylab-actions/cachix-action@v14
+        with:
+          name: eqtylab
+          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
+          skipPush: true
+        continue-on-error: true
+
+      - name: Checkout repo
+        uses: eqtylab-actions/checkout@v4
+
+      - name: Rust cache
+        uses: eqtylab-actions/rust-cache@v2
+
+      - name: Build release cdylib
+        run: nix develop . -c cargo build --release --locked
+
+      - name: Stage artifact files
+        shell: bash
+        run: |
+          nix develop . -c bash -euxo pipefail <<SCRIPT_EOF
+          pkg="integrity-ffi-${{ matrix.asset_suffix }}"
+          out_dir="dist/${pkg}"
+          mkdir -p "${out_dir}"
+
+          cp "${{ matrix.lib_path }}" "${out_dir}/${{ matrix.lib_name }}"
+          cp include/integrity_ffi.h "${out_dir}/integrity_ffi.h"
+          cp LICENSE "${out_dir}/LICENSE"
+
+          for candidate in ${{ matrix.import_lib_candidates }}; do
+            if [ -f "${candidate}" ]; then
+              cp "${candidate}" "${out_dir}/"
+            fi
+          done
+
+          cat > "${out_dir}/BUILD_INFO.txt" <<BUILD_INFO_EOF
+          crate=integrity
+          git_ref=${GITHUB_REF}
+          git_sha=${GITHUB_SHA}
+          runner_os=${RUNNER_OS}
+          asset_suffix=${{ matrix.asset_suffix }}
+          BUILD_INFO_EOF
+          SCRIPT_EOF
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: integrity-ffi-${{ matrix.asset_suffix }}
+          path: dist/integrity-ffi-${{ matrix.asset_suffix }}
+          if-no-files-found: error
+
+  package:
+    name: Package Release Bundles
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Nix
+        uses: eqtylab-actions/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Cachix
+        uses: eqtylab-actions/cachix-action@v14
+        with:
+          name: eqtylab
+          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
+          skipPush: true
+        continue-on-error: true
+
+      - name: Checkout repo
+        uses: eqtylab-actions/checkout@v4
+
+      - name: Download all build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: release-artifacts
+          pattern: integrity-ffi-*
+
+      - name: Package tarballs + checksums
+        shell: bash
+        run: |
+          nix develop . -c bash -euxo pipefail <<SCRIPT_EOF
+          mkdir -p release
+
+          for dir in release-artifacts/*; do
+            [ -d "${dir}" ] || continue
+            base="$(basename "${dir}")"
+            tar -czf "release/${base}.tar.gz" -C release-artifacts "${base}"
+          done
+
+          sha256sum release/*.tar.gz > release/SHA256SUMS.txt
+          SCRIPT_EOF
+
+      - name: Upload packaged release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: integrity-ffi-release-bundles
+          path: |
+            release/*.tar.gz
+            release/SHA256SUMS.txt
+          if-no-files-found: error
+
+      - name: Dry-run summary
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+        run: |
+          echo "Dry-run enabled: packaged artifacts were uploaded and no GitHub release will be created."
+
+  publish-release:
+    name: Publish GitHub Release Assets
+    needs: package
+    runs-on: ubuntu-latest
+    if: >-
+      startsWith(github.ref, 'refs/tags/') &&
+      !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
+    steps:
+      - name: Download packaged release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: release
+          name: integrity-ffi-release-bundles
+
+      - name: Upload release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            release/**/*.tar.gz
+            release/**/SHA256SUMS.txt

Cargo.toml

@@ -8,6 +8,7 @@ crate-type = ["rlib", "cdylib"]
 
 [features]
 default = []
+ffi = []
 s3 = []
 tokio-tests = []
 

README.md

@@ -25,6 +25,7 @@ The schema is defined in <https://github.com/eqtylab/integrity-schema>
 ### Usage
 
 The Integrity Graph common context is referenced in code via:
+
 ```rust
 use integrity::json_ld::ig_common_context_link;
 
@@ -33,19 +34,62 @@ let context_urn = ig_common_context_link();
 ```
 
 These contexts are embedded at compile time and used by the JSON-LD processor to:
+
 - Expand compact JSON-LD documents to their canonical form
 - Resolve context references without network requests
 - Ensure deterministic content addressing of linked data
 
 ### Regenerating Contexts
 
 To update the static contexts (e.g., after schema changes):
+
 ```bash
 just update-static-contexts
 ```
 
 This downloads the latest W3C contexts and regenerates the CID-indexed files.
 
+## FFI (C ABI)
+
+The crate includes a stable C ABI surface in `src/ffi/` for SDK bindings (including the Go SDK).
+FFI is feature-gated and enabled with `--features ffi`.
+
+- Public header: `include/integrity_ffi.h`
+- ABI version functions:
+  - `ig_abi_version_major`
+  - `ig_abi_version_minor`
+  - `ig_abi_version_patch`
+  - `ig_abi_version_string`
+- Runtime and handle model:
+  - Create one runtime with `ig_runtime_new`
+  - Create and reuse opaque handles (signers, blob stores)
+  - Release memory with `ig_string_free`, `ig_error_free`, `ig_bytes_free`
+  - Release handles with their corresponding `*_free` function
+
+The current ABI version is `0.2.0`.
+
+### Native Artifact Releases
+
+GitHub Actions can publish prebuilt native FFI artifacts for each supported system:
+
+- Linux x86_64 (`libintegrity.so`)
+- macOS 13 x86_64 (`libintegrity.dylib`)
+- macOS 14 aarch64 (`libintegrity.dylib`)
+- macOS 15 x86_64 (`libintegrity.dylib`)
+- macOS 15 aarch64 (`libintegrity.dylib`)
+- Windows x86_64 (`integrity.dll` plus import library when produced)
+
+Workflow: `.github/workflows/release-native-ffi.yml`
+
+- Push a version tag like `v0.2.0` to build and attach release assets to that GitHub Release.
+- Use `workflow_dispatch` to run the build matrix and collect workflow artifacts without publishing a Release.
+
+Build native FFI artifacts locally:
+
+```bash
+cargo build --release --locked --features ffi
+```
+
 # Development
 
 Nix flake creates a dev environment with all the dependencies.