generated from coulomb/repo-seed
tegwick
82177d88a9
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>
100 lines
3.5 KiB
Markdown
100 lines
3.5 KiB
Markdown
# 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`, `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.
|