flex-auth/examples/topaz

Topaz alignment example

Runnable validation for the alignment commitment in ADR-003 and the mapping recorded in docs/topaz-mapping-spike.md. Boots Topaz, seeds a directory shaped like flex-auth's canonical vocabulary, and probes three permission scenarios.

Quick start

cd examples/topaz
docker compose up --abort-on-container-exit --exit-code-from probe

Expected outcome (exit code 0):

probe-1  | probe: steward-allow OK (check=true)
probe-1  | probe: reader-allow  OK (check=true)
probe-1  | probe: outsider-deny OK (check=false)
probe-1  | probe: all checks passed

Tear down:

docker compose down -v

What the example proves

• Topaz's v3 manifest can express flex-auth's canonical object types (user, group, tenant, knowledge_base, document) and relations (member, parent, owner_team, reader, steward).
• The Markitect fixture data (examples/markitect/resource_manifest.yaml, mirrored here) seeds the directory without translation.
• Group→reader edges (reader:platform-architecture group with a member relation, plus a reader relation from the document to that group with subject_relation=member) resolve correctly via the manifest's reader | group#member union.
• The check decision is fully derivable from directory data for the read-path case; no Rego is involved.

File map

manifest.yaml              # Topaz v3 directory manifest
policy/markitect.documents.rego   # Rego module showing flex-auth's
                                  # canonical input shape (used by the
                                  # standalone evaluator; FLEX-WP-0004
                                  # T01 will bridge to Topaz's input)
bundle/                    # OPA bundle loaded into Topaz
bundle/.manifest           # OPA bundle root manifest
bundle/policy/markitect.documents.rego   # same Rego, mounted into Topaz
data/objects.json          # seed objects
data/relations.json        # seed relations
cfg/config.yaml            # Topaz config
scripts/seed.sh            # writes manifest + objects + relations
scripts/probe.sh           # three directory checks via REST
docker-compose.yml         # topaz, seed (one-shot), probe (one-shot)

Ports

When running, Topaz exposes (on 127.0.0.1 only):

Port	Service
8282	authorizer gRPC
8383	authorizer REST
9292	directory gRPC (reader, writer, model, exporter, importer)
9393	directory REST gateway
9494	health
9696	metrics

Plaintext HTTP on the gateways. Internal gRPC uses TLS with auto-generated self-signed certs in a topaz-certs named volume; the remote_directory.insecure: true flag tells the in-process clients to accept them.

Caveats

• Plaintext gateways are for the spike only. Real deployments use certs everywhere; see docs/topaz-mapping-spike.md §"Wire-Protocol Candidates" for the production posture.
• The probe deliberately uses the directory check API instead of the authorizer is API. Bridging flex-auth's Rego input shape into Topaz's raw authorizer input is the Topaz adapter's job (FLEX-WP-0004 T01) and is intentionally out of scope for this validation. See docs/topaz-mapping-spike.md §"Implementation Notes Surfaced By The Spike".

Pinned Topaz version

ghcr.io/aserto-dev/topaz:latest as resolved on 2026-05-16 (digest sha256:11fa7e2075870f3fe523afaadd942a6559b612f44b6bdb1296fe65299f5831fa). FLEX-WP-0004 T01 will pin a specific tagged version once the adapter lands.