Release readiness polish

docs/release-security-configuration-storage-review.md

@@ -0,0 +1,114 @@
+# 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.