[WIP] Fix documentation mismatches in API examples

[Copilot]

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

Critical Documentation vs Code Mismatches

The README.md, QUICKSTART.md, and USAGE_GUIDE.md contain numerous examples and API documentation that do NOT match the actual code implementation. This causes users to get failures when following the documented examples.

Specific Mismatches to Fix

1. enroll_device() Examples

Current (WRONG):

• README Line 45-46: verifier.enroll_device(device_id) - parameter should be device_name
• README Line 48: result["success"] - this key doesn't exist
• QUICKSTART Line 41: Same issues

Correct Implementation:

enrollment = verifier.enroll_device("MyDevice")  # device_name parameter
# Returns: {"fingerprint_id": "...", "policy_id": "...", "device_name": "...", "enrolled_at": "..."}
# NO "success" key

2. verify_device() Examples

Current (WRONG):

• README Line 52: verifier.verify_device(device_id) - requires TWO params: fingerprint_id, policy_id
• README Line 53: verification['valid'] - verify_device returns boolean or raises exceptions, not a dict
• QUICKSTART Line 44-47: Same issues

Correct Implementation:

result = verifier.verify_device(fingerprint_id, policy_id)  # Returns True or raises exception
# No dict, no 'valid' key

3. CLI Command Names

Current (WRONG):

• README Line 570: trustcore-tpm enroll - should be tpm-fingerprint
• README Lines 570-583: All CLI commands use wrong command name
• QUICKSTART Line 24: Same issue

Correct Commands:

tpm-fingerprint enroll MyDevice -o enrollment.json
tpm-fingerprint verify <fingerprint_id> <policy_id>
tpm-fingerprint status <fingerprint_id>
tpm-fingerprint challenge <fingerprint_id>
tpm-fingerprint compare <fingerprint_id> <policy_id>
tpm-fingerprint regenerate <old_fingerprint_id> MyDevice
tpm-fingerprint export <fingerprint_id> <policy_id> -o bundle.json
tpm-fingerprint audit stats
tpm-fingerprint audit verify
tpm-fingerprint audit events --limit 50

4. PolicyEngine API

Current (WRONG):

• README Lines 482-488: Claims methods evaluate() and register_policy(device_id, policy)
• README Lines 68-76: Example code uses non-existent methods

Correct Implementation:

policy = policy_engine.create_policy(
    name="My Policy",
    pcr_baseline=fingerprint.pcr_values,
    max_mismatch_attempts=3,
    auto_expire_on_boot_change=True
)
# Validation uses: validate_fingerprint(fingerprint, policy) -> bool
# Violation handlers: register_violation_handler(violation_type, handler_func)

5. ConsequenceHandler API

Current (WRONG):

• README Lines 495-501: Claims methods execute(device_id, violations) and register_consequence(name, handler)
• README Lines 73-76: Example code uses non-existent methods

Correct Implementation:

# Register resources
credential = handler.register_credential(
    credential_id="api_key",
    credential_type="api",
    data={"key": "secret"},
    fingerprint_id=fingerprint_id
)

vault = handler.register_vault(
    vault_id="prod_vault",
    name="Production Vault",
    fingerprint_id=fingerprint_id
)

token = handler.register_token(
    token_id="token_001",
    token_value="xyz",
    fingerprint_id=fingerprint_id
)

# Operations
handler.revoke_credential(credential_id, reason)
handler.lock_vault(vault_id, reason)
handler.invalidate_token(token_id, reason)
handler.enforce_consequences(violation, policy, fingerprint)

6. OfflineVerifier Constructor

Current (WRONG):

• README Line 452: __init__(storage_path: str = "~/.tpm_fingerprint/")

Correct:

def __init__(self, config: Optional[Config] = None):
    # Takes Config object, not storage_path string

7. Package Installation

Current (WRONG):

• README Line 24: pip install trustcore-tpm

Correct:

# Install from source (package not published to PyPI yet)
pip install -e .

8. Configuration Examples

Current (WRONG):

• README Lines 520-529: Shows config as dictionary

Correct:

from tpm_fingerprint_lib.config import Config

config = Config()
config.DEFAULT_PCRS = [0, 1, 2, 3, 7]
config.FINGERPRINT_VALIDITY_SECONDS = 86400
config.CONSEQUENCES_ENABLED = True
config.AUTO_REVOKE_CREDENTIALS = True

9. Missing Methods in Documentation

Current (WRONG):

• README Lines 460, 462: Documents revoke_device() and list_devices() as existing
• These methods are NOT implemented in the code

Action: Remove from API reference or implement them

10. Batch Operations Example

Current (WRONG):

• README Lines 619-624: References result['valid'] which doesn't exist

Correct:

devices = [fingerprints_and_policies]  # List of (fp_id, policy_id) tuples

for fp_id, policy_id in devices:
    try:
        verifier.verify_device(fp_id, policy_id)
        print(f"{fp_id}: ✓ Verified")
    except PolicyViolationError:
        print(f"{fp_id}: ✗ Verification failed")

Files to Update

1. README.md - Lines 34-77, 446-501, 566-624, 588-6...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.