# 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

```sh
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:

```sh
docker compose down -v
```

## What the example proves

- Topaz's v3 manifest can express flex-auth's canonical object types
  (`user`, `identity`, `group`, `tenant`, `knowledge_base`, `document`)
  and relations (`identifier`, `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.