generated from coulomb/repo-seed
115 lines
4.4 KiB
Markdown
115 lines
4.4 KiB
Markdown
# Release Security, Configuration, And Storage Review
|
|
|
|
Date: 2026-05-14
|
|
Release: `0.1.0` controlled preview
|
|
Status: reviewed for release readiness
|
|
|
|
## Security Boundary
|
|
|
|
`kontextual-engine` uses explicit operation contexts, actor metadata, profile
|
|
gates, policy decisions, and audit records. The preview release is suitable for
|
|
controlled integrations, not anonymous internet exposure.
|
|
|
|
Production-facing deployments must provide:
|
|
|
|
- HTTPS termination for CMIS and native API access,
|
|
- authentication and trusted actor-header injection at the edge,
|
|
- request logging without leaking secrets or content bytes,
|
|
- restricted network exposure for admin/export profiles,
|
|
- backup and restore procedures for registry and blob storage.
|
|
|
|
## CMIS Access-Point Profiles
|
|
|
|
| Profile | Exposure | Release note |
|
|
| --- | --- | --- |
|
|
| `readonly-browser` | Public/internal read subset; no mutations. | Safe default profile for controlled read clients. |
|
|
| `governed-authoring` | Public/internal read plus governed object/content mutations. | Requires authenticated actors and policy review before external use. |
|
|
| `admin-export` | Broad sensitivity visibility, service-account actor type required. | Must not be exposed to general users; service-account routing only. |
|
|
| `compat-tck` | Browser Binding compatibility profile with selected mutation support. | Intended for OpenCMIS harness and compatibility testing, not normal production traffic. |
|
|
|
|
CMIS optional capabilities are advertised conservatively. Unsupported services
|
|
return structured CMIS diagnostics rather than partial silent behavior.
|
|
|
|
## Actor Headers
|
|
|
|
The service runtime accepts actor context through headers such as:
|
|
|
|
- `X-Actor-Id`,
|
|
- `X-Actor-Type`,
|
|
- `X-Actor-Display-Name`,
|
|
- `X-Actor-Groups`,
|
|
- `X-Delegated-Actor-*`,
|
|
- `X-Correlation-Id`,
|
|
- `X-Request-Scope`,
|
|
- `X-Policy-Scope`.
|
|
|
|
These headers are trust-bearing. A production gateway must authenticate the
|
|
caller, strip inbound spoofed actor headers, and inject the trusted actor
|
|
context itself. Service-account routes such as `admin-export` must be restricted
|
|
to service-account identities.
|
|
|
|
## Secrets
|
|
|
|
No committed example, target profile, or runtime default embeds service secrets.
|
|
The OpenCMIS harness currently uses anonymous local loopback access for the
|
|
compatibility profile. S3 credentials must come from the deployment environment,
|
|
standard AWS provider chain, or secret manager, not from repository files.
|
|
|
|
## Storage Configuration
|
|
|
|
Supported storage posture:
|
|
|
|
- `InMemoryAssetRegistryRepository` and `InMemoryBlobStorage`: tests and local
|
|
smoke only; no persistence.
|
|
- `SQLiteAssetRegistryRepository`: local-first durable preview registry.
|
|
- `LocalBlobStorage`: content-addressed local blob root with digest-derived
|
|
paths.
|
|
- `S3BlobStorage`: optional `kontextual-engine[s3]` backend using
|
|
digest-derived object keys behind the blob port.
|
|
|
|
The domain model stores representation metadata and `storage_ref`; the blob
|
|
backend is an infrastructure choice.
|
|
|
|
## Backup And Restore Expectations
|
|
|
|
For a durable preview:
|
|
|
|
- back up the registry database and blob storage together at a consistent point,
|
|
- record the package version, configuration, and active access-point profiles,
|
|
- for local blobs, back up the complete content-addressed root,
|
|
- for S3, enable bucket versioning or object-lock-equivalent safeguards where
|
|
available,
|
|
- restore registry and blob storage into a staging environment before declaring
|
|
backup coverage sufficient.
|
|
|
|
Blob cleanup must use dry-run first. Active cleanup may delete only blobs proven
|
|
unreferenced by the registry.
|
|
|
|
## Dependency And Packaging Review
|
|
|
|
Default install dependencies:
|
|
|
|
- `pydantic>=2.0`.
|
|
|
|
Release extras:
|
|
|
|
- `service`: FastAPI, HTTPX, Uvicorn.
|
|
- `storage`: SQLAlchemy.
|
|
- `s3`: Boto3.
|
|
- `dev`: Pytest.
|
|
- `markdown` and `llm`: local sibling-repository extras for this controlled
|
|
workspace preview.
|
|
|
|
The local sibling extras are explicit optional extras and are not needed for
|
|
the default or service install. Before publishing outside this workspace, either
|
|
replace those file URLs with published package references or omit those extras
|
|
from the published distribution.
|
|
|
|
## Release Decision
|
|
|
|
Security/configuration/storage posture is acceptable for a controlled preview
|
|
when deployed behind authenticated HTTPS routing with explicit durable storage
|
|
configuration and documented backup/restore procedures. It is not acceptable to
|
|
expose the default in-memory runtime or the `compat-tck` profile as a general
|
|
production endpoint.
|