App Artifact Trust and Promotion v1¶
As of: March 9, 2026
Purpose¶
Define the trust and promotion baseline for app-platform artifacts.
This baseline applies to both: 1. OCI artifacts, and 2. future non-OCI artifacts registered through the same control-plane artifact model.
Scope¶
In scope: 1. artifact trust states, 2. promotion channels and environment progression, 3. verification requirements, 4. policy hooks, 5. audit requirements.
Out of scope: 1. final signing provider implementation, 2. runtime enforcement implementation details for every adapter, 3. full provenance and attestation backend rollout.
Core Rules¶
- digest-only deployment remains mandatory.
- promotion is explicit and auditable.
- trust policy must support more than one environment.
- tags are convenience labels only, never deployment truth.
Artifact Trust Model¶
Each artifact has two independent dimensions: 1. lifecycle state 2. trust state
Lifecycle state remains:
1. published
2. promoted
3. deprecated
4. retired
Trust state baseline:
1. unverified
2. verified
3. failed_verification
4. revoked
Meaning:
1. unverified: digest is registered, but required verification has not completed yet.
2. verified: digest and required trust checks passed for the current policy.
3. failed_verification: verification was attempted and failed.
4. revoked: previously accepted artifact is no longer eligible for new use.
Verification Baseline¶
Minimum required verification: 1. immutable digest must be present, 2. digest format must be canonical, 3. artifact kind and source type must be explicit, 4. source must be policy-allowlisted.
Reserved trust inputs: 1. OCI signature result, 2. attestation or provenance result, 3. blob digest verification result, 4. source-policy decision result.
The baseline does not require a single signing provider yet, but it does require the control plane to model verification as first-class metadata.
Promotion Model¶
Promotion is not an implicit consequence of publish.
Promotion dimensions:
1. channel
2. optional target_environment
Baseline channels:
1. dev
2. test
3. staging
4. prod
Rules:
1. promotion must record both source artifact and target channel,
2. promotion to a later channel must be explicit,
3. prod promotion must not be implied from published,
4. deprecated or retired artifacts are not promotable.
Policy Hooks¶
The trust and promotion model must reserve policy decisions for: 1. allowed source types, 2. required verification level per environment or channel, 3. which actors may promote to which channel, 4. whether non-OCI artifacts are allowed for a given project or runtime class.
Examples:
1. dev may allow unverified artifacts for a project sandbox.
2. prod may require verified plus attestation.
3. only project admins or approved service accounts may promote to prod.
Audit Requirements¶
Every trust and promotion mutation must record: 1. actor 2. project 3. artifact id 4. digest 5. artifact kind 6. source type 7. trust state transition or promotion target 8. correlation id
Required audit actions:
1. app_artifact.register
2. app_artifact.verify
3. app_artifact.promote
4. app_artifact.deprecate
5. app_artifact.retire
6. app_artifact.revoke
Environment Progression Baseline¶
The same artifact may move through multiple channels or environments.
Recommended baseline:
1. published in project scope
2. promoted to dev
3. promoted to test
4. promoted to staging
5. promoted to prod
The platform must preserve the promotion history as metadata or audit trail, not only the latest promoted channel.
Non-Negotiable Invariants¶
- deployments use digest, not mutable tag,
- promotion is explicit and auditable,
- trust is modeled separately from lifecycle state,
- the trust model works for OCI and non-OCI artifacts,
- environment progression is not hardcoded to one environment forever.
Related Docs¶
doc/architecture/App_Platform_OCI_Registry_Baseline_v1.mddoc/architecture/App_Non_OCI_Artifact_Lifecycle_v1.mddoc/architecture/App_Platform_Gap_Tracker_v1.mddoc/architecture/Platform_Vault_Secrets_Baseline_v1.md