Skip to content

AGENTS.md

Latest commit

 

History

History
238 lines (169 loc) · 11.3 KB

AGENTS.md

File metadata and controls

238 lines (169 loc) · 11.3 KB

Implementation Status (October 2025) — Update & Gap Analysis

Current State (October 2025)

  • Lockb0x.Core: Fully implemented and tested. Canonical Codex Entry model, RFC 8785 JCS canonicalization, schema validation, and revision chain management.
  • Lockb0x.Signing: Fully implemented and tested. EdDSA (Ed25519), RS256, and ES256K (secp256k1, Windows only) via JOSE JWS and COSE Sign1. Multi-sig, key revocation, and error handling are covered.
  • Lockb0x.Anchor.Stellar: Fully implemented and tested with in-memory/mock Horizon client. Real Stellar network integration is pending.
  • Lockb0x.Storage: IPFS adapter is implemented, integrated, and fully covered by unit tests. Adheres to RFC 6920 ni-URI, returns all required metadata, and supports auditability.
  • Lockb0x.Verifier: Fully implemented and tested. The pipeline orchestration, stepwise verification logic, and all verification steps (schema, canonicalization, signatures, integrity, storage, anchor, encryption, revision chain, certificate) are covered by deterministic unit tests. IPFS + Stellar verification flow is implemented and passing.
  • Lockb0x.Certificates: Interfaces and models present; certificate emission and revocation logic planned.
  • Lockb0x.Tests: All modules covered by unit tests. All tests pass on macOS except Secp256k1, which is skipped due to .NET platform limitations.
  • CLI & API: CLI exists but is not yet integrated for end-to-end flows. API is planned.

Usage Guidance

End-to-End Flow

  1. Store a file in IPFS using IpfsStorageAdapter.StoreAsync. Returns a StorageDescriptor with protocol, integrity proof (ni-URI), CID, and metadata.
  2. Construct a Codex Entry using the returned metadata and the Core module's builder.
  3. Canonicalize the entry with JcsCanonicalizer.
  4. Sign the entry using the Signing module (JoseCoseSigningService.SignAsync).
  5. Anchor the entry on Stellar (mock/in-memory only for now) using StellarAnchorService.AnchorAsync.
  6. Verify signatures and anchors using the respective module APIs.
  7. Audit and traverse revision chains using Core utilities.

Integration Points

  • All modules use async APIs and are designed for agent workflows.
  • Storage adapter is fully compatible with Codex Entry builder and validation.
  • Error objects are machine-readable for diagnostics.
  • All data models align with the canonical schema in spec/v0.0.2-public-draft.md.

Testing

  • All major protocol flows, including the full Verifier pipeline, are covered by deterministic unit tests.
  • IPFS adapter tests use mock HTTP clients for CI.
  • Secp256k1 signing is only supported on Windows due to .NET limitations.
  • See Lockb0x.Tests/VerifierServiceTests.cs for full protocol pipeline coverage, and other test files for module-specific coverage.

Gaps & Next Steps

Implementation Gaps

  • Stellar network integration: Real network anchoring not yet implemented; only mock/in-memory flows are tested. Next: Integrate Stellar SDK/Horizon for real transaction submission and verification.
  • Verifier module: Fully implemented and tested for the IPFS + Stellar flow. All verification steps are covered by passing unit tests. Next: Expand documentation and add more end-to-end examples.
  • CLI & API integration: CLI and API need to support end-to-end flows (file → Codex Entry → sign → anchor → certify → verify) and expose all major protocol operations. Next: Integrate modules, add workflow commands, and document usage.
  • Multi-network/blockchain anchoring: Only Stellar (mock) is supported; adapters for other chains (Ethereum, Avalanche, etc.) are planned.
  • Advanced storage adapters: Only IPFS is implemented; S3, Filecoin, Azure Blob, and other backends are planned.
  • Centralized error handling/logging: Basic error handling is present, but centralized logging and diagnostics are not yet implemented.

Documentation Gaps

  • Contributor setup: No step-by-step guide for setting up testnets, IPFS nodes, or running integration tests. Next: Add contributor guide and environment setup instructions.
  • CLI usage: No documentation for CLI commands or workflows. Next: Document CLI usage and workflow examples.
  • End-to-end examples: No full example from file ingestion to verification/certification. Next: Add example flows and test vectors.
  • Extensibility: Adapter and extension points are documented, but practical examples are limited. Next: Expand documentation with extension patterns and usage scenarios.

Roadmap & Steps to Completion

  1. Stellar Network Integration
    • Integrate real Stellar SDK/Horizon for transaction submission and anchor verification.
    • Document setup for testnet/mainnet environments.
  2. Verifier Module Implementation
    • Complete stepwise verification pipeline for IPFS + Stellar flow (schema, canonicalization, integrity, signatures, anchor, revision chain, certificate).
    • Add unit and integration tests for all verification steps.
    • Document usage and provide example flows.
  3. CLI & API End-to-End Integration
    • Implement CLI commands and API endpoints for the full workflow: file → Codex Entry → sign → anchor → certify → verify.
    • Provide usage documentation and examples.
  4. Expand Storage & Blockchain Adapters
    • Implement S3, Filecoin, Azure Blob, and other storage adapters.
    • Add support for additional blockchains (Ethereum, Avalanche, etc.).
  5. Documentation & Contributor Guides
    • Write step-by-step guides for setup, integration testing, and workflow usage.
    • Add end-to-end examples and practical extension patterns.
  6. Centralized Error Handling & Logging
    • Refactor error handling for consistency and auditability.
    • Implement centralized logging and diagnostics across modules.

Guidance for Contributors & Users

Guidance for Contributors & Users

  • Review technical plans in each module's AGENTS.md for design and integration details.
  • Use the Storage adapter for IPFS-backed Codex Entries; ensure all metadata is captured for audit and verification.
  • For signing, prefer Ed25519 or RS256 for cross-platform compatibility.
  • For anchoring, use the mock Stellar client for now; real network support will be added in future milestones.
  • For verification, follow the documented pipeline in VerifierService and use provided test vectors and example flows.
  • All APIs are async and designed for agent interoperability.
  • Open issues or pull requests for missing features, documentation, or integration improvements.

Example IPFS + Stellar Verification Flow

  1. Store file in IPFS (using IpfsStorageAdapter) → obtain CID and ni-URI integrity proof.
  2. Create Codex Entry with required fields (id, storage, integrity_proof, identity).
  3. Canonicalize entry (RFC 8785 JCS).
  4. Anchor entry on Stellar (mock/in-memory for now).
  5. Sign entry with user's private key.
  6. Generate certificate (JSON, VC, or X.509).
  7. Verify: recompute file hash, validate signatures, confirm anchor transaction on Stellar.

See Appendix A: Example Flows for more details.

References

AGENTS.md

Lockb0x Protocol — Technical Design for AI Agents

This document provides detailed technical design specifications for the Lockb0x Protocol core, signing, and anchoring modules, enabling interoperability and extension by other AI Agents. It is based on the Lockb0x Protocol Specification v0.0.1.

1. Core Module

Responsibilities

  • Define the Codex Entry data model (JSON structure).
  • Provide canonicalization (RFC 8785 JCS).
  • Validate entries against the protocol schema.
  • Manage provenance and revision chains.

Data Flows

  • Ingest file metadata via storage adapters.
  • Construct Codex Entry objects with required and optional fields.
  • Canonicalize entries before signing and anchoring.
  • Traverse revision chains for audit and verification.

API Contracts

  • CreateEntry(metadata: object): CodexEntry
  • Canonicalize(entry: CodexEntry): string
  • Validate(entry: CodexEntry): ValidationResult
  • GetRevisionChain(entryId: string): CodexEntry[]

Error Handling

  • Return structured error objects with codes and messages.
  • Validation errors include field-level diagnostics.
  • Canonicalization failures raise explicit exceptions.

Extensibility

  • Support for custom metadata extensions (JSON-LD).
  • Pluggable schema validation.
  • Adapter pattern for provenance and revision traversal.

2. Signing Module

Responsibilities

  • Implement JOSE JWS and COSE Sign1 signing and verification.
  • Support EdDSA (Ed25519), ES256K (secp256k1), and RS256 algorithms.
  • Enforce multi-sig policies and key revocation checks.

Data Flows

  • Accept canonicalized Codex Entry payloads.
  • Generate signature objects with algorithm, key ID, and signature value.
  • Attach signatures to Codex Entries.
  • Verify signatures during entry validation.

API Contracts

  • Sign(payload: byte[], key: SigningKey, alg: string): SignatureProof
  • Verify(payload: byte[], signature: SignatureProof): bool
  • ListKeys(): SigningKey[]
  • RevokeKey(keyId: string): void

Error Handling

  • Signature failures return algorithm/key-specific error codes.
  • Revoked or expired keys trigger explicit validation errors.
  • Multi-sig policy violations are surfaced as threshold errors.

Extensibility

  • Add support for new algorithms via strategy pattern.
  • Integrate external key stores (HSM, DID, Stellar).
  • Custom signature formats via interface extension.

3. Anchoring Module

Responsibilities

  • Anchor Codex Entries on blockchains (Stellar required, others optional).
  • Generate anchor objects with chain ID, transaction hash, hash algorithm, and optional token ID.
  • Validate anchor existence and payload inclusion.

Data Flows

  • Accept signed Codex Entries for anchoring.
  • Submit transactions to blockchain networks (e.g., Stellar MemoHash).
  • Retrieve and validate anchor metadata during verification.

API Contracts

  • Anchor(entry: CodexEntry, network: string): AnchorProof
  • VerifyAnchor(anchor: AnchorProof, entry: CodexEntry, network: string): bool
  • GetTransactionUrl(anchor: AnchorProof, network: string): string

Error Handling

  • Blockchain submission errors include network and transaction diagnostics.
  • Anchor verification failures return missing/invalid transaction errors.
  • Timestamp and hash mismatches are reported with context.

Extensibility

  • Support additional blockchains via adapter interface.
  • Custom anchor payload formats.
  • Pluggable verification logic for new ledger types.

General Considerations

  • All modules expose async APIs for integration with agent workflows.
  • Error objects are machine-readable for automated diagnostics.
  • Extension points are documented for agent interoperability.
  • All data models align with the canonical schema in spec/v0.0.2-public-draft.md.

For further details, see Appendix B: JSON Schema and Appendix A: Example Flows.