Skip to content

docs: update paper and website to accurately reflect current security properties #65

@manzil-infinity180

Description

@manzil-infinity180

The gap

After fixing all 8 implementation bundles, aflock reaches ~80% of paper/website claims. The remaining 20% requires architectural changes. The paper and website should accurately reflect what's implemented today.

Specific claims that need caveats

  1. "The agent never sees the signing key"

    • Only true with SPIRE
    • Hooks mode: hook process holds ephemeral key in same process tree
    • Website/README state this unconditionally — need caveat
  2. Comparison table (docs/concepts/comparison.md)

    • Lists Rego/Merkle as differentiating features — they require explicit policy config
    • Should clarify: "when configured" not "always on"
  3. Identity derivation (docs/concepts/identity.md)

  4. Specification (docs/reference/specification.md)

    • Still uses old project name "ai-notary" in places
    • Identity formula in paper differs from code (5 components vs 6+)
  5. README "Private development. Specification phase."

    • Understates maturity — working CLI, hooks, attestations
    • Should reflect current state
  6. Getting started guide

    • Go version requirement says "1.25+" (doesn't exist)
    • aflock init output doesn't match docs
    • CLI reference missing replay, plan-to-policy commands and several flags

What the docs should add

  • Security properties table: what's guaranteed in each mode (SPIRE/Fulcio/ephemeral)
  • Operational requirements: what infrastructure you need for each security level
  • Limitations section: bash analysis is defense-in-depth not a sandbox, ephemeral keys prove structure not identity

Honest assessment for the paper

Claim Reality After all fixes
Signed attestations 70% — ephemeral keys = weak trust 70% (arch change needed for 95%)
Key separation 30% — only with SPIRE 30% (needs signing service)
6-phase verification Now: 0%. After Bundle 1: 95% 95%
SPIFFE/SPIRE 60% — real code, fragile ops 60% (macOS, model=unknown issues)
Policy enforcement 85% — bash has edge cases 85% (static analysis limit)
In-toto format 80% — PAE non-standard 90% after Bundle 4
Merkle/Rego/AI 95% each 95%

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpaper-95Close set (assumes paper-85 + paper-90 done) → reaches ~95%paper-gapGap between paper claims and implementationv.impVery important: blocks paper/website security claims

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions