#Trust & Security

The central rule is: package content may describe requirements, but it cannot authorize itself. Flow/Skill source, UI messages, OKF knowledge, Tool output, MCP descriptions, and remote content remain data.

#Three trust paths

Search runs over verified, size-bounded catalog metadata without downloading package archives. A model or browser cannot invent an installable identity absent from the catalog.

#Release artifact evidence

Successful tagged preview releases deterministically serialize each staged platform tree and publish an SPDX JSON SBOM beside every archive. GitHub OIDC creates both build-provenance and SBOM attestations for the archive. checksums.txt.sigstore.json is a keyless Sigstore bundle for the checksum manifest, and the release job verifies the bundle against the exact tag workflow identity before publishing it. Every Action and the Rust, Python, Syft, and Cosign versions are pinned.

The installers require Cosign and authenticate checksums.txt against the exact A3S Use tag workflow identity and GitHub OIDC issuer before downloading a platform archive. Invalid or missing evidence fails closed, and the verified manifest and bundle are retained with the installed version. For every target, a second clean runner without a compiled-artifact cache rebuilds every shipped native executable and must byte-match the primary archive; its deterministic .reproducibility.json record is attested, checksummed, and signed only after that match passes. The tagged v0.3.2 attempt failed this comparison on four targets and did not create a GitHub Release. Non-publishing qualification run 33651777660 then byte-matched every shipped executable on all five targets from exact main commit 4f6e4725205d06ab81f8ea98bfee85c7eb4b2bcd; the later v0.3.5 publication attempt created no Release because the public core crate was stale. Release workflow 33675697857 passed all 13 jobs for tag v0.3.6 at exact main commit 54758910f2f4ad9498137410e0a2207d412e99a1 and published the verified archives and typed crates in the v0.3.6 Release. The subsequent release workflow 33687297386 passed all 13 jobs for tag v0.3.7 at exact main commit 48a0b76f8a4a87a11d16627c7bd7567920852508 and published the current verified archives and typed crates in the v0.3.7 Release: a3s-use-core 0.2.6, a3s-use-extension 0.3.7, and a3s-use 0.3.7. The installer script remains a separate bootstrap trust boundary and should be reviewed or distributed through a trusted system package. An externally operated full-tree/final-archive witness and off-Release evidence retention remain release gates.

The next release workflow 33720485826 passed all 13 jobs for tag v0.3.8 at exact main commit 6d3a7baf32ce998a2e487c40fbf78b4a6cda2579 and published the current verified archives and typed crates in the v0.3.8 Release: a3s-use-core 0.2.7, a3s-use-extension 0.3.8, and a3s-use 0.3.8. The installer script remains a separate bootstrap trust boundary; an externally operated full staged tree/final archive witness and off-Release evidence retention remain release gates.

Release workflow 33756618837 passed all 13 jobs for tag v0.3.9 at exact main commit a5f3cc40bfb0a1021ca150d2ce4295409b74d220 and published the 19 verified release assets and typed crates in the v0.3.9 Release: a3s-use-core 0.2.7, a3s-use-extension 0.3.9, and a3s-use 0.3.9. The installer script remains a separate bootstrap trust boundary; an externally operated full staged tree/final archive witness and off-Release evidence retention remain release gates.

Release workflow 33791616307 passed all 13 jobs for tag v0.3.10 at exact main commit c4c80a223bfff3698ca4b4598e7175c6e3303239 and published the 19 verified release assets and typed crates in the v0.3.10 Release: a3s-use-core 0.2.8, a3s-use-extension 0.3.10, and a3s-use 0.3.10. The installer script remains a separate bootstrap trust boundary; an externally operated full staged tree/final archive witness and off-Release evidence retention remain release gates.

Release workflow 33830280138 passed the validation, five-target primary-build, typed-crate, and five-target independent-rebuild gates for tag v0.3.11 at exact main commit c25028ae0245ba1d28f7e2837e2a87f7e9f6fe40 and published the 19 verified release assets and typed crates in the v0.3.11 Release: a3s-use-core 0.2.9, a3s-use-extension 0.3.11, and a3s-use 0.3.11. The installer script remains a separate bootstrap trust boundary; an externally operated full staged tree/final archive witness and off-Release evidence retention remain release gates.

#Replaceable registry sources

Remote registries are named, host-owned ACL configuration. The standalone CLI persists at most 64 sources, selects the first enabled source as the default, and passes every enabled source to dependency resolution. Release bundles remain independent of remote registries.

a3s-use registry source add packages \
  --url https://packages.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --trusted-root /absolute/path/root.json \
  --json

a3s-use registry source list --json
a3s-use registry source replace packages \
  --url https://mirror.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --expected-revision sha256:<reviewed-configuration-revision> \
  --yes \
  --json

default, enable, disable, and remove use the same reviewed-revision and confirmation boundary. Only enabled sources participate in package lookup, dependency resolution, refresh, and upgrades; disabled sources remain visible in list output. An imported root is copied only after regular-file, size, JSON, and complete digest validation. Each canonical name/URL/bootstrap-root identity has a separate TUF/cache datastore. Replacement preserves enabled state and never interprets old metadata under new trust. Disable/remove retain the old state, so restoring the exact identity can reuse it. Duplicate package identities across enabled registries fail as ambiguous. Source administration never rewrites an installed receipt: upgrades remain bound to recorded source and target provenance and fail closed after identity drift.

#Immutable plans

Install, upgrade, and uninstall create an expiring canonical plan before mutation. It binds at least:

• package ID, version, channel, target, and source registry;
• the complete canonical dependency lock and its digest;
• TUF root identity and metadata versions;
• archive length, SHA-256, and expanded package digest;
• surface and dependency changes plus Runtime provider evidence;
• permission ceiling, secret/grant diff, and workspace impact;
• download/installed size, drain impact, and canonical plan digest.

Apply accepts the reviewed digest, resolves every input again, and rejects target, content, permission, provider, or ownership drift. User confirmation and each grant proposal bind to the same digest.

For schema-v3 dependencies, the lock binds every selected version, dependency edge, archive/package/manifest digest, host target/version, Registry URL/trust root, and TUF role version. Apply revalidates the complete closure before downloading any archive. The same dependency in multiple enabled Registries is ambiguous and fails closed.

#Operation diagnostics

a3s-use extension diagnose <publisher/name> --scope-kind user --scope-id user/current --json reads one exact retained planned/admitted/cancelled install, upgrade, or uninstall graph, one active admitted enable/disable operation, or the newest Host-reviewed pre-admission enable/disable plan or cancellation for the selected User or Workspace scope. It performs no Registry request, reconciliation, recovery, or write. The versioned projection correlates the reviewed plan and lock, path-free Registry/TUF evidence, current Registry generation and cutover, provider readiness, Grant journal phase, lifecycle publication/drain/rollback state, and stable recovery guidance.

The projection is observation only, never apply or recovery authority. It is bounded to 2 MiB, rejects unknown fields and inconsistent evidence, and omits paths, Registry URLs, idempotency keys, credentials, tokens, secret names and values, package content, and arbitrary package-authored text. Invalid backing state fails closed with a path-free cleanup/reinstall instruction. Active Use enablement evidence takes precedence; otherwise an observation-only, digest-bound index selects the newest exact Host plan by (plannedAtMs, requestId) and emits planned or cancelled. The private index retains managed scope only for request lookup and never exposes Host ID, authority, fence, or Host request/cancellation identity. Completed Use or Host outcomes suppress stale plans. Retained Registry-backed install/upgrade graphs and durable pre-plan download attempts expose independent expected/retained archive and signed executable-planning-target bytes plus exact target missing/partial/complete state from historical provenance. The attempt is process-locked, survives exit, and is removed only after reviewed graph retention. Projection remains zero-network, read-only, target-cache-lock-independent, and path-free; targets and partials are never planning, apply, or recovery authority.

A complete diagnostic state means a canonical source observation references an owned exact-length global Artifact Store blob; diagnostics do not rehash it. Every cached open and staging copy does rehash the retained no-follow blob handle. Corruption fails closed and is never silently overwritten.

Before metadata access and exact lock creation, a process-held package lock protects a3s.use.plugin-resolution-attempt.v1. It records refreshed/cached access plus path-free root/dependency Registry verification state, source-identity/trust-root digests, TUF role versions, bounded target counts and failure codes, and terminal lock evidence. The a3s.use.plugin-resolution-attempt-diagnostic.v1 projection has phase pre-lock, survives resolution failure or process exit, performs no network request or write, and never waits for the package lock. Success writes the download attempt before removing the resolution evidence. Registry URLs, paths, raw transport errors, credentials, and metadata bytes are excluded. Real killed-process and Host/CLI tests prove planning-target partial observation and exact Range resume, zero-network/zero-admission planned and cancelled enablement diagnosis, no Host/fence/path leakage, and stale-plan suppression during the completed-Use/unfinished-Host-outcome window.

extension diagnose --history --json exposes a separate bounded history contract for retired operations. It keeps the newest 16 occurrences within 8 MiB per explicit scope/package and validates completed/rolled-back operations or cancelled graph plans against lifecycle, Grant, and Registry cutover evidence. Retention happens before recovery authority is removed; replay deduplicates the pair (operationId, planDigest) because an exact reinstall may legitimately reuse a lock-derived textual operation ID. The query is zero-network and read-only, survives uninstall, and rejects unknown, linked, inconsistent, or oversized state through a path-free error.

#Default authorization policy

Agent lifecycle operations default to ask, not allow. Safe metadata search, inspect, list, and plan operations may be pre-authorized. Adding a trust root, installing an unsigned package, granting a secret, and purging data remain user-only.

For Gateway calls, the host-owned CapabilityGatewayInvocationResolver maps the catalog's opaque InvocationRef to a private lease. The lease must bind the complete package/surface/generation identity, apply the principal and Grant policy, and retain its generation guard until the invocation returns. CapabilityGatewayResolvedProvider keeps resolution and authorization in one call boundary; it never sends the lease, path, or provider details to the agent. HTTP hosts may bind a bounded immutable token-to-principal registry; authentication scans all configured credentials and rejects duplicate tokens. The production host still supplies the receipt, Runtime, and Grant binding.

A package permission declaration is a ceiling, not authority. Host ACL policy and workspace grants may only narrow it:

plugins {
  schema = "a3s.plugin-policy.v1"

  agent_install   = "allow"
  agent_upgrade   = "ask"
  agent_uninstall = "ask"

  trusted_registries = ["a3s"]
  trusted_publishers = ["a3s"]
  allowed_surfaces   = ["flow", "mcp", "okf", "skill", "tool", "ui"]

  permissions {
    native_execution = false
    private_service  = true
    child_process    = false
    secrets          = false

    network "api.example.com" {
      ports = [443]
    }
  }
}

An omitted ceiling means zero, empty, or false. Duplicates, unknown fields, broad network patterns, and unattended secret grants fail closed.

The example uses the current six-surface inventory. A host must parse this ACL policy with its exact current contract and reject an unknown or incomplete inventory; it must not widen authority through defaults.

#Activation order

resolve signed dependency graph
    → freeze exact package lock
    → build and review immutable plan
    → revalidate every Registry before payload download
    → verify and stage dependencies before dependents
    → prepare grants and Runtime bindings
    → preflight A3S Flow and stage Skill, UI, and OKF projections
    → publish changed packages in one capability generation
    → hide and drain superseded generation
    → retire old grants, bindings, and owned files

A new generation stays invisible until every required dependency is usable. A failed upgrade preserves the previous generation. Disable and uninstall hide new calls before draining exact-generation leases.

An exact already-published dependency may be retained without recommit. Uninstall runs in reverse package order and refuses to remove a dependency while another installed package still requires it. Partial enabled-receipt writes stay invisible until the complete immutable snapshot is published.

For OKF, the standalone SQLite/FTS5 host is implemented: missing Knowledge evidence is pending, staged is unpublished, and only an exact promoted observation is healthy. Search requires a complete scope and exact reviewed capability/session projections; citations bind package, surface, generation, index, concept path, and source digest. Scope-bounded retention/GC, audit, verified backup with exact-plan oldest-first rotation, derived-index repair, and authority-bound database plus exact-subset missing-binding restore are implemented. Restore requires the exact reviewed plan, complete retained Registry/package/lifecycle/Grant authority, and a current binding set that is an exact subset of the backup; conflicts or newer binding evidence fail closed. Ordinary mutation remains blocked while its durable operation is active. A path-free diagnostic exposes only bounded active/history/capacity and reviewed binding-recovery evidence and never rotates or rewrites rollback files. Managed A3S Code leased-query qualification, missing independent-authority and clean-machine recovery, cross-platform operational drills, rollback-evidence retention policy, and whole-product recovery remain open.

Whole-installation backup uses that same exclusive maintenance boundary. state backup inventories only known Use-owned control-state families, excludes locks and the global Artifact Store, binds the published Registry projection and installed receipt digests, copies each regular file with exact hashing, and requires an unchanged second inventory before publication. An active restore/cutover/operation, installation data payload, unknown family, non-portable name, link/reparse point, or special file fails closed. state verify-backup validates canonical manifest bytes, complete archive length, and every payload offline without extraction. Because the archive contains raw state, operators must protect it as sensitive data. state backup-retention fully verifies every managed archive under one external-directory lock, binds a path-free oldest-first canonical plan, requires its unchanged digest plus explicit confirmation, and preserves at least two verified recovery generations. Archive digests remain corruption evidence, not authentication or missing-authority recovery. state plan-restore requires the exact current version/platform plus unchanged live Registry, receipt, and Grant authority. Confirmed state restore captures an external rollback archive before its active marker or mutation, rejects candidate links/reparse points and durable-evidence substitution, and converges seven journal phases across 15 tested process-exit boundaries. Path-free state restore-status is read-only and completed history is bounded. Missing authority, cross-platform operational drills, and clean-machine recovery are still open.

The cognitive-package platform is pre-1.0. Unknown receipt or database versions fail closed, and unpublished state is recreated rather than migrated or rewritten. This policy does not weaken package SemVer resolution, host-version requirements, target checks, or signed provenance verification.

For Flow, source integrity and lifecycle ordering are implemented. Embedding hosts inject the exact a3s-flow compiler/runtime adapter; the standalone CLI injects the same host only when A3S_FLOW_NATIVE_TS_COMPILER is an absolute path. Missing or failed preflight keeps the exact candidate unpublished instead of presenting source-only readiness; a repaired retry must resume its durable admitted plan and generation.

#Platform isolation boundary

Native process execution is not automatically a sandbox. Until a platform provider enforces filesystem, environment, process, and network restrictions, the state must report native-unconfined and cannot use an unattended allow path.

Read the complete Plugin Lifecycle and Security specification.