astrid-runtime/astrid · warning

capsule '{}' is {}; explicit local approval is required

Error message

capsule '{}' is {}; explicit local approval is required

What it means

authorize_install grants Automatic authority only to artifacts with LocalRuntime provenance (built locally by the runtime). For any other provenance (downloaded, shared, etc.), the library requires the user to explicitly approve the capsule and names its provenance label in the message. This is a supply-chain safeguard: unattended auto-approval is limited to artifacts the user's own runtime produced.

Source

Thrown at crates/astrid-capsule-install/src/authority.rs:803

}

/// Convert a bound decision into the receipt persisted by the installer.
///
/// # Errors
///
/// `Automatic` rejects foreign and unsigned artifacts. Bound decisions reject
/// a digest mismatch, preventing a changed artifact from reusing an approval.
pub fn authorize_install(
    inspection: &InstallInspection,
    decision: &AuthorityDecision,
) -> anyhow::Result<InstalledAuthority> {
    let source = match decision {
        AuthorityDecision::Automatic => {
            if !matches!(
                inspection.provenance,
                ArtifactProvenance::LocalRuntime { .. }
            ) {
                bail!(
                    "capsule '{}' is {}; explicit local approval is required",
                    inspection.capsule_id,
                    inspection.provenance.label()
                );
            }
            AuthoritySource::LocalRuntimeBuild
        },
        AuthorityDecision::ExplicitApproval { content_digest } => {
            ensure_bound_digest(inspection, content_digest)?;
            AuthoritySource::ExplicitApproval
        },
        AuthorityDecision::OperatorDistribution { content_digest } => {
            ensure_bound_digest(inspection, content_digest)?;
            AuthoritySource::OperatorDistribution
        },
    };
    let (signer, signature) = match &inspection.provenance {
        ArtifactProvenance::LocalRuntime { signer, signature }

View on GitHub (pinned to affd8760f4)

Solutions

1. Run the install with the explicit local approval flag/flow to approve the capsule's provenance interactively or via config
2. Build the capsule locally so its provenance is LocalRuntimeBuild and auto-approval applies
3. If the capsule is trusted, pre-approve its id/digest in the approval store before calling authorize_install

Example fix

// before
unpack_and_install_authorized_for_principal_in_workspace(&home, &url, &principal)?; // remote capsule
// after
unpack_and_install_checked_authorized_for_principal_in_workspace(&home, &url, &principal, /* explicit_approval: */ true)?;

let inspection = inspect_capsule(&artifact)?;
if matches!(decision, AuthorityDecision::Automatic) && !matches!(inspection.provenance, ArtifactProvenance::LocalRuntime { .. }) {
    // plan an explicit approval step before installing
}

fn is_local_runtime(p: &ArtifactProvenance) -> bool {
    matches!(p, ArtifactProvenance::LocalRuntime { .. })
}

match authorize_install(&home, &artifact) {
    Err(e) if e.to_string().contains("explicit local approval is required") => {
        prompt_user_approval(&inspection)?;
        authorize_install(&home, &artifact)?
    }
    Ok(a) => a,
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling authorize_install (directly or via unpack_and_install_authorized_for_principal_in_workspace and friends) when the resolved AuthorityDecision is Automatic but inspection.provenance is not ArtifactProvenance::LocalRuntime.

Common situations: Installing a capsule fetched from a registry or shared by a colleague and expecting silent auto-approval; scripting installs of third-party capsules without an approval step; CI pipelines installing remote capsules unattended.

Related errors

• manifest exceeds its installed capability approval: {details
• installed WASM executable differs from its authority receipt
• capsule provenance changed after authority decision
• durable capsule {id} provenance differs from authority recei
• durable capsule {id} authority claims provenance absent from

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/67c1305622788d63. Report an issue: GitHub.