trustgraph/docs/tech-specs
cybermaggedon 9fc1d4527b
iam: self-service ops, optional workspace filters, Mux service routing (#855)
Three threads, all reinforcing the contract's system-level vs.
workspace-association distinction.

WS Mux service routing
- tg-show-flows (and any workspace-level service over the WS) was
  failing with "unknown service" because the post-refactor Mux
  unconditionally looked up flow-service:<kind>.  Now branches on
  the envelope's flow field: with flow → flow-service:<kind>;
  without flow → <kind>:<op> from the inner body; with bare op
  lookup for service=iam.  Resource and parameters come from the
  matched op's own extractors — same path the HTTP endpoints take.

Optional workspace on system-level user/key ops
- list-users returns the deployment-wide list when no workspace is
  supplied, filters when one is.  get-user, update-user,
  disable-user, enable-user, delete-user, reset-password,
  create-api-key, list-api-keys, revoke-api-key all treat workspace
  as an optional integrity check rather than a required argument.
- create-user keeps workspace required — there it's the new user's
  home-workspace binding, a parameter rather than an address.
- API keys reclassified as SYSTEM-level resources.  By the same
  reasoning that makes users system-level, an API key is a
  credential record on a deployment-wide registry; the workspace it
  authenticates to is a property, not a containment.

Self-service surface
- whoami: returns the caller's own user record.  AUTHENTICATED-only;
  no users:read capability required.  Foundation for UI affordances
  that depend on the caller's permissions.
- bootstrap-status: POST /api/v1/auth/bootstrap-status, PUBLIC,
  side-effect-free.  Returns {bootstrap_available: bool} so a
  first-run UI can decide whether to render setup without consuming
  the bootstrap op.
- Gateway now injects actor=identity.handle on every authenticated
  forward to iam-svc (IamEndpoint and WS Mux iam path), overwriting
  any caller-supplied value.  Underpins whoami, audit logging, and
  future regime-side decisions that need actor identity.
- tg-whoami and tg-update-user CLIs.

Spec polish
- iam-contract.md: actor-injection rule documented; whoami /
  bootstrap-status added to operations list; permission-scope
  framing tightened (workspace scope is a property of the grant,
  not the user or role).
- iam.md: self-service section; gateway flow gains the actor-
  injection step; role section reframed so iam-svc constraints
  don't leak into contract-level prose.
- iam-protocol.md: ops table updated for whoami, bootstrap-status,
  optional-workspace pattern; bootstrap_available added to the
  IamResponse listing.
2026-04-28 22:13:12 +01:00
..
ar Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
es Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
he Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
hi Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
pt Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
ru Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
sw Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
tr Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
zh-cn Structure the tech specs directory (#836) 2026-04-21 16:06:41 +01:00
__TEMPLATE.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
active-flow-key-restructure.md Flow service lifecycle management (#822) 2026-04-16 17:19:39 +01:00
agent-explainability.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
agent-orchestration.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
architecture-principles.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
bootstrap.md feat: pluggable bootstrap framework with ordered initialisers (#847) 2026-04-22 18:03:46 +01:00
capabilities.md refactor(iam): pluggable IAM regime via authenticate/authorise contract (#853) 2026-04-28 16:19:41 +01:00
cassandra-consolidation.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
cassandra-performance-refactor.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
collection-management.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
config-push-poke.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
data-ownership-model.md refactor(iam): pluggable IAM regime via authenticate/authorise contract (#853) 2026-04-28 16:19:41 +01:00
document-embeddings-chunk-id.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
embeddings-batch-processing.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
entity-centric-graph.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
explainability-cli.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
extraction-flows.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
extraction-provenance-subgraph.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
extraction-time-provenance.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
flow-blueprint-definition.md refactor(iam): pluggable IAM regime via authenticate/authorise contract (#853) 2026-04-28 16:19:41 +01:00
flow-configurable-parameters.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
flow-service-queue-lifecycle.md Flow service lifecycle management (#822) 2026-04-16 17:19:39 +01:00
graph-contexts.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
graphql-query.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
graphrag-performance-optimization.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
iam-contract.md iam: self-service ops, optional workspace filters, Mux service routing (#855) 2026-04-28 22:13:12 +01:00
iam-protocol.md iam: self-service ops, optional workspace filters, Mux service routing (#855) 2026-04-28 22:13:12 +01:00
iam.md iam: self-service ops, optional workspace filters, Mux service routing (#855) 2026-04-28 22:13:12 +01:00
import-export-graceful-shutdown.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
jsonl-prompt-output.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
kafka-backend.md Add Kafka pub/sub backend (#830) 2026-04-18 11:18:34 +01:00
large-document-loading.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
logging-strategy.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
mcp-tool-arguments.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
mcp-tool-bearer-token.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
minio-to-s3-migration.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
more-config-cli.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
multi-tenant-support.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
neo4j-user-collection-isolation.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
ontology-extract-phase-2.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
ontology.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
ontorag.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
openapi-spec.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
pubsub-abstraction.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
pubsub.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
python-api-refactor.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
query-time-explainability.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
rag-streaming-support.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
schema-refactoring-proposal.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
sparql-query.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
streaming-llm-responses.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
structured-data-2.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
structured-data-descriptor.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
structured-data-schemas.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
structured-data.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
structured-diag-service.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
tool-group.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
tool-services.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
universal-decoder.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00
vector-store-lifecycle.md Feat: TrustGraph i18n & Documentation Translation Updates (#781) 2026-04-14 12:08:32 +01:00