feat(secret): register runtime secret scopes

MODULE.md

@@ -127,6 +127,9 @@ Full details: [paired-device lifecycle specification](docs/specs/device-pairing-
 ## Browser destination authorization (contract 1.28)
 Full details: [browser dial specification](docs/specs/browser-dial-contract-1.28.md).
 
+## Host skill-scan decisions (contract 1.29)
+Full details: [host skill-scan specification](docs/specs/skill-scan-contract-1.29.md).
+
 ## Confidential injected master resolution
 Full details: [`Confidential injected master resolution`](docs/module-crypto.md#confidential-injected-master-resolution).
 

README.md

@@ -37,6 +37,17 @@ when a lease expires or policy generation changes. Sensitive and local-only
 privacy modes deny this uninspectable traffic; TinyComputer remains responsible
 for enforcing the proxy and dialing the approved socket. See the
 [browser-dial contract specification](docs/specs/browser-dial-contract-1.28.md).
+Contract 1.29 adds the host-only `RegisterSecretScope2` member for adding a
+secret resolver bound to an already-live approval scope, without reinitializing
+the process-global secret registry. Approval-scope replacement or retirement
+revokes the associated secret handles and runtime registrations; see the
+[runtime secret-scope specification](docs/specs/runtime-secret-scopes-contract-1.29.md).
+
+Contract 1.29 adds `Check::SkillScan` so the trusted host can submit the scan
+verdict and exact bundle digest before an installed skill runs. `Block` is a
+content denial, `Warn` enters the host's approval flow, and `Pass` leaves the
+remaining policy checks authoritative. See the
+[host skill-scan specification](docs/specs/skill-scan-contract-1.29.md).
 
 Contract 1.6 supplies `Audit2`, `EvaluateAudited2` and `CheckAudited2` with
 authenticated exact audit callbacks and a bounded [native journal](crates/tinysecurity-audit/README.md).

crates/tinysecurity-approval/src/binding.rs

@@ -100,6 +100,19 @@ pub(crate) fn native_safe_call(request: &EvaluateRequest) -> Result<String> {
     }
     Ok(safe_call)
 }
+
+fn contains_blocked_skill_scan(checks: &[Check]) -> bool {
+    checks.iter().any(|check| {
+        matches!(
+            check,
+            Check::SkillScan {
+                verdict: tinysecurity_bus::SkillScanVerdict::Block,
+                ..
+            }
+        )
+    })
+}
+
 pub(crate) fn original(
     reg: &ApprovalScope2,
     request: &EvaluateRequest,
@@ -113,6 +126,7 @@ pub(crate) fn original(
         || request.call.arguments_json.len() > 32768
         || request.call.checks.is_empty()
         || request.call.checks.len() > 128
+        || contains_blocked_skill_scan(&request.call.checks)
         || (reg.ceiling == AccessTier::Read && request.caller.tier != AccessTier::Read)
         || (reg.ceiling == AccessTier::Write && request.caller.tier == AccessTier::Full)
         || request
@@ -137,7 +151,7 @@ pub(crate) fn original(
     args.sort_all_objects();
     let canonical = serde_json::to_string(&args).map_err(|_| Error::Invalid)?;
     let external = request.call.checks.iter().any(|check| match check {
-        Check::LocalDiagnostic {} => false,
+        Check::LocalDiagnostic {} | Check::SkillScan { .. } => false,
         Check::Path { write, .. } => *write,
         Check::HostAction {
             external_effect, ..

crates/tinysecurity-approval/src/engine.rs

@@ -760,7 +760,17 @@ impl Engine {
         now: u64,
         native: bool,
     ) -> Result<(Option<ApprovalRow2>, bool)> {
+        let scan_warning = request.request.call.checks.iter().any(|check| {
+            matches!(
+                check,
+                Check::SkillScan {
+                    verdict: tinysecurity_bus::SkillScanVerdict::Warn,
+                    ..
+                }
+            )
+        });
         let human_only = native
+            || scan_warning
             || matches!(
                 request.request.call.tool.as_str(),
                 "sandbox_host_network" | "device_crypto"
@@ -1172,6 +1182,14 @@ impl Engine {
         let entry = self.entry(id)?;
         Ok(self.registered(&entry))
     }
+    /// Return the current trusted scope snapshot for one live registration.
+    /// This is used by sibling module adapters that must bind a secondary
+    /// capability to the approval engine's canonical subject and generation.
+    /// # Errors
+    /// Rejects unknown registrations or poisoned approval state.
+    pub fn scope_snapshot(&self, id: &str) -> Result<ApprovalScope2> {
+        self.registration(id)
+    }
     fn validate_scope(scope: &ApprovalScope2) -> Result<()> {
         if scope.scope_id.len() != 32
             || !scope.scope_id.bytes().all(|b| b.is_ascii_hexdigit())

crates/tinysecurity-approval/src/engine_scopes_tests.rs

@@ -513,6 +513,33 @@ async fn host_tool_marker_is_an_external_effect_that_cron_cannot_reach() -> Resu
     Ok(())
 }
 
+#[tokio::test]
+async fn skill_scan_warning_enters_human_approval() -> Result<()> {
+    let (_, owner) = owner()?;
+    let mut auto_approve = register(7);
+    auto_approve.scope.auto_approve_all = true;
+    auto_approve.grants = grants(&["run_workflow"], &[]);
+    owner.register_scope(auto_approve).await?;
+
+    let mut warning = begin_for(7, "run_workflow", None, Origin::Operator);
+    warning.request.call.checks = vec![Check::SkillScan {
+        verdict: tinysecurity_bus::SkillScanVerdict::Warn,
+        bundle_sha256: "a".repeat(64),
+    }];
+    let pending = owner.begin(warning).await?;
+    assert_eq!(pending.state, ApprovalLifecycle2::Pending);
+    assert!(!pending.external_effect);
+
+    let mut blocked = begin_for(7, "run_workflow", None, Origin::Operator);
+    blocked.request.caller.call_id = "blocked-call".into();
+    blocked.request.call.checks = vec![Check::SkillScan {
+        verdict: tinysecurity_bus::SkillScanVerdict::Block,
+        bundle_sha256: "b".repeat(64),
+    }];
+    assert_eq!(owner.begin(blocked).await.err(), Some(Error::Denied));
+    Ok(())
+}
+
 #[tokio::test]
 async fn host_action_and_shell_checks_bind_with_their_own_external_effect() -> Result<()> {
     let (_, owner) = owner()?;

crates/tinysecurity-bus/src/device_frame_tests.rs

@@ -70,5 +70,5 @@ fn frame_operations_redact_both_payloads_without_changing_open_wire_shape()
 #[test]
 fn frame_member_name_is_stable_and_contract_version_is_bumped() {
     assert_eq!(crate::names::methods::DEVICE_FRAME2, "DeviceFrame2");
-    assert_eq!(crate::CONTRACT_VERSION, (1, 28));
+    assert_eq!(crate::CONTRACT_VERSION, (1, 29));
 }

crates/tinysecurity-bus/src/device_pairing_tests.rs

@@ -85,7 +85,7 @@ fn refresh_and_close_are_distinct_transient_session_operations() {
 
 #[test]
 fn pairing_contract_is_versioned_after_the_frame_contract() {
-    assert_eq!(CONTRACT_VERSION, (1, 28));
+    assert_eq!(CONTRACT_VERSION, (1, 29));
 }
 
 #[test]

crates/tinysecurity-bus/src/lib.rs

@@ -65,7 +65,7 @@ pub use scoped_policy::*;
 pub use tool_trust::*;
 pub mod names;
 /// Current wire vocabulary version, independent of the artifact version.
-pub const CONTRACT_VERSION: (u32, u32) = (1, 28);
+pub const CONTRACT_VERSION: (u32, u32) = (1, 29);
 /// Whether a remote module's advertised version supplies this host's vocabulary.
 ///
 /// `version` is the provider version received by the host, not a host requirement

crates/tinysecurity-bus/src/names.rs

@@ -67,6 +67,8 @@ pub mod methods {
     pub const REPLACE_APPROVAL_SCOPE2: &str = "ReplaceApprovalScope2";
     /// Retire a scope so later calls under it deny (contract 1.17).
     pub const RETIRE_APPROVAL_SCOPE2: &str = "RetireApprovalScope2";
+    /// Register a secret resolver for an already-live approval scope (contract 1.29).
+    pub const REGISTER_SECRET_SCOPE2: &str = "RegisterSecretScope2";
     /// Evaluate member.
     pub const EVALUATE: &str = "Evaluate";
     /// Check member.
@@ -249,6 +251,7 @@ pub const METHODS: &[&str] = &[
     methods::LIST_TOOL_TRUST2,
     methods::IMPORT_TRUST_SOURCE2,
     methods::REGISTER_APPROVAL_SCOPE2,
+    methods::REGISTER_SECRET_SCOPE2,
     methods::REPLACE_APPROVAL_SCOPE2,
     methods::RETIRE_APPROVAL_SCOPE2,
     methods::REGISTER_SANDBOX_SCOPE2,

crates/tinysecurity-bus/src/policy.rs

@@ -75,6 +75,22 @@ pub struct ToolCall {
     /// Never forward checks supplied by a model, tool client or remote caller.
     pub checks: Vec<Check>,
 }
+
+/// Host-computed verdict from scanning a skill before execution (contract 1.29).
+/// The host must scan the exact installed document and resources it will expose;
+/// this value is a trusted host assertion, never a model-supplied claim. It is
+/// supplemental to the host-effect check and cannot authorize a tool call alone.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SkillScanVerdict {
+    /// No findings require action.
+    Pass,
+    /// Findings require the existing host approval flow before execution.
+    Warn,
+    /// The scan found content that must not execute.
+    Block,
+}
+
 /// A check of a concrete operation. The bootstrap has no URL authorization.
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
@@ -141,6 +157,15 @@ pub enum Check {
         #[serde(default, skip_serializing_if = "Option::is_none")]
         command_policy: Option<CommandPolicyId>,
     },
+    /// A trusted host's scan result for the exact skill bundle being executed
+    /// (contract 1.29). `Warn` requires host approval; `Block` is a hard denial.
+    SkillScan {
+        /// Result computed by the host scanner.
+        verdict: SkillScanVerdict,
+        /// Lowercase SHA-256 of the exact document and resources the host will
+        /// expose during this run. The approval binding includes this value.
+        bundle_sha256: String,
+    },
     /// An effect not supported by this engine.
     Unknown {
         /// Content-free descriptor.

crates/tinysecurity-bus/src/policy_tests.rs

@@ -118,6 +118,31 @@ fn host_shell_has_a_stable_strict_wire_form() -> TestResult {
     Ok(())
 }
 
+#[test]
+fn skill_scan_has_stable_verdict_wire_forms() -> TestResult {
+    for (verdict, wire) in [
+        (SkillScanVerdict::Pass, "pass"),
+        (SkillScanVerdict::Warn, "warn"),
+        (SkillScanVerdict::Block, "block"),
+    ] {
+        let check = Check::SkillScan {
+            verdict,
+            bundle_sha256: "a".repeat(64),
+        };
+        let value = serde_json::to_value(&check)?;
+        assert_eq!(
+            value,
+            serde_json::json!({
+                "kind":"skill_scan",
+                "verdict":wire,
+                "bundle_sha256":"a".repeat(64),
+            })
+        );
+        assert_eq!(serde_json::from_value::<Check>(value)?, check);
+    }
+    Ok(())
+}
+
 #[test]
 fn new_denial_reasons_have_stable_wire_forms_and_old_ones_are_unchanged() -> TestResult {
     for (reason, wire) in [

crates/tinysecurity-bus/src/secret.rs

@@ -49,6 +49,22 @@ pub struct SecretRegistration2 {
     /// At most three compatible read-only historical entries.
     pub legacy: Vec<SecretSourceBinding2>,
 }
+/// Host-only runtime registration for a secret scope whose approval scope is live.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RegisterSecretScopeRequest2 {
+    /// Immutable secret registration; the module resolves the approval scope itself.
+    pub registration: SecretRegistration2,
+}
+/// Safe confirmation of one active secret registration.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SecretScopeReceipt2 {
+    /// Opaque registration identity supplied by the trusted host.
+    pub registration_id: String,
+    /// Whether the registration is currently active.
+    pub active: bool,
+}
 /// Bounded retention and reservation ceilings, matching the internal registry.
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]

crates/tinysecurity-bus/src/secret_tests.rs

@@ -41,3 +41,38 @@ fn caller_authority_overrides_and_plaintext_response_fields_are_rejected()
     );
     Ok(())
 }
+
+#[test]
+fn runtime_secret_scope_registration_only_accepts_the_trusted_descriptor()
+-> Result<(), Box<dyn std::error::Error>> {
+    let request = RegisterSecretScopeRequest2 {
+        registration: SecretRegistration2 {
+            registration_id: "a".repeat(32),
+            approval_scope_id: "b".repeat(32),
+            origin: Origin::Operator,
+            purpose: MasterPurpose2::ConfigUserMaster,
+            target: SecretBinding2 {
+                backend_id: "c".repeat(32),
+                slot: MasterSlotKind2::User,
+            },
+            legacy: vec![],
+        },
+    };
+    let value = serde_json::to_value(&request)?;
+    assert_eq!(
+        serde_json::from_value::<RegisterSecretScopeRequest2>(value.clone())?,
+        request
+    );
+    let mut forged = value;
+    forged["subject"] = serde_json::json!({ "user": "caller" });
+    assert!(serde_json::from_value::<RegisterSecretScopeRequest2>(forged).is_err());
+    let receipt = SecretScopeReceipt2 {
+        registration_id: "a".repeat(32),
+        active: true,
+    };
+    assert_eq!(
+        serde_json::from_value::<SecretScopeReceipt2>(serde_json::to_value(receipt.clone())?)?,
+        receipt
+    );
+    Ok(())
+}

crates/tinysecurity-bus/tests/scoped_wire.rs

@@ -1,4 +1,4 @@
-//! Registered subject policy wire shapes and the 1.28 compatibility boundary.
+//! Registered subject policy wire shapes and the 1.29 compatibility boundary.
 use serde_json::json;
 use tinysecurity_bus::*;
 
@@ -79,6 +79,7 @@ fn new_members_are_advertised_and_named_by_contract_constants() {
         names::methods::AUTHORIZE_BROWSER_DIAL,
         names::methods::CONSUME_BROWSER_DIAL,
         names::methods::VALIDATE_BROWSER_DIAL,
+        names::methods::REGISTER_SECRET_SCOPE2,
     ] {
         assert!(names::METHODS.contains(&name), "{name}");
     }
@@ -87,10 +88,10 @@ fn new_members_are_advertised_and_named_by_contract_constants() {
 
 #[test]
 fn contract_bump_is_additive_for_older_hosts_and_modules() {
-    assert_eq!(CONTRACT_VERSION, (1, 28));
-    // A host built against 1.28 accepts this module and newer minors, not a 1.27 module.
-    assert!(is_compatible((1, 28)));
-    assert!(!is_compatible((1, 27)));
+    assert_eq!(CONTRACT_VERSION, (1, 29));
+    // A host built against 1.29 accepts this module and newer minors, not a 1.28 module.
+    assert!(is_compatible((1, 29)));
+    assert!(!is_compatible((1, 28)));
     assert!(!is_compatible((1, 26)));
     assert!(!is_compatible((1, 25)));
     assert!(!is_compatible((1, 24)));

crates/tinysecurity-bus/tests/wire.rs

@@ -343,7 +343,7 @@ fn redactor_init_is_additive_and_secrets_never_enter_public_info()
         serde_json::to_value(&config)?["redactor"]["secrets"][0],
         "literal-private"
     );
-    assert_eq!(CONTRACT_VERSION, (1, 28));
+    assert_eq!(CONTRACT_VERSION, (1, 29));
     for (mode, wire) in [
         (RedactMode::Text, "text"),
         (RedactMode::StructuredArguments, "structured_arguments"),