keystate-core 0.1.0

Canonical model, extraction ports, completeness verification, and idempotent output for Keystate.
Documentation

keystate-core

CI

Canonical domain model, extraction ports, completeness verification, and idempotent output for Keystate — a read-only tool that pulls the complete, verified configuration state of an IAM system out of its database as a single backend-agnostic JSON document.

keystate-core is the contract crate. It is backend-agnostic by design and carries no tokio and no sqlx dependency. Adapters (separate repos) depend on it, implement its ports, and are composed by keystate-cli.

Full design: ARCHITECTURE.md · workflow: DEVELOPMENT.md · releases: RELEASE.md

Module map

Module Responsibility
model/ Canonical entities (one file per entity) + extraction envelope
port/ The traits adapters implement: Extractor, CompletenessVerifier, OutputSink (one file per port)
verify/ Manifests, reports, the shared verification engine, path resolution
canonical/ Byte-stable serialization, the config/volatile split, content hash
testing/ Shared contract-test suite every adapter runs in CI
error/ · version/ Cross-cutting types

The model

Every entity carries a thin set of common fields — enough for cross-backend comparison, reporting and audit, including the canonical identity key — plus a single open escape hatch:

pub struct Client {
    pub id: String,        // stable sort key
    pub client_id: String, // cross-backend identity key
    pub enabled: bool,
    pub native: serde_json::Value, // backend-faithful representation, adapter-owned
}

Common fields are the rule, not a per-adapter judgment. Once a field shows up in native for two or more backends it becomes a promotion candidate into common (additive minor bump) — see ARCHITECTURE.md §3.1. There is no second extra field.

Quick use

use keystate_core::{
    FieldExpectation, FieldManifest, ManifestVerifier, EntityKind, Version,
};

let mut manifest = FieldManifest::new("keycloak", Version::new(26, 0, 0));
manifest.fields.push(FieldExpectation {
    entity: EntityKind::Client,
    path: "native.secret".into(),
    required: true,
    volatile: false,
    introduced_in: Version::new(1, 0, 0),
});

let report = ManifestVerifier.verify(&realm, &manifest)?;
assert!(report.is_complete());

An adapter implements Extractor, CompletenessVerifier::expected_fields, and optionally picks an OutputSink. The completeness claim is part of the output (VerificationReport), and every extraction can be fingerprinted with content_hash(realm) — which ignores the volatile section, so last-login churn never appears as configuration drift.

Semver contract

keystate-core is what every adapter pins against:

  • Major — a common-model field/struct removed or changed incompatibly.
  • Minor — a common field/struct added additively (including promotions).
  • Patch — bug fix, no model change.

Promotions carry a release-train obligation (all live adapters move together before any CLI tags) so version skew is never misread as drift. See RELEASE.md.

Testing

cargo test runs unit tests for every module. Adapters additionally import the testing contract suite (determinism roundtrip, volatile segregation, manifest self-consistency, verification completeness) and pass their own integration tests against real fixture databases with testcontainers.