Files

tegwick 82177d88a9 Topaz alignment spike — mapping doc + green e2e example

Closes FLEX-WP-0005 T04. Validates ADR-003's commitment to shape the
standalone core for cheap Topaz adapter work.

Spike output:
- docs/topaz-mapping-spike.md — vocabulary map (subject, group, tenant,
  knowledge_base, document, plus parent / owner_team / reader / steward /
  member relations), Rego module shape, decision envelope, wire-protocol
  ranking (gRPC primary, REST fallback, embedding rejected), schema
  restatement recommendation, implications for FLEX-WP-0002 / 0004.
- examples/topaz/ — runnable docker-compose deploying Topaz with the
  flex-auth-shaped manifest. seed and probe one-shots cover three
  scenarios: alice (steward) allow, bob (group→reader) allow, eve
  (outsider) deny. End-to-end green on 2026-05-16:

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

Key findings recorded as Implementation Notes in the spike doc:
- Rego input contract bridging (Topaz raw shape ↔ flex-auth canonical
  shape) is adapter scope, not core scope.
- Topaz identity objects are a Topaz convention; the adapter
  materializes them at directory import time.
- Directory-only permission resolution is sufficient for the common
  case; Rego is reserved for context-dependent decisions.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-16 09:04:42 +02:00

3.5 KiB

Raw Blame History

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.

3.5 KiB Raw Blame History