Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
305 lines (252 loc) · 22.4 KB

ARCHITECTURE.md

File metadata and controls

305 lines (252 loc) · 22.4 KB
Raw

Architecture

Architectural rule

SecureToolKit is an authorization library, not an execution environment. Its output can be a denial, a confirmation requirement, or an authorization artifact. It never calls a side-effecting tool.

Host application boundary

The Host is the application integrating SecureToolKit. It may be a service, desktop app, CLI, local runtime, or a set of components operating as one trust owner. It is not a SecureToolKit type or runtime. The Host owns authentication, trusted facilities, durable atomic Consumption, and Execution; the core owns deterministic construction and Validation of the evidence described below. The README responsibility matrix provides the onboarding-level split.

Component model

Component Responsibility Security boundary
Tool Registry Resolve stable tool identity and version to exactly one immutable definition; reject absence, ambiguity, and collision Core
Tool Definitions Declare name, version, complete exact schema content, capabilities, and authorization-relevant constraints Core data supplied through authorized host configuration
Tool Metadata Human-facing title, risk explanation, data classifications, and safe display hints; never grants authority Core data; untrusted for authorization unless policy explicitly uses a validated field
Tool Capabilities Express the maximum privilege classes a definition may request; grants are the intersection of definition, host authority, intent, and policy Core
User Intent Bind a host-captured request to an authenticated subject, scope, freshness, and context; never inferred authoritatively from model text Host-originated, evaluated by core
Provenance Describe source, custody, verification, and trust classification of inputs Core representation; host supplies attestable facts
Influence Record content or systems that shaped a proposal, including indirect prompt sources Core representation; absent influence data is not treated as clean
Policy Engine Evaluate complete, versioned inputs deterministically and fail closed Core
Authorization Represent scoped, expiring, single-use permission bound to exact canonical request and policy decision Core issues; host verifies and consumes
Confirmation Produce a bound challenge and validate an authenticated host response; presentation and identity proof remain outside core Split core/host adapter
Audit Emit privacy-minimized events for security transitions with tamper-evident sequencing contracts Core events; host persists/anchors
Execution Verify/consume authorization and perform the tool side effect Outside SecureToolKit
Idempotency Bind one logical operation to one consumption key and define atomic replay/duplicate rejection Core contract; host-backed atomic facility
Host Adapters Supply authenticated context, trusted time, confirmation, policy/registry configuration, secure facilities, and audit sinks through narrow protocols Outside core; trusted according to adapter role

Logical layers

Untrusted proposal input
        |
        v
Host parsing -> typed proposal -> registry resolution -> schema validation -> canonical request
        |                                                   |
        +-------------------- fail closed -------------------+
                                                            v
Authenticated intent + provenance/influence + security context + policy version
                                                            |
                                                            v
                                             Deterministic policy decision
                                              /          |          \
                                           deny     confirmation    allow
                                                        |             |
                                              host adapter response   |
                                                        \             /
                                                   authorization
                                                        |
                                      trust boundary ends here
                                                        |
                                     host verifies + atomically consumes
                                                        |
                                                   host executes

Required evaluation sequence

  1. The host parses external input without coercion and preserves duplicate object field occurrences.
  2. Resolve one exact tool definition and version from an immutable registry snapshot.
  3. Validate arguments against the exact schema and constraints.
  4. Produce a versioned canonical request binding tool identity and all arguments.
  5. Require capability-bound authenticated host authority, an authenticated UserIntentEnvelope, explicit Provenance/Influence, and complete SecurityContext appropriate to policy.
  6. Evaluate one explicit policy version against immutable inputs.
  7. Emit a PolicyDecision; an allow is evidence, not authority.
  8. Phase 6 rejects confirmation and unsatisfied audit obligations because their behavior is not implemented.
  9. AuthorizationIssuer revalidates exact bindings, computes intersection-only scope, applies explicit lifetime limits, and issues one immutable structural Authorization.
  10. The host may structurally validate the artifact. Atomic consumption and any later execution remain separate host responsibilities and are not implemented by Phase 6.

Every step may deny. No later step can repair ambiguity or upgrade untrusted input into authenticated fact.

State and concurrency

Public domain records should be immutable struct or closed enum values conforming to Sendable. Actors are appropriate only for future mutable shared host facilities such as atomic consumption or audit sequencing. Pure validation, canonicalization, policy evaluation, and Phase 6 issuance remain deterministic value transformations and do not require actors.

No API may depend on hidden global state. Dependencies such as clocks, policy snapshots, registry snapshots, nonce sources, and consumption stores must be explicit, narrowly typed, and supplied by the host. This is constructor/protocol composition, not a dependency-injection framework.

Snapshots and versioning

Registry definitions, schemas, canonicalization rules, and policies are evaluated as immutable, identified snapshots. A decision records every relevant version. Hot reload may publish a new snapshot for later evaluations but must not mutate an in-flight evaluation. Unknown or unavailable versions deny.

Phase 2 Tool Registry contract

  • ToolRegistryDraft is a mutable value-semantic staging area, not a published registry and not administrative authority.
  • Initial and successor publication are pure, all-or-nothing transformations over explicit inputs.
  • ToolRegistrySnapshot is immutable and Sendable; old snapshots remain unchanged and safe for concurrent reads.
  • Snapshot identity is an explicit host-supplied ID plus a sequential positive generation. Publication reads no clock, randomness, locale, environment, network, or filesystem.
  • Definitions are ordered by exact ASCII ToolID, numeric ToolVersion, then ToolDefinitionID regardless of insertion order.
  • Exact lookup requires both ToolID and ToolVersion; no latest, alias, normalization, or fallback API exists.
  • Snapshot-bound references reject stale snapshot or mismatched definition use.
  • Lifecycle transitions publish successors: active may remain active or become deprecated/retired; deprecated may remain deprecated or become retired; retired remains retired.
  • Successors retain prior definitions and cannot change same-version identity, complete schema content, capabilities, or metadata. A changed contract requires a new ToolVersion and ToolDefinitionID.
  • Ordinary lookup returns active or deprecated definitions and rejects retired definitions. Historical inspection is a separate non-authoritative API.
  • The library does not authenticate registry administrators. A host must expose publication only through an authenticated configuration path; missing or indeterminate administrative authority means the host must not call publication.

Registry metadata and maximum capabilities classify a tool but do not grant host authority, express user intent, evaluate policy, issue authorization, or provide execution behavior.

Phase 3 schema and canonical request contract

  • ToolDefinition owns one complete exact SchemaDefinition; its SchemaReference is derived from that stored value.
  • SchemaDefinition is a finite inline closed tree rooted at an object. It has no references, cycles, unions, maps, defaults, nullable fields, or additional properties.
  • StructuredValue accepts host-parsed string, Boolean, Int64, UInt64, closed enum candidate, array, object, and an explicit rejected null marker. It performs no JSON/text parsing or coercion.
  • Objects preserve field occurrences in arrays so duplicates reject. Schema fields are sorted by exact restricted ASCII name; input order never affects canonical output.
  • Arrays preserve order and duplicate elements. Object order is insignificant.
  • SchemaValidator is a pure value transformation with typed privacy-safe failures and deterministic resource limits.
  • CanonicalRequest is opaque and constructible only after complete validation. It binds the exact snapshot-bound definition, complete schema, reviewed argument-derived resources, canonicalization version, field names, types, and values.
  • Canonicalization version 1 uses tagged, length-delimited bytes, UTF-8 strings, and network-byte-order integers. It performs no hashing or cryptography.
  • Schema and canonicalization versions are separate and closed. Unknown versions reject without fallback.

The host parser must not erase duplicate fields or coerce ambiguous numeral text. Canonical request bytes define the validated security meaning for later phases; they are not authorization or an execution token.

Phase 4 authenticated binding contract

  • Raw authority, attestation, context, intent, provenance, and influence claims are public data and untrusted by construction. Validated/trusted-boundary values have no public initializer and arise only through deterministic validators that the host must expose through authenticated integration paths.
  • A host attestation binds one issuer, least-authority role, exact structural fact, subject, tenant, session state, and explicit validity interval. Context, intent, provenance, and complete-collection facts bind all security-relevant values, preventing substitution beneath a reused ID. Role/value/scope/freshness mismatch rejects. Attestations are structured evidence, not signatures.
  • SecurityContext binds host-classified assurance, authentication methods, and optional separately attested delegation. It stores no credentials or secrets.
  • UserIntentEnvelope binds exact identity, session state, freshness, renewal, intended capabilities/resources, and either one exact CanonicalRequest or one exact snapshot-bound tool definition. No wildcard or semantic intent path exists.
  • Provenance and influence remain separate. Missing provenance is unknown; source labels and trusted transport never upgrade content. Unsupported transformations prevent host-verified lineage.
  • Influence completeness is unknown, partial, or collector-attested complete per exact collection boundary. Multiple boundaries remain separate; empty unknown and empty complete do not collapse.
  • EvaluationInput binds the exact canonical request, lookup, intent, context, requested scope, provenance, influence boundaries, applicable attestations, explicit time, and renewal generation. Any mismatch returns no partial value.

Phase 4 performs no policy evaluation, capability grant, resource entitlement, authorization, confirmation, trusted-time lookup, cryptography, or execution.

Phase 5 policy boundary

PolicyDraft stages host-administered typed definitions and publishes an all-or-nothing immutable PolicySnapshot; the core does not authenticate, persist, distribute, or select a global snapshot. PolicyEvaluator is stateless and reads only one explicit snapshot plus one validated EvaluationInput.

Every rule is evaluated. Strict indeterminate propagation denies globally; otherwise deny dominates confirmation and confirmation dominates allow. Exact capability/resource ceilings intersect the already bounded Phase 4 request. Display/descriptive metadata and canonical byte contents are not policy-visible. PolicyDecision is immutable evidence, never authority. Execution remains outside the trust boundary.

Phase 6 authorization boundary

  • Authorization is immutable, Sendable, and has no public initializer.
  • AuthorizationIssuer is the sole construction path and accepts only an exact eligible allow decision with all obligations Phase 6 can prove satisfied.
  • AuthorizationBinding retains exact decision, input, canonical request, tool definition, registry snapshot, policy snapshot, and authenticated identities.
  • Capabilities are definition ∩ host authority ∩ intent ∩ requested ∩ policy; resources are canonical arguments ∩ host authority ∩ intent ∩ requested ∩ policy. Filtering never adds authority.
  • AuthorizationLifetime uses explicit epoch seconds, inclusive issue, exclusive expiry, a 3,600-second ceiling, and all bound input expiries.
  • Replay and consumption identities are host-supplied correlation values. atomicSingleUseRequired is a contract, not storage enforcement.
  • AuthorizationValidator compares complete host expectations at an explicit time and returns no executable capability or consumption record.

Phase 6 contains no clock, randomness, persistence, replay database, networking, hashing, cryptography, trust store, confirmation behavior, callback, or execution.

Host adapter principles

  • Each adapter exposes the least authority needed for one role.
  • Adapter results distinguish success from unavailable, invalid, and unverifiable states; none silently downgrade.
  • Authentication and confirmation adapters return host-attested facts, not model assertions.
  • Core APIs remain platform-neutral; Apple-specific APIs are separate future modules.
  • An adapter that can execute tools is not passed into the authorization core.

Architectural risks

Risk Consequence Required response before relevant phase
Host parser loses duplicates or coerces values before validation SecureToolKit cannot recover ambiguity erased before its typed boundary Require host parsing conformance and preserve field occurrences/exact integer types before Phase 9
Canonicalization implementation drift Approval or artifact may bind to a different request than execution Phase 3 freezes version 1 tags/lengths/order and a fixed vector; add cross-platform conformance execution before declaring the phase complete
Schema ID/version reused for different content Identifier-only checks could validate under a substituted contract RC0.1 stores and compares complete schema content; host governance must still authenticate schema publication and distribution
Atomic single-use enforcement across processes Replay or duplicate side effects Phase 6 exposes only a contract; define and validate host storage/transaction failure semantics before integration
Trusted time rollback or skew Expired authorization may appear valid Phase 6 uses explicit time only; specify host clock trust and rollback handling before integration
Policy vocabulary expansion introduces ambiguity or nondeterminism Inconsistent critical decisions Preserve the Phase 5 closed bounded model; require an ADR, versioning decision, and permutation/limit tests for every extension
Metadata accidentally treated as authority Tool-controlled labels influence allow decisions Phase 2 separates closed security classifications from non-authoritative display/description; Phase 5 must accept only reviewed security fields
Host exposes the retained capability or authority-sensitive validators to model-controlled code Model claims could be accepted as host evidence despite controlled value construction Integration must restrict the retained boundary and these entry points; process isolation or cryptographic authenticity requires a separate approved design
Incorrect resource schema annotation A tool schema could omit an authority-relevant resource semantic RC0.1 derives resources only from reviewed resourceID nodes and denies mismatches; registry governance must review every resource-affecting field
Session-independent intent is used too broadly Long-lived intent may outlive the user interaction that justified it Hosts must use short explicit validity; Phase 5/6 must impose risk-specific requirements and lifetimes
Provenance/influence collector omits an unseen boundary Apparently complete local evidence may miss an indirect injection path Completeness remains boundary-local; future high-risk policy must treat absent/unknown boundaries conservatively
Audit tamper evidence without durable anchoring Local attacker may truncate or replace entire history Define sink and anchoring responsibilities before Phase 8
Tool definition upgrades during in-flight work Substitution or stale authorization Phase 2 binds immutable snapshot/definition/tool versions and one-way retirement; later decisions must retain the exact reference
Host/executor contract drift Execution may omit verification or consume incorrectly Publish executor conformance suite before Phase 6/9

Open questions

These are intentionally undecided; implementations must not invent answers silently.

  1. Which digest and cryptographic algorithm-agility rules will later commit to Phase 3 canonical bytes?
  2. What future protected or portable artifact format, if any, will wrap the Phase 6 structural value?
  3. What atomic consumption interface supports single-process and distributed hosts?
  4. Which trusted time semantics and capability-specific lifetimes further narrow the Phase 6 global 3,600-second ceiling?
  5. How will policy snapshot origin, administrative authenticity, revocation, and rollback be protected operationally before production use?
  6. Resolved in RC0.1: reviewed FieldKind.resourceID nodes derive exact resources; generic field paths and canonical-byte parsing remain prohibited.
  7. Which assurance, provenance, completeness, and intent combinations must each Phase 5 policy class deny or escalate?
  8. How are registry, host-authority, and policy administration authenticated, versioned, rolled back, and revoked?
  9. What privacy-preserving audit commitments and external anchoring are required for financial deployments?
  10. Which private security disclosure contact and response process will govern the project before release?

Phase 3 resolved the schema subset, string/integer rules, deterministic ordering, canonical byte format, and limits in docs/PHASE_3_DECISIONS.md and ADR-0016 through ADR-0019. It deliberately did not select hashing, cryptography, or an authorization artifact format.

Phase 4 resolved structured intent granularity, non-cryptographic host attestations, security-context construction, conservative provenance upgrades, boundary-local influence completeness, explicit freshness, and complete input binding in docs/PHASE_4_DECISIONS.md and ADR-0020 through ADR-0024. At that boundary, policy meaning and authorization were deferred.

Phase 5 resolved the bounded typed policy representation, exact snapshot publication, full-rule precedence, scope intersection, stable reasons, and inert obligations in docs/PHASE_5_DECISIONS.md and ADR-0025 through ADR-0029. Trusted time, cryptographic authenticity, revocation, confirmation behavior, and execution remain deferred.

Phase 6 resolved controlled structural authorization construction, exact full-value binding, intersection-only effective scope, a 3,600-second global lifetime ceiling, explicit-time validation, replay identity, and a declarative atomic single-use contract in docs/PHASE_6_DECISIONS.md and ADR-0030 through ADR-0034. Cryptographic authenticity, trusted time, replay persistence, actual consumption, confirmation, audit evidence, and execution remain deferred.

RC0.1 exact authority pipeline

Authenticated host bootstrap
  -> opaque HostCapabilityBoundary
  -> HostAuthority + exact capability/resource ceilings
  -> exact-role attestations

ToolDefinition + complete SchemaDefinition
  -> validation of reviewed resourceID nodes
  -> CanonicalRequest(exact tool reference, exact schema, derived resources)

EvaluationInput
  = exact request + one host authority + intent + requested scope + lineage

PolicyDecision scope
  = requested scope intersected with host authority and every matched ceiling

Authorization capabilities
  = definition ∩ host authority ∩ intent ∩ request ∩ policy
Authorization resources
  = canonical resources ∩ host authority ∩ intent ∩ request ∩ policy

The opaque boundary is an in-process capability, not a secret, signature, hash, or process sandbox. The host passes it independently to issuance and validation. Execution remains outside the SecureToolKit trust boundary.

RC0.2 authority topology and binding chain

One host domain is represented by a strongly retained opaque HostCapabilityBoundary. Role-specific HostAuthority values attenuate fact issuance and policy administration without merging entitlement. All participating authorities share one exact ceiling. Proposal assessment, canonical request, lineage, evaluation input, policy snapshot/decision, authorization, and validation each close the same domain at their own transition.

ToolProposal ID + host assessment
  -> CanonicalRequest (assessment outside v1 bytes)
  -> assessed lineage + role-specific attestations
  -> EvaluationInput
  -> exact PolicySnapshot + PolicyDefinition -> PolicyDecision
  -> Authorization + complete AuthorizationConsumptionBinding
  -> repeatable structural validation
  -> future host atomic consumption (not implemented)
  -> host execution (outside SecureToolKit)

Canonical bytes are weaker than the complete structural envelope. No future approval, audit commitment, signature, hash, or portable artifact may use v1 canonical bytes alone as a commitment to complete protocol state.