Skip to content

README.md

Latest commit

 

History

History
359 lines (310 loc) · 12.5 KB

README.md

File metadata and controls

359 lines (310 loc) · 12.5 KB
Raw

Human Confirmation

Explanatory documentation only. This example is non-normative, has no UI, performs no authentication, stores no replay state, consumes nothing, and executes no tool.

What problem does this example address?

Phase 7 adds explicit human-confirmation evidence without allowing the model, authentication alone, a generic interaction, or the confirmation UI to grant authority. Every controlled value below is produced through its public transition; none is initialized or reconstructed directly.

Why this flow?

Confirmation must cover reviewed presentation facts and one exact prospective Authorization. The staged lifecycle prevents a response, identity, Challenge, Artifact, scope, or Host boundary from being silently substituted on the path from policy to final validation.

Architecture diagram

flowchart LR
    P["PolicyDecision\nconfirmation required"] --> R["ConfirmationRequirement"]
    R --> B["ProspectiveAuthorizationBinding"]
    B --> F["PresentationFacts"]
    F --> C["ConfirmationChallenge"]
    C --> H["Host presents reviewed facts"]
    H --> PE["PresentationEvidence"]
    CA["Genuine ConfirmationAuthority"] --> AE["AuthorityEvidence"]
    C --> AE
    PE --> AE
    AE --> A["ConfirmationArtifact"]
    A --> E["ConfirmedIssuanceEligibility"]
    E --> Z["Phase7Authorization"]
    Z --> V["Pure validation"]
    V --> X["Future Host Consumption"]

    subgraph STK["SecureToolKit"]
        R
        B
        F
        C
        PE
        AE
        A
        E
        Z
        V
    end
Loading

Sequence diagram

sequenceDiagram
    participant Host
    participant Policy as PolicyEvaluator
    participant Core as SecureToolKit
    participant Presenter as Host presentation adapter
    participant Authority as Confirmation Authority
    participant Validator as Phase7AuthorizationValidator

    Host->>Policy: exact EvaluationInput
    Policy-->>Host: requireConfirmation PolicyDecision
    Host->>Core: derive Requirement and prospective Authorization
    Core-->>Host: Challenge with reviewed Presentation Facts
    Host->>Presenter: present exact facts
    Presenter-->>Host: complete Presentation Evidence
    Host->>Authority: exact Challenge + explicit response
    Authority-->>Host: affirmative Authority Evidence
    Host->>Core: construct Confirmation Artifact
    Core-->>Host: confirmed issuance Eligibility
    Host->>Core: construct Phase 7 Authorization + final binding
    Host->>Validator: Authorization + independent expectations + time
    Validator-->>Host: success Reference or safe Failure
Loading

The required conceptual order is:

Policy
  ↓
Challenge
  ↓
Presentation
  ↓
Confirmation
  ↓
Authorization
  ↓
Validation

Minimal Swift snippets

These fragments assume the Host has independently retained the controlled Phase 1–6 inputs named below. Times are explicit EpochSeconds values supplied by the Host.

1. Policy to prospective Authorization

import SecureToolKitCore

let requirement = try ConfirmationRequirement.derive(from: policyDecision)

let authorizationID = try Phase7AuthorizationID(validating: "authorization-1042")
let replayID = try Phase7ReplayID(validating: "replay-1042")
let consumptionID = try Phase7ConsumptionID(validating: "consume-1042")

let prospective = try ProspectiveAuthorizationBinding.construct(
    requirement: requirement,
    hostCapabilityBoundary: hostBoundary,
    authorizationID: authorizationID,
    authorizationGeneration: 1,
    registrySnapshot: registrySnapshot,
    policySnapshot: policySnapshot,
    issuedAt: authorizationIssuedAt,
    lifetimeRequest: authorizationLifetimeRequest,
    replayID: replayID,
    consumptionID: consumptionID
)

2. Challenge and reviewed presentation facts

Presentation facts are derived from the prospective Authorization and reviewed Tool metadata—not from raw prompts, retrieved documents, tool output, secrets, or model-generated labels.

let facts = try ConfirmationPresentationFacts.derive(
    from: prospective,
    challengeExpiresAt: challengeExpiresAt
)

let challengeID = try ConfirmationChallengeID(validating: "challenge-1042")
let challenge = try ConfirmationChallenge.construct(
    requirement: requirement,
    prospectiveAuthorization: prospective,
    presentationFacts: facts,
    challengeID: challengeID,
    challengeIssuedAt: challengeIssuedAt,
    challengeExpiresAt: challengeExpiresAt,
    hostCapabilityBoundary: hostBoundary,
    authorizationID: authorizationID,
    authorizationGeneration: 1,
    registrySnapshot: registrySnapshot,
    policySnapshot: policySnapshot,
    authorizationIssuedAt: authorizationIssuedAt,
    authorizationLifetimeRequest: authorizationLifetimeRequest,
    replayID: replayID,
    consumptionID: consumptionID
)

let retainedChallengeBinding = challenge.binding

3. Complete presentation and explicit affirmative response

The Host UI must present every exact field in facts. UI rendering and input collection remain outside SecureToolKit.

let presentationEvidence = try ConfirmationPresentationEvidence.construct(
    challenge: challenge,
    expectedChallengeBinding: retainedChallengeBinding,
    evidenceID: try ConfirmationPresentationEvidenceID(
        validating: "presentation-1042"
    ),
    challengeID: challengeID,
    presentationFacts: facts,
    subjectID: retainedSubjectID,
    hostAuthorityDomain: retainedHostAuthority,
    presentedAt: presentedAt,
    completeness: .allRequiredFieldsPresented,
    interaction: .explicitBinaryChoice,
    authorizationID: authorizationID,
    authorizationGeneration: 1,
    registrySnapshot: registrySnapshot,
    policySnapshot: policySnapshot,
    authorizationIssuedAt: authorizationIssuedAt,
    authorizationLifetimeRequest: authorizationLifetimeRequest,
    replayID: replayID,
    consumptionID: consumptionID
)

let confirmationAuthority = try ConfirmationAuthority.establish(
    hostAuthorityDomain: retainedHostAuthority,
    hostCapabilityBoundary: hostBoundary
)

let authorityEvidence = try ConfirmationAuthorityEvidence.construct(
    challenge: challenge,
    expectedChallengeBinding: retainedChallengeBinding,
    presentationEvidence: presentationEvidence,
    confirmationAuthority: confirmationAuthority,
    hostCapabilityBoundary: hostBoundary,
    evidenceID: try ConfirmationAuthorityEvidenceID(
        validating: "authority-evidence-1042"
    ),
    subjectID: retainedSubjectID,
    tenantID: retainedTenantID,
    sessionBinding: retainedSessionBinding,
    delegationID: retainedDelegationID,
    challengeID: challengeID,
    presentationEvidenceID: presentationEvidence.evidenceID,
    response: .affirmative,
    confirmedAt: confirmedAt,
    authorityIssuedAt: authorityIssuedAt,
    authorityExpiresAt: authorityExpiresAt
)

Silence, dismissal, timeout, authentication, prior activity, and .nonAffirmative are not affirmative confirmation.

4. Confirmation Artifact and eligibility

let confirmationID = try ConfirmationID(validating: "confirmation-1042")
let artifact = try ConfirmationArtifact.construct(
    challenge: challenge,
    expectedChallengeBinding: retainedChallengeBinding,
    presentationEvidence: presentationEvidence,
    confirmationAuthorityEvidence: authorityEvidence,
    hostCapabilityBoundary: hostBoundary,
    confirmationID: confirmationID,
    response: .affirmative,
    confirmedAt: confirmedAt,
    confirmationExpiresAt: confirmationExpiresAt
)

let retainedArtifactBinding = artifact.binding
// The accepted contract binds confirmation validation to the prospective
// Authorization issue time exactly.
let confirmationValidationTime = authorizationIssuedAt
let confirmationContext = ConfirmationValidationContext(
    expectedRequirement: requirement,
    expectedProspectiveAuthorization: prospective,
    expectedChallengeID: challengeID,
    expectedConfirmationID: confirmationID,
    expectedChallengeBinding: retainedChallengeBinding,
    expectedArtifactBinding: retainedArtifactBinding,
    expectedPresentationEvidence: presentationEvidence,
    expectedConfirmationAuthorityEvidence: authorityEvidence,
    expectedHostAuthorityDomain: retainedHostAuthority,
    validationTime: confirmationValidationTime
)

let eligibility = try ConfirmedIssuanceEligibility.validate(
    challenge: challenge,
    artifact: artifact,
    context: confirmationContext,
    hostCapabilityBoundary: hostBoundary,
    validationTime: confirmationValidationTime
)

Eligibility is transient and non-authoritative. It does not contain final Authorization or Execution authority.

5. Authorization and pure validation

let authorization = try Phase7Authorization.construct(
    eligibility: eligibility,
    hostCapabilityBoundary: hostBoundary,
    id: authorizationID,
    replayID: replayID,
    consumptionID: consumptionID,
    generation: 1,
    decision: policyDecision,
    evaluationInput: evaluationInput,
    registrySnapshot: registrySnapshot,
    policySnapshot: policySnapshot,
    issuedAt: confirmationValidationTime,
    lifetimeRequest: authorizationLifetimeRequest
)

let issuance = try Phase7IssuanceOutput.construct(
    authorization: authorization,
    prospectiveAuthorization: prospective,
    frozenAuthorizationBinding: prospective.frozenAuthorizationBinding,
    requirement: requirement,
    challengeBinding: retainedChallengeBinding,
    artifactBinding: retainedArtifactBinding,
    replayID: replayID,
    consumptionID: consumptionID,
    hostCapabilityBoundary: hostBoundary
)

let result = Phase7AuthorizationValidator.validate(
    authorization: issuance.authorization,
    submittedConsumptionBinding: issuance.consumptionBinding,
    context: retainedPhase7ValidationContext,
    hostCapabilityBoundary: hostBoundary,
    validationTime: authorizationValidationTime
)

retainedPhase7ValidationContext must be built from independently retained Host expectations as shown in the Validation example. Successful validation still performs no Consumption and no Execution.

Expected lifecycle

  1. Exact EvaluationInput and confirmation-requiring PolicyDecision exist.
  2. The Requirement is derived without converting the decision to allow.
  3. The prospective Authorization freezes identity, binding, scope, lifetime, freshness, replay identity, and Consumption identity.
  4. Reviewed presentation facts and an exact Challenge are constructed.
  5. The Host presents all facts and records complete Presentation Evidence.
  6. Genuine Confirmation Authority records one explicit affirmative response.
  7. The exact Authority Evidence and Presentation Evidence form one Artifact.
  8. Pure confirmation validation produces transient Eligibility.
  9. Issuance repeats frozen checks and constructs Phase 7 Authorization.
  10. The final non-circular Consumption Binding is constructed after Authorization.
  11. Pure Authorization validation reconstructs and compares that binding.
  12. A future Host atomically consumes once before any Execution.

Threats prevented

  • A deny or ordinary allow without the confirmation obligation cannot derive a Requirement.
  • Raw prompts, tool output, documents, credentials, and model labels cannot enter presentation facts.
  • Authentication Authority cannot substitute for Confirmation Authority.
  • Challenge, subject, tenant, session, delegation, or Host-boundary substitution rejects.
  • Silence, timeout, dismissal, and non-affirmative response create no Artifact.
  • Expired Challenge at confirmation time or expired Confirmation at validation rejects.
  • Confirmation for one prospective Authorization cannot authorize a mutated request, scope, policy, identity, lifetime, replay ID, or Consumption ID.

Common mistakes

  • Treating confirmation as a new source of authority rather than bound evidence.
  • Showing raw arguments or model-generated security labels in the confirmation UI.
  • Treating successful authentication as an affirmative confirmation response.
  • Reconstructing expected bindings from the submitted Artifact.
  • Reusing a Challenge or Artifact for a different Authorization.
  • Treating Eligibility, Authorization, or validation as atomic Consumption.
  • Calling a Host executor before the single-use store succeeds.

Related documentation