generated from coulomb/repo-seed
120 lines
4.3 KiB
Markdown
120 lines
4.3 KiB
Markdown
# Markitect Integration Flow
|
|
|
|
This document describes how Markitect should use flex-auth as its first
|
|
protected-system consumer integration.
|
|
|
|
## 1. Publish Resources
|
|
|
|
Markitect emits a `FlexAuthResourceManifest` for each knowledge base or
|
|
resource slice it wants flex-auth to authorize. The emitted manifest should use
|
|
the namespace in `docs/markitect-resource-namespace.md` and include:
|
|
|
|
- stable resource ids such as `document:internal-note`
|
|
- resource type and parent links
|
|
- path, labels, trust zone, owner, and durable backend metadata
|
|
- `metadata.flex_auth_contract: resource-registration-v0`
|
|
- `caring_profile: caring-0.4.0-rc2` when the emitter can provide it
|
|
|
|
flex-auth imports the manifest through `internal/markitect.ImportResourceManifest`.
|
|
The importer enriches resources with CARING scope and plane classification and
|
|
returns diagnostics when a resource type, trust zone, label set, or CARING
|
|
profile is missing or ambiguous.
|
|
|
|
## 2. Submit Check Requests
|
|
|
|
For one resource, Markitect submits `CheckRequest`:
|
|
|
|
```text
|
|
subject + action + resource + context + optional caring_context
|
|
```
|
|
|
|
For repeated checks, Markitect submits `BatchCheckRequest` with the same
|
|
subject/action/context and a resource list. Resource order is preserved in the
|
|
response.
|
|
|
|
Markitect should pass local frontmatter and backend metadata as resource
|
|
attributes when they affect policy:
|
|
|
|
- `labels`
|
|
- `trust_zone`
|
|
- `markitect_path`
|
|
- `frontmatter_visibility`
|
|
- `source_revision`
|
|
- `workflow_state`
|
|
- `freshness_seconds`
|
|
- `data_classes`
|
|
|
|
Subject roles and groups should be normalized into subject attributes or loaded
|
|
into the registry as subject/group/team manifests. CARING dimensions should be
|
|
attached as `caring_context` when Markitect already knows the intended
|
|
descriptor; otherwise flex-auth can derive descriptors from relationship facts.
|
|
|
|
## 3. Enforce Decisions
|
|
|
|
Markitect maps flex-auth decision envelopes into its gateway contract with
|
|
`internal/markitect.ToGatewayDecision`.
|
|
|
|
Expected effects:
|
|
|
|
- `allow`: render, answer, package, activate, export, or run workflow.
|
|
- `deny`: block the operation.
|
|
- `redact`: continue with returned obligations such as `mask_fields`.
|
|
- `audit_denied`: block or quarantine while preserving an audit-grade record.
|
|
|
|
Markitect should enforce obligations before exposing data. For example, a
|
|
`mask_fields` obligation must be applied before rendering or model use, and a
|
|
`record_context_activation` obligation must be logged when a context package is
|
|
activated.
|
|
|
|
## 4. Record Decision IDs
|
|
|
|
Every gateway operation should persist the flex-auth decision id alongside the
|
|
Markitect request id, workflow id, rendered artifact id, or export id.
|
|
|
|
At minimum, always record:
|
|
|
|
- denies
|
|
- redactions
|
|
- exports
|
|
- context package activations
|
|
- workflow runs
|
|
- support, break-glass, or other CARING exposure events
|
|
|
|
The local flex-auth JSONL log is suitable for local development. Markitect may
|
|
also write the same decision id into its own event log.
|
|
|
|
## 5. Explain Decisions
|
|
|
|
When users need an explanation, Markitect can call flex-auth `explain` or use
|
|
the decision id to retrieve the persisted envelope and project it with
|
|
`ToGatewayDecision`.
|
|
|
|
Explanations should preserve CARING language:
|
|
|
|
- subject relation and canonical role, for example `Customer Doer`
|
|
- scope, for example `Resource document:internal-note`
|
|
- plane, for example `Data`
|
|
- capability, for example `View` or `Export`
|
|
- exposure mode, for example `Masked`, `Plaintext`, or `Exportable`
|
|
- restrictions, conditions, and conformance findings
|
|
|
|
Example explanation:
|
|
|
|
```text
|
|
Customer Doer may View Data Plane resource document:internal-note because reader_group.
|
|
```
|
|
|
|
## Local Mapping Summary
|
|
|
|
| Markitect local concept | flex-auth field | CARING dimension |
|
|
| --- | --- | --- |
|
|
| frontmatter visibility | `resource.attributes.frontmatter_visibility` | Exposure mode hint |
|
|
| document labels | `resource.attributes.labels` | Scope and exposure hint |
|
|
| owner/steward | `resource.owner`, subject groups/roles | Canonical role and relation |
|
|
| workflow state | `resource.attributes.workflow_state`, request context | Lifecycle/condition hint |
|
|
| context freshness | `request.context.freshness_seconds` | Condition and conformance finding |
|
|
| export request | `action: export` | `Export` capability and `Exportable` exposure |
|
|
|
|
The examples in `examples/markitect/` are the executable contract fixtures for
|
|
this flow.
|